Lines Matching full:to
9 Unless required by applicable law or agreed to in writing, software
17 This document describes a protocol for host to BMC communication via the
19 This protocol is specifically designed to allow a host to request and manage
20 access to a flash device(s) with the specifics of how the host is required to
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
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.
43 OCC, OPAL, ...) has to have a complete driver for the flash controller,
45 chips supported etc... We have 3 copies on the host already in addition to
48 2. There are serious issues of access conflicts to that controller between the
51 3. It's very hard to support "BMC reboots" when doing that
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
60 flash too as nothing can be trusted. So we want to disable it.
62 To address all these, we have implemented a new mechanism that we call mbox.
67 circumstances but we tend to prefer going via memory).
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
74 When set for writing, the BMC makes the window point to a chunk of RAM instead.
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
82 * A read window can be a direct window to the flash controller space (ie.
83 0x3000\_0000) or it can be a window to a RAM image of a flash. It doesn't have
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
93 command to map the write window at a given offset of the flash, the BMC should
95 LPC mapping to point to that buffer.
97 The host can then write to that window directly (updating the BMC memory) and
98 send a command to "commit" those updates to flash.
101 SEEPROM of the POWER9 chip will find what it needs to load HostBoot. The
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.
109 This is Apache licensed but we are keen to see any enhancements you may have.
126 Interrupts can also be raised per write to each data register, for BMC and
129 Two 8 bit registers are present to act as a mask for write triggered
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
147 prior to completing the response may lead to a data race, and must, therefore,
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
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
168 to write to mailbox register data 1. After these two values, any
170 generate an interrupt to the BMC by using bit 0 of its control register and
173 used to poll for messages.
181 BMC should then use its control register to generate an interrupt for
182 the host to notify it of a response.
184 ### Asynchronous BMC to Host Events
186 BMC to host communication is also possible for notification of events
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
204 host requests access to a section of flash. It is worth noting that the host
206 referred to as the active window.
209 MARK_WRITE_ERASED and WRITE_FLUSH commands to identify changed blocks and
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
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
229 less than or equal to that requested by the host, or in the event that there is
231 must not continue to communicate with the BMC. Otherwise, the protocol version
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
250 irrespective of type. A host must not write to a read window. A host may read
257 implicit flush. If the host tries to open a new window with an already active
271 occurred. The host must use the MARK_WRITE_DIRTY command to tell the BMC where
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
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
282 written to flash unless an explicit flush call was successful, a close of an
287 The host is not required to perform an erase before a write command and the
294 to mark dirty or erased this area of flash must fail with the LOCKED_ERROR
296 of flash however changes to a locked area of flash must never be written back
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
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
307 possible for the given event) acknowledge it to inform the BMC it has been
319 The BMC may at some points require access to the flash and the BMC daemon must
360 responses. V1, V2 and V3 of the protocol permit either zero or one commands to
361 be in progress (yet to receive a response).
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
373 response it must consider any in-progress commands to have failed. The host may
382 WRITE_ERROR - Error writing to the backing file system
388 BUSY - Daemon in suspended state (currently unable to access flash)
396 LOCKED_ERROR - Tried to mark dirty or erased locked area of flash
405 Block size refers to an agreed value which is used as a unit for the
407 allows us to specify larger values with fewer command and response fields.
409 In V1 block size is hard coded to 4K.
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
414 host to request a block size is provided such that it can choose an appropriate
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
420 LPC address do so in 16 bits, thus we need at least a 12-bit unit to ensure
422 to specify flash addresses of at least 256MB.
426 Sizes and addresses specified in blocks must be converted to bytes by
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
439 use it. Currently, this means pointing back to BMC flash
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
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
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
490 size is negotiated by another call to GET_MBOX_INFO. (V3)
519 Args 2-3: Requested flash size to access (blocks)
523 Args 2-3: Requested flash size to access (blocks)
534 The flash offset which the host requests access to is always
543 want to use the requested size to pre-load the remainder
548 offset and must be less than or equal to the flash offset
550 to use this information to access any offset which is required.
553 BMC is free to create any sized window but it must contain
555 window is of course preferred and should correspond to
574 Closes the active window. Any further access to the LPC bus
575 address specified to address the previously active window will
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
587 window closed with this flag as first to be
595 Args 0-1: Flash offset to mark from base of flash (blocks)
596 Args 2-5: Number to mark dirty at offset (bytes)
599 Args 0-1: Window offset to mark (blocks)
600 Args 2-3: Number to mark dirty at offset (blocks)
609 can be flushed to backing storage.
612 active window (V2)) and a zero offset refers to the first
616 The host can give a hint to the daemon that is doesn't have to
617 erase a flash area before writing to it by setting ARG[4]. This
618 means that the daemon will blindly perform a write to that area
619 and will not try to erase it before hand. This can be used if
621 example but then wants to perform many small writes.
628 Args 0-1: Flash offset to mark from base of flash (blocks)
629 Args 2-5: Number to mark dirty at offset (bytes)
637 Flushes any dirty/erased blocks in the active window to
640 In V1 this can also be used to mark parts of the flash
642 mark dirty command must be used before a call to flush
653 register 15) to ack
657 The host should use this command to acknowledge BMC events
665 Args 0-1: Window offset to erase (blocks)
666 Args 2-3: Number to erase at offset (blocks)
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
689 Describes a flash with some kind of identifier useful to the
693 as part of the flash name field which the host should expect to
700 Args 0-1: Flash offset to lock (blocks)
701 Args 2-3: Number to lock at offset (blocks)
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
741 Used to inform the host that a BMC reboot has occurred.
748 required to perform protocol version negotiation again. The
754 These events cannot be acknowledged by the host and a call to
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
765 control of the flash (the host isn't able to clear it
770 Used to inform the host that the BMC daemon is ready to
771 accept command requests. The host isn't able to clear