1# Sketch of OpenBMC OEM message formats
2
3This document describes OEM Requests to be supported using the OpenBMC
4OEM Number.
5
6### What's in the box?
7
8* Briefly recap OEM Extension layout as described in IPMI Specification.
9* Enumerate Command codes allocated for use with the OpenBMC OEM Number.
10* For each such code, describe the associated messages, including
11  representation, function, meaning, limits, and so on.
12
13### OEM Extensions, Block Transfer Transport Example.
14
15This table and the next briefly recap OEM Extension messages as
16described in the
17[IPMI Specification](
18http://www.intel.com/content/www/us/en/servers/ipmi/ipmi-second-gen-interface-spec-v2-rev1-1.html).
19To keep it both simple and concrete, only BT Tansport is described.
20Please consult that specification for the full story.
21
22#### OEM Request
23
24Per section 11.1 of IPMI Spec
25
26| Bytes   | Bits | Spec ID | Value | Description
27| :---:   | ---: | :------ | :---: | :----------
28| 0       |      | Length* |   -   | Number of bytes to follow in this request
29| 1       |  2:7 | NetFn   | 0x2E  | OEM Request
30| 1       |  0:1 | LUN     |   -   | Allow any LUN
31| 2       |      | Seq*    |   -   | Per section 11.3 of IPMI Spec
32| 3       |      | Cmd     |   -   | Table 3 - OpenBMC Cmd Codes
33| 4 ~ 6   |      | OEN     | 49871 | OEM Enterprise Number
34| 2 ~ n+6 |      | Data    |   -   | n data bytes, encoding depends on Cmd
35
36Notes:
37
38* Length and Seq are specific to BT transport - other transports may not
39  have them.
40
41* Serialize numbers larger than 1 byte LSB first - e.g.,
42  represent OEM Enterprise Number 49871 as `{0xcf, 0xc2, 0x00}`
43
44#### OEM Response
45
46Per section 11.2 of IPMI Spec
47
48| Bytes   | Bits | Spec ID | Value | Description
49| :---:   | ---: | :------ | :---: | :----------
50| 0       |      | Length* |   -   | Number of bytes to follow in this response
51| 1       | 2:7  | NetFn   | 0x2F  | OEM Response
52| 1       | 0:1  | LUN     |   -   | LUN of request to which this is a response
53| 2       |      | Seq*    |   -   | Seq of request to which this is a response
54| 3       |      | Cmd     |   -   | Cmd code of request to which this is a response
55| 4       |      | CC      |   -   | Completion code, Section 5.2 of IPMI Spec v2.0
56| 5 ~ 7   |      | OEN     | 49871 | OEM Enterprise Number
57| 8 ~ n+7 |      | Data    |   -   | n data bytes, encoding depends on Cmd
58
59### OpenBMC OEM Cmd Codes
60
61```
62/*
63 * This is the OpenBMC IANA OEM Number
64 */
65constexpr OemNumber obmcOemNumber = 49871;
66```
67
68These are the Command codes allocated for use with the OpenBMC OEM Number.
69
70| Cmd     | Identifier    | Description
71| :---:   | :---          | :---
72| 0       | -             | Reserved
73| 1       | gpioCmd       | GPIO Access
74| 2       | i2cCmd        | I2C Device Access
75| 3       | flashCmd      | Flash Device Access
76| 4       | fanManualCmd  | Manual Fan Controls
77| 5 ~ 255 |       -       | Unallocated
78
79### I2C Device Access (Command 2)
80
81The next subsections describe command and response messages supporting
82the I2C Device Access extension OpenBMC OEM extension (command code 2).
83
84#### I2C Request Message - Overall
85
86| Bytes   | Bits | Identifier    | Description
87| :---:   | :--- | :---          | :---
88| 0       |      | bus           | Logical I2C bus.
89| 1       |      | xferFlags     | Flags for all steps.
90|         | 7    | I2cFlagUsePec | 1 => use PEC - see note.
91|         | 6:0  |               | Reserved(0)
92| 2 ~ n-1 |      |               | Step sequence - see next.
93
94Notes
95
96* Total length of step sequence must exactly fill request.
97
98* Intent is to handle [Linux Kernel SMBus Protocol](https://www.kernel.org/doc/Documentation/i2c/smbus-protocol),
99with com generalized to m byte sequence - e.g., at24c64 uses 2 address bytes,
100and n bytes of received data,
101rather than specific operations for various sizes.
102
103* Goal is to support SMBus v2 32-byte data block length limit;
104but easily supports new 4 and 8 byte transfers added for
105[SMBus v3](http://smbus.org/specs/SMBus_3_0_20141220.pdf).
106
107* PEC refers to SMBus Packet Error Check.
108
109* SMBus address resolution, alerts, and non-standard protocols not supported.
110So for example, there is no way to insert a stop command within a transfer.
111
112* Depending on options, i2cdetect uses either quick write or 1 byte read;
113default is 1-byte read for eeprom/spd memory ranges, else quick write.
114
115#### I2C Request Message - Step Properties
116
117| Bytes | Bits  | Identifier     | Description
118| :---: | :---: | :---           | :---
119| 0     |       | devAndDir
120|       |  7:1  | dev            | 7-bit I2C device address.
121|       |  0    | isRead         | 1 = read, 0 = write.
122| 1     |       | stepFlags
123|       |  7    | i2cFlagRecvLen | 1 if block read, else regular; see table.
124|       |  6    | i2cFlagNoStart | 1 to suppress I2C start.
125|       |  5:0  |                | Reserved(0)
126| 2     |       | p              | Count parameter; see table
127| 3:m+2 |       | wrPayload      | Nonempty iff p supplies nonzero m; see table.
128
129##### Allowed step property combinations
130
131| is_read | RecvLen | p     | Size | Description
132| :---:   | :---:   | :---: | :--- | :---
133| 0       | 0       | 0     | 3    | Quick write 0; same as write m=0 bytes.
134| 0       | 0       | m     | m+3  | Consume and write next m bytes.
135| 0       | 1       | -     | 3    | Reserved.
136| 1       | 0       | 0     | 3    | Quick write 1; same as read n=0 bytes.
137| 1       | 0       | n     | 3    | Read n bytes.
138| 1       | 1       | -     | 3    | Read count from device.
139
140Notes
141
142* All other combinations are reserved.
143
144* RecvLen corresponds to Linux
145[I2C_M_RECV_LEN message flags bit](http://elixir.free-electrons.com/linux/v4.10.17/source/include/uapi/linux/i2c.h#L78)
146
147* Transfers include byte count in SMBUS block modes, and
148  PEC byte when selected. Allows for use with SMBUS compatibility layer.
149
150* In case of write steps, wrPayload may include:
151    * register address byte or bytes;
152    * count byte if implementing SMBUS block or call operation;
153    * up to 32 bytes of logical payload; and
154    * PEC byte.
155
156#### I2C Response Message
157
158| Bytes | Identifier | Size   | Description
159| :---: | :---       | :---:  | :---
160| 0:n-1 | rd_data    | 0 ~ 34 | byte sequence read
161
162Notes
163
164* Maximum logical payload is 32.
165
166* In the unlikely event a transfer specifies multiple read steps,
167  all bytes read are simply concatenated in the order read.
168
169* However, maximum reply limit is sized for the largest single read.
170
171* RecvLen case w/ PEC can return up to 34 bytes:
172    count + payload + PEC
173