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: If25c6524616e9c814ceab023c877d6049cb9f959
Signed-off-by: Patrick Williams <patrick@stwcx.xyz>
diff --git a/Documentation/mboxd.md b/Documentation/mboxd.md
index 193d19d..69a6b39 100644
--- a/Documentation/mboxd.md
+++ b/Documentation/mboxd.md
@@ -1,16 +1,15 @@
Copyright 2017,2018 IBM
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at
- http://www.apache.org/licenses/LICENSE-2.0
+http://www.apache.org/licenses/LICENSE-2.0
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
## Intro
@@ -20,7 +19,7 @@
## Files
The main mailbox daemon is implemented in mboxd.c. This file uses helper
-functions from the various mboxd_*.c files.
+functions from the various mboxd\_\*.c files.
```
dbus.c - Contains the handlers for the D-Bus commands which the daemon can
@@ -81,9 +80,9 @@
## Window Cache
-While the protocol describes that there is only one active window at a time,
-the daemon keeps a cache of previously accessed windows to avoid the need to
-reload them from flash should the host access them again in the future.
+While the protocol describes that there is only one active window at a time, the
+daemon keeps a cache of previously accessed windows to avoid the need to reload
+them from flash should the host access them again in the future.
The reserved memory region is divided among a number of windows which make up
the window cache. When the host requests a flash offset the cache is searched
@@ -92,8 +91,8 @@
offset.
If there is no window in the cache which contains the requested flash offset
-then we have to find one to load with the requested flash contents. If there
-are any windows which are empty then we choose those, otherwise, we choose one to
+then we have to find one to load with the requested flash contents. If there are
+any windows which are empty then we choose those, otherwise, we choose one to
evict using a least recently used (LRU) scheme. The flash is then copied into
this window and the host pointed at its location on the LPC bus.
@@ -119,9 +118,9 @@
```
If any of the required parameters are missing or invalid an error will be
-printed and the daemon will terminate.
-If window-size and window-num aren't specified then the default is to have a
-single window which spans the entire reserved memory region.
+printed and the daemon will terminate. If window-size and window-num aren't
+specified then the default is to have a single window which spans the entire
+reserved memory region.
### Initialisation
@@ -157,8 +156,8 @@
#### Handling Signals
-The daemon blocks SIGINTs, SIGTERMs, and SIGHUPs and instead polls for them on
-a signal file descriptor.
+The daemon blocks SIGINTs, SIGTERMs, and SIGHUPs and instead polls for them on a
+signal file descriptor.
When an event occurs on this file descriptor the signal received is determined
and processed as follows:
@@ -176,6 +175,6 @@
to initialise, received SIGINT or SIGTERM, or because it received the kill D-Bus
command.
-On termination, the daemon clears the window cache and notifies the host that the
-active window has been closed, points the LPC bus mapping back to flash, clears
-the BMC_READY BMC event bit and frees all of its allocated resources.
+On termination, the daemon clears the window cache and notifies the host that
+the active window has been closed, points the LPC bus mapping back to flash,
+clears the BMC_READY BMC event bit and frees all of its allocated resources.
diff --git a/Documentation/protocol.md b/Documentation/protocol.md
index ecca087..14eb195 100644
--- a/Documentation/protocol.md
+++ b/Documentation/protocol.md
@@ -1,16 +1,15 @@
Copyright 2018 IBM
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at
- http://www.apache.org/licenses/LICENSE-2.0
+http://www.apache.org/licenses/LICENSE-2.0
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
# Introduction
@@ -46,8 +45,8 @@
# Background, Design and Constraints
The protocol was developed to meet requirements on OpenPOWER systems based
-around the ASPEED BMC System-on-Chips such as the AST2400 and AST2500.
-The ASPEED BMCs have properties and features that need to be taken into account:
+around the ASPEED BMC System-on-Chips such as the AST2400 and AST2500. The
+ASPEED BMCs have properties and features that need to be taken into account:
1. A read-only mapping of the SPI flash devices onto the ARM core's AHB
2. Remapping of LPC Firmware cycles onto the AHB (LPC2AHB bridge)
@@ -58,19 +57,18 @@
writes were serviced by a separate bridge that suffers significant performance
and security issues.
-Point 3 serves to justify some of the design decisions embodied in the
-protocol, mainly the complexity required by the flexibility to absorb as much
-or as little reserved memory as desired via the concept of BMC-controlled
-windowing.
+Point 3 serves to justify some of the design decisions embodied in the protocol,
+mainly the complexity required by the flexibility to absorb as much or as little
+reserved memory as desired via the concept of BMC-controlled windowing.
-The core concept of the protocol moves access away from the naive routing of
-LPC firmware cycles onto the host firmware SPI flash AHB mapping, and
-concentrates on servicing the LPC firmware cycles from reserved system memory.
-As the memory backing the LPC2AHB mapping is now writable the protocol meets
-the host's write requirements by defining commands to open, dirty and flush an
-in-memory window representing the state of the flash. The mechanism to read the
-flash becomes same as write, just that the dirty and flush commands are not
-legal on such windows.
+The core concept of the protocol moves access away from the naive routing of LPC
+firmware cycles onto the host firmware SPI flash AHB mapping, and concentrates
+on servicing the LPC firmware cycles from reserved system memory. As the memory
+backing the LPC2AHB mapping is now writable the protocol meets the host's write
+requirements by defining commands to open, dirty and flush an in-memory window
+representing the state of the flash. The mechanism to read the flash becomes
+same as write, just that the dirty and flush commands are not legal on such
+windows.
## Historic and Future Naming
@@ -92,48 +90,48 @@
However, as there is now an active software component on the BMC consuming
access requests, the BMC must occasionally indicate state changes to the host.
Such interactions are labelled "events". For example, if a user or other system
-software on the BMC suspends the host's access to its flash device, the
-BMC-side daemon implementing the protocol must notify the host that its
-requests will be denied until further notice.
+software on the BMC suspends the host's access to its flash device, the BMC-side
+daemon implementing the protocol must notify the host that its requests will be
+denied until further notice.
## Protocol Versioning
To enable evolution of the command and event interfaces, incremental changes to
-the behaviour are defined in new versions of the protocol. The descriptions
-and tables that follow all identify the versions to which they are applicable.
+the behaviour are defined in new versions of the protocol. The descriptions and
+tables that follow all identify the versions to which they are applicable.
The highest currently specified protocol version is version 3.
## Table of Commands
-| ID | Name | v1 | v2 | v3 | Description |
-|----|------|----|----|----|-------------|
-| 1 | [`RESET`](#reset-command) | ✓ | ✓ | ✓ | Reset the state of the LPC firmware space, closing any active window |
-| 2 | [`GET_INFO`](#get_info-command) | ✓ | ✓ | ✓ | Perform protocol version negotiation and retrieve fundamental parameters |
-| 3 | [`GET_FLASH_INFO`](#get_flash_info-command) | ✓ | ✓ | ✓ | Retrieve flash-specific parameters |
-| 4 | [`CREATE_READ_WINDOW`](#create_read_window-command) | ✓ | ✓ | ✓ | Request mapping of a flash region for read |
-| 5 | [`CLOSE`](#close-command) | ✓ | ✓ | ✓ | Close the current window, flushing any dirty regions |
-| 6 | [`CREATE_WRITE_WINDOW`](#create_write_window-command) | ✓ | ✓ | ✓ | Request mapping of a flash region for write |
-| 7 | [`MARK_DIRTY`](#mark_dirty-command) | ✓ | ✓ | ✓ | Mark a region of a write window as modified |
-| 8 | [`FLUSH`](#flush-command) | ✓ | ✓ | ✓ | Flush dirty regions of the write window to flash |
-| 9 | [`ACK`](#ack-command) | ✓ | ✓ | ✓ | Acknowledge the receipt of an event from the BMC |
-| 10 | [`ERASE`](#erase-command) | | ✓ | ✓ | Mark a region of a write window as erased |
-| 11 | [`GET_FLASH_NAME`](#get_flash_name-command) | | | ✓ | Retrieve the name of an indexed flash device |
-| 12 | [`LOCK`](#lock-command) | | | ✓ | Mark a region of the current flash window as immutable |
+| ID | Name | v1 | v2 | v3 | Description |
+| --- | ----------------------------------------------------- | --- | --- | --- | ------------------------------------------------------------------------ |
+| 1 | [`RESET`](#reset-command) | ✓ | ✓ | ✓ | Reset the state of the LPC firmware space, closing any active window |
+| 2 | [`GET_INFO`](#get_info-command) | ✓ | ✓ | ✓ | Perform protocol version negotiation and retrieve fundamental parameters |
+| 3 | [`GET_FLASH_INFO`](#get_flash_info-command) | ✓ | ✓ | ✓ | Retrieve flash-specific parameters |
+| 4 | [`CREATE_READ_WINDOW`](#create_read_window-command) | ✓ | ✓ | ✓ | Request mapping of a flash region for read |
+| 5 | [`CLOSE`](#close-command) | ✓ | ✓ | ✓ | Close the current window, flushing any dirty regions |
+| 6 | [`CREATE_WRITE_WINDOW`](#create_write_window-command) | ✓ | ✓ | ✓ | Request mapping of a flash region for write |
+| 7 | [`MARK_DIRTY`](#mark_dirty-command) | ✓ | ✓ | ✓ | Mark a region of a write window as modified |
+| 8 | [`FLUSH`](#flush-command) | ✓ | ✓ | ✓ | Flush dirty regions of the write window to flash |
+| 9 | [`ACK`](#ack-command) | ✓ | ✓ | ✓ | Acknowledge the receipt of an event from the BMC |
+| 10 | [`ERASE`](#erase-command) | | ✓ | ✓ | Mark a region of a write window as erased |
+| 11 | [`GET_FLASH_NAME`](#get_flash_name-command) | | | ✓ | Retrieve the name of an indexed flash device |
+| 12 | [`LOCK`](#lock-command) | | | ✓ | Mark a region of the current flash window as immutable |
## Table of Events
-| ID | Name | v1 | v2 | v3 | Description |
-|----|------|----|----|----|-------------|
-| 0 | [`PROTOCOL_RESET`](#protocol_reset-event) | ✓ | ✓ | ✓ | The host is required to perform version negotiation and re-establish its window of interest |
-| 1 | [`WINDOW_RESET`](#window_reset-event) | | ✓ | ✓ | The host must re-establish its window of interest |
-| 6 | [`FLASH_CONTROL_LOST`](#flash_control_lost-event) | | ✓ | ✓ | The host should suspend access requests |
-| 7 | [`DAEMON_READY`](#daemon_ready-event) | | ✓ | ✓ | The daemon is active and can accept commands |
+| ID | Name | v1 | v2 | v3 | Description |
+| --- | ------------------------------------------------- | --- | --- | --- | ------------------------------------------------------------------------------------------- |
+| 0 | [`PROTOCOL_RESET`](#protocol_reset-event) | ✓ | ✓ | ✓ | The host is required to perform version negotiation and re-establish its window of interest |
+| 1 | [`WINDOW_RESET`](#window_reset-event) | | ✓ | ✓ | The host must re-establish its window of interest |
+| 6 | [`FLASH_CONTROL_LOST`](#flash_control_lost-event) | | ✓ | ✓ | The host should suspend access requests |
+| 7 | [`DAEMON_READY`](#daemon_ready-event) | | ✓ | ✓ | The daemon is active and can accept commands |
## List of Transports
-An essential feature of the protocol is that its behaviour is independent of
-the host-BMC transport. The command and event interfaces of each transport
+An essential feature of the protocol is that its behaviour is independent of the
+host-BMC transport. The command and event interfaces of each transport
necessarily reflect the version of the protocol they are implementing, but the
transport has no influence otherwise.
@@ -149,8 +147,8 @@
transport - where only 11 bytes are available for encoding of command
parameters.
-Implementations must choose to support one or more of the transports outlined
-in this document.
+Implementations must choose to support one or more of the transports outlined in
+this document.
Note that the DBus transport is intended for BMC-internal communications, and
can be used to separate a host-interface transport from the protocol
@@ -164,8 +162,8 @@
follow.
Once `GET_INFO` has successfully completed, the host should request the flash
-parameters with `GET_FLASH_INFO`. The response provides information on the
-flash capacity and the size of its erase granule.
+parameters with `GET_FLASH_INFO`. The response provides information on the flash
+capacity and the size of its erase granule.
Following `GET_FLASH_INFO`, the next act is to establish an active flash window
with either one of the `CREATE_READ_WINDOW` or `CREATE_WRITE_WINDOW` commands.
@@ -173,8 +171,8 @@
In the event of creating a write window the host must inform the BMC of the
regions to which it has written with `MARK_DIRTY`- the BMC receives no
notification of accesses from the host, they are simply mapped by the LPC2AHB
-bridge as necessary. As the accesses are to system memory and not the flash
-the changes identified by the `MARK_DIRTY` commands are not permanent until a
+bridge as necessary. As the accesses are to system memory and not the flash the
+changes identified by the `MARK_DIRTY` commands are not permanent until a
`FLUSH` command is received (implicit flushes are discussed below), at which
point the dirty regions of the active window will be written to the flash
device.
@@ -185,14 +183,14 @@
## Version Negotiation
-When invoking `GET_INFO` the host must provide the BMC its highest
-supported version of the protocol. The BMC must respond with a protocol version
-less than or equal to that requested by the host, or in the event that there is
-no such value, an error code. In the event that an error is returned the host
-must not continue to communicate with the BMC. Otherwise, the protocol version
-returned by the BMC is the agreed protocol version for all further
-communication. The host may at a future point request a change in protocol
-version by issuing a subsequent `GET_INFO` command.
+When invoking `GET_INFO` the host must provide the BMC its highest supported
+version of the protocol. The BMC must respond with a protocol version less than
+or equal to that requested by the host, or in the event that there is no such
+value, an error code. In the event that an error is returned the host must not
+continue to communicate with the BMC. Otherwise, the protocol version returned
+by the BMC is the agreed protocol version for all further communication. The
+host may at a future point request a change in protocol version by issuing a
+subsequent `GET_INFO` command.
### Unversioned Commands
@@ -207,16 +205,15 @@
to the negotiated version of the protocol.
The arguments to the `GET_INFO` command are considered unversioned and as a
-result are static in nature - the protocol implementation has no means to
-decode version-specific arguments as the version has not yet been
-negotiated. With respect to the response, the version field is unversioned, but
-all subsequent fields _may_ be versioned.
+result are static in nature - the protocol implementation has no means to decode
+version-specific arguments as the version has not yet been negotiated. With
+respect to the response, the version field is unversioned, but all subsequent
+fields _may_ be versioned.
`RESET` remaining unversioned is an optimisation catering to deeply embedded
-components on the host side that may need access to the command. Keeping
-`RESET` unversioned removes the complexity of implementing `GET_INFO` with its
-version negotiation and minimises the overhead required to get into the
-pre-boot state.
+components on the host side that may need access to the command. Keeping `RESET`
+unversioned removes the complexity of implementing `GET_INFO` with its version
+negotiation and minimises the overhead required to get into the pre-boot state.
Defining `ACK` as unversioned ensures host firmware that has minimal protocol
support can silence interrupts from the BMC as required.
@@ -250,14 +247,14 @@
read from a write window and the BMC must guarantee that the window reflects
what the host has written there.
-A window can be closed by issuing the `CLOSE` command, in which case there is
-no active window and the host must not access the LPC firmware space until a
-window is subsequently opened. If the host closes an active write window then
-the BMC must perform an implicit flush. If the host tries to open a new window
-with an already active window then the active window is closed (and implicitly
-flushed if it was a write window). If the new window is successfully opened
-then it is the new active window; if the command fails then there is no active
-window and the previously active window must no longer be accessed.
+A window can be closed by issuing the `CLOSE` command, in which case there is no
+active window and the host must not access the LPC firmware space until a window
+is subsequently opened. If the host closes an active write window then the BMC
+must perform an implicit flush. If the host tries to open a new window with an
+already active window then the active window is closed (and implicitly flushed
+if it was a write window). If the new window is successfully opened then it is
+the new active window; if the command fails then there is no active window and
+the previously active window must no longer be accessed.
The host must not access an LPC address other than that which is contained by
the active window. The host must not use write management functions (see below)
@@ -265,13 +262,13 @@
## Command Parameter Types
-It is common in the protocol definition for command parameters to be
-represented in terms of a block size. This block size may refer to e.g. the
-size of the erase granule of the flash, or it may be another value entirely.
-Regardless of what it represents, the argument values are scaled by the block
-size determined by version negotiation. Specifying arguments in terms of a
-block size allows transports to keep a compact representation in constrained
-implementations such as the LPC mailbox transport.
+It is common in the protocol definition for command parameters to be represented
+in terms of a block size. This block size may refer to e.g. the size of the
+erase granule of the flash, or it may be another value entirely. Regardless of
+what it represents, the argument values are scaled by the block size determined
+by version negotiation. Specifying arguments in terms of a block size allows
+transports to keep a compact representation in constrained implementations such
+as the LPC mailbox transport.
Note that for simplicity block size must always be a power-of-2. The block size
must also be greater than or equal to 4K regardless of the negotiated protocol
@@ -292,22 +289,22 @@
## Mailbox Transport
-* Multi-byte quantity endianness: Little-endian
-* Command length encoding: Assumed from negotiated protocol version
-* Parameter alignment: Packed (no padding)
-* Command status response: ABI-defined Response byte
-* Event Delivery: ABI-defined BMC Status byte
+- Multi-byte quantity endianness: Little-endian
+- Command length encoding: Assumed from negotiated protocol version
+- Parameter alignment: Packed (no padding)
+- Command status response: ABI-defined Response byte
+- Event Delivery: ABI-defined BMC Status byte
-The mailbox transport defines the ABI used over the mailbox registers. There
-are 16 data registers and several status and control registers for managing
+The mailbox transport defines the ABI used over the mailbox registers. There are
+16 data registers and several status and control registers for managing
interrupts between the host and the BMC. For the purpose of defining the
transport ABI the status and control registers can mostly be disregarded, save
for the necessity of issuing and responding to interrupts on each side.
Assuming the registers are in a contiguous layout (this is not reflected in the
-hardware, but may be the abstraction presented by the associated kernel
-driver), the ABI is defined as follows, where the bytes in the range [2, 12]
-are available for command parameters and are defined on a per-command basis.
+hardware, but may be the abstraction presented by the associated kernel driver),
+the ABI is defined as follows, where the bytes in the range [2, 12] are
+available for command parameters and are defined on a per-command basis.
```
0 7 15 31
@@ -327,25 +324,25 @@
### Status Codes
-| ID | Name | v1 | v2 | v3 | Description |
-|----|----------------|----|----|----|------------------------------------------------------|
-| 1 | `SUCCESS` | ✓ | ✓ | ✓ | Command completed successfully |
-| 2 | `PARAM_ERROR` | ✓ | ✓ | ✓ | Error with parameters supplied or command invalid |
-| 3 | `WRITE_ERROR` | ✓ | ✓ | ✓ | Error writing to the backing file system |
-| 4 | `SYSTEM_ERROR` | ✓ | ✓ | ✓ | Error in BMC performing system action |
-| 5 | `TIMEOUT` | ✓ | ✓ | ✓ | Timeout in performing action |
-| 6 | `BUSY` | | ✓ | ✓ | Flash access suspended, retry later |
-| 7 | `WINDOW_ERROR` | | ✓ | ✓ | Invalid window state or command invalid for window |
-| 8 | `SEQ_ERROR` | | ✓ | ✓ | Invalid sequence number supplied with command |
-| 9 | `LOCKED_ERROR` | | | ✓ | Erased or dirtied region intersected a locked region |
+| ID | Name | v1 | v2 | v3 | Description |
+| --- | -------------- | --- | --- | --- | ---------------------------------------------------- |
+| 1 | `SUCCESS` | ✓ | ✓ | ✓ | Command completed successfully |
+| 2 | `PARAM_ERROR` | ✓ | ✓ | ✓ | Error with parameters supplied or command invalid |
+| 3 | `WRITE_ERROR` | ✓ | ✓ | ✓ | Error writing to the backing file system |
+| 4 | `SYSTEM_ERROR` | ✓ | ✓ | ✓ | Error in BMC performing system action |
+| 5 | `TIMEOUT` | ✓ | ✓ | ✓ | Timeout in performing action |
+| 6 | `BUSY` | | ✓ | ✓ | Flash access suspended, retry later |
+| 7 | `WINDOW_ERROR` | | ✓ | ✓ | Invalid window state or command invalid for window |
+| 8 | `SEQ_ERROR` | | ✓ | ✓ | Invalid sequence number supplied with command |
+| 9 | `LOCKED_ERROR` | | | ✓ | Erased or dirtied region intersected a locked region |
## IPMI Transport
-* Multi-byte quantity endianness: Little-endian
-* Command length encoding: Assumed from negotiated protocol version
-* Parameter alignment: Packed (no padding)
-* Command status response: Mapped to IPMI completion codes
-* Event Delivery: Status byte in SEL via `SMS_ATN`
+- Multi-byte quantity endianness: Little-endian
+- Command length encoding: Assumed from negotiated protocol version
+- Parameter alignment: Packed (no padding)
+- Command status response: Mapped to IPMI completion codes
+- Event Delivery: Status byte in SEL via `SMS_ATN`
The IPMI transport must reserve one `(NetFn, Command)` pair for host-to-BMC
communications and one SEL `(NetFn, Command)` pair for BMC-to-host
@@ -366,18 +363,17 @@
## DBus Transport
-* Multi-byte quantity endianness: Transport encoded
-* Command length encoding: Transport encoded
-* Parameter alignment: Transport encoded
-* Command status response: Mapped to Unix system error codes
-* Event Delivery: DBus signals and properties per event type
+- Multi-byte quantity endianness: Transport encoded
+- Command length encoding: Transport encoded
+- Parameter alignment: Transport encoded
+- Command status response: Mapped to Unix system error codes
+- Event Delivery: DBus signals and properties per event type
-DBus defines its own wire-format for messages, and so support for this
-transport concentrates on mapping commands and events onto DBus concepts.
-Specifically, commands are represented by DBus methods and events are
-represented by properties. DBus will automatically generate a
-`PropertiesChanged` signal for changes to properties allowing consumers to
-learn of updates as they happen.
+DBus defines its own wire-format for messages, and so support for this transport
+concentrates on mapping commands and events onto DBus concepts. Specifically,
+commands are represented by DBus methods and events are represented by
+properties. DBus will automatically generate a `PropertiesChanged` signal for
+changes to properties allowing consumers to learn of updates as they happen.
As the commands are represented by DBus methods there is no need to encode the
command index in the request - this is represented by the appropriate method on
@@ -398,20 +394,20 @@
The command identifier values and command-response parameter formats are
described in tables under headers for each command. The order of the parameters
-in the parameter tables reflects the order of the parameters in the commands
-and responses. The M, I, and D columns represent the Mailbox, IPMI and DBus
+in the parameter tables reflects the order of the parameters in the commands and
+responses. The M, I, and D columns represent the Mailbox, IPMI and DBus
transports respectively. For the command identifier table the value in these
columns' cells represent the command index, or for DBus, its method name. For
the parameter tables the value represent the parameter's offset in the message
(disregarding the command and sequence bytes), or in the case of DBus the
-appropriate [type
-signature](https://dbus.freedesktop.org/doc/dbus-specification.html#basic-types).
+appropriate
+[type signature](https://dbus.freedesktop.org/doc/dbus-specification.html#basic-types).
## `RESET` Command
-| v1 | v2 | v3 | M | I | D |
-|----|----|----|---|---|-------|
-| ✓ | ✓ | ✓ | 1 | 1 | Reset |
+| v1 | v2 | v3 | M | I | D |
+| --- | --- | --- | --- | --- | ----- |
+| ✓ | ✓ | ✓ | 1 | 1 | Reset |
### v1 Parameters
@@ -422,20 +418,19 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
</table>
-
### v2 Parameters
<table>
@@ -445,14 +440,14 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
@@ -467,14 +462,14 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
@@ -487,9 +482,9 @@
## `GET_INFO` Command
-| v1 | v2 | v3 | M | I | D |
-|----|----|----|---|---|---------|
-| ✓ | ✓ | ✓ | 2 | 2 | GetInfo |
+| v1 | v2 | v3 | M | I | D |
+| --- | --- | --- | --- | --- | ------- |
+| ✓ | ✓ | ✓ | 2 | 2 | GetInfo |
### v1 Parameters
@@ -500,24 +495,23 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Version | Version | 1 | 0 | 0 | y |
+| Parameter | Unit | Size | M | I | D |
+| --------- | ------- | ---- | --- | --- | --- |
+| Version | Version | 1 | 0 | 0 | y |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Version | Version | 1 | 0 | 0 | y |
-| Read Window Size | Blocks | 2 | 1 | 1 | q |
-| Write Window Size | Blocks | 2 | 3 | 3 | q |
+| Parameter | Unit | Size | M | I | D |
+| ----------------- | ------- | ---- | --- | --- | --- |
+| Version | Version | 1 | 0 | 0 | y |
+| Read Window Size | Blocks | 2 | 1 | 1 | q |
+| Write Window Size | Blocks | 2 | 3 | 3 | q |
</td>
</tr>
</table>
-
### v2 Parameters
<table>
@@ -527,18 +521,18 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Version | Version | 1 | 0 | 0 | y |
+| Parameter | Unit | Size | M | I | D |
+| --------- | ------- | ---- | --- | --- | --- |
+| Version | Version | 1 | 0 | 0 | y |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Version | Version | 1 | 0 | 0 | y |
-| Block Size Shift | Count | 1 | 5 | 1 | y |
-| Timeout | Seconds | 2 | 6 | 2 | q |
+| Parameter | Unit | Size | M | I | D |
+| ---------------- | ------- | ---- | --- | --- | --- |
+| Version | Version | 1 | 0 | 0 | y |
+| Block Size Shift | Count | 1 | 5 | 1 | y |
+| Timeout | Seconds | 2 | 6 | 2 | q |
</td>
</tr>
@@ -553,20 +547,20 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Version | Version | 1 | 0 | 0 | y |
-| Block Size Shift | Count | 1 | 1 | 1 | y |
+| Parameter | Unit | Size | M | I | D |
+| ---------------- | ------- | ---- | --- | --- | --- |
+| Version | Version | 1 | 0 | 0 | y |
+| Block Size Shift | Count | 1 | 1 | 1 | y |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Version | Version | 1 | 0 | 0 | y |
-| Block Size Shift | Count | 1 | 5 | 1 | y |
-| Timeout | Seconds | 2 | 6 | 2 | q |
-| Devices | Count | 1 | 8 | 4 | y |
+| Parameter | Unit | Size | M | I | D |
+| ---------------- | ------- | ---- | --- | --- | --- |
+| Version | Version | 1 | 0 | 0 | y |
+| Block Size Shift | Count | 1 | 5 | 1 | y |
+| Timeout | Seconds | 2 | 6 | 2 | q |
+| Devices | Count | 1 | 8 | 4 | y |
</td>
</tr>
@@ -575,23 +569,22 @@
### Description
The suggested timeout is a hint to the host as to how long it should wait after
-issuing a command to the BMC before it times out waiting for a response. This
-is the maximum time which the BMC thinks it could take to service any command
-which the host could issue. This may be set to zero to indicate that the BMC
-does not wish to provide a hint in which case the host must choose some
-reasonable value.
+issuing a command to the BMC before it times out waiting for a response. This is
+the maximum time which the BMC thinks it could take to service any command which
+the host could issue. This may be set to zero to indicate that the BMC does not
+wish to provide a hint in which case the host must choose some reasonable value.
From v3 the host may desire a specific block size and thus can request this by
-giving a hint to the daemon (may be zero). The daemon may use this to select
-the block size which it will use however is free to ignore it. The value in the
+giving a hint to the daemon (may be zero). The daemon may use this to select the
+block size which it will use however is free to ignore it. The value in the
response is the block size which must be used for all further requests until a
new size is negotiated by another call to `GET_INFO`.
## `GET_FLASH_INFO` Command
-| v1 | v2 | v3 | M | I | D |
-|----|----|----|---|---|--------------|
-| ✓ | ✓ | ✓ | 3 | 3 | GetFlashInfo |
+| v1 | v2 | v3 | M | I | D |
+| --- | --- | --- | --- | --- | ------------ |
+| ✓ | ✓ | ✓ | 3 | 3 | GetFlashInfo |
### v1 Parameters
@@ -602,22 +595,21 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Flash Size | Bytes | 4 | 0 | 0 | u |
-| Erase Granule | Bytes | 4 | 4 | 4 | u |
+| Parameter | Unit | Size | M | I | D |
+| ------------- | ----- | ---- | --- | --- | --- |
+| Flash Size | Bytes | 4 | 0 | 0 | u |
+| Erase Granule | Bytes | 4 | 4 | 4 | u |
</td>
</tr>
</table>
-
### v2 Parameters
<table>
@@ -627,16 +619,16 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Flash Size | Blocks | 2 | 0 | 0 | q |
-| Erase Granule | Blocks | 2 | 2 | 2 | q |
+| Parameter | Unit | Size | M | I | D |
+| ------------- | ------ | ---- | --- | --- | --- |
+| Flash Size | Blocks | 2 | 0 | 0 | q |
+| Erase Granule | Blocks | 2 | 2 | 2 | q |
</td>
</tr>
@@ -651,17 +643,17 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Device ID | Index | 1 | 0 | 0 | y |
+| Parameter | Unit | Size | M | I | D |
+| --------- | ----- | ---- | --- | --- | --- |
+| Device ID | Index | 1 | 0 | 0 | y |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Flash Size | Blocks | 2 | 0 | 0 | q |
-| Erase Granule | Blocks | 2 | 2 | 2 | q |
+| Parameter | Unit | Size | M | I | D |
+| ------------- | ------ | ---- | --- | --- | --- |
+| Flash Size | Blocks | 2 | 0 | 0 | q |
+| Erase Granule | Blocks | 2 | 2 | 2 | q |
</td>
</tr>
@@ -669,9 +661,9 @@
## `CREATE_READ_WINDOW` Command
-| v1 | v2 | v3 | M | I | D |
-|----|----|----|---|---|------------------|
-| ✓ | ✓ | ✓ | 4 | 4 | CreateReadWindow |
+| v1 | v2 | v3 | M | I | D |
+| --- | --- | --- | --- | --- | ---------------- |
+| ✓ | ✓ | ✓ | 4 | 4 | CreateReadWindow |
### v1 Parameters
@@ -682,22 +674,21 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Flash Offset | Blocks | 2 | 0 | 0 | q |
+| Parameter | Unit | Size | M | I | D |
+| ------------ | ------ | ---- | --- | --- | --- |
+| Flash Offset | Blocks | 2 | 0 | 0 | q |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| LPC FW Offset | Blocks | 2 | 0 | 0 | q |
+| Parameter | Unit | Size | M | I | D |
+| ------------- | ------ | ---- | --- | --- | --- |
+| LPC FW Offset | Blocks | 2 | 0 | 0 | q |
</td>
</tr>
</table>
-
### v2 Parameters
<table>
@@ -707,19 +698,19 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Flash Address | Blocks | 2 | 0 | 0 | q |
-| Length | Blocks | 2 | 2 | 2 | q |
+| Parameter | Unit | Size | M | I | D |
+| ------------- | ------ | ---- | --- | --- | --- |
+| Flash Address | Blocks | 2 | 0 | 0 | q |
+| Length | Blocks | 2 | 2 | 2 | q |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| LPC FW Address | Blocks | 2 | 0 | 0 | q |
-| Length | Blocks | 2 | 2 | 2 | q |
-| Flash Address | blocks | 2 | 4 | 4 | q |
+| Parameter | Unit | Size | M | I | D |
+| -------------- | ------ | ---- | --- | --- | --- |
+| LPC FW Address | Blocks | 2 | 0 | 0 | q |
+| Length | Blocks | 2 | 2 | 2 | q |
+| Flash Address | blocks | 2 | 4 | 4 | q |
</td>
</tr>
@@ -734,20 +725,20 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Flash Address | Blocks | 2 | 0 | 0 | q |
-| Length | Blocks | 2 | 2 | 2 | q |
-| Device ID | Index | 1 | 4 | 4 | y |
+| Parameter | Unit | Size | M | I | D |
+| ------------- | ------ | ---- | --- | --- | --- |
+| Flash Address | Blocks | 2 | 0 | 0 | q |
+| Length | Blocks | 2 | 2 | 2 | q |
+| Device ID | Index | 1 | 4 | 4 | y |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| LPC FW Address | Blocks | 2 | 0 | 0 | q |
-| Length | Blocks | 2 | 2 | 2 | q |
-| Flash Address | blocks | 2 | 4 | 4 | q |
+| Parameter | Unit | Size | M | I | D |
+| -------------- | ------ | ---- | --- | --- | --- |
+| LPC FW Address | Blocks | 2 | 0 | 0 | q |
+| Length | Blocks | 2 | 2 | 2 | q |
+| Flash Address | blocks | 2 | 4 | 4 | q |
</td>
</tr>
@@ -761,15 +752,15 @@
LPC bus address is always given from the start of the LPC address space - that
is it is an absolute address.
-The requested access size is only a hint. The response indicates the actual
-size of the window. The BMC may want to use the requested size to pre-load the
+The requested access size is only a hint. The response indicates the actual size
+of the window. The BMC may want to use the requested size to pre-load the
remainder of the request. The host must not access past the end of the active
window.
The flash offset mapped by the window is an absolute flash offset and must be
less than or equal to the flash offset requested by the host. It is the
-responsibility of the host to use this information to access any offset which
-is required.
+responsibility of the host to use this information to access any offset which is
+required.
The requested window size may be zero. In this case the BMC is free to create
any sized window but it must contain at least the first block of data requested
@@ -781,9 +772,9 @@
## `CLOSE` Command
-| v1 | v2 | v3 | M | I | D |
-|----|----|----|---|---|-------|
-| ✓ | ✓ | ✓ | 5 | 5 | Close |
+| v1 | v2 | v3 | M | I | D |
+| --- | --- | --- | --- | --- | ----- |
+| ✓ | ✓ | ✓ | 5 | 5 | Close |
### v1 Parameters
@@ -794,20 +785,19 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
</table>
-
### v2 Parameters
<table>
@@ -817,15 +807,15 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Flags | Field | 1 | 0 | 0 | y |
+| Parameter | Unit | Size | M | I | D |
+| --------- | ----- | ---- | --- | --- | --- |
+| Flags | Field | 1 | 0 | 0 | y |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
@@ -840,15 +830,15 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Flags | Field | 1 | 0 | 0 | y |
+| Parameter | Unit | Size | M | I | D |
+| --------- | ----- | ---- | --- | --- | --- |
+| Flags | Field | 1 | 0 | 0 | y |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
@@ -856,9 +846,9 @@
### Description
-Closes the active window. Any further access to the LPC bus address specified
-to address the previously active window will have undefined effects. If the
-active window is a write window then the BMC must perform an implicit flush.
+Closes the active window. Any further access to the LPC bus address specified to
+address the previously active window will have undefined effects. If the active
+window is a write window then the BMC must perform an implicit flush.
The Flags argument allows the host to provide some hints to the BMC. Defined
values are:
@@ -873,9 +863,9 @@
## `CREATE_WRITE_WINDOW` Command
-| v1 | v2 | v3 | M | I | D |
-|----|----|----|---|---|-------------------|
-| ✓ | ✓ | ✓ | 6 | 6 | CreateWriteWindow |
+| v1 | v2 | v3 | M | I | D |
+| --- | --- | --- | --- | --- | ----------------- |
+| ✓ | ✓ | ✓ | 6 | 6 | CreateWriteWindow |
### v1 Parameters
@@ -886,22 +876,21 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Flash Offset | Blocks | 2 | 0 | 0 | q |
+| Parameter | Unit | Size | M | I | D |
+| ------------ | ------ | ---- | --- | --- | --- |
+| Flash Offset | Blocks | 2 | 0 | 0 | q |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| LPC FW Offset | Blocks | 2 | 0 | 0 | q |
+| Parameter | Unit | Size | M | I | D |
+| ------------- | ------ | ---- | --- | --- | --- |
+| LPC FW Offset | Blocks | 2 | 0 | 0 | q |
</td>
</tr>
</table>
-
### v2 Parameters
<table>
@@ -911,19 +900,19 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Flash Address | Blocks | 2 | 0 | 0 | q |
-| Length | Blocks | 2 | 2 | 2 | q |
+| Parameter | Unit | Size | M | I | D |
+| ------------- | ------ | ---- | --- | --- | --- |
+| Flash Address | Blocks | 2 | 0 | 0 | q |
+| Length | Blocks | 2 | 2 | 2 | q |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| LPC FW Address | Blocks | 2 | 0 | 0 | q |
-| Length | Blocks | 2 | 2 | 2 | q |
-| Flash Address | blocks | 2 | 4 | 4 | q |
+| Parameter | Unit | Size | M | I | D |
+| -------------- | ------ | ---- | --- | --- | --- |
+| LPC FW Address | Blocks | 2 | 0 | 0 | q |
+| Length | Blocks | 2 | 2 | 2 | q |
+| Flash Address | blocks | 2 | 4 | 4 | q |
</td>
</tr>
@@ -938,20 +927,20 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Flash Address | Blocks | 2 | 0 | 0 | q |
-| Length | Blocks | 2 | 2 | 2 | q |
-| Device ID | Index | 1 | 4 | 4 | y |
+| Parameter | Unit | Size | M | I | D |
+| ------------- | ------ | ---- | --- | --- | --- |
+| Flash Address | Blocks | 2 | 0 | 0 | q |
+| Length | Blocks | 2 | 2 | 2 | q |
+| Device ID | Index | 1 | 4 | 4 | y |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| LPC FW Address | Blocks | 2 | 0 | 0 | q |
-| Length | Blocks | 2 | 2 | 2 | q |
-| Flash Address | blocks | 2 | 4 | 4 | q |
+| Parameter | Unit | Size | M | I | D |
+| -------------- | ------ | ---- | --- | --- | --- |
+| LPC FW Address | Blocks | 2 | 0 | 0 | q |
+| Length | Blocks | 2 | 2 | 2 | q |
+| Flash Address | blocks | 2 | 4 | 4 | q |
</td>
</tr>
@@ -965,15 +954,15 @@
LPC bus address is always given from the start of the LPC address space - that
is it is an absolute address.
-The requested access size is only a hint. The response indicates the actual
-size of the window. The BMC may want to use the requested size to pre-load the
+The requested access size is only a hint. The response indicates the actual size
+of the window. The BMC may want to use the requested size to pre-load the
remainder of the request. The host must not access past the end of the active
window.
The flash offset mapped by the window is an absolute flash offset and must be
less than or equal to the flash offset requested by the host. It is the
-responsibility of the host to use this information to access any offset which
-is required.
+responsibility of the host to use this information to access any offset which is
+required.
The requested window size may be zero. In this case the BMC is free to create
any sized window but it must contain at least the first block of data requested
@@ -985,9 +974,9 @@
## `MARK_DIRTY` Command
-| v1 | v2 | v3 | M | I | D |
-|----|----|----|---|---|-----------|
-| ✓ | ✓ | ✓ | 7 | 7 | MarkDirty |
+| v1 | v2 | v3 | M | I | D |
+| --- | --- | --- | --- | --- | --------- |
+| ✓ | ✓ | ✓ | 7 | 7 | MarkDirty |
### v1 Parameters
@@ -998,22 +987,21 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Flash Offset | Blocks | 2 | 0 | 0 | q |
-| Length | Bytes | 4 | 2 | 2 | u |
+| Parameter | Unit | Size | M | I | D |
+| ------------ | ------ | ---- | --- | --- | --- |
+| Flash Offset | Blocks | 2 | 0 | 0 | q |
+| Length | Bytes | 4 | 2 | 2 | u |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
</table>
-
### v2 Parameters
<table>
@@ -1023,16 +1011,16 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Window Offset | Blocks | 2 | 0 | 0 | q |
-| Length | Blocks | 2 | 2 | 2 | q |
+| Parameter | Unit | Size | M | I | D |
+| ------------- | ------ | ---- | --- | --- | --- |
+| Window Offset | Blocks | 2 | 0 | 0 | q |
+| Length | Blocks | 2 | 2 | 2 | q |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
@@ -1047,17 +1035,17 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Window Offset | Blocks | 2 | 0 | 0 | q |
-| Length | Blocks | 2 | 2 | 2 | q |
-| Flags | Field | 1 | 4 | 4 | y |
+| Parameter | Unit | Size | M | I | D |
+| ------------- | ------ | ---- | --- | --- | --- |
+| Window Offset | Blocks | 2 | 0 | 0 | q |
+| Length | Blocks | 2 | 2 | 2 | q |
+| Flags | Field | 1 | 4 | 4 | y |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
@@ -1065,29 +1053,25 @@
### Description
+The BMC has no method for intercepting writes that occur over the LPC bus. The
+host must explicitly notify the daemon of where and when a write has occurred so
+it can be flushed to backing storage.
-The BMC has no method for intercepting writes that
-occur over the LPC bus. The host must explicitly notify
-the daemon of where and when a write has occurred so it
-can be flushed to backing storage.
-
-Offsets are given as an absolute (either into flash (V1) or the
-active window (V2)) and a zero offset refers to the first
-block. If the offset + number exceeds the size of the active
-window then the command must not succeed.
+Offsets are given as an absolute (either into flash (V1) or the active window
+(V2)) and a zero offset refers to the first block. If the offset + number
+exceeds the size of the active window then the command must not succeed.
The host can give a hint to the daemon that is doesn't have to erase a flash
-area before writing to it by setting bit zero of the Flags parameter. This
-means that the daemon will blindly perform a write to that area and will not
-try to erase it before hand. This can be used if the host knows that a large
-area has already been erased for example but then wants to perform many small
-writes.
+area before writing to it by setting bit zero of the Flags parameter. This means
+that the daemon will blindly perform a write to that area and will not try to
+erase it before hand. This can be used if the host knows that a large area has
+already been erased for example but then wants to perform many small writes.
## `FLUSH` Command
-| v1 | v2 | v3 | M | I | D |
-|----|----|----|---|---|-------|
-| ✓ | ✓ | ✓ | 8 | 8 | Flush |
+| v1 | v2 | v3 | M | I | D |
+| --- | --- | --- | --- | --- | ----- |
+| ✓ | ✓ | ✓ | 8 | 8 | Flush |
### v1 Parameters
@@ -1098,22 +1082,21 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Flash Offset | Blocks | 2 | 0 | 0 | q |
-| Length | Bytes | 4 | 2 | 2 | u |
+| Parameter | Unit | Size | M | I | D |
+| ------------ | ------ | ---- | --- | --- | --- |
+| Flash Offset | Blocks | 2 | 0 | 0 | q |
+| Length | Bytes | 4 | 2 | 2 | u |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
</table>
-
### v2 Parameters
<table>
@@ -1123,14 +1106,14 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
@@ -1145,14 +1128,14 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
@@ -1163,15 +1146,15 @@
Flushes any dirty/erased blocks in the active window to the backing storage.
In V1 this can also be used to mark parts of the flash dirty and flush in a
-single command. In V2 the explicit mark dirty command must be used before a
-call to flush since there are no longer any arguments. If the offset + length
-exceeds the size of the active window then the command must not succeed.
+single command. In V2 the explicit mark dirty command must be used before a call
+to flush since there are no longer any arguments. If the offset + length exceeds
+the size of the active window then the command must not succeed.
## `ACK` Command
-| v1 | v2 | v3 | M | I | D |
-|----|----|----|---|---|-----|
-| ✓ | ✓ | ✓ | 9 | 9 | Ack |
+| v1 | v2 | v3 | M | I | D |
+| --- | --- | --- | --- | --- | --- |
+| ✓ | ✓ | ✓ | 9 | 9 | Ack |
### v1 Parameters
@@ -1182,21 +1165,20 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Ack Mask | Field | 1 | 0 | 0 | y |
+| Parameter | Unit | Size | M | I | D |
+| --------- | ----- | ---- | --- | --- | --- |
+| Ack Mask | Field | 1 | 0 | 0 | y |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
</table>
-
### v2 Parameters
<table>
@@ -1206,15 +1188,15 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Ack Mask | Field | 1 | 0 | 0 | y |
+| Parameter | Unit | Size | M | I | D |
+| --------- | ----- | ---- | --- | --- | --- |
+| Ack Mask | Field | 1 | 0 | 0 | y |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
@@ -1229,15 +1211,15 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Ack Mask | Field | 1 | 0 | 0 | y |
+| Parameter | Unit | Size | M | I | D |
+| --------- | ----- | ---- | --- | --- | --- |
+| Ack Mask | Field | 1 | 0 | 0 | y |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
@@ -1250,9 +1232,9 @@
## `ERASE` Command
-| v1 | v2 | v3 | M | I | D |
-|----|----|----|----|----|-------|
-| | ✓ | ✓ | 10 | 10 | Erase |
+| v1 | v2 | v3 | M | I | D |
+| --- | --- | --- | --- | --- | ----- |
+| | ✓ | ✓ | 10 | 10 | Erase |
### v2 Parameters
@@ -1263,16 +1245,16 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Window Offset | Blocks | 2 | 0 | 0 | q |
-| Length | Blocks | 2 | 2 | 2 | q |
+| Parameter | Unit | Size | M | I | D |
+| ------------- | ------ | ---- | --- | --- | --- |
+| Window Offset | Blocks | 2 | 0 | 0 | q |
+| Length | Blocks | 2 | 2 | 2 | q |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
@@ -1287,16 +1269,16 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Window Offset | Blocks | 2 | 0 | 0 | q |
-| Length | Blocks | 2 | 2 | 2 | q |
+| Parameter | Unit | Size | M | I | D |
+| ------------- | ------ | ---- | --- | --- | --- |
+| Window Offset | Blocks | 2 | 0 | 0 | q |
+| Length | Blocks | 2 | 2 | 2 | q |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
@@ -1307,17 +1289,16 @@
This command allows the host to erase a large area without the need to
individually write 0xFF repetitively.
-Offset is the offset within the active window to start erasing from (zero
-refers to the first block of the active window) and number is the number of
-blocks of the active window to erase starting at offset. If the offset + number
-exceeds the size of the active window then the command must not succeed.
+Offset is the offset within the active window to start erasing from (zero refers
+to the first block of the active window) and number is the number of blocks of
+the active window to erase starting at offset. If the offset + number exceeds
+the size of the active window then the command must not succeed.
## `GET_FLASH_NAME` Command
-| v1 | v2 | v3 | M | I | D |
-|----|----|----|----|----|--------------|
-| | | ✓ | 11 | 11 | GetFlashName |
-
+| v1 | v2 | v3 | M | I | D |
+| --- | --- | --- | --- | --- | ------------ |
+| | | ✓ | 11 | 11 | GetFlashName |
### v3 Parameters
@@ -1328,17 +1309,17 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Device ID | Index | 1 | 0 | 0 | y |
+| Parameter | Unit | Size | M | I | D |
+| --------- | ----- | ---- | --- | --- | --- |
+| Device ID | Index | 1 | 0 | 0 | y |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Name length | Bytes | 1 | 0 | 0 | - |
-| Name | String | 10 | 1 | 1 | s |
+| Parameter | Unit | Size | M | I | D |
+| ----------- | ------ | ---- | --- | --- | --- |
+| Name length | Bytes | 1 | 0 | 0 | - |
+| Name | String | 10 | 1 | 1 | s |
</td>
</tr>
@@ -1356,9 +1337,9 @@
## `LOCK` Command
-| v1 | v2 | v3 | M | I | D |
-|----|----|----|----|----|------|
-| | | ✓ | 12 | 12 | Lock |
+| v1 | v2 | v3 | M | I | D |
+| --- | --- | --- | --- | --- | ---- |
+| | | ✓ | 12 | 12 | Lock |
### v3 Parameters
@@ -1369,17 +1350,17 @@
<tr>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
-| Flash Offset | Blocks | 2 | 0 | 0 | q |
-| Length | Blocks | 2 | 2 | 2 | q |
-| Device ID | Index | 1 | 4 | 4 | y |
+| Parameter | Unit | Size | M | I | D |
+| ------------ | ------ | ---- | --- | --- | --- |
+| Flash Offset | Blocks | 2 | 0 | 0 | q |
+| Length | Blocks | 2 | 2 | 2 | q |
+| Device ID | Index | 1 | 4 | 4 | y |
</td>
<td valign="top">
-| Parameter | Unit | Size | M | I | D |
-|-------------------|---------|------|---|---|---|
+| Parameter | Unit | Size | M | I | D |
+| --------- | ---- | ---- | --- | --- | --- |
</td>
</tr>
@@ -1399,14 +1380,14 @@
relevant property.
For the DBus interface, properties are used for all event types regardless of
-whether they should be acknowledged or not as part of the protocol. This
-ensures that state changes can be published atomically.
+whether they should be acknowledged or not as part of the protocol. This ensures
+that state changes can be published atomically.
## `PROTOCOL_RESET` Event
-| v1 | v2 | v3 | M | I | D |
-|----|----|----|---|---|---------------|
-| ✓ | ✓ | ✓ | 0 | 0 | ProtocolReset |
+| v1 | v2 | v3 | M | I | D |
+| --- | --- | --- | --- | --- | ------------- |
+| ✓ | ✓ | ✓ | 0 | 0 | ProtocolReset |
### Description
@@ -1417,22 +1398,22 @@
## `WINDOW_RESET` Event
-| v1 | v2 | v3 | M | I | D |
-|----|----|----|---|---|-------------|
-| | ✓ | ✓ | 1 | 1 | WindowReset |
+| v1 | v2 | v3 | M | I | D |
+| --- | --- | --- | --- | --- | ----------- |
+| | ✓ | ✓ | 1 | 1 | WindowReset |
### Description
The host must assume that its active window has been closed and that it no
longer has an active window. The host is not required to perform protocol
-version negotiation again. The host must assume that any in-flight commands
-have failed.
+version negotiation again. The host must assume that any in-flight commands have
+failed.
## `FLASH_CONTROL_LOST` Event
-| v1 | v2 | v3 | M | I | D |
-|----|----|----|---|---|------------------|
-| | ✓ | ✓ | 6 | 6 | FlashControlLost |
+| v1 | v2 | v3 | M | I | D |
+| --- | --- | --- | --- | --- | ---------------- |
+| | ✓ | ✓ | 6 | 6 | FlashControlLost |
### Description
@@ -1448,18 +1429,18 @@
## `DAEMON_READY` Event
-| v1 | v2 | v3 | M | I | D |
-|----|----|----|---|---|-------------|
-| | ✓ | ✓ | 7 | 7 | DaemonReady |
+| v1 | v2 | v3 | M | I | D |
+| --- | --- | --- | --- | --- | ----------- |
+| | ✓ | ✓ | 7 | 7 | DaemonReady |
### Description
-Used to inform the host that the BMC daemon is ready to accept command
-requests. The host isn't able to clear this bit through an acknowledge command,
-the BMC daemon must clear it before it terminates (assuming it didn't terminate
+Used to inform the host that the BMC daemon is ready to accept command requests.
+The host isn't able to clear this bit through an acknowledge command, the BMC
+daemon must clear it before it terminates (assuming it didn't terminate
unexpectedly).
The host should not expect a response while this bit is not set.
-Note that this bit being set is not a guarantee that the BMC daemon will
-respond as it or the BMC may have crashed without clearing it.
+Note that this bit being set is not a guarantee that the BMC daemon will respond
+as it or the BMC may have crashed without clearing it.
diff --git a/README.md b/README.md
index 7e00cb8..88888ea 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,22 @@
-HIOMAP: The Host I/O Mapping Protocol for Power-based Systems
-=============================================================
+# HIOMAP: The Host I/O Mapping Protocol for Power-based Systems
-This repository contains [the specification for the Power systems Host I/O
-mapping protocol (HIOMAP)](Documentation/protocol.md) along with a reference
-implementation of the daemon and associated utilities.
+This repository contains
+[the specification for the Power systems Host I/O mapping protocol (HIOMAP)](Documentation/protocol.md)
+along with a reference implementation of the daemon and associated utilities.
For historical reasons, source and generated binaries may refer to 'mbox' or
'the mailbox interface' in contexts that aren't completely sensible. It's
unfortunate, but it's our current reality.
-Building
-========
+# Building
-The build system is a standard autotools setup. `bootstrap.sh` runs all the
-jobs necessary to initialise autotools.
+The build system is a standard autotools setup. `bootstrap.sh` runs all the jobs
+necessary to initialise autotools.
-By default the build is configured and built _with_ the 'virtual PNOR'
-feature discussed below. The virtual PNOR functionality is written in C++, and
-due to some autotools clunkiness even if it is disabled mboxd will still be
-linked with `CXX`.
+By default the build is configured and built _with_ the 'virtual PNOR' feature
+discussed below. The virtual PNOR functionality is written in C++, and due to
+some autotools clunkiness even if it is disabled mboxd will still be linked with
+`CXX`.
If you are hacking on the reference implementation it's recommended to run
`bootstrap.sh` with the `dev` argument:
@@ -42,8 +40,8 @@
$ make check
```
-Through the virtual PNOR feature the daemon's role as a flash abstraction can
-be augmented to support partition/filesystem abstraction. This is complex and
+Through the virtual PNOR feature the daemon's role as a flash abstraction can be
+augmented to support partition/filesystem abstraction. This is complex and
unnecessary for a number of platforms, and so the feature can be disabled at
`configure` time. If you do not have a C++ compiler for your target, set
`CXX=cc`.
@@ -55,28 +53,25 @@
$ make check
```
-Coding Style Guide
-==================
+# Coding Style Guide
-Preamble
---------
+## Preamble
-For not particularly good reasons the codebase is a mix of C and C++. This is
-an ugly split: message logging and error handling can be vastly different
-inside the same codebase. The aim is to remove the split one way or the other
-over time and have consistent approaches to solving problems.
+For not particularly good reasons the codebase is a mix of C and C++. This is an
+ugly split: message logging and error handling can be vastly different inside
+the same codebase. The aim is to remove the split one way or the other over time
+and have consistent approaches to solving problems.
However, the current reality is the codebase is developed as part of OpenBMC's
support for Power platforms, which leads to integration of frameworks such as
-[phosphor-logging](https://github.com/openbmc/phosphor-logging). It's noted
-that with phosphor-logging we can achieve absurd duplication or irritating
-splits in where errors are reported, as the C code is not capable of making use
-of the interfaces provided.
+[phosphor-logging](https://github.com/openbmc/phosphor-logging). It's noted that
+with phosphor-logging we can achieve absurd duplication or irritating splits in
+where errors are reported, as the C code is not capable of making use of the
+interfaces provided.
So:
-Rules
------
+## Rules
1. Message logging MUST be done to stdout or stderr, and MUST NOT be done
directly via journal APIs or wrappers of the journal APIs.
@@ -93,8 +88,8 @@
journal. To this end, systemd will by default capture stdout and stderr of
the launched binary and redirect it to the journal.
- In the second case it is *desirable* that messages be captured by the test
- runner (`make check`) for test failure analysis, and it is *undesirable* for
+ In the second case it is _desirable_ that messages be captured by the test
+ runner (`make check`) for test failure analysis, and it is _undesirable_ for
messages to appear in the system journal (as these are tests, not issues
affecting the health of the system they are being executed on).
@@ -104,19 +99,17 @@
Note: This section specifically targets the use of phosphor-logging's
`log<T>()`. It does not prevent the use of `elog<T>()`.
-License and Copyright
-=====================
+# License and Copyright
Copyright 2017 IBM
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at
- http://www.apache.org/licenses/LICENSE-2.0
+http://www.apache.org/licenses/LICENSE-2.0
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
diff --git a/vpnor/README.md b/vpnor/README.md
index 12e1911..2fac3cf 100644
--- a/vpnor/README.md
+++ b/vpnor/README.md
@@ -1,5 +1,4 @@
-Virtual PNOR Functionality
-==========================
+# Virtual PNOR Functionality
In the abstract, the virtual PNOR function shifts mboxd away from accessing raw
flash to dynamically presenting a raw flash image to the host from a set of
@@ -9,33 +8,30 @@
protocol), and the BMC's access to the flash (via some filesystem on top of the
flash device).
-Do I want to use this feature in my platform?
----------------------------------------------
+## Do I want to use this feature in my platform?
Maybe. It depends on how the image construction is managed, particularly the
behaviour around writes from the host. It is likely the scheme will prevent
firmware updates from being correctly applied when using flash tools on the
host.
-Use-case Requirements
----------------------
+## Use-case Requirements
Currently, the virtual PNOR implementation requires that:
-* The host expect an FFS layout (OpenPOWER systems)
-* The BMC provide a directory tree presenting the backing files in a hierarchy
+- The host expect an FFS layout (OpenPOWER systems)
+- The BMC provide a directory tree presenting the backing files in a hierarchy
that reflects the partition properties in the FFS table of contents.
-Implementation Behavioural Properties
--------------------------------------
+## Implementation Behavioural Properties
1. The FFS ToC defines the set of valid access ranges in terms of partitions
2. The read-only property of partitions is enforced
3. The ToC is considered read-only
4. Read access to valid ranges must be granted
5. Write access to valid ranges may be granted
-6. Access ranges that are valid may map into a backing file associated with
- the partition
+6. Access ranges that are valid may map into a backing file associated with the
+ partition
7. A read of a valid access range that maps into the backing file will render
the data held in the backing file at the appropriate offset
8. A read of a valid access range that does not map into the backing file will
@@ -43,14 +39,14 @@
9. A read of an invalid access range will appear erased
10. A write to a valid access range that maps into the backing file will update
the data in the file at the appropriate offset
-11. A write to a valid access range that does not map into the backing file
- will expand the backing file to accommodate the write.
+11. A write to a valid access range that does not map into the backing file will
+ expand the backing file to accommodate the write.
12. A write to a valid access range may fail if the range is not marked as
writeable. The error should be returned in response to the request to open
the write window intersecting the read-only range.
-13. A write of an invalid access range will return an error. The error should
- be returned in response to the request to open the write window covering
- the invalid range.
+13. A write of an invalid access range will return an error. The error should be
+ returned in response to the request to open the write window covering the
+ invalid range.
The clarification on when the failure occurs in points 11 and 12 is useful for
host-side error handling. Opening a write window gives the indication that