diff options
| -rw-r--r-- | Documentation/mbox_protocol.md | 653 | ||||
| -rw-r--r-- | Documentation/mboxctl.md | 110 | ||||
| -rw-r--r-- | Documentation/mboxd.md | 181 | ||||
| -rw-r--r-- | README.md | 646 |
4 files changed, 953 insertions, 637 deletions
diff --git a/Documentation/mbox_protocol.md b/Documentation/mbox_protocol.md new file mode 100644 index 0000000..5a0879e --- /dev/null +++ b/Documentation/mbox_protocol.md @@ -0,0 +1,653 @@ +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 + + 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. + +## Intro + +This document describes a protocol for host to BMC communication via the +mailbox registers present on the Aspeed 2400 and 2500 chips. +This protocol is specifically designed to allow a host to request and manage +access to the flash with the specifics of how the host is required to control +this described below. + +## Version + +Both version 1 and version 2 of the protocol are described below with version 2 +specificities represented with V2 in brackets - (V2). + +## Problem Overview + +"mbox" is the name we use to represent a protocol we have established between +the host and the BMC via the Aspeed mailbox registers. This protocol is used +for the host to control the flash. + +Prior to the mbox protocol, the host uses a backdoor into the BMC address space +(the iLPC-to-AHB bridge) to directly manipulate the BMCs own flash controller. + +This is not sustainable for a number of reasons. The main ones are: + +1. Every piece of the host software stack that needs flash access (HostBoot, + OCC, OPAL, ...) has to have a complete driver for the flash controller, + update it on each BMC generation, have all the quirks for all the flash + chips supported etc... We have 3 copies on the host already in addition to + the one in the BMC itself. + +2. There are serious issues of access conflicts to that controller between the + host and the BMC. + +3. It's very hard to support "BMC reboots" when doing that + +4. It's slow + +5. Last but probably most important, having that backdoor open is a security + risk. It means the host can access any address on the BMC internal bus and + implant malware in the BMC itself. So if the host is a "bare metal" shared + system in some kind of data center, not only the host flash needs to be + reflashed when switching from one customer to another, but the entire BMC + flash too as nothing can be trusted. So we want to disable it. + +To address all these, we have implemented a new mechanism that we call mbox. + +When using this mechanism, the BMC is solely responsible for directly accessing +the flash controller. All flash erase and write operations are performed by the +BMC and the BMC only. (We can allow direct reads from flash under some +circumstances but we tend to prefer going via memory). + +The host uses the mailbox registers to send "commands" to the BMC, which +responds via the same mechanism. Those commands allow the host to control a +"window" (which is the LPC -> AHB FW space mapping) that is either a read +window or a write window onto the flash. + +When set for writing, the BMC makes the window point to a chunk of RAM instead. +When the host "commits" a change (via MBOX), then the BMC can perform the +actual flashing from the data in the RAM window. + +The idea is to have the LPC FW space be routed to an active "window". That +window can be a read or a write window. The commands allow to control which +window and which offset into the flash it maps. + +* A read window can be a direct window to the flash controller space (ie. + 0x3000\_0000) or it can be a window to a RAM image of a flash. It doesn't have + to be the full size of the flash per protocol (commands can be use to "slide" + it to various parts of the flash) but if its set to map the actual flash + controller space at 0x3000\_0000, it's probably simpler to make it the full + flash. The host makes no assumption, it's your choice what to provide. The + simplest implementation is to just route to the flash read/only. + +* A write window has to be a chunk of BMC memory. The minimum size is not + defined in the spec, but it should be at least one block (4k for now but it + should support larger block sizes in the future). When the BMC receive the + command to map the write window at a given offset of the flash, the BMC should + copy that portion of the flash into a reserved memory buffer, and modify the + LPC mapping to point to that buffer. + +The host can then write to that window directly (updating the BMC memory) and +send a command to "commit" those updates to flash. + +Finally there is a `RESET_STATE`. It's the state in which the bootloader in the +SEEPROM of the POWER9 chip will find what it needs to load HostBoot. The +details are still being ironed out: either mapping the full flash read only or +reset to a "window" that is either at the bottom or top of the flash. The +current implementation resets to point to the full flash. + +## Where is the code? + +The mbox userspace is available [on GitHub](https://github.com/openbmc/mboxbridge) +This is Apache licensed but we are keen to see any enhancements you may have. + +The kernel driver is still in the process of being upstreamed but can be found +in the OpenBMC Linux kernel staging tree: + +https://github.com/openbmc/linux/commit/85770a7d1caa6a1fa1a291c33dfe46e05755a2ef + +## Building + +The autotools of this requires the autoconf-archive package for your +system + +## The Hardware + +The Aspeed mailbox consists of 16 (8 bit) data registers see Layout for their +use. Mailbox interrupt enabling, masking and triggering is done using a pair +of control registers, one accessible by the host the other by the BMC. +Interrupts can also be raised per write to each data register, for BMC and +host. Write tiggered interrupts are configured using two 8 bit registers where +each bit represents a data register and if an interrupt should fire on write. +Two 8 bit registers are present to act as a mask for write triggered +interrupts. + +### Layout + +``` +Byte 0: COMMAND +Byte 1: Sequence +Byte 2-12: Arguments +Byte 13: Response code +Byte 14: Host controlled status reg +Byte 15: BMC controlled status reg +``` + +## Low Level Protocol Flow + +What we essentially have is a set of registers which either the host or BMC can +write to in order to communicate to the other which will respond in some way. +There are 3 basic types of communication. + +1. Commands sent from the Host to the BMC +2. Responses sent from the BMC to the Host in response to commands +3. Asyncronous events raised by the BMC + +### General Use + +Messages usually originate from the host to the BMC. There are special +cases for a back channel for the BMC to pass new information to the +host which will be discussed later. + +To initiate a request the host must set a command code (see +Commands) into mailbox data register 0. It is also the hosts +responsibility to generate a unique sequence number into mailbox +register 1. After this any command specific data should be written +(see Layout). The host must then generate an interrupt to the BMC by +using bit 0 of its control register and wait for an interrupt on the +response register. Generating an interrupt automatically sets bit 7 of the +corresponding control register. This bit can be used to poll for +messages. + +On receiving an interrupt (or polling on bit 7 of its Control +Register) the BMC should read the message from the general registers +of the mailbox and perform the necessary action before responding. On +responding the BMC must ensure that the sequence number is the same as +the one in the request from the host. The BMC must also ensure that +mailbox data regsiter 13 is a valid response code (see Responses). The +BMC should then use its control register to generate an interrupt for +the host to notify it of a response. + +### Asynchronous BMC to Host Events + +BMC to host communication is also possible for notification of events +from the BMC. This requires that the host have interrupts enabled on +mailbox data register 15 (or otherwise poll on bit 7 of mailbox status +register 1). On receiving such a notification the host should read +mailbox data register 15 to determine the event code which was set by the +BMC (see BMC Event notifications in Commands for detail). Events which are +defined as being able to be acknowledged by the host must be with a +BMC_EVENT_ACK command. + +## High Level Protocol Flow + +When a host wants to communicate with the BMC via the mbox protocol the first +thing it should do it call MBOX_GET_INFO in order to establish the protocol +version which each understands. Before this the only other commands which are +allowed are RESET_STATE and BMC_EVENT_ACK. + +After this the host can open and close windows with the CREATE_READ_WINDOW, +CREATE_WRITE_WINDOW and CLOSE_WINDOW commands. Creating a window is how the +host requests access to a section of flash. It is worth noting that the host +can only ever have one window that it is accessing at a time - hence forth +referred to as the active window. + +When the active window is a write window the host can perform MARK_WRITE_DIRTY, +MARK_WRITE_ERASED and WRITE_FLUSH commands to identify changed blocks and +control when the changed blocks are written to flash. + +Independently, and at any point not during an existing mbox command +transaction, the BMC may raise raise asynchronous events with the host to +communicate a change in state. + +### Version Negotiation + +Given that a majority of command and response arguments are specified as a +multiple of block size it is necessary for the host and BMC to agree on a +protocol version as this determines the block size. In V1 it is hard coded at +4K and in V2 the BMC chooses and specifies this to the host as a response +argument to MBOX_GET_INFO. Thus the host must always call MBOX_GET_INFO before +any other command which specifies an argument in block size. + +The host must tell the BMC the highest protocol level which it supports. The +BMC will then respond with a protocol level. If the host doesn't understand +the protocol level specified by the BMC then it must not continue to +communicate with the BMC. Otherwise the protocol level specified by the +BMC is taken to be the protocol level used for further communication and can +only be changed by another call to MBOX_GET_INFO. The BMC should use the +request from the host to influence its protocol version choice. + +### Window Management + +In order to access flash contents the host must request a window be opened at +the flash offset it would like to access. The host may give a hint as to how +much data it would like to access or otherwise set this argument to zero. The +BMC must respond with the lpc bus address to access this window and the +window size. The host must not access past the end of the active window. + +There is only ever one active window which is the window created by the most +recent CREATE_READ_WINDOW or CREATE_WRITE_WINDOW call which succeeded. Even +though there are two types of windows there can still only be one active window +irrespective of type. A host must not write to a read window. A host may 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 calling CLOSE_WINDOW in which case there is no active +window and the host must not access the LPC window after it has been closed. +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 +previous 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) +if the active window is a read window or if there is no active window. + +### Write Management + +The BMC has no method for intercepting writes that occur over the LPC bus. Thus +the host must explicitly notify the BMC of where and when a write has +occured. The host must use the MARK_WRITE_DIRTY command to tell the BMC where +within the write window it has modified. The host may also use the +MARK_WRITE_ERASED command to erase large parts of the active window without the +need to write 0xFF. The BMC must ensure that if the host +reads from an area it has erased that the read values are 0xFF. Any part of the +active window marked dirty/erased is only marked for the lifetime of the current +active write window and does not persist if the active window is closed either +implicitly or explicitly by the host or the BMC. The BMC may at any time +or must on a call to WRITE_FLUSH flush the changes which it has been notified +of back to the flash, at which point the dirty or erased marking is cleared +for the active window. The host must not assume that any changes have been +written to flash unless an explicit flush call was successful, a close of an +active write window was successful or a create window command with an active +write window was successful - otherwise consistency between the flash and memory +contents cannot be guaranteed. + +The host is not required to perform an erase before a write command and the +BMC must ensure that a write performs as expected - that is if an erase is +required before a write then the BMC must perform this itself. + +### BMC Events + +The BMC can raise events with the host asynchronously to communicate to the +host a change in state which it should take notice of. The host must (if +possible for the given event) acknowledge it to inform the BMC it has been +received. + +If the BMC raises a BMC Reboot event then the host must renegotiate the +protocol version so that both the BMC and the host agree on the block size. +A BMC Reboot event implies a BMC Windows Reset event. +If the BMC raises a BMC Windows Reset event then the host must +assume that there is no longer an active window - that is if there was an +active window it has been closed by the BMC and if it was a write window +then the host must not assume that it was flushed unless a previous explicit +flush call was successful. + +The BMC may at some points require access to the flash and the BMC daemon must +set the BMC Flash Control Lost event when the BMC is accessing the flash behind +the BMC daemons back. When this event is set the host must assume that the +contents of the active window could be inconsistent with the contents of flash. + +## Protocol Definition + +### Commands + +``` +RESET_STATE 0x01 +GET_MBOX_INFO 0x02 +GET_FLASH_INFO 0x03 +CREATE_READ_WINDOW 0x04 +CLOSE_WINDOW 0x05 +CREATE_WRITE_WINDOW 0x06 +MARK_WRITE_DIRTY 0x07 +WRITE_FLUSH 0x08 +BMC_EVENT_ACK 0x09 +MARK_WRITE_ERASED 0x0a (V2) +``` + +### Sequence + +The host must ensure a unique sequence number at the start of a +command/response pair. The BMC must ensure the responses to +a particular message contain the same sequence number that was in the +command request from the host. + +### Responses + +``` +SUCCESS 1 +PARAM_ERROR 2 +WRITE_ERROR 3 +SYSTEM_ERROR 4 +TIMEOUT 5 +BUSY 6 (V2) +WINDOW_ERROR 7 (V2) +``` + +#### Description: + +SUCCESS - Command completed successfully + +PARAM_ERROR - Error with parameters supplied or command invalid + +WRITE_ERROR - Error writing to the backing file system + +SYSTEM_ERROR - Error in BMC performing system action + +TIMEOUT - Timeout in performing action + +BUSY - Daemon in suspended state (currently unable to access flash) + - Retry again later + +WINDOW_ERROR - Command not valid for active window or no active window + - Try opening an appropriate window and retrying the command + +### Information +- All multibyte messages are LSB first (little endian) +- All responses must have a valid return code in byte 13 + + +### Commands in detail + +Note in V1 block size is hard coded to 4K, in V2 it is variable and must be +queried with GET_MBOX_INFO. +Sizes and addresses are specified in either bytes - (bytes) + or blocks - (blocks) +Sizes and addresses specified in blocks must be converted to bytes by +multiplying by the block size. +``` +Command: + RESET_STATE + Implemented in Versions: + V1, V2 + Arguments: + - + Response: + - + Notes: + This command is designed to inform the BMC that it should put + host LPC mapping back in a state where the SBE will be able to + use it. Currently this means pointing back to BMC flash + pre mailbox protocol. Final behavour is still TBD. + +Command: + GET_MBOX_INFO + Implemented in Versions: + V1, V2 + Arguments: + V1: + Args 0: API version + + V2: + Args 0: API version + + Response: + V1: + Args 0: API version + Args 1-2: default read window size (blocks) + Args 3-4: default write window size (blocks) + + V2: + Args 0: API version + Args 1-2: reserved + Args 3-4: reserved + Args 5: Block size as power of two (encoded as a shift) + +Command: + GET_FLASH_INFO + Implemented in Versions: + V1, V2 + Arguments: + - + Response: + V1: + Args 0-3: Flash size (bytes) + Args 4-7: Erase granule (bytes) + + V2: + Args 0-1: Flash size (blocks) + Args 2-3: Erase granule (blocks) + +Command: + CREATE_{READ/WRITE}_WINDOW + Implemented in Versions: + V1, V2 + Arguments: + V1: + Args 0-1: Window location as offset into flash (blocks) + + V2: + Args 0-1: Window location as offset into flash (blocks) + Args 2-3: Requested window size (blocks) + + Response: + V1: + Args 0-1: LPC bus address of window (blocks) + + V2: + Args 0-1: LPC bus address of window (blocks) + Args 2-3: Actual window size (blocks) + Args 4-5: Actual window location as offset into flash (blocks) + Notes: + Window location is always given as an offset into flash as + taken from the start of flash - that is it is an absolute + address. + + LPC bus address is always given from the start of the LPC + address space - that is it is an absolute address. + + The requested window 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 actual window location indicates the absolute flash offset + that the window actually maps and is not required to be equal + to the flash offset requested by the host, but however must be + less than or equal to it. Thus the first block of the window at + the lpc address in the response will map the first block at the + actual flash offset also contained in the response. It is the + 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 + atleast the first block of data requested by the host. A large + window is of course preferred and should correspond to + the default size returned in the GET_MBOX_INFO command. + + If this command returns successfully then the window which the + host requested is the active window. If it fails then there is + no active window. + +Command: + CLOSE_WINDOW + Implemented in Versions: + V1, V2 + Arguments: + V1: + - + + V2: + Args 0: Flags + Response: + - + Notes: + 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: + 0x01 - Short Lifetime: + The window is unlikely to be accessed + anytime again in the near future. The effect of + this will depend on BMC implementation. In + the event that the BMC performs some caching + the BMC daemon could mark data contained in a + window closed with this flag as first to be + evicted from the cache. + +Command: + MARK_WRITE_DIRTY + Implemented in Versions: + V1, V2 + Arguments: + V1: + Args 0-1: Flash offset to mark from base of flash (blocks) + Args 2-5: Number to mark dirty at offset (bytes) + + V2: + Args 0-1: Window offset to mark (blocks) + Args 2-3: Number to mark dirty at offset (blocks) + + Response: + - + Notes: + 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 occured 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. + +Command + WRITE_FLUSH + Implemented in Versions: + V1, V2 + Arguments: + V1: + Args 0-1: Flash offset to mark from base of flash (blocks) + Args 2-5: Number to mark dirty at offset (bytes) + + V2: + - + + Response: + - + Notes: + 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 + number + exceeds the size of the active window then the command must not + succeed. + + +Command: + BMC_EVENT_ACK + Implemented in Versions: + V1, V2 + Arguments: + Args 0: Bits in the BMC status byte (mailbox data + register 15) to ack + Response: + *clears the bits in mailbox data register 15* + Notes: + The host should use this command to acknowledge BMC events + supplied in mailbox register 15. + +Command: + MARK_WRITE_ERASED + Implemented in Versions: + V2 + Arguments: + V2: + Args 0-1: Window offset to erase (blocks) + Args 2-3: Number to erase at offset (blocks) + Response: + - + Notes: + 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. +``` + +### BMC Events in Detail: + +If the BMC needs to tell the host something then it simply +writes to Byte 15. The host should have interrupts enabled +on that register, or otherwise be polling it. + +#### Bit Definitions: + +Events which should be ACKed: +``` +0x01: BMC Reboot +0x02: BMC Windows Reset (V2) +``` + +Events which cannot be ACKed (BMC will clear when no longer +applicable): +``` +0x40: BMC Flash Control Lost (V2) +0x80: BMC MBOX Daemon Ready (V2) +``` + +#### Event Description: + +Events which must be ACKed: +The host should acknowledge these events with BMC_EVENT_ACK to +let the BMC know that they have been received and understood. +``` +0x01 - BMC Reboot: + Used to inform the host that a BMC reboot has occured. + The host must perform protocol verison negotiation again and + must assume it has no active window. The host must not assume + that any commands which didn't respond as such succeeded. +0x02 - BMC Windows Reset: (V2) + 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 not assume that any commands which didn't respond as such + succeeded. +``` + +Events which cannot be ACKed: +These events cannot be acknowledged by the host and a call to +BMC_EVENT_ACK with these bits set will have no effect. The BMC +will clear these bits when they are no longer applicable. +``` +0x40 - BMC Flash Control Lost: (V2) + The BMC daemon has been suspended and thus no longer + controls access to the flash (most likely because some + other process on the BMC required direct access to the + flash and has suspended the BMC daemon to preclude + concurrent access). + The BMC daemon must clear this bit itself when it regains + control of the flash (the host isn't able to clear it + through an acknowledge command). + The host must not assume that the contents of the active window + correctly reflect the contents of flash while this bit is set. +0x80 - BMC MBOX Daemon Ready: (V2) + 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. +``` diff --git a/Documentation/mboxctl.md b/Documentation/mboxctl.md new file mode 100644 index 0000000..49bf90e --- /dev/null +++ b/Documentation/mboxctl.md @@ -0,0 +1,110 @@ +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 + + 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. + +## Intro + +This document describes the reference mailbox control program contained in this +repository. + +The mailbox control program is a program which can be used to generate dbus +messages to control the operation of the mailbox daemon. + +## Files + +The mailbox control program is implemented entirely in the mboxctl.c file. + +## Operation + +### Invocation + +The mailbox control program is invoked with a command and any arguments which +that command takes. + +### Sending Command + +The appropriate dbus message is then generated and sent on the dbus. + +### Receiving Commands + +After sending a command mboxctl then waits for a response from the daemon on +the dbus and processes the response. + +A message is printed to convey the response provided by the daemon. It mboxctl +is run in silent mode then no output is generated and the exit code reflects +the response. + +## DBUS Protocol + +### Commands + +``` +0x00: Ping - Ping the daemon + - Args: NONE + - Resp: NONE +0x01: Daemon State - Get the daemon status + - Args: NONE + - Resp[0]: Daemon Status: + 0x00 - Active + 0x01 - Suspended +0x02: Reset - Reset the daemon (same as the reset mbox command) + - Args: NONE + - Resp: NONE +0x03: Suspend - Suspend the daemon + - Allow the BMC to manage concurrent flash + access + - The daemon will return BUSY to mbox window + commands + - Will return Success if daemon successfully + of already suspended + - Args: NONE + - Resp: NONE +0x04: Resume - Resume the daemon + - Will return Sucess if daemon successfully + or already resumed + - Args[0]: Flash Modified: + "clean" - Not Modified (daemon won't + clear its cache) + "modified" - Modified (daemon will clear + its cache) + - Resp: NONE +0x05: Clear Cache - Tell the daemon its data source has been modified + - Causes the daemon to clear its cache + - Args: NONE + - Resp: NONE +0x06: Kill - Terminates the daemon + - Args: NONE + - Resp: NONE +0x07: LPC State - Query the state of the lpc mapping + - Args: NONE + - Resp[0]: LPC Bus Mapping State: + 0x00 - Invalid (implies internal daemon + error) + 0x01 - Flash (LPC bus maps flash) + 0x02 - Memory (LPC bus maps reserved + memory) +``` + +### Return Values + +``` +0x00: Success - Command succeeded +0x01: Internal - Internal DBUS Error +0x02: Invalid - Invalid command or parameters +0x03: Rejected - Daemon rejected the request + - If this occurs on a suspend command then the BMC must + not access the flash device until a suspend command + succeeds +0x04: Hardware - BMC Hardware Error +0x05: Memory - Memory Allocation Failed +``` diff --git a/Documentation/mboxd.md b/Documentation/mboxd.md new file mode 100644 index 0000000..d60925d --- /dev/null +++ b/Documentation/mboxd.md @@ -0,0 +1,181 @@ +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 + + 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. + +## Intro + +This document describes the reference mailbox daemon contained in this +repository. + +## Files + +The main mailbox daemon is implemented in mboxd.c. This file uses helper +functions from the various mboxd_*.c files. + +``` +mboxd_dbus.c - Contains the handlers for the dbus commands which the daemon can + receive. +mboxd_flash.c - Contains the functions for performing flash access including + read, write and erase. +mboxd_lpc.c - Contains the functions for controlling the lpc bus mapping + including pointing the bus so it maps flash and memory. +mboxd_msg.c - Contains the handlers for the mbox commands which the daemon + can receive. +mboxd_windows.c - Contains the functions for managing the window cache. +``` + +## Daemon State + +The daemon is a state machine with 5 valid states: + +``` +UNINITIALISED - The daemon is still in the initialisation phase and + will not respond +ACTIVE_MAPS_FLASH - The daemon is polling for incoming commands, is not + currently suspended and the lpc bus maps the flash + device. +SUSPEND_MAPS_FLASH - The daemon is polling for incoming commands, is + currently suspended and the lpc bus maps the flash + device. +ACTIVE_MAPS_MEM - The daemon is polling for incoming commands, is not + currently suspended and the lpc bus maps the reserved + memory region. +SUSPEND_MAPS_MEM - The daemon is polling for incoming commands, is + currently suspended and the lpc bus maps the reserved + memory region. +``` + +As described in the protocol, the daemon can be suspended to allow the BMC to +access flash without the daemon interfering. The daemon will still respond to +commands while suspended but won't allow the host to, or itself, access the +flash. + +### State Transitions + +``` +UNINITIALISED -> ACTIVE_MAPS_FLASH - Uninitiated: Occurs when the daemon is + finished initialising. +ACTIVE_MAPS_FLASH -> SUSPEND_MAPS_FLASH - Suspend command received over + dbus +SUSPEND_MAPS_FLASH -> ACTIVE_MAPS_FLASH - Resume command received over + dbus +ACTIVE_MAPS_MEM -> SUSPEND_MAPS_MEM - Suspend command received over dbus +SUSPEND_MAPS_MEM -> ACTIVE_MAPS_MEM - Resume command received over dbus +ACTIVE_MAPS_FLASH -> ACTIVE_MAPS_MEM - GET_MBOX_INFO command received +SUSPEND_MAPS_FLASH -> SUSPEND_MAPS_MEM - GET_MBOX_INFO command received +ACTIVE_MAPS_MEM -> ACTIVE_MAPS_FLASH - Reset dbus or mbox command received +SUSPEND_MAPS_MEM -> SUSPEND_MAPS_FLASH - Transition not allowed, we + don't let the host modify flash + while the daemon is suspended. +``` + +## 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. + +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 +for one which contains that offset. If one is found we simply point the host to +it at the correct lpc offset for that windows location and the requested flash +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 +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. + +When ever the flash is changed we have to invalidate all windows in the window +cache as their contents may no longer accurately reflect those of the flash. + +## Daemon Operation + +### Invocation + +The daemon is invoked on the command line with a few parameters: + +``` +(*) - required +(#) - optional but recommended +(~) - optional + +--flash * - The size of the PNOR image on the flash device +--window-size # - The size to make each window in the cache +--window-num # - The number of windows to have in the cache +--verbose ~ - Increase the verbosity with which the daemon runs +--sys-log ~ - Use the system log rather than outputing to the console +``` + +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. + +### Initialisation + +After the command line has been parsed the daemon will initalise its various +interfaces. If any of these initialisations fail it will print an error and the +daemon will terminate. + +After initilisation the daemon points the lpc mapping to the actual flash +device, sets the BMC_READY BMC event and starts polling. + +### Polling + +The daemon sits in a poll loop waiting for an event to happen on one or more of +the mbox, dbus or signal file descriptors. + +#### Handling MBOX Commands + +When an event occurs on the mbox file descriptor the mbox request is read from +the mbox registers and processed. + +The command is validated and then the appropriate handler called. The response +is then written back to the mbox registers to indicate the outcome of the +command and an interrupt generated to the host. + +#### Handling DBUS Commands + +When an event occurs on the dbus file descriptor the dbus request is read from +the dbus interface and processed. + +The command is validated and then the appropriate handler called. The response +is then written back to the dbus interface to indicate the outcome of the +command. + +#### Handling Signals + +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: + +``` +SIGINT - Terminate the daemon +SIGTERM - Terminate the daemon +SIGHUP - Clear the window cache and point the lpc bus mapping back to + flash +``` + +### Termination + +The daemon can be terminated for multiple reasons; invalid command line, unable +to initialise, received SIGINT or SIGTERM, or because it received the kill dbus +command. + +On termination the daemon clears the window cache and notifys 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. @@ -1,4 +1,4 @@ -Copyright 2016 IBM +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. @@ -12,642 +12,14 @@ 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 +## MBOX -This document describes a protocol for host to BMC communication via the -mailbox registers present on the Aspeed 2400 and 2500 chips. -This protocol is specifically designed to allow a host to request and manage -access to the flash with the specifics of how the host is required to control -this described below. +This repo contains the protocol definition for the host to BMC mailbox +communication specification which can be found in +Documentation/mbox_procotol.md. -## Version +There is also a reference implementation of a BMC mailbox daemon, the details +of which can be found in Documentation/mboxd.md. -Both version 1 and version 2 of the protocol are described below with version 2 -specificities represented with V2 in brackets - (V2). - -## Problem Overview - -"mbox" is the name we use to represent a protocol we have established between -the host and the BMC via the Aspeed mailbox registers. This protocol is used -for the host to control the flash. - -Prior to the mbox protocol, the host uses a backdoor into the BMC address space -(the iLPC-to-AHB bridge) to directly manipulate the BMCs own flash controller. - -This is not sustainable for a number of reasons. The main ones are: - -1. Every piece of the host software stack that needs flash access (HostBoot, - OCC, OPAL, ...) has to have a complete driver for the flash controller, - update it on each BMC generation, have all the quirks for all the flash - chips supported etc... We have 3 copies on the host already in addition to - the one in the BMC itself. - -2. There are serious issues of access conflicts to that controller between the - host and the BMC. - -3. It's very hard to support "BMC reboots" when doing that - -4. It's slow - -5. Last but probably most important, having that backdoor open is a security - risk. It means the host can access any address on the BMC internal bus and - implant malware in the BMC itself. So if the host is a "bare metal" shared - system in some kind of data center, not only the host flash needs to be - reflashed when switching from one customer to another, but the entire BMC - flash too as nothing can be trusted. So we want to disable it. - -To address all these, we have implemented a new mechanism that we call mbox. - -When using this mechanism, the BMC is solely responsible for directly accessing -the flash controller. All flash erase and write operations are performed by the -BMC and the BMC only. (We can allow direct reads from flash under some -circumstances but we tend to prefer going via memory). - -The host uses the mailbox registers to send "commands" to the BMC, which -responds via the same mechanism. Those commands allow the host to control a -"window" (which is the LPC -> AHB FW space mapping) that is either a read -window or a write window onto the flash. - -When set for writing, the BMC makes the window point to a chunk of RAM instead. -When the host "commits" a change (via MBOX), then the BMC can perform the -actual flashing from the data in the RAM window. - -The idea is to have the LPC FW space be routed to an active "window". That -window can be a read or a write window. The commands allow to control which -window and which offset into the flash it maps. - -* A read window can be a direct window to the flash controller space (ie. - 0x3000\_0000) or it can be a window to a RAM image of a flash. It doesn't have - to be the full size of the flash per protocol (commands can be use to "slide" - it to various parts of the flash) but if its set to map the actual flash - controller space at 0x3000\_0000, it's probably simpler to make it the full - flash. The host makes no assumption, it's your choice what to provide. The - simplest implementation is to just route to the flash read/only. - -* A write window has to be a chunk of BMC memory. The minimum size is not - defined in the spec, but it should be at least one block (4k for now but it - should support larger block sizes in the future). When the BMC receive the - command to map the write window at a given offset of the flash, the BMC should - copy that portion of the flash into a reserved memory buffer, and modify the - LPC mapping to point to that buffer. - -The host can then write to that window directly (updating the BMC memory) and -send a command to "commit" those updates to flash. - -Finally there is a `RESET_STATE`. It's the state in which the bootloader in the -SEEPROM of the POWER9 chip will find what it needs to load HostBoot. The -details are still being ironed out: either mapping the full flash read only or -reset to a "window" that is either at the bottom or top of the flash. The -current implementation resets to point to the full flash. - -## Where is the code? - -The mbox userspace is available [on GitHub](https://github.com/openbmc/mboxbridge) -This is Apache licensed but we are keen to see any enhancements you may have. - -The kernel driver is still in the process of being upstreamed but can be found -in the OpenBMC Linux kernel staging tree: - -https://github.com/openbmc/linux/commit/85770a7d1caa6a1fa1a291c33dfe46e05755a2ef - -## Building - -The autotools of this requires the autoconf-archive package for your -system - -## The Hardware - -The Aspeed mailbox consists of 16 (8 bit) data registers see Layout for their -use. Mailbox interrupt enabling, masking and triggering is done using a pair -of control registers, one accessible by the host the other by the BMC. -Interrupts can also be raised per write to each data register, for BMC and -host. Write tiggered interrupts are configured using two 8 bit registers where -each bit represents a data register and if an interrupt should fire on write. -Two 8 bit registers are present to act as a mask for write triggered -interrupts. - -### Layout - -``` -Byte 0: COMMAND -Byte 1: Sequence -Byte 2-12: Arguments -Byte 13: Response code -Byte 14: Host controlled status reg -Byte 15: BMC controlled status reg -``` - -## Low Level Protocol Flow - -What we essentially have is a set of registers which either the host or BMC can -write to in order to communicate to the other which will respond in some way. -There are 3 basic types of communication. - -1. Commands sent from the Host to the BMC -2. Responses sent from the BMC to the Host in response to commands -3. Asyncronous events raised by the BMC - -### General Use - -Messages usually originate from the host to the BMC. There are special -cases for a back channel for the BMC to pass new information to the -host which will be discussed later. - -To initiate a request the host must set a command code (see -Commands) into mailbox data register 0. It is also the hosts -responsibility to generate a unique sequence number into mailbox -register 1. After this any command specific data should be written -(see Layout). The host must then generate an interrupt to the BMC by -using bit 0 of its control register and wait for an interrupt on the -response register. Generating an interrupt automatically sets bit 7 of the -corresponding control register. This bit can be used to poll for -messages. - -On receiving an interrupt (or polling on bit 7 of its Control -Register) the BMC should read the message from the general registers -of the mailbox and perform the necessary action before responding. On -responding the BMC must ensure that the sequence number is the same as -the one in the request from the host. The BMC must also ensure that -mailbox data regsiter 13 is a valid response code (see Responses). The -BMC should then use its control register to generate an interrupt for -the host to notify it of a response. - -### Asynchronous BMC to Host Events - -BMC to host communication is also possible for notification of events -from the BMC. This requires that the host have interrupts enabled on -mailbox data register 15 (or otherwise poll on bit 7 of mailbox status -register 1). On receiving such a notification the host should read -mailbox data register 15 to determine the event code which was set by the -BMC (see BMC Event notifications in Commands for detail). Events which are -defined as being able to be acknowledged by the host must be with a -BMC_EVENT_ACK command. - -## High Level Protocol Flow - -When a host wants to communicate with the BMC via the mbox protocol the first -thing it should do it call MBOX_GET_INFO in order to establish the protocol -version which each understands. Before this the only other commands which are -allowed are RESET_STATE and BMC_EVENT_ACK. - -After this the host can open and close windows with the CREATE_READ_WINDOW, -CREATE_WRITE_WINDOW and CLOSE_WINDOW commands. Creating a window is how the -host requests access to a section of flash. It is worth noting that the host -can only ever have one window that it is accessing at a time - hence forth -referred to as the active window. - -When the active window is a write window the host can perform MARK_WRITE_DIRTY, -MARK_WRITE_ERASED and WRITE_FLUSH commands to identify changed blocks and -control when the changed blocks are written to flash. - -Independently, and at any point not during an existing mbox command -transaction, the BMC may raise raise asynchronous events with the host to -communicate a change in state. - -### Version Negotiation - -Given that a majority of command and response arguments are specified as a -multiple of block size it is necessary for the host and BMC to agree on a -protocol version as this determines the block size. In V1 it is hard coded at -4K and in V2 the BMC chooses and specifies this to the host as a response -argument to MBOX_GET_INFO. Thus the host must always call MBOX_GET_INFO before -any other command which specifies an argument in block size. - -The host must tell the BMC the highest protocol level which it supports. The -BMC will then respond with a protocol level. If the host doesn't understand -the protocol level specified by the BMC then it must not continue to -communicate with the BMC. Otherwise the protocol level specified by the -BMC is taken to be the protocol level used for further communication and can -only be changed by another call to MBOX_GET_INFO. The BMC should use the -request from the host to influence its protocol version choice. - -### Window Management - -In order to access flash contents the host must request a window be opened at -the flash offset it would like to access. The host may give a hint as to how -much data it would like to access or otherwise set this argument to zero. The -BMC must respond with the lpc bus address to access this window and the -window size. The host must not access past the end of the active window. - -There is only ever one active window which is the window created by the most -recent CREATE_READ_WINDOW or CREATE_WRITE_WINDOW call which succeeded. Even -though there are two types of windows there can still only be one active window -irrespective of type. A host must not write to a read window. A host may 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 calling CLOSE_WINDOW in which case there is no active -window and the host must not access the LPC window after it has been closed. -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 -previous 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) -if the active window is a read window or if there is no active window. - -### Write Management - -The BMC has no method for intercepting writes that occur over the LPC bus. Thus -the host must explicitly notify the BMC of where and when a write has -occured. The host must use the MARK_WRITE_DIRTY command to tell the BMC where -within the write window it has modified. The host may also use the -MARK_WRITE_ERASED command to erase large parts of the active window without the -need to write 0xFF. The BMC must ensure that if the host -reads from an area it has erased that the read values are 0xFF. Any part of the -active window marked dirty/erased is only marked for the lifetime of the current -active write window and does not persist if the active window is closed either -implicitly or explicitly by the host or the BMC. The BMC may at any time -or must on a call to WRITE_FLUSH flush the changes which it has been notified -of back to the flash, at which point the dirty or erased marking is cleared -for the active window. The host must not assume that any changes have been -written to flash unless an explicit flush call was successful, a close of an -active write window was successful or a create window command with an active -write window was successful - otherwise consistency between the flash and memory -contents cannot be guaranteed. - -The host is not required to perform an erase before a write command and the -BMC must ensure that a write performs as expected - that is if an erase is -required before a write then the BMC must perform this itself. - -### BMC Events - -The BMC can raise events with the host asynchronously to communicate to the -host a change in state which it should take notice of. The host must (if -possible for the given event) acknowledge it to inform the BMC it has been -received. - -If the BMC raises a BMC Reboot event then the host must renegotiate the -protocol version so that both the BMC and the host agree on the block size. -A BMC Reboot event implies a BMC Windows Reset event. -If the BMC raises a BMC Windows Reset event then the host must -assume that there is no longer an active window - that is if there was an -active window it has been closed by the BMC and if it was a write window -then the host must not assume that it was flushed unless a previous explicit -flush call was successful. - -The BMC may at some points require access to the flash and the BMC daemon must -set the BMC Flash Control Lost event when the BMC is accessing the flash behind -the BMC daemons back. When this event is set the host must assume that the -contents of the active window could be inconsistent with the contents of flash. - -## Protocol Definition - -### Commands - -``` -RESET_STATE 0x01 -GET_MBOX_INFO 0x02 -GET_FLASH_INFO 0x03 -CREATE_READ_WINDOW 0x04 -CLOSE_WINDOW 0x05 -CREATE_WRITE_WINDOW 0x06 -MARK_WRITE_DIRTY 0x07 -WRITE_FLUSH 0x08 -BMC_EVENT_ACK 0x09 -MARK_WRITE_ERASED 0x0a (V2) -``` - -### Sequence - -The host must ensure a unique sequence number at the start of a -command/response pair. The BMC must ensure the responses to -a particular message contain the same sequence number that was in the -command request from the host. - -### Responses - -``` -SUCCESS 1 -PARAM_ERROR 2 -WRITE_ERROR 3 -SYSTEM_ERROR 4 -TIMEOUT 5 -BUSY 6 (V2) -WINDOW_ERROR 7 (V2) -``` - -#### Description: - -SUCCESS - Command completed successfully - -PARAM_ERROR - Error with parameters supplied or command invalid - -WRITE_ERROR - Error writing to the backing file system - -SYSTEM_ERROR - Error in BMC performing system action - -TIMEOUT - Timeout in performing action - -BUSY - Daemon in suspended state (currently unable to access flash) - - Retry again later - -WINDOW_ERROR - Command not valid for active window or no active window - - Try opening an appropriate window and retrying the command - -### Information -- All multibyte messages are LSB first (little endian) -- All responses must have a valid return code in byte 13 - - -### Commands in detail - -Note in V1 block size is hard coded to 4K, in V2 it is variable and must be -queried with GET_MBOX_INFO. -Sizes and addresses are specified in either bytes - (bytes) - or blocks - (blocks) -Sizes and addresses specified in blocks must be converted to bytes by -multiplying by the block size. -``` -Command: - RESET_STATE - Implemented in Versions: - V1, V2 - Arguments: - - - Response: - - - Notes: - This command is designed to inform the BMC that it should put - host LPC mapping back in a state where the SBE will be able to - use it. Currently this means pointing back to BMC flash - pre mailbox protocol. Final behavour is still TBD. - -Command: - GET_MBOX_INFO - Implemented in Versions: - V1, V2 - Arguments: - V1: - Args 0: API version - - V2: - Args 0: API version - - Response: - V1: - Args 0: API version - Args 1-2: default read window size (blocks) - Args 3-4: default write window size (blocks) - - V2: - Args 0: API version - Args 1-2: reserved - Args 3-4: reserved - Args 5: Block size as power of two (encoded as a shift) - -Command: - GET_FLASH_INFO - Implemented in Versions: - V1, V2 - Arguments: - - - Response: - V1: - Args 0-3: Flash size (bytes) - Args 4-7: Erase granule (bytes) - - V2: - Args 0-1: Flash size (blocks) - Args 2-3: Erase granule (blocks) - -Command: - CREATE_{READ/WRITE}_WINDOW - Implemented in Versions: - V1, V2 - Arguments: - V1: - Args 0-1: Window location as offset into flash (blocks) - - V2: - Args 0-1: Window location as offset into flash (blocks) - Args 2-3: Requested window size (blocks) - - Response: - V1: - Args 0-1: LPC bus address of window (blocks) - - V2: - Args 0-1: LPC bus address of window (blocks) - Args 2-3: Actual window size (blocks) - Args 4-5: Actual window location as offset into flash (blocks) - Notes: - Window location is always given as an offset into flash as - taken from the start of flash - that is it is an absolute - address. - - LPC bus address is always given from the start of the LPC - address space - that is it is an absolute address. - - The requested window 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 actual window location indicates the absolute flash offset - that the window actually maps and is not required to be equal - to the flash offset requested by the host, but however must be - less than or equal to it. Thus the first block of the window at - the lpc address in the response will map the first block at the - actual flash offset also contained in the response. It is the - 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 - atleast the first block of data requested by the host. A large - window is of course preferred and should correspond to - the default size returned in the GET_MBOX_INFO command. - - If this command returns successfully then the window which the - host requested is the active window. If it fails then there is - no active window. - -Command: - CLOSE_WINDOW - Implemented in Versions: - V1, V2 - Arguments: - V1: - - - - V2: - Args 0: Flags - Response: - - - Notes: - 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: - 0x01 - Short Lifetime: - The window is unlikely to be accessed - anytime again in the near future. The effect of - this will depend on BMC implementation. In - the event that the BMC performs some caching - the BMC daemon could mark data contained in a - window closed with this flag as first to be - evicted from the cache. - -Command: - MARK_WRITE_DIRTY - Implemented in Versions: - V1, V2 - Arguments: - V1: - Args 0-1: Flash offset to mark from base of flash (blocks) - Args 2-5: Number to mark dirty at offset (bytes) - - V2: - Args 0-1: Window offset to mark (blocks) - Args 2-3: Number to mark dirty at offset (blocks) - - Response: - - - Notes: - 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 occured 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. - -Command - WRITE_FLUSH - Implemented in Versions: - V1, V2 - Arguments: - V1: - Args 0-1: Flash offset to mark from base of flash (blocks) - Args 2-5: Number to mark dirty at offset (bytes) - - V2: - - - - Response: - - - Notes: - 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 + number - exceeds the size of the active window then the command must not - succeed. - - -Command: - BMC_EVENT_ACK - Implemented in Versions: - V1, V2 - Arguments: - Args 0: Bits in the BMC status byte (mailbox data - register 15) to ack - Response: - *clears the bits in mailbox data register 15* - Notes: - The host should use this command to acknowledge BMC events - supplied in mailbox register 15. - -Command: - MARK_WRITE_ERASED - Implemented in Versions: - V2 - Arguments: - V2: - Args 0-1: Window offset to erase (blocks) - Args 2-3: Number to erase at offset (blocks) - Response: - - - Notes: - 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. -``` - -### BMC Events in Detail: - -If the BMC needs to tell the host something then it simply -writes to Byte 15. The host should have interrupts enabled -on that register, or otherwise be polling it. - -#### Bit Definitions: - -Events which should be ACKed: -``` -0x01: BMC Reboot -0x02: BMC Windows Reset (V2) -``` - -Events which cannot be ACKed (BMC will clear when no longer -applicable): -``` -0x40: BMC Flash Control Lost (V2) -0x80: BMC MBOX Daemon Ready (V2) -``` - -#### Event Description: - -Events which must be ACKed: -The host should acknowledge these events with BMC_EVENT_ACK to -let the BMC know that they have been received and understood. -``` -0x01 - BMC Reboot: - Used to inform the host that a BMC reboot has occured. - The host must perform protocol verison negotiation again and - must assume it has no active window. The host must not assume - that any commands which didn't respond as such succeeded. -0x02 - BMC Windows Reset: (V2) - 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 not assume that any commands which didn't respond as such - succeeded. -``` - -Events which cannot be ACKed: -These events cannot be acknowledged by the host and a call to -BMC_EVENT_ACK with these bits set will have no effect. The BMC -will clear these bits when they are no longer applicable. -``` -0x40 - BMC Flash Control Lost: (V2) - The BMC daemon has been suspended and thus no longer - controls access to the flash (most likely because some - other process on the BMC required direct access to the - flash and has suspended the BMC daemon to preclude - concurrent access). - The BMC daemon must clear this bit itself when it regains - control of the flash (the host isn't able to clear it - through an acknowledge command). - The host must not assume that the contents of the active window - correctly reflect the contents of flash while this bit is set. -0x80 - BMC MBOX Daemon Ready: (V2) - 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. -``` +Finally there is also an implementation of a mailbox daemon control program, the +details of which can be found in Documentation/mboxctl.md. |
