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