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
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
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
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
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.
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 | ------- | ----------- |
315 | ---- | ------------------------------------------------------- |
328 | ---- | ------------------------------------------------------- |
341 | ---- | -------------------------------------------------------------- |
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
380 [KCS Control](#kcs-control).
388 | ---- | ------------------------------------------------------------------------------------- |
395 | ---- | --- | --- | --- | ------------------------------------------------------------------------…
411 | ---- | --- | --- | --- | ------------------------------------------------------------------------…
412 | 1    |     |     | ✓   | The host calculates the CRC-32 over the packet data                     …
414 | 3    | ✓   | ✓   | ✓   | The host writes the packet data and medium-specific metadata to its Tx a…
417 | 6    | ✓   | ✓   | ✓   | The BMC reads the packet data and medium-specific metadata from the its …
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 | 3    | ✓   | ✓   | ✓   | The BMC writes the packet data and medium-specific metadata to its Tx ar…
431 | 6    | ✓   | ✓   | ✓   | The host reads the packet data and medium-specific metadata from the hos…
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
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