# Sketch of OpenBMC OEM message formats This document describes OEM Requests to be supported using the OpenBMC OEM Number. ### What's in the box? - Briefly recap OEM Extension layout as described in IPMI Specification. - Enumerate Command codes allocated for use with the OpenBMC OEM Number. - For each such code, describe the associated messages, including representation, function, meaning, limits, and so on. ### OEM Extensions, Block Transfer Transport Example. This table and the next briefly recap OEM Extension messages as described in the [IPMI Specification](http://www.intel.com/content/www/us/en/servers/ipmi/ipmi-second-gen-interface-spec-v2-rev1-1.html). To keep it both simple and concrete, only BT Tansport is described. Please consult that specification for the full story. #### OEM Request Per section 11.1 of IPMI Spec | Bytes | Bits | Spec ID | Value | Description | | :-----: | ---: | :------- | :---: | :---------------------------------------- | | 0 | | Length\* | - | Number of bytes to follow in this request | | 1 | 2:7 | NetFn | 0x2E | OEM Request | | 1 | 0:1 | LUN | - | Allow any LUN | | 2 | | Seq\* | - | Per section 11.3 of IPMI Spec | | 3 | | Cmd | - | Table 3 - OpenBMC Cmd Codes | | 4 ~ 6 | | OEN | 49871 | OEM Enterprise Number | | 2 ~ n+6 | | Data | - | n data bytes, encoding depends on Cmd | Notes: - Length and Seq are specific to BT transport - other transports may not have them. - Serialize numbers larger than 1 byte LSB first - e.g., represent OEM Enterprise Number 49871 as `{0xcf, 0xc2, 0x00}` #### OEM Response Per section 11.2 of IPMI Spec | Bytes | Bits | Spec ID | Value | Description | | :-----: | ---: | :------- | :---: | :---------------------------------------------- | | 0 | | Length\* | - | Number of bytes to follow in this response | | 1 | 2:7 | NetFn | 0x2F | OEM Response | | 1 | 0:1 | LUN | - | LUN of request to which this is a response | | 2 | | Seq\* | - | Seq of request to which this is a response | | 3 | | Cmd | - | Cmd code of request to which this is a response | | 4 | | CC | - | Completion code, Section 5.2 of IPMI Spec v2.0 | | 5 ~ 7 | | OEN | 49871 | OEM Enterprise Number | | 8 ~ n+7 | | Data | - | n data bytes, encoding depends on Cmd | ### OpenBMC OEM Cmd Codes ``` /* * This is the OpenBMC IANA OEM Number */ constexpr OemNumber obmcOemNumber = 49871; ``` These are the Command codes allocated for use with the OpenBMC OEM Number. | Cmd | Identifier | Description | | :-----: | :----------- | :------------------ | | 0 | - | Reserved | | 1 | gpioCmd | GPIO Access | | 2 | i2cCmd | I2C Device Access | | 3 | flashCmd | Flash Device Access | | 4 | fanManualCmd | Manual Fan Controls | | 5 ~ 255 | - | Unallocated | ### I2C Device Access (Command 2) The next subsections describe command and response messages supporting the I2C Device Access extension OpenBMC OEM extension (command code 2). #### I2C Request Message - Overall | Bytes | Bits | Identifier | Description | | :-----: | :--- | :------------ | :------------------------ | | 0 | | bus | Logical I2C bus. | | 1 | | xferFlags | Flags for all steps. | | | 7 | I2cFlagUsePec | 1 => use PEC - see note. | | | 6:0 | | Reserved(0) | | 2 ~ n-1 | | | Step sequence - see next. | Notes - Total length of step sequence must exactly fill request. - Intent is to handle [Linux Kernel SMBus Protocol](https://www.kernel.org/doc/Documentation/i2c/smbus-protocol), with com generalized to m byte sequence - e.g., at24c64 uses 2 address bytes, and n bytes of received data, rather than specific operations for various sizes. - Goal is to support SMBus v2 32-byte data block length limit; but easily supports new 4 and 8 byte transfers added for [SMBus v3](http://smbus.org/specs/SMBus_3_0_20141220.pdf). - PEC refers to SMBus Packet Error Check. - SMBus address resolution, alerts, and non-standard protocols not supported. So for example, there is no way to insert a stop command within a transfer. - Depending on options, i2cdetect uses either quick write or 1 byte read; default is 1-byte read for eeprom/spd memory ranges, else quick write. #### I2C Request Message - Step Properties | Bytes | Bits | Identifier | Description | | :---: | :--: | :------------- | :-------------------------------------------- | | 0 | | devAndDir | | | 7:1 | dev | 7-bit I2C device address. | | | 0 | isRead | 1 = read, 0 = write. | | 1 | | stepFlags | | | 7 | i2cFlagRecvLen | 1 if block read, else regular; see table. | | | 6 | i2cFlagNoStart | 1 to suppress I2C start. | | | 5:0 | | Reserved(0) | | 2 | | p | Count parameter; see table | | 3:m+2 | | wrPayload | Nonempty iff p supplies nonzero m; see table. | ##### Allowed step property combinations | is_read | RecvLen | p | Size | Description | | :-----: | :-----: | :-: | :--- | :-------------------------------------- | | 0 | 0 | 0 | 3 | Quick write 0; same as write m=0 bytes. | | 0 | 0 | m | m+3 | Consume and write next m bytes. | | 0 | 1 | - | 3 | Reserved. | | 1 | 0 | 0 | 3 | Quick write 1; same as read n=0 bytes. | | 1 | 0 | n | 3 | Read n bytes. | | 1 | 1 | - | 3 | Read count from device. | Notes - All other combinations are reserved. - RecvLen corresponds to Linux [I2C_M_RECV_LEN message flags bit](http://elixir.free-electrons.com/linux/v4.10.17/source/include/uapi/linux/i2c.h#L78) - Transfers include byte count in SMBUS block modes, and PEC byte when selected. Allows for use with SMBUS compatibility layer. - In case of write steps, wrPayload may include: - register address byte or bytes; - count byte if implementing SMBUS block or call operation; - up to 32 bytes of logical payload; and - PEC byte. #### I2C Response Message | Bytes | Identifier | Size | Description | | :---: | :--------- | :----: | :----------------- | | 0:n-1 | rd_data | 0 ~ 34 | byte sequence read | Notes - Maximum logical payload is 32. - In the unlikely event a transfer specifies multiple read steps, all bytes read are simply concatenated in the order read. - However, maximum reply limit is sized for the largest single read. - RecvLen case w/ PEC can return up to 34 bytes: count + payload + PEC