docs/bindings/vendor-ibm-astlpc.md

1 # Management Component Transport Protocol (MCTP) LPC Transport Binding Specification for ASPEED BMC…
6 host and BMC over the LPC bus on ASPEED BMC platforms.
17 2. Intel (R) Low Pin Count (LPC) Interface Specification 1.1,
18 …<https://www.intel.com/content/dam/www/program/design/us/en/documents/low-pin-count-interface-spec…
29 MCTP-compliant endpoints must accept.
33 A hardware-defined flag bit in a KCS device's Status Register (STR). The IBF
34 flag indicates that a value has been written by the host to the corresponding
40 byte buffer which is written by the host and read by the BMC.
42 ### KCS: Keyboard-Controller-Style
48 systems. This interface is available built-in to several commercially available
49 microcontrollers. Data is transferred across the KCS interface using a per-byte
52 ### LPC Bus: Low Pin Count Bus
57 ### LPC FW: LPC Firmware Cycles
59 LPC firmware cycles allow separate boot BIOS firmware memory cycles and
60 application memory cycles with respect to the LPC bus. The ASPEED BMCs allow
61 remapping of the LPC firmware cycles onto arbitrary regions of the BMC's
68 values larger than the BTU may improve throughput for data-intensive transfers.
72 A hardware-defined flag bit in a KCS device's Status Register (STR). The OBF
79 byte buffer which is written by the BMC and read by the host.
84 BMC-controlled, eight-bit register exposed to both the BMC and the host for
86 Bits that are not defined by hardware can be software-controlled in a manner
87 defined by a platform-specific ABI.
94 ## MCTP over LPC Transport
100 - An interrupt mechanism using the IPMI KCS interface
101 - A window of the LPC FW address space, where reads and writes are forwarded to
104 In order to transfer a packet, either side of the channel (BMC or host) will:
106 1. Write the packet to the LPC FW window
107    - The BMC will perform writes by writing to the memory backing the LPC window
108    - The host will perform writes by writing to the LPC bus, at predefined
114 1. Read from the KCS status register, which shows that the single-byte KCS data
118 3. Read the MCTP packet from the LPC FW window
125 1. The LPC IO address and Serial IRQ parameters of the KCS device
126 2. The concrete location of the control region in the LPC FW address space
131 remote side, that a packet is ready to be transferred through the LPC FW
134 The KCS hardware consists of two single-byte buffers: the Output Data Register
136 by the host. The IDR is the obverse.
138 The KCS unit also contains a status register (STR), allowing both host and BMC
139 to determine if there is data in the ODR or IDR. These are single-bit flags,
145 software-defined bits in the status register are used to carry other required
150 buffer-full flag and invoke an interrupt.
156 ### LPC FW Window
158 The window of BMC-memory-backed LPC FW address space has a predefined format,
161 - A control descriptor, describing static data about the rest of the window
162 - A receive area for BMC-to-host packets
163 - A transmit area, for host-to-BMC packets
166 transmit and receive areas. These offsets are relative to the start of the LPC
197 All medium-specific metadata is in big-endian format. This includes:
200 2. Medium-specific packet header fields
201 3. Medium-specific packet trailer fields
207 medium-specific header comprising a 32-bit payload length field, followed
218 A medium-specific packet trailer must immediately follow the payload. The length
219 of the trailer is not accounted for in the length field of the medium-specific
223 For protocol versions 1 and 2, the medium-specific trailer length is zero.
225 For protocol version 3, the medium-specific trailer comprises a CRC-32 checksum
234 Where the CRC-32 implementation is defined by the following characteristics (or
239 2. Initialising the remainder state to `2^32 - 1`
242 4. `XOR`ing the calculated remainder with `2^32 - 1`
257 necessarily backwards-compatible.
262 `rx_size` for backwards compatibility with version 1, the host MAY write
263 `rx_size` without regard for its current value if the host supports version 2.
265 to the host's proposed `rx_size` value. As such, when `Channel Active` is set by
266 the BMC, the host MUST read both `rx_size` and `tx_size` in response to ensure
267 both the BMC and the host have a consistent understanding of the MTU in each
275 - Intersect neither eachother nor the control region
276 - Not extend beyond the window allocated to MCTP in the LPC FW address space
277 - Must accommodate at least BTU-sized payloads
285 the ability to send and receive packets on the LPC bus.
290 | ------- | ---------- | ---------------------------------- |
303 | ------- | ----------- |
309 #### Host Command to BMC Sequence
311 The host sends commands to the BMC to signal channel initialisation, begin
315 | ---- | ------------------------------------------------------- |
316 | 1    | The host writes a command value to IDR                  |
319 | 4    | If IBF is set, the BMC reads the host command from IDR  |
322 #### BMC Command to Host Sequence
324 The BMC sends commands to the host to begin transmission of a packet or to
328 | ---- | ------------------------------------------------------- |
330 | 2    | The hardware sets OBF, which triggers a host interrupt  |
331 | 3    | The host reads the status register for OBF              |
332 | 4    | If OBF is set, the host reads the BMC command from ODR  |
337 The BMC sends status updates to the host to signal loss of function, loss of
341 | ---- | -------------------------------------------------------------- |
344 | 3    | The hardware sets OBF, which triggers a host interrupt         |
345 | 4    | If OBF is set, the host reads the BMC command from ODR         |
347 | 6    | The host observes the command is the dummy command             |
348 | 7    | The host reads the status register to capture the state change |
350 #### LPC Window Ownership and Synchronisation
352 Because the LPC FW window is shared between the host and the BMC we need strict
357 - The control data is only written during initialisation. The control area is
359 - Only the BMC may write to the Rx buffer described in the control area
360 - Only the host may write to the Tx buffer described in the control area
371 ### LPC Binding Operation
378 where commands are sent between the BMC and the host. The act of updating status
380 [KCS Control](#kcs-control).
388 | ---- | ------------------------------------------------------------------------------------- |
392 #### Host Initialisation Sequence
395 | ---- | --- | --- | --- | ------------------------------------------------------------------------…
396 | 1    | ✓   | ✓   | ✓   | The host waits for the `BMC Active` state                               …
397 | 2    | ✓   | ✓   | ✓   | The host populates the its version fields                               …
398 | 3    |     | ✓   | ✓   | The host derives and writes to `rx_size` the packet size associated with…
399 | 4    | ✓   | ✓   | ✓   | The host sends the `Initialise` command                                 …
404 | 9    | ✓   | ✓   | ✓   | The host observes that `Channel Active` is set                          …
405 | 10   | ✓   | ✓   | ✓   | The host reads the negotiated version                                   …
406 | 11   |     | ✓   | ✓   | The host reads both `rx_size` and `tx_size` to derive the negotiated MTU…
408 #### Host Packet Transmission Sequence
411 | ---- | --- | --- | --- | ------------------------------------------------------------------------…
412 | 1    |     |     | ✓   | The host calculates the CRC-32 over the packet data                     …
413 | 2    | ✓   | ✓   | ✓   | The host waits on any previous `Rx Complete` message                    …
414 | 3    | ✓   | ✓   | ✓   | The host writes the packet data and medium-specific metadata to its Tx a…
415 | 4    | ✓   | ✓   | ✓   | The host sends the `Tx Begin` command, transferring ownership of its Tx …
417 …| ✓   | ✓   | The BMC reads the packet data and medium-specific metadata from the its Rx area (hos…
418 … | The BMC sends the `Rx Complete` command, transferring ownership of its Rx buffer to the host   |
419 | 8    | ✓   | ✓   | ✓   | The host observes the `Rx Complete` command                             …
420 | 9    |     |     | ✓   | The BMC validates the provided CRC-32 over the packet data              …
425 | ---- | --- | --- | --- | ------------------------------------------------------------------------…
426 | 1    |     |     | ✓   | The BMC calculates the CRC-32 over the packet data                      …
428 …  | ✓   | ✓   | The BMC writes the packet data and medium-specific metadata to its Tx area (host R…
429 …| The BMC sends the `Tx Begin` command, transferring ownership of its Tx buffer to the host       |
430 | 5    | ✓   | ✓   | ✓   | The host observes the `Tx Begin` command                                …
431 | 6    | ✓   | ✓   | ✓   | The host reads the packet data and medium-specific metadata from the hos…
432 | 7    | ✓   | ✓   | ✓   | The host sends the `Rx Complete` command, transferring ownership of its …
434 | 9    |     |     | ✓   | The host validates the provided CRC-32 over the packet data             …
441 - An LPC KCS device exposed by a [binding-specific kernel driver][mctp-driver]
442 - The reserved memory mapped by the LPC2AHB bridge via the [aspeed-lpc-ctrl
443   driver][aspeed-lpc-ctrl]
444 - The astlpc binding found in [libmctp][libmctp]
446 [mctp-driver]:
448 [aspeed-lpc-ctrl]:
449 …el.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/soc/aspeed/aspeed-lpc-ctrl.c?h=v5.7
452 From the host side, the LPC Firmware and KCS IO cycles are driven by
453 free-standing firmware. Some firmwares exploit [libmctp][libmctp] by
454 implementing the driver hooks for direct access to the LPC devices.
461 arbitrarily-sized MCTP messages. However, there are much larger overheads in
462 synchronisation between host and BMC for every byte transferred.
469 the complexity introduced would make low-level debugging both more difficult and
474 The BT interface allows for block-at-time transfers. However, the BT buffer size
475 is only 64 bytes on the AST2500 hardware, which does not allow us to comply with
476 the MCTP Base Specification (DSP0236) that requires a 64-byte payload size as
477 the minimum. The 64-byte BT buffer does not allow for MCTP and transport
485 ### Using the AST2500 LPC Mailbox
487 This would require enabling the SuperIO interface, which allows the host to