docs: vendor-ibm-astlpc: Define v3 of the protocol
v3 adds a CRC-32 integrity check across each packet exchanged via the
binding.
Signed-off-by: Andrew Jeffery <andrew@aj.id.au>
Change-Id: Ie9b798e1076e099525ebf7bcfe5d8ea81367ae3a
diff --git a/docs/bindings/vendor-ibm-astlpc.md b/docs/bindings/vendor-ibm-astlpc.md
index 2cf85c5..c07b2fe 100644
--- a/docs/bindings/vendor-ibm-astlpc.md
+++ b/docs/bindings/vendor-ibm-astlpc.md
@@ -196,13 +196,53 @@
#define LPC_MAGIC 0x4d435450
```
-All control data is in big-endian format. MCTP packet data is transferred
-exactly as is presented, and no data escaping is performed.
+All medium-specific metadata is in big-endian format. This includes:
-The transmit and receive areas contain a length field, followed by the actual
-MCTP packet to be transferred. At version 1, only a single MCTP packet is
-present in the Rx and Tx areas. This may change for future versions of the
-protocol.
+1. Control area data
+2. Medium-specific packet header fields
+3. Medium-specific packet trailer fields
+
+MCTP packet data is transferred exactly as is presented, and no data escaping is
+performed.
+
+In all versions of the protocol, the transmit and receive areas contain a
+medium-specific header comprising a 32-bit payload length field, followed
+immediately by the MCTP packet data to be transferred. The full MCTP packet,
+including MCTP header, is considered to be the payload for the purpose of the
+header's length field.
+
+```c
+struct mctp_lpcbuf_hdr {
+ uint32_t length;
+} __attribute__((packed));
+```
+
+A medium-specific packet trailer must immediately follow the payload. The length
+of the trailer is not accounted for in the length field of the medium-specific
+packet header: The length of the trailer is implied by the negotiated protocol
+version.
+
+For protocol versions 1 and 2, the medium-specific trailer length is zero.
+
+For protocol version 3, the medium-specific trailer comprises a CRC-32 checksum
+of the payload.
+
+```c
+struct mctp_lpcbuf_tlr {
+ uint32_t crc32;
+} __attribute__((packed));
+```
+
+Where the CRC-32 implementation is defined by the following characteristics (or
+equivalent):
+
+1. The polynomial `x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11 + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1`
+2. Initialising the remainder state to `2^32 - 1`
+3. Incrementally shifting and `XOR`ing data bytes through the reversed polynomial representation `0xEDB88320`
+4. `XOR`ing the calculated remainder with `2^32 - 1`
+
+For all defined versions, only a single MCTP packet is present in the Rx and Tx
+areas. This may change for future versions of the protocol.
#### Negotiation of the Maximum Transmission Unit
@@ -351,43 +391,47 @@
#### Host Initialisation Sequence
-| Step | v1 | v2 | Description |
-|------|----|----|------------------------------------------------|
-| 1 | ✓ | ✓ | The host waits for the `BMC Active` state |
-| 2 | ✓ | ✓ | The host populates the its version fields |
-| 3 | | ✓ | The host derives and writes to `rx_size` the packet size associated with its desired MTU |
-| 4 | ✓ | ✓ | The host sends the `Initialise` command |
-| 5 | ✓ | ✓ | The BMC observes the `Initialise` command |
-| 6 | ✓ | ✓ | The BMC calculates and writes `negotiated_ver` |
-| 7 | | ✓ | The BMC calculates the MTUs and updates neither, one or both of `rx_size` and `tx_size` |
-| 8 | ✓ | ✓ | The BMC sets the status to `Channel Active` |
-| 9 | ✓ | ✓ | The host observes that `Channel Active` is set |
-| 10 | ✓ | ✓ | The host reads the negotiated version |
-| 11 | | ✓ | The host reads both `rx_size` and `tx_size` to derive the negotiated MTUs |
+| Step | v1 | v2 | v3 | Description |
+|------|----|----|----|------------------------------------------------|
+| 1 | ✓ | ✓ | ✓ | The host waits for the `BMC Active` state |
+| 2 | ✓ | ✓ | ✓ | The host populates the its version fields |
+| 3 | | ✓ | ✓ | The host derives and writes to `rx_size` the packet size associated with its desired MTU |
+| 4 | ✓ | ✓ | ✓ | The host sends the `Initialise` command |
+| 5 | ✓ | ✓ | ✓ | The BMC observes the `Initialise` command |
+| 6 | ✓ | ✓ | ✓ | The BMC calculates and writes `negotiated_ver` |
+| 7 | | ✓ | ✓ | The BMC calculates the MTUs and updates neither, one or both of `rx_size` and `tx_size` |
+| 8 | ✓ | ✓ | ✓ | The BMC sets the status to `Channel Active` |
+| 9 | ✓ | ✓ | ✓ | The host observes that `Channel Active` is set |
+| 10 | ✓ | ✓ | ✓ | The host reads the negotiated version |
+| 11 | | ✓ | ✓ | The host reads both `rx_size` and `tx_size` to derive the negotiated MTUs |
#### Host Packet Transmission Sequence
-| Step | Description |
-|------|--------------------------------------------------------------|
-| 1 | The host waits on any previous `Rx Complete` message |
-| 2 | The host writes the packet to its Tx area (BMC Rx area) |
-| 3 | The host sends the `Tx Begin` command, transferring ownership of its Tx buffer to the BMC |
-| 4 | The BMC observes the `Tx Begin` command |
-| 5 | The BMC reads the packet from the its Rx area (host Tx area) |
-| 6 | The BMC sends the `Rx Complete` command, transferring ownership of its Rx buffer to the host |
-| 7 | The host observes the `Rx Complete` command |
+| Step | v1 | v2 | v3 | Description |
+|------|----|----|----|--------------------------------------------------------------|
+| 1 | | | ✓ | The host calculates the CRC-32 over the packet data |
+| 2 | ✓ | ✓ | ✓ | The host waits on any previous `Rx Complete` message |
+| 3 | ✓ | ✓ | ✓ | The host writes the packet data and medium-specific metadata to its Tx area (BMC Rx area) |
+| 4 | ✓ | ✓ | ✓ | The host sends the `Tx Begin` command, transferring ownership of its Tx buffer to the BMC |
+| 5 | ✓ | ✓ | ✓ | The BMC observes the `Tx Begin` command |
+| 6 | ✓ | ✓ | ✓ | The BMC reads the packet data and medium-specific metadata from the its Rx area (host Tx area) |
+| 7 | ✓ | ✓ | ✓ | The BMC sends the `Rx Complete` command, transferring ownership of its Rx buffer to the host |
+| 8 | ✓ | ✓ | ✓ | The host observes the `Rx Complete` command |
+| 9 | | | ✓ | The BMC validates the provided CRC-32 over the packet data |
#### BMC Packet Transmission Sequence
-| Step | Description |
-|------|---------------------------------------------------------------|
-| 1 | The BMC waits on any previous `Rx Complete` message |
-| 2 | The BMC writes the packet to its Tx area (host Rx area) |
-| 3 | The BMC sends the `Tx Begin` command, transferring ownership of its Tx buffer to the host |
-| 4 | The host observes the `Tx Begin` command |
-| 5 | The host reads the packet from the host Rx area (BMC Tx area) |
-| 6 | The host sends the `Rx Complete` command, transferring ownership of its Rx buffer to the BMC |
-| 7 | The BMC observes the `Rx Complete` command |
+| Step | v1 | v2 | v3 | Description |
+|------|----|----|----|---------------------------------------------------------------|
+| 1 | | | ✓ | The BMC calculates the CRC-32 over the packet data |
+| 2 | ✓ | ✓ | ✓ | The BMC waits on any previous `Rx Complete` message |
+| 3 | ✓ | ✓ | ✓ | The BMC writes the packet data and medium-specific metadata to its Tx area (host Rx area) |
+| 4 | ✓ | ✓ | ✓ | The BMC sends the `Tx Begin` command, transferring ownership of its Tx buffer to the host |
+| 5 | ✓ | ✓ | ✓ | The host observes the `Tx Begin` command |
+| 6 | ✓ | ✓ | ✓ | The host reads the packet data and medium-specific metadata from the host Rx area (BMC Tx area) |
+| 7 | ✓ | ✓ | ✓ | The host sends the `Rx Complete` command, transferring ownership of its Rx buffer to the BMC |
+| 8 | ✓ | ✓ | ✓ | The BMC observes the `Rx Complete` command |
+| 9 | | | ✓ | The host validates the provided CRC-32 over the packet data |
## Implementation Notes