hiomapd/Documentation/protocol.md

7 http://www.apache.org/licenses/LICENSE-2.0
17 mediation between the host and the Baseboard Management Controller (BMC).
20 BMC to the host. Usually, the flash device of interest is the host's firmware
21 flash device - in some platform designs this is owned by the BMC to enable
22 lights-out updates of the host firmware.
24 As the flash is owned by the BMC, access by the host to its firmware must be
28 2. Conflict of access between the host and the BMC to the flash controller
33 flash data in the LPC firmware space, communicated via functions in the LPC IO
40 written to the flash by the host firmware.
42 The definition of transport-specific parameters, for example selection of IPMI
48 around the ASPEED BMC System-on-Chips such as the AST2400 and AST2500. The
51 1. A read-only mapping of the SPI flash devices onto the ARM core's AHB
52 2. Remapping of LPC Firmware cycles onto the AHB (LPC2AHB bridge)
56 serviced by pointing the LPC2AHB bridge at the read-only flash mapping, and
62 reserved memory as desired via the concept of BMC-controlled windowing.
64 The core concept of the protocol moves access away from the naive routing of LPC
65 firmware cycles onto the host firmware SPI flash AHB mapping, and concentrates
66 on servicing the LPC firmware cycles from reserved system memory. As the memory
67 backing the LPC2AHB mapping is now writable the protocol meets the host's write
68 requirements by defining commands to open, dirty and flush an in-memory window
75 The original transport for the protocol was the ASPEED BMC LPC mailbox
81 The protocol has been tentatively renamed to the "Host I/O Mapping Protocol" or
82 "hiomap". This is a reflection of its true purpose - to control the host's view
87 The primary flow of the protocol is for the host to send requests to the BMC,
88 which adjusts the mapping of the LPC firmware space as requested and returns a
89 status response to the host. These interactions are labelled "commands".
91 access requests, the BMC must occasionally indicate state changes to the host.
93 software on the BMC suspends the host's access to its flash device, the BMC-side
94 daemon implementing the protocol must notify the host that its requests will be
108 …--- | ----------------------------------------------------- | --- | --- | --- | ------------------…
109 | 1   | [`RESET`](#reset-command)                             | ✓   | ✓   | ✓   | Reset the state o…
110 | 2   | [`GET_INFO`](#get_info-command)                       | ✓   | ✓   | ✓   | Perform protocol …
111 | 3   | [`GET_FLASH_INFO`](#get_flash_info-command)           | ✓   | ✓   | ✓   | Retrieve flash-sp…
112 | 4   | [`CREATE_READ_WINDOW`](#create_read_window-command)   | ✓   | ✓   | ✓   | Request mapping o…
113 | 5   | [`CLOSE`](#close-command)                             | ✓   | ✓   | ✓   | Close the current…
114 | 6   | [`CREATE_WRITE_WINDOW`](#create_write_window-command) | ✓   | ✓   | ✓   | Request mapping o…
115 | 7   | [`MARK_DIRTY`](#mark_dirty-command)                   | ✓   | ✓   | ✓   | Mark a region of …
116 | 8   | [`FLUSH`](#flush-command)                             | ✓   | ✓   | ✓   | Flush dirty regio…
117 | 9   | [`ACK`](#ack-command)                                 | ✓   | ✓   | ✓   | Acknowledge the r…
118 | 10  | [`ERASE`](#erase-command)                             |     | ✓   | ✓   | Mark a region of …
119 | 11  | [`GET_FLASH_NAME`](#get_flash_name-command)           |     |     | ✓   | Retrieve the name…
120 | 12  | [`LOCK`](#lock-command)                               |     |     | ✓   | Mark a region of …
125 …--- | ------------------------------------------------- | --- | --- | --- | ----------------------…
126 …TOCOL_RESET`](#protocol_reset-event)         | ✓   | ✓   | ✓   | The host is required to perform v…
127 | 1   | [`WINDOW_RESET`](#window_reset-event)             |     | ✓   | ✓   | The host must re-esta…
128 | 6   | [`FLASH_CONTROL_LOST`](#flash_control_lost-event) |     | ✓   | ✓   | The host should suspe…
129 | 7   | [`DAEMON_READY`](#daemon_ready-event)             |     | ✓   | ✓   | The daemon is active …
134 host-BMC transport. The command and event interfaces of each transport
140 1. The [ASPEED BMC LPC Mailbox transport](#mailbox-transport)
141 2. The [IPMI transport](#ipmi-transport)
142 3. The [DBus transport](#dbus-transport)
146 design is limited by the most constrained transport - the LPC mailbox
147 transport - where only 11 bytes are available for encoding of command
153 Note that the DBus transport is intended for BMC-internal communications, and
154 can be used to separate a host-interface transport from the protocol
159 The high-level protocol flow is that the host first issues a `GET_INFO` command
164 Once `GET_INFO` has successfully completed, the host should request the flash
171 In the event of creating a write window the host must inform the BMC of the
172 regions to which it has written with `MARK_DIRTY`- the BMC receives no
173 notification of accesses from the host, they are simply mapped by the LPC2AHB
180 As an optimisation the host may choose to use the `ERASE` command to indicate
182 the associated LPC firmware cycles to write the regions into the erased state.
186 When invoking `GET_INFO` the host must provide the BMC its highest supported
188 or equal to that requested by the host, or in the event that there is no such
189 value, an error code. In the event that an error is returned the host must not
192 host may at a future point request a change in protocol version by issuing a
208 result are static in nature - the protocol implementation has no means to decode
209 version-specific arguments as the version has not yet been negotiated. With
214 components on the host side that may need access to the command. Keeping `RESET`
216 negotiation and minimises the overhead required to get into the pre-boot state.
218 Defining `ACK` as unversioned ensures host firmware that has minimal protocol
227 For generality, the host must generate a sequence number that is unique with
229 in-progress commands. Sequence numbers meeting this requirement are considered
231 issued by the host as found in the relevant command.
237 the host receives a sequence-related error response it must consider any
238 in-progress commands to have failed. The host may retry the affected command(s)
246 irrespective of type. The host must not write to a read window. The host may
248 what the host has written there.
251 active window and the host must not access the LPC firmware space until a window
252 is subsequently opened. If the host closes an active write window then the BMC
253 must perform an implicit flush. If the host tries to open a new window with an
259 The host must not access an LPC address other than that which is contained by
260 the active window. The host must not use write management functions (see below)
271 as the LPC mailbox transport.
273 Note that for simplicity block size must always be a power-of-2. The block size
278 dividing or multiplying the quantity by the negotiated block-size.
283 features of transport support are the wire-format, delivery mechanisms of
292 - Multi-byte quantity endianness: Little-endian
293 - Command length encoding: Assumed from negotiated protocol version
294 - Parameter alignment: Packed (no padding)
295 - Command status response: ABI-defined Response byte
296 - Event Delivery: ABI-defined BMC Status byte
300 interrupts between the host and the BMC. For the purpose of defining the
307 available for command parameters and are defined on a per-command basis.
311    +----------+----------+---------------------+
313    +----------+----------+---------------------+
315    +-------------------------------------------+
317    +----------+----------+----------+----------+
318 12 |          | Response |  BMC Sts | Host Sts |
319    +----------+----------+----------+----------+
328 | --- | -------------- | --- | --- | --- | ---------------------------------------------------- |
341 - Multi-byte quantity endianness: Little-endian
342 - Command length encoding: Assumed from negotiated protocol version
343 - Parameter alignment: Packed (no padding)
344 - Command status response: Mapped to IPMI completion codes
345 - Event Delivery: Status byte in SEL via `SMS_ATN`
347 The IPMI transport must reserve one `(NetFn, Command)` pair for host-to-BMC
348 communications and one SEL `(NetFn, Command)` pair for BMC-to-host
359    +----------+----------+---------     -------+
361    +----------+----------+---------     -------+
366 - Multi-byte quantity endianness: Transport encoded
367 - Command length encoding: Transport encoded
368 - Parameter alignment: Transport encoded
369 - Command status response: Mapped to Unix system error codes
370 - Event Delivery: DBus signals and properties per event type
372 DBus defines its own wire-format for messages, and so support for this transport
379 command index in the request - this is represented by the appropriate method on
395 The command identifier values and command-response parameter formats are
404 [type signature](https://dbus.freedesktop.org/doc/dbus-specification.html#basic-types).
409 | --- | --- | --- | --- | --- | ----- |
422 | --------- | ---- | ---- | --- | --- | --- |
428 | --------- | ---- | ---- | --- | --- | --- |
444 | --------- | ---- | ---- | --- | --- | --- |
450 | --------- | ---- | ---- | --- | --- | --- |
466 | --------- | ---- | ---- | --- | --- | --- |
472 | --------- | ---- | ---- | --- | --- | --- |
480 Requests the BMC return the LPC firmware space to a state ready for host
486 | --- | --- | --- | --- | --- | ------- |
499 | --------- | ------- | ---- | --- | --- | --- |
506 | ----------------- | ------- | ---- | --- | --- | --- |
525 | --------- | ------- | ---- | --- | --- | --- |
532 | ---------------- | ------- | ---- | --- | --- | --- |
551 | ---------------- | ------- | ---- | --- | --- | --- |
559 | ---------------- | ------- | ---- | --- | --- | --- |
571 The suggested timeout is a hint to the host as to how long it should wait after
574 the host could issue. This may be set to zero to indicate that the BMC does not
575 wish to provide a hint in which case the host must choose some reasonable value.
577 From v3 the host may desire a specific block size and thus can request this by
586 | --- | --- | --- | --- | --- | ------------ |
599 | --------- | ---- | ---- | --- | --- | --- |
605 | ------------- | ----- | ---- | --- | --- | --- |
623 | --------- | ---- | ---- | --- | --- | --- |
629 | ------------- | ------ | ---- | --- | --- | --- |
647 | --------- | ----- | ---- | --- | --- | --- |
654 | ------------- | ------ | ---- | --- | --- | --- |
665 | --- | --- | --- | --- | --- | ---------------- |
678 | ------------ | ------ | ---- | --- | --- | --- |
685 | ------------- | ------ | ---- | --- | --- | --- |
686 | LPC FW Offset | Blocks | 2    | 0   | 0   | q   |
702 | ------------- | ------ | ---- | --- | --- | --- |
710 | -------------- | ------ | ---- | --- | --- | --- |
711 | LPC FW Address | Blocks | 2    | 0   | 0   | q   |
729 | ------------- | ------ | ---- | --- | --- | --- |
738 | -------------- | ------ | ---- | --- | --- | --- |
739 | LPC FW Address | Blocks | 2    | 0   | 0   | q   |
749 The flash offset which the host requests access to is always taken from the
750 start of flash - that is it is an absolute offset into flash.
752 LPC bus address is always given from the start of the LPC address space - that
756 of the window. The BMC may want to use the requested size to pre-load the
757 remainder of the request. The host must not access past the end of the active
761 less than or equal to the flash offset requested by the host. It is the
762 responsibility of the host to use this information to access any offset which is
767 by the host. A large window is of course preferred and should correspond to the
776 | --- | --- | --- | --- | --- | ----- |
789 | --------- | ---- | ---- | --- | --- | --- |
795 | --------- | ---- | ---- | --- | --- | --- |
811 | --------- | ----- | ---- | --- | --- | --- |
818 | --------- | ---- | ---- | --- | --- | --- |
834 | --------- | ----- | ---- | --- | --- | --- |
841 | --------- | ---- | ---- | --- | --- | --- |
849 Closes the active window. Any further access to the LPC bus address specified to
853 The Flags argument allows the host to provide some hints to the BMC. Defined
857 0x01 - Short Lifetime:
867 | --- | --- | --- | --- | --- | ----------------- |
880 | ------------ | ------ | ---- | --- | --- | --- |
887 | ------------- | ------ | ---- | --- | --- | --- |
888 | LPC FW Offset | Blocks | 2    | 0   | 0   | q   |
904 | ------------- | ------ | ---- | --- | --- | --- |
912 | -------------- | ------ | ---- | --- | --- | --- |
913 | LPC FW Address | Blocks | 2    | 0   | 0   | q   |
931 | ------------- | ------ | ---- | --- | --- | --- |
940 | -------------- | ------ | ---- | --- | --- | --- |
941 | LPC FW Address | Blocks | 2    | 0   | 0   | q   |
951 The flash offset which the host requests access to is always taken from the
952 start of flash - that is it is an absolute offset into flash.
954 LPC bus address is always given from the start of the LPC address space - that
958 of the window. The BMC may want to use the requested size to pre-load the
959 remainder of the request. The host must not access past the end of the active
963 less than or equal to the flash offset requested by the host. It is the
964 responsibility of the host to use this information to access any offset which is
969 by the host. A large window is of course preferred and should correspond to the
978 | --- | --- | --- | --- | --- | --------- |
991 | ------------ | ------ | ---- | --- | --- | --- |
999 | --------- | ---- | ---- | --- | --- | --- |
1015 | ------------- | ------ | ---- | --- | --- | --- |
1023 | --------- | ---- | ---- | --- | --- | --- |
1039 | ------------- | ------ | ---- | --- | --- | --- |
1048 | --------- | ---- | ---- | --- | --- | --- |
1056 The BMC has no method for intercepting writes that occur over the LPC bus. The
1057 host must explicitly notify the daemon of where and when a write has occurred so
1064 The host can give a hint to the daemon that is doesn't have to erase a flash
1067 erase it before hand. This can be used if the host knows that a large area has
1073 | --- | --- | --- | --- | --- | ----- |
1086 | ------------ | ------ | ---- | --- | --- | --- |
1094 | --------- | ---- | ---- | --- | --- | --- |
1110 | --------- | ---- | ---- | --- | --- | --- |
1116 | --------- | ---- | ---- | --- | --- | --- |
1132 | --------- | ---- | ---- | --- | --- | --- |
1138 | --------- | ---- | ---- | --- | --- | --- |
1156 | --- | --- | --- | --- | --- | --- |
1169 | --------- | ----- | ---- | --- | --- | --- |
1176 | --------- | ---- | ---- | --- | --- | --- |
1192 | --------- | ----- | ---- | --- | --- | --- |
1199 | --------- | ---- | ---- | --- | --- | --- |
1215 | --------- | ----- | ---- | --- | --- | --- |
1222 | --------- | ---- | ---- | --- | --- | --- |
1230 The host should use this command to acknowledge BMC events propagated to the
1231 host.
1236 | --- | --- | --- | --- | --- | ----- |
1249 | ------------- | ------ | ---- | --- | --- | --- |
1257 | --------- | ---- | ---- | --- | --- | --- |
1273 | ------------- | ------ | ---- | --- | --- | --- |
1281 | --------- | ---- | ---- | --- | --- | --- |
1289 This command allows the host to erase a large area without the need to
1300 | --- | --- | --- | --- | --- | ------------ |
1313 | --------- | ----- | ---- | --- | --- | --- |
1320 | ----------- | ------ | ---- | --- | --- | --- |
1321 | Name length | Bytes  | 1    | 0   | 0   | -   |
1330 Describes a flash with some kind of identifier useful to the host system.
1333 flash name field which the host should expect to have been populated.
1341 | --- | --- | --- | --- | --- | ---- |
1354 | ------------ | ------ | ---- | --- | --- | --- |
1363 | --------- | ---- | ---- | --- | --- | --- |
1371 Lock an area of flash so that the host can't mark it dirty or erased. If the
1389 | --- | --- | --- | --- | --- | ------------- |
1394 Used to inform the host that a protocol reset has occurred, likely due to
1395 restarting the daemon. The host must perform protocol version negotiation again
1396 and must assume it has no active window. The host must also assume that any
1397 in-flight commands have failed.
1402 | --- | --- | --- | --- | --- | ----------- |
1407 The host must assume that its active window has been closed and that it no
1408 longer has an active window. The host is not required to perform protocol
1409 version negotiation again. The host must assume that any in-flight commands have
1415 | --- | --- | --- | --- | --- | ---------------- |
1425 (the host isn't able to clear it through an acknowledge command).
1427 The host must not assume that the contents of the active window correctly
1433 | --- | --- | --- | --- | --- | ----------- |
1438 Used to inform the host that the BMC daemon is ready to accept command requests.
1439 The host isn't able to clear this bit through an acknowledge command, the BMC
1443 The host should not expect a response while this bit is not set.