phosphor-mboxd/Documentation/mbox_protocol.md

27 2 specific funtionality). All version specific functionality must also be
144 above), the "Response Code" (Register 13) must be the last register written to.
147 prior to completing the response may lead to a data race, and must, therefore,
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
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
192 defined as being able to be acknowledged by the host must be with 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
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
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
244 window commands the BMC must guarantee that the window provided contains data
250 irrespective of type. A host must not write to a read window. A host may read
251 from a write window and the BMC must guarantee that the window reflects what
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
261 previously active window must no longer be accessed.
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)
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
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
281 for the active window. The host must not assume that any changes have been
288 BMC must ensure that a write performs as expected - that is if an erase is
289 required before a write then the BMC must perform this itself (unless 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
299 of flash which is not clean in the current window must fail with PARAM_ERROR.
300 Locked flash regions must persist across a BMC reboot or daemon restart. It is
306 host a change in state which it should take notice of. The host must (if
310 If the BMC raises a BMC Reboot event then the host must renegotiate the
313 If the BMC raises a BMC Windows Reset event then the host must
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
321 the BMC daemons back. When this event is set the host must assume that the
363 For generality, the host must generate a sequence number that is unique with
366 valid. The BMC's response to a command must contain the same sequence number
371 invalid sequence number. For all other cases, the BMC must respond with
373 response it must consider any in-progress commands to have failed. The host may
400 - All responses must have a valid return code in byte 13
410 In V2 it is variable and must be queried with the GET_MBOX_INFO command.
413 command response. The host must respect the daemons choice. The ability for the
417 Note that for simplicity block size must always be a power-of-2.
418 Block size must also be greater than or equal to 4K. This is due to the
426 Sizes and addresses specified in blocks must be converted to bytes by
483 		must choose some reasonable value.
489 		size which must be used for all further requests until a new
544 		of the request. The host must not access past the end of the
548 		offset and must be less than or equal to the flash offset
553 		BMC is free to create any sized window but it must contain
577 		write window then the BMC must perform an implicit flush.
607 		occur over the LPC bus. The host must explicitly notify
614 		window then the command must not succeed.
642 		mark dirty command must be used before a call to flush
644 		exceeds the size of the active window then the command must not
678 		the active window then the command must not succeed.
709 		must fail with PARAM_ERROR.
721 Events which must be ACKed:
736 Events which must be ACKed:
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
749 	host must not assume that any commands which didn't respond as such
764 	The BMC daemon must clear this bit itself when it regains
767 	The host must not assume that the contents of the active window
772 	this bit through an acknowledge command, the BMC daemon must