prettier: re-format
Prettier is enabled in openbmc-build-scripts on Markdown, JSON, and YAML
files to have consistent formatting for these file types. Re-run the
formatter on the whole repository.
Change-Id: Ibcba1d4dcfc062988d71ea12912b53512fa644ff
Signed-off-by: Patrick Williams <patrick@stwcx.xyz>
diff --git a/README.md b/README.md
index aff174c..96ac0b3 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,19 @@
-libmctp: Implementation of MCTP (DTMF DSP0236)
-==============================================
+# libmctp: Implementation of MCTP (DTMF DSP0236)
This library is intended to be a portable implementation of the Management
-Component Transport Protocol (MCTP), as defined by DMTF standard "DSP0236",
-plus transport binding specifications.
+Component Transport Protocol (MCTP), as defined by DMTF standard "DSP0236", plus
+transport binding specifications.
-Contact
--------
+## Contact
-* Email: See [OWNERS](OWNERS). Please also Cc openbmc@lists.ozlabs.org
-* Discord: #mctp on https://discord.gg/69Km47zH98
-* IRC: #openbmc on Freenode
+- Email: See [OWNERS](OWNERS). Please also Cc openbmc@lists.ozlabs.org
+- Discord: #mctp on https://discord.gg/69Km47zH98
+- IRC: #openbmc on Freenode
-API/ABI Stability
------------------
+## API/ABI Stability
-The APIs and ABI of libmctp are not yet stablised as we continue to explore
-ways to present the MCTP protocol to firmware and applications. Please bear
-with us!
+The APIs and ABI of libmctp are not yet stablised as we continue to explore ways
+to present the MCTP protocol to firmware and applications. Please bear with us!
When we approach a complete implementation of DSP0236 we will consider the
suitability of the API/ABI for stabilisation.
@@ -25,59 +21,59 @@
In the mean time, we'd like your feedback on the library's suitability for your
environment.
-Core API
---------
+## Core API
To initialise the MCTP stack with a single hardware bus:
- * `mctp = mctp_init()`: Initialise the MCTP core
- * `binding = mctp_<binding>_init()`: Initialise a hardware binding
- * `mctp_register_bus(mctp, binding, eid)`: Register the hardware binding with
- the core, using a predefined EID
+- `mctp = mctp_init()`: Initialise the MCTP core
+- `binding = mctp_<binding>_init()`: Initialise a hardware binding
+- `mctp_register_bus(mctp, binding, eid)`: Register the hardware binding with
+ the core, using a predefined EID
Then, register a function call to be invoked when a message is received:
- * `mctp_set_rx_all(mctp, function)`: Provide a callback to be invoked when a
- MCTP message is received
+- `mctp_set_rx_all(mctp, function)`: Provide a callback to be invoked when a
+ MCTP message is received
Or transmit a message:
- * `mctp_message_tx(mctp, message, len)`: Transmit a MCTP message
+- `mctp_message_tx(mctp, message, len)`: Transmit a MCTP message
-The binding may require you to notify it to receive packets. For example,
-for the serial binding, the `mctp_serial_read()` function should be invoked
-when the file-descriptor for the serial device has data available.
+The binding may require you to notify it to receive packets. For example, for
+the serial binding, the `mctp_serial_read()` function should be invoked when the
+file-descriptor for the serial device has data available.
### Bridging
-libmctp implements basic support for bridging between two hardware bindings.
-In this mode, bindings may have different MTUs, so packets are reassembled into
+libmctp implements basic support for bridging between two hardware bindings. In
+this mode, bindings may have different MTUs, so packets are reassembled into
their messages, then the messages are re-packetised for the outgoing binding.
For bridging between two endpoints, use the `mctp_bridge_busses()` function:
- * `mctp = mctp_init()`: Initialise the MCTP core
- * `b1 = mctp_<binding>_init(); b2 = mctp_<binding>_init()`: Initialise two hardware bindings
- * `mctp_bridge_busses(mctp, b1, b2)`: Setup bridge
+- `mctp = mctp_init()`: Initialise the MCTP core
+- `b1 = mctp_<binding>_init(); b2 = mctp_<binding>_init()`: Initialise two
+ hardware bindings
+- `mctp_bridge_busses(mctp, b1, b2)`: Setup bridge
-Note that no EIDs are defined here; the bridge does not deliver any messages
-to a local rx callback, and messages are bridged as-is.
+Note that no EIDs are defined here; the bridge does not deliver any messages to
+a local rx callback, and messages are bridged as-is.
-Binding API
------------
+## Binding API
Hardware bindings provide a method for libmctp to send and receive packets
-to/from hardware. A binding defines a hardware specific structure (`struct
-mctp_binding_<name>`), which wraps the generic binding (`struct mctp_binding`):
+to/from hardware. A binding defines a hardware specific structure
+(`struct mctp_binding_<name>`), which wraps the generic binding
+(`struct mctp_binding`):
struct mctp_binding_foo {
- struct mctp_binding binding;
- /* hardware-specific members here... */
+ struct mctp_binding binding;
+ /* hardware-specific members here... */
};
-The binding code then provides a method (`_init`) to allocate and initialise
-the binding; this may be of any prototype (calling code will know what
-arguments to pass):
+The binding code then provides a method (`_init`) to allocate and initialise the
+binding; this may be of any prototype (calling code will know what arguments to
+pass):
struct mctp_binding_foo *mctp_binding_foo_init(void);
@@ -91,62 +87,56 @@
struct mctp_binding *mctp_binding_foo_core(struct mctp_binding_foo *b);
(Implementations of this will usually be fairly consistent, just returning
-`b->binding`). Callers can then use that generic pointer to register the
-binding with the core:
+`b->binding`). Callers can then use that generic pointer to register the binding
+with the core:
struct mctp_binding *binding = mctp_binding_foo_core(foo);
mctp_register_bus(mctp, binding, 8);
-
-Integration
------------
+## Integration
The libmctp code is intended to be integrated into other codebases by two
methods:
- 1. as a simple library (`libmctp.{a,so}`) which can be compiled separately
- and linked into the containing project
+1. as a simple library (`libmctp.{a,so}`) which can be compiled separately and
+ linked into the containing project
- 2. as a set of sources to be included into the containing project (either
+2. as a set of sources to be included into the containing project (either
imported, or as a git subtree/submodule)
For (1), you can use the top-level makefile to produce `libmctp.a`.
For (2), the `Makefile.inc` file provides the minimum set of dependencies to
either build libmctp.a, or just the actual object files (`LIBMCTP_OBS`), which
-you can include into your existing make definitions. You'll want to set
+you can include into your existing make definitions. You'll want to set
`LIBMTCP_DIR` to refer to the subdirectory that contains that makefile, so we
can set the correct paths to sources.
-
-Environment configuration
--------------------------
+## Environment configuration
This library is intended to be portable to be used in a range of environments,
but the main targets are:
- - Linux userspace, typically for BMC use-cases
- - Low-level firmware environments
+- Linux userspace, typically for BMC use-cases
+- Low-level firmware environments
For the latter, we need to support customisation of the functions that libmctp
uses (for example, POSIX file IO is not available).
In order to support these, we have a few compile-time definitions:
- - `MCTP_HAVE_FILEIO`: define if POSIX file io is available, allowing the
- serial hardware binding to access char devices for IO.
+- `MCTP_HAVE_FILEIO`: define if POSIX file io is available, allowing the serial
+ hardware binding to access char devices for IO.
- - `MCTP_HAVE_SYSLOG`: allow logging to syslog, through the `vsyslog`
- call.
+- `MCTP_HAVE_SYSLOG`: allow logging to syslog, through the `vsyslog` call.
- - `MCTP_DEFAULT_ALLOC`: set default allocator functions (malloc, free,
- realloc), so that applications do not have to provide their own.
+- `MCTP_DEFAULT_ALLOC`: set default allocator functions (malloc, free, realloc),
+ so that applications do not have to provide their own.
-TODO
-----
+## TODO
- - Partial packet queue transmit
- - Control messages
- - Message- and packet-buffer pools and preallocation
- - C++ API
- - Non-file-based serial binding
+- Partial packet queue transmit
+- Control messages
+- Message- and packet-buffer pools and preallocation
+- C++ API
+- Non-file-based serial binding
diff --git a/docs/bindings/vendor-ibm-astlpc.md b/docs/bindings/vendor-ibm-astlpc.md
index c07b2fe..4c523fe 100644
--- a/docs/bindings/vendor-ibm-astlpc.md
+++ b/docs/bindings/vendor-ibm-astlpc.md
@@ -7,19 +7,19 @@
## References
-The following referenced documents are indispensable for the application of
-this document.
+The following referenced documents are indispensable for the application of this
+document.
1. DMTF DSP0236, Management Component Transport Protocol (MCTP) Base
-Specification 1.0,
-http://www.dmtf.org/standards/published_documents/DSP0236_1.0.pdf
+ Specification 1.0,
+ http://www.dmtf.org/standards/published_documents/DSP0236_1.0.pdf
2. Intel (R) Low Pin Count (LPC) Interface Specification 1.1,
-https://www.intel.com/content/dam/www/program/design/us/en/documents/low-pin-count-interface-specification.pdf
+ https://www.intel.com/content/dam/www/program/design/us/en/documents/low-pin-count-interface-specification.pdf
3. IPMI Consortium, Intelligent Platform Management Interface Specification,
-v1.5 Revision 1.1 February 20, 2002,
-http://download.intel.com/design/servers/ipmi/IPMIv1_5rev1_1.pdf
+ v1.5 Revision 1.1 February 20, 2002,
+ http://download.intel.com/design/servers/ipmi/IPMIv1_5rev1_1.pdf
## Definitions
@@ -45,9 +45,9 @@
keyboard microcontrollers and embedded controllers. The term "Keyboard
Controller Style" reflects that the register definition was originally used as
the legacy "8742" keyboard controller interface in PC architecture computer
-systems. This interface is available built-in to several commercially
-available microcontrollers. Data is transferred across the KCS interface using
-a per-byte handshake.
+systems. This interface is available built-in to several commercially available
+microcontrollers. Data is transferred across the KCS interface using a per-byte
+handshake.
**LPC Bus: Low Pin Count Bus**
@@ -64,9 +64,8 @@
**MTU: Maximum Transmission Unit**
The largest payload the link will accept for a packet. The Maximum Transmission
-Unit represents a value that is at least as large as the BTU. Negotiation of
-MTU values larger than the BTU may improve throughput for data-intensive
-transfers.
+Unit represents a value that is at least as large as the BTU. Negotiation of MTU
+values larger than the BTU may improve throughput for data-intensive transfers.
**OBF: Output Buffer Full**
@@ -76,8 +75,8 @@
**ODR: Output Data Register**
-One of the three register interfaces exposed by a KCS device. The ODR is a
-one byte buffer which is written by the BMC and read by the host.
+One of the three register interfaces exposed by a KCS device. The ODR is a one
+byte buffer which is written by the BMC and read by the host.
**STR: Status Register**
@@ -98,16 +97,15 @@
The basic components used for the transfer are:
-* An interrupt mechanism using the IPMI KCS interface
-* A window of the LPC FW address space, where reads and writes are forwarded to
+- An interrupt mechanism using the IPMI KCS interface
+- A window of the LPC FW address space, where reads and writes are forwarded to
BMC memory, using the LPC2AHB hardware
In order to transfer a packet, either side of the channel (BMC or host) will:
1. Write the packet to the LPC FW window
- * The BMC will perform writes by writing to the memory backing the LPC
- window
- * The host will perform writes by writing to the LPC bus, at predefined
+ - The BMC will perform writes by writing to the memory backing the LPC window
+ - The host will perform writes by writing to the LPC bus, at predefined
addresses
2. Trigger an interrupt on the remote side, by writing to the KCS data buffer
@@ -145,11 +143,11 @@
While the IBF and OBF flags are managed in hardware, the remaining
software-defined bits in the status register are used to carry other required
-protocol state. A problematic feature of the KCS status register is described
-in the IPMI specification, which states that an interrupt may be triggered on
+protocol state. A problematic feature of the KCS status register is described in
+the IPMI specification, which states that an interrupt may be triggered on
writes to the KCS status register but hardware implementations are not required
-to do so. Comparatively, writes to the data registers must set the
-corresponding buffer-full flag and invoke an interrupt.
+to do so. Comparatively, writes to the data registers must set the corresponding
+buffer-full flag and invoke an interrupt.
To ensure interrupts are generated for status updates, we exploit the OBF
interrupt to signal a status update by writing a dummy command to ODR after
@@ -160,9 +158,9 @@
The window of BMC-memory-backed LPC FW address space has a predefined format,
consisting of:
-* A control descriptor, describing static data about the rest of the window
-* A receive area for BMC-to-host packets
-* A transmit area, for host-to-BMC packets
+- A control descriptor, describing static data about the rest of the window
+- A receive area for BMC-to-host packets
+- A transmit area, for host-to-BMC packets
The control descriptor contains a version, and offset and size data for the
transmit and receive areas. These offsets are relative to the start of the LPC
@@ -236,9 +234,11 @@
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`
+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`
+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
@@ -247,34 +247,34 @@
#### Negotiation of the Maximum Transmission Unit
Version 1 of the protocol offers no mechanism for negotiation of the maximum
-transmission unit. The Rx and Tx buffers must be sized to accommodate packets
-up to the Baseline Transmission Unit, and the implementation assumes that the
-MTU is set to the BTU regardless of the values of `rx_size` and `tx_size`.
+transmission unit. The Rx and Tx buffers must be sized to accommodate packets up
+to the Baseline Transmission Unit, and the implementation assumes that the MTU
+is set to the BTU regardless of the values of `rx_size` and `tx_size`.
Version 2 of the protocol exploits the `rx_size` and `tx_size` fields in the
control region to negotiate the link MTU. Note that at the time that the MTU is
-under negotiation the protocol version has not been finalised, so the process
-is necessarily backwards-compatible.
+under negotiation the protocol version has not been finalised, so the process is
+necessarily backwards-compatible.
The relevant property that each endpoint must control is the MTU of packets it
will receive, as this governs how the remote endpoint's packetisation impacts
memory pressure at the local endpoint. As such while the BMC MUST populate
`rx_size` for backwards compatibility with version 1, the host MAY write
`rx_size` without regard for its current value if the host supports version 2.
-The BMC controls the value of `tx_size`, and MAY choose to adjust it in
-response to the host's proposed `rx_size` value. As such, when `Channel Active`
-is set by the BMC, the host MUST read both `rx_size` and `tx_size` in response
-to ensure both the BMC and the host have a consistent understanding of the MTU
-in each direction. It is convention for `rx_size` and `tx_size` to be set to
-the same value by the BMC as part of finalising the channel, though it is not
-invalid to have asymmetric MTUs.
+The BMC controls the value of `tx_size`, and MAY choose to adjust it in response
+to the host's proposed `rx_size` value. As such, when `Channel Active` is set by
+the BMC, the host MUST read both `rx_size` and `tx_size` in response to ensure
+both the BMC and the host have a consistent understanding of the MTU in each
+direction. It is convention for `rx_size` and `tx_size` to be set to the same
+value by the BMC as part of finalising the channel, though it is not invalid to
+have asymmetric MTUs.
For all protocol versions, the following properties must be upheld for the Rx
and Tx buffers to be considered valid:
-* Intersect neither eachother nor the control region
-* Not extend beyond the window allocated to MCTP in the LPC FW address space
-* Must accommodate at least BTU-sized payloads
+- Intersect neither eachother nor the control region
+- Not extend beyond the window allocated to MCTP in the LPC FW address space
+- Must accommodate at least BTU-sized payloads
The BMC MAY choose to fail channel initialisation if these properties are
violated in the negotiation process.
@@ -286,25 +286,25 @@
#### KCS Status Register Layout
-| Bit | Managed By | Description |
-|----------|------------|-------------|
-| 7 (MSB) | Software | BMC Active |
-| 6 | Software | Channel active, version negotiated |
-| 5 | Software | Unused |
-| 4 | Software | Unused |
-| 3 | Hardware | Command / Data |
-| 2 | Software | Unused |
-| 1 | Hardware | Input Buffer Full |
-| 0 (LSB) | Hardware | Output Buffer Full |
+| Bit | Managed By | Description |
+| ------- | ---------- | ---------------------------------- |
+| 7 (MSB) | Software | BMC Active |
+| 6 | Software | Channel active, version negotiated |
+| 5 | Software | Unused |
+| 4 | Software | Unused |
+| 3 | Hardware | Command / Data |
+| 2 | Software | Unused |
+| 1 | Hardware | Input Buffer Full |
+| 0 (LSB) | Hardware | Output Buffer Full |
#### KCS Data Register Commands
| Command | Description |
-|---------|-------------|
-| 0x00 | Initialise |
-| 0x01 | Tx Begin |
-| 0x02 | Rx Complete |
-| 0xff | Dummy Value |
+| ------- | ----------- |
+| 0x00 | Initialise |
+| 0x01 | Tx Begin |
+| 0x02 | Rx Complete |
+| 0xff | Dummy Value |
#### Host Command to BMC Sequence
@@ -312,12 +312,12 @@
transmission of a packet, or to complete reception of a packet.
| Step | Description |
-|------|---------------------------------------------------------|
-| 1 | The host writes a command value to IDR |
-| 2 | The hardware sets IBF, which triggers a BMC interrupt |
-| 3 | The BMC reads the status register for IBF |
-| 4 | If IBF is set, the BMC reads the host command from IDR |
-| 5 | The interrupt is acknowledged by the data register read |
+| ---- | ------------------------------------------------------- |
+| 1 | The host writes a command value to IDR |
+| 2 | The hardware sets IBF, which triggers a BMC interrupt |
+| 3 | The BMC reads the status register for IBF |
+| 4 | If IBF is set, the BMC reads the host command from IDR |
+| 5 | The interrupt is acknowledged by the data register read |
#### BMC Command to Host Sequence
@@ -325,12 +325,12 @@
complete reception of a packet.
| Step | Description |
-|------|---------------------------------------------------------|
-| 1 | The BMC writes a command value to ODR |
-| 2 | The hardware sets OBF, which triggers a host interrupt |
-| 3 | The host reads the status register for OBF |
-| 4 | If OBF is set, the host reads the BMC command from ODR |
-| 5 | The interrupt is acknowledged by the data register read |
+| ---- | ------------------------------------------------------- |
+| 1 | The BMC writes a command value to ODR |
+| 2 | The hardware sets OBF, which triggers a host interrupt |
+| 3 | The host reads the status register for OBF |
+| 4 | If OBF is set, the host reads the BMC command from ODR |
+| 5 | The interrupt is acknowledged by the data register read |
#### BMC Status Update Sequence
@@ -338,26 +338,26 @@
channel state, or the presence of a command in the KCS data register.
| Step | Description |
-|------|----------------------------------------------------------------|
-| 1 | The BMC writes the status value to the status register |
-| 2 | The BMC writes the dummy command to ODR |
-| 3 | The hardware sets OBF, which triggers a host interrupt |
-| 4 | If OBF is set, the host reads the BMC command from ODR |
-| 5 | The interrupt is acknowledged by the data register read |
-| 6 | The host observes the command is the dummy command |
-| 7 | The host reads the status register to capture the state change |
+| ---- | -------------------------------------------------------------- |
+| 1 | The BMC writes the status value to the status register |
+| 2 | The BMC writes the dummy command to ODR |
+| 3 | The hardware sets OBF, which triggers a host interrupt |
+| 4 | If OBF is set, the host reads the BMC command from ODR |
+| 5 | The interrupt is acknowledged by the data register read |
+| 6 | The host observes the command is the dummy command |
+| 7 | The host reads the status register to capture the state change |
#### LPC Window Ownership and Synchronisation
-Because the LPC FW window is shared between the host and the BMC we need
-strict rules on which entity is allowed to access it at specific times.
+Because the LPC FW window is shared between the host and the BMC we need strict
+rules on which entity is allowed to access it at specific times.
Firstly, we have rules for modification:
-* The control data is only written during initialisation. The control area
- is never modified once the channel is active.
-* Only the BMC may write to the Rx buffer described in the control area
-* Only the host may write to the Tx buffer described in the control area
+- The control data is only written during initialisation. The control area is
+ never modified once the channel is active.
+- Only the BMC may write to the Rx buffer described in the control area
+- Only the host may write to the Tx buffer described in the control area
During packet transmission, the follow sequence occurs:
@@ -375,76 +375,78 @@
below.
The sequences below contain steps where the BMC updates the channel status and
-where commands are sent between the BMC and the host. The act of updating
-status or sending a command invokes the behaviour outlined in [KCS
-Control](#kcs-control).
+where commands are sent between the BMC and the host. The act of updating status
+or sending a command invokes the behaviour outlined in
+[KCS Control](#kcs-control).
The packet transmission sequences assume that `BMC Active` and `Channel Active`
are set.
#### BMC Initialisation Sequence
-| Step | Description |
-|------|------------------------------------------|
-| 1 | The BMC initialises the control area: magic value, BMC versions and buffer parameters |
-| 2 | The BMC sets the status to `BMC Active` |
+| Step | Description |
+| ---- | ------------------------------------------------------------------------------------- |
+| 1 | The BMC initialises the control area: magic value, BMC versions and buffer parameters |
+| 2 | The BMC sets the status to `BMC Active` |
#### Host Initialisation Sequence
-| 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 |
+| 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 | 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 |
+| 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 | 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 |
+| 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
On the BMC the initial prototype implementation makes use of the following
components:
-* An LPC KCS device exposed by a [binding-specific kernel driver][mctp-driver]
-* The reserved memory mapped by the LPC2AHB bridge via the [aspeed-lpc-ctrl
+- An LPC KCS device exposed by a [binding-specific kernel driver][mctp-driver]
+- The reserved memory mapped by the LPC2AHB bridge via the [aspeed-lpc-ctrl
driver][aspeed-lpc-ctrl]
-* The astlpc binding found in [libmctp][libmctp]
+- The astlpc binding found in [libmctp][libmctp]
-[mctp-driver]: https://github.com/openbmc/linux/commit/9a3b539a175cf4fe1f8fc2997e8a91abec25c37f
-[aspeed-lpc-ctrl]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/soc/aspeed/aspeed-lpc-ctrl.c?h=v5.7
+[mctp-driver]:
+ https://github.com/openbmc/linux/commit/9a3b539a175cf4fe1f8fc2997e8a91abec25c37f
+[aspeed-lpc-ctrl]:
+ https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/soc/aspeed/aspeed-lpc-ctrl.c?h=v5.7
[libmctp]: https://github.com/openbmc/libmctp
From the host side, the LPC Firmware and KCS IO cycles are driven by
@@ -464,24 +466,23 @@
We could use the VUART hardware to transfer the MCTP packets according to the
existing MCTP Serial Binding. However, the VUART device is already used for
console data. Multiplexing both MCTP and console would be an alternative, but
-the complexity introduced would make low-level debugging both more difficult
-and less reliable.
+the complexity introduced would make low-level debugging both more difficult and
+less reliable.
### The BT interface
-The BT interface allows for block-at-time transfers. However, the BT buffer
-size is only 64 bytes on the AST2500 hardware, which does not allow us to
-comply with the MCTP Base Specification (DSP0236) that requires a 64-byte
-payload size as the minimum. The 64-byte BT buffer does not allow for MCTP and
-transport headers.
+The BT interface allows for block-at-time transfers. However, the BT buffer size
+is only 64 bytes on the AST2500 hardware, which does not allow us to comply with
+the MCTP Base Specification (DSP0236) that requires a 64-byte payload size as
+the minimum. The 64-byte BT buffer does not allow for MCTP and transport
+headers.
Additionally, we would like to develop the MCTP channel alongside the existing
IPMI interfaces, to allow a gradual transition from IPMI to MCTP. As the BT
-channel is already used on OpenPOWER systems for IPMI transfers, we would not
-be able to support both in parallel.
+channel is already used on OpenPOWER systems for IPMI transfers, we would not be
+able to support both in parallel.
### Using the AST2500 LPC Mailbox
This would require enabling the SuperIO interface, which allows the host to
-access the entire BMC address space, and so introduces security
-vulnerabilities.
+access the entire BMC address space, and so introduces security vulnerabilities.