Lines Matching full:the
3 Licensed under the Apache License, Version 2.0 (the "License");
4 you may not use this file except in compliance with the License.
5 You may obtain a copy of the License at
10 distributed under the License is distributed on an "AS IS" BASIS,
12 See the License for the specific language governing permissions and
13 limitations under the License.
17 This document describes a protocol for host to BMC communication via the
18 mailbox registers present on the Aspeed 2400 and 2500 chips.
20 access to a flash device(s) with the specifics of how the host is required to
25 Version specific protocol functionalities are represented by the version number
26 in brackets next to the definition of the functionality. (e.g. (V2) for version
28 implemented by proceeding versions up to and not including the version a command
33 "mbox" is the name we use to represent a protocol we have established between
34 the host and the BMC via the Aspeed mailbox registers. This protocol is used
35 for the host to control access to the flash device(s).
37 Prior to the mbox protocol, the host uses a backdoor into the BMC address space
38 (the iLPC-to-AHB bridge) to directly manipulate the BMCs own flash controller.
40 This is not sustainable for a number of reasons. The main ones are:
42 1. Every piece of the host software stack that needs flash access (HostBoot,
43 OCC, OPAL, ...) has to have a complete driver for the flash controller,
44 update it on each BMC generation, have all the quirks for all the flash
45 chips supported etc... We have 3 copies on the host already in addition to
46 the one in the BMC itself.
48 2. There are serious issues of access conflicts to that controller between the
49 host and the BMC.
56 risk. It means the host can access any address on the BMC internal bus and
57 implant malware in the BMC itself. So if the host is a "bare metal" shared
58 system in some kind of data center, not only the host flash needs to be
59 reflashed when switching from one customer to another, but the entire BMC
64 When using this mechanism, the BMC is solely responsible for directly accessing
65 the flash controller. All flash erase and write operations are performed by the
66 BMC and the BMC only. (We can allow direct reads from flash under some
69 The host uses the mailbox registers to send "commands" to the BMC, which
70 responds via the same mechanism. Those commands allow the host to control a
71 "window" (which is the LPC -> AHB FW space mapping) that is either a read
72 window or a write window onto the flash.
74 When set for writing, the BMC makes the window point to a chunk of RAM instead.
75 When the host "commits" a change (via MBOX), then the BMC can perform the
76 actual flashing from the data in the RAM window.
78 The idea is to have the LPC FW space be routed to an active "window". That
79 window can be a read or a write window. The commands allow to control which
80 window and which offset into the flash it maps.
82 * A read window can be a direct window to the flash controller space (ie.
84 to be the full size of the flash per protocol (commands can be used to "slide"
85 it to various parts of the flash) but if it's set to map the actual flash
86 controller space at 0x3000\_0000, it's probably simpler to make it the full
87 flash. The host makes no assumption, it's your choice what to provide. The
88 simplest implementation is to just route to the flash read/only.
90 * A write window has to be a chunk of BMC memory. The minimum size is not
91 defined in the spec, but it should be at least one block (4k for now but it
92 should support larger block sizes in the future). When the BMC receive the
93 command to map the write window at a given offset of the flash, the BMC should
94 copy that portion of the flash into a reserved memory buffer, and modify the
97 The host can then write to that window directly (updating the BMC memory) and
100 Finally, there is a `RESET_STATE`. It's the state in which the bootloader in the
101 SEEPROM of the POWER9 chip will find what it needs to load HostBoot. The
102 details are still being ironed out: either mapping the full flash read only or
103 reset to a "window" that is either at the bottom or top of the flash. The
104 current implementation resets to point to the full flash.
106 ## Where is the code?
108 The mbox userspace is available [on GitHub](https://github.com/openbmc/mboxbridge)
111 The kernel driver is still in the process of being upstreamed but can be found
112 in the OpenBMC Linux kernel staging tree:
118 The Autotools of this requires the autoconf-archive package for your
121 ## The Hardware
123 The Aspeed mailbox consists of 16 (8 bit) data registers see Layout for their
125 of control registers, one accessible by the host the other by the BMC.
143 Note: when the BMC is writing a response to the mbox registers (as described
144 above), the "Response Code" (Register 13) must be the last register written to.
145 Writing register 13 will trigger an interrupt to the host indicating a complete
146 response has been written. Triggering the interrupt by writing register 13
147 prior to completing the response may lead to a data race, and must, therefore,
152 What we essentially have is a set of registers which either the host or BMC can
153 write to in order to communicate to the other which will respond in some way.
156 1. Commands sent from the Host to the BMC
157 2. Responses sent from the BMC to the Host in response to commands
158 3. Asynchronous events raised by the BMC
162 Messages usually originate from the host to the BMC. There are special
163 cases for a back channel for the BMC to pass new information to the
166 To initiate a request the host must set a command code (see Commands) into
169 command-specific data should be written (see Layout). The host must then
170 generate an interrupt to the BMC by using bit 0 of its control register and
171 wait for an interrupt on the response register. Generating an interrupt
172 automatically sets bit 7 of the corresponding control register. This bit can be
176 Register) the BMC should read the message from the general registers
177 of the mailbox and perform the necessary action before responding. On
178 responding the BMC must ensure that the sequence number is the same as
179 the one in the request from the host. The BMC must also ensure that
180 mailbox data register 13 is a valid response code (see Responses). The
182 the host to notify it of a response.
187 from the BMC. This requires that the host have interrupts enabled on
189 register 1). On receiving such a notification the host should read
190 mailbox data register 15 to determine the event code which was set by the
192 defined as being able to be acknowledged by the host must be with a
197 When a host wants to communicate with the BMC via the mbox protocol the first
198 thing it should do it call MBOX_GET_INFO in order to establish the protocol
199 version which each understands. Before this, the only other commands which are
202 After this, the host can open and close windows with the CREATE_READ_WINDOW,
203 CREATE_WRITE_WINDOW and CLOSE_WINDOW commands. Creating a window is how the
204 host requests access to a section of flash. It is worth noting that the host
206 referred to as the active window.
208 When the active window is a write window the host can perform MARK_WRITE_DIRTY,
210 control when the changed blocks are written to flash.
213 transaction, the BMC may raise asynchronous events with the host to
219 multiple of block size it is necessary for the host and BMC to agree on a
220 protocol version as this determines the block size. In V1 it is hard coded at
221 4K, in V2 the BMC chooses and in V3 the host is allowed to request a specific
222 block size with the actual size chosen communicated back to the host as a
223 response argument to `MBOX_GET_INFO`. Thus the host must always call
227 When invoking `MBOX_GET_INFO` the host must provide the BMC its highest
228 supported version of the protocol. The BMC must respond with a protocol version
229 less than or equal to that requested by the host, or in the event that there is
230 no such value, an error code. In the event that an error is returned the host
231 must not continue to communicate with the BMC. Otherwise, the protocol version
232 returned by the BMC is the agreed protocol version for all further
233 communication. The host may at a future point request a change in protocol
238 In order to access flash contents, the host must request a window be opened at
239 the flash offset it would like to access with the CREATE_{READ,WRITE}_WINDOW
240 commands. The host may give a hint as to how much data it would like to access
241 or otherwise set this argument to zero. The BMC must respond with the LPC bus
242 address to access this window and the window size. The host must not access
243 past the end of the active window. On returning success to either of the create
244 window commands the BMC must guarantee that the window provided contains data
245 which correctly represents the state of flash at the time the response is given.
247 There is only ever one active window which is the window created by the most
251 from a write window and the BMC must guarantee that the window reflects what
252 the host has written there.
255 window and the host must not access the LPC window after it has been closed.
256 If the host closes an active write window then the BMC must perform an
257 implicit flush. If the host tries to open a new window with an already active
258 window then the active window is closed (and implicitly flushed if it was a
259 write window). If the new window is successfully opened then it is the new
260 active window, if the command fails then there is no active window and the
263 The host must not access an LPC address other than that which is contained by
264 the active window. The host must not use write management functions (see below)
265 if the active window is a read window or if there is no active window.
269 The BMC has no method for intercepting writes that occur over the LPC bus. Thus
270 the host must explicitly notify the BMC of where and when a write has
271 occurred. The host must use the MARK_WRITE_DIRTY command to tell the BMC where
272 within the write window it has modified. The host may also use the
273 MARK_WRITE_ERASED command to erase large parts of the active window without the
274 need to write 0xFF. The BMC must ensure that if the host
275 reads from an area it has erased that the read values are 0xFF. Any part of the
276 active window marked dirty/erased is only marked for the lifetime of the current
277 active write window and does not persist if the active window is closed either
278 implicitly or explicitly by the host or the BMC. The BMC may at any time
279 or must on a call to WRITE_FLUSH flush the changes which it has been notified
280 of back to the flash, at which point the dirty or erased marking is cleared
281 for the active window. The host must not assume that any changes have been
284 write window was successful - otherwise consistency between the flash and memory
287 The host is not required to perform an erase before a write command and the
289 required before a write then the BMC must perform this itself (unless the
290 no_erase flag is set in the MARK_WRITE_DIRTY command in which case the BMC will
293 The host may lock an area of flash using the MARK_LOCKED command. Any attempt
294 to mark dirty or erased this area of flash must fail with the LOCKED_ERROR
295 response code. The host may open a write window which contains a locked area
297 to the backing data source (i.e. that area of flash must be treated as read
298 only with respect to the backing store at all times). An attempt to lock an area
299 of flash which is not clean in the current window must fail with PARAM_ERROR.
301 only possible to clear the lock state through a clear_locked dbus command. (V3)
305 The BMC can raise events with the host asynchronously to communicate to the
306 host a change in state which it should take notice of. The host must (if
307 possible for the given event) acknowledge it to inform the BMC it has been
310 If the BMC raises a BMC Reboot event then the host must renegotiate the
311 protocol version so that both the BMC and the host agree on the block size.
313 If the BMC raises a BMC Windows Reset event then the host must
315 active window it has been closed by the BMC and if it was a write window
316 then the host must not assume that it was flushed unless a previous explicit
319 The BMC may at some points require access to the flash and the BMC daemon must
320 set the BMC Flash Control Lost event when the BMC is accessing the flash behind
321 the BMC daemons back. When this event is set the host must assume that the
322 contents of the active window could be inconsistent with the contents of flash.
360 responses. V1, V2 and V3 of the protocol permit either zero or one commands to
363 For generality, the host must generate a sequence number that is unique with
364 respect to the previous command (one that has received a response) and any
366 valid. The BMC's response to a command must contain the same sequence number
367 issued by the host as found in the relevant command.
369 Sequence numbers may be reused in accordance with the constraints outlined
370 above. However, it is not an error if the BMC receives a `GET_MBOX_INFO` with an
371 invalid sequence number. For all other cases, the BMC must respond with
372 `SEQ_ERROR` if the constraints are violated. If the host receives a `SEQ_ERROR`
373 response it must consider any in-progress commands to have failed. The host may
374 retry the affected command(s) after generating a suitable sequence number.
382 WRITE_ERROR - Error writing to the backing file system
392 - Try opening an appropriate window and retrying the command
405 Block size refers to an agreed value which is used as a unit for the
410 In V2 it is variable and must be queried with the GET_MBOX_INFO command.
411 In V3 the host can request a given block size however it is ultimately up to
412 the daemon to choose a block size which is returned as part of the GET_MBOX_INFO
413 command response. The host must respect the daemons choice. The ability for the
415 size to be able to utilise commands which only operate at the block level.
418 Block size must also be greater than or equal to 4K. This is due to the
421 that we can specify the entire address space. This additionally allows us
427 multiplying by the block size.
437 This command is designed to inform the BMC that it should put
438 host LPC mapping back in a state where the SBE will be able to
477 The suggested timeout is a hint to the host as to how long
478 it should wait after issuing a command to the BMC before it
479 times out waiting for a response. This is the maximum time
480 which the BMC thinks it could take to service any command which
481 the host could issue. This may be set to zero to indicate that
482 the BMC does not wish to provide a hint in which case the host
485 The host may desire a specific block size and thus can request
486 this by giving a hint to the daemon (may be zero). The daemon
487 may use this to select the block size which it will use however
488 is free to ignore it. The value in the response is the block
534 The flash offset which the host requests access to is always
535 taken from the start of flash - that is it is an absolute
538 LPC bus address is always given from the start of the LPC
541 The requested access size is only a hint. The response
542 indicates the actual size of the window. The BMC may
543 want to use the requested size to pre-load the remainder
544 of the request. The host must not access past the end of the
547 The flash offset mapped by the window is an absolute flash
548 offset and must be less than or equal to the flash offset
549 requested by the host. It is the responsibility of the host
552 The requested window size may be zero. In this case the
554 atleast the first block of data requested by the host. A large
556 the default size returned in the GET_MBOX_INFO command.
558 If this command returns successfully then the created window
559 is the active window. If it fails then there is no active
574 Closes the active window. Any further access to the LPC bus
575 address specified to address the previously active window will
576 have undefined effects. If the active window is a
577 write window then the BMC must perform an implicit flush.
579 The Flags argument allows the host to provide some
580 hints to the BMC. Defined Values:
582 The window is unlikely to be accessed
583 anytime again in the near future. The effect of
585 the event that the BMC performs some caching
586 the BMC daemon could mark data contained in a
588 evicted from the cache.
606 The BMC has no method for intercepting writes that
607 occur over the LPC bus. The host must explicitly notify
608 the daemon of where and when a write has occurred so it
611 Offsets are given as an absolute (either into flash (V1) or the
612 active window (V2)) and a zero offset refers to the first
613 block. If the offset + number exceeds the size of the active
614 window then the command must not succeed.
616 The host can give a hint to the daemon that is doesn't have to
618 means that the daemon will blindly perform a write to that area
620 the host knows that a large area has already been erased for
637 Flushes any dirty/erased blocks in the active window to
638 the backing storage.
640 In V1 this can also be used to mark parts of the flash
641 dirty and flush in a single command. In V2 the explicit
643 since there are no longer any arguments. If the offset + number
644 exceeds the size of the active window then the command must not
652 Args 0: Bits in the BMC status byte (mailbox data
655 *clears the bits in mailbox data register 15*
657 The host should use this command to acknowledge BMC events
670 This command allows the host to erase a large area
671 without the need to individually write 0xFF
674 Offset is the offset within the active window to start erasing
675 from (zero refers to the first block of the active window) and
676 number is the number of blocks of the active window to erase
677 starting at offset. If the offset + number exceeds the size of
678 the active window then the command must not succeed.
689 Describes a flash with some kind of identifier useful to the
692 The length in the response is the number of response arguments
693 as part of the flash name field which the host should expect to
706 Lock an area of flash so that the host can't mark it dirty or
707 erased. If the requested area is within the current window and
715 If the BMC needs to tell the host something then it simply
716 writes to Byte 15. The host should have interrupts enabled
737 The host should acknowledge these events with BMC_EVENT_ACK to
738 let the BMC know that they have been received and understood.
741 Used to inform the host that a BMC reboot has occurred.
742 The host must perform protocol version negotiation again and
743 must assume it has no active window. The host must not assume
746 The host must assume that its active window has been closed and
747 that it no longer has an active window. The host is not
748 required to perform protocol version negotiation again. The
754 These events cannot be acknowledged by the host and a call to
755 BMC_EVENT_ACK with these bits set will have no effect. The BMC
759 The BMC daemon has been suspended and thus no longer
760 controls access to the flash (most likely because some
761 other process on the BMC required direct access to the
762 flash and has suspended the BMC daemon to preclude
764 The BMC daemon must clear this bit itself when it regains
765 control of the flash (the host isn't able to clear it
767 The host must not assume that the contents of the active window
768 correctly reflect the contents of flash while this bit is set.
770 Used to inform the host that the BMC daemon is ready to
771 accept command requests. The host isn't able to clear
772 this bit through an acknowledge command, the BMC daemon must
775 The host should not expect a response while this bit is
777 Note that this bit being set is not a guarantee that the BMC daemon
778 will respond as it or the BMC may have crashed without clearing