| Message ID | 20171004004520.18593-1-sjitindarsingh@gmail.com |
|---|---|
| State | Not Applicable |
| Headers | show |
| Series | docs: Specify V3 of the mbox protocol | expand |
On Wed, 2017-10-04 at 11:45 +1100, Suraj Jitindar Singh wrote: > Version 3 of the mbox protocol makes four protocol changes: > - Add a requested block size argument to GET_MBOX_INFO > - Add a no erase argument to MARK_DIRTY > - Add a GET_FLASH_NAME command and support multiple flash devices > - Add a MARK_LOCKED command > > Requested Block Size: > The requested block size argument has been added to the GET_MBOX_INFO > command to allow the host to request a specified block size which might > be required to allow data manipulation at a finer granularity. The > daemon should take this into account when choosing a block size for use > which it will specify in the response as before. The daemon has final > say and the host must use the block size the daemon chooses. > > No Erase: > The no erase argument to the mark dirty command allows a host to specify > that an area of flash should not be erased before being written to, as is > the default behaviour. This can be used when a host has already erased a > large area and then performs many small writes which would normally mean > many erases due to the implicit erase before write, making this slow. > > Add GET_FLASH_NAME command: > The ability to support multiple flash devices has been added so that the > mbox protocol can be used to arbitrate access from the host to a number > of flash devices which the daemon has access to. To facilitate this the > GET_FLASH_INFO, CREATE_{READ/WRITE}_WINDOW, and MARK_LOCKED commands now > take a flash ID, with the number of flash IDs allocated returned by the > GET_MBOX_INFO commands. There is also a new command GET_FLASH_NAME used > to convert a flash ID to a flash name. > > Add MARK_LOCKED command: > The MARK_LOCKED command has been added to allow an area(s) of flash to be > locked, that is that area must be treated as read only and the host is > not allowed to dirty or erase any windows which map that area of flash. > Additionally another error code LOCKED_ERROR was added to be returned > when the host does try to dirty or erase a locked area. > > The host cannot lock a currently dirty or erased area of the current > write window as it is not defined if the clean/dirty/erased value is > what should actually be "locked". > > A locked area of flash remains so until the daemon receives an > mboxctl --clear-locked command and the locked areas are stored in a file > on the BMC filesystem to ensure persistence across BMC reboots/daemon > crashes. > > Multiple flash device support proposed and defined by: > > William A. Kennington III <wak@google.com> > > Change-Id: I898698840dec221ae20e33943bb28e65abc4fe37 > Signed-off-by: Suraj Jitindar Singh <sjitindarsingh@gmail.com> Reviewed-by: Andrew Jeffery <andrew@aj.id.au> But everyone else: please chime in. Cheers, Andrew > --- > Documentation/mbox_protocol.md | 163 ++++++++++++++++++++++++++++++++--------- > 1 file changed, 127 insertions(+), 36 deletions(-) > > diff --git a/Documentation/mbox_protocol.md b/Documentation/mbox_protocol.md > index bcd70a8..797ac7b 100644 > --- a/Documentation/mbox_protocol.md > +++ b/Documentation/mbox_protocol.md > @@ -17,19 +17,22 @@ limitations under the License. > 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. > +access to a flash device(s) 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). > +Version specific protocol functionalities are represented by the version number > +in brackets next to the definition of the functionality. (e.g. (V2) for version > +2 specific funtionality). All version specific functionality must also be > +implemented by proceeding versions up to and not including the version a command > +was removed. > > ## 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. > +for the host to control access to the flash device(s). > > 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. > @@ -215,9 +218,11 @@ communicate a change in state. > 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. > +4K, in V2 the BMC chooses and in V3 the host is allowed to request a specific > +block size with the actual size chosen communicated back 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. > > When invoking `MBOX_GET_INFO` the host must provide the BMC its highest > supported version of the protocol. The BMC must respond with a protocol version > @@ -231,10 +236,13 @@ version by issuing a subsequent `MBOX_GET_INFO` command. > ### 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. > +the flash offset it would like to access with the CREATE_{READ,WRITE}_WINDOW > +commands. 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. On returning success to either of the create > +window commands the BMC must guarantee that the window provided contains data > +which correctly represents the state of flash at the time the response is given. > > 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 > @@ -278,7 +286,19 @@ 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. > +required before a write then the BMC must perform this itself (unless the > +no_erase flag is set in the MARK_WRITE_DIRTY command in which case the BMC will > +blindly write without a prior erase (V3)). > + > +The host may lock an area of flash using the MARK_LOCKED command. Any attempt > +to mark dirty or erased this area of flash must fail with the LOCKED_ERROR > +response code. The host may open a write window which contains a locked area > +of flash however changes to a locked area of flash must never be written back > +to the backing data source (i.e. that area of flash must be treated as read > +only with respect to the backing store at all times). An attempt to lock an area > +of flash which is not clean in the current window must fail with PARAM_ERROR. > +Locked flash regions must persist across a BMC reboot or daemon restart. It is > +only possible to clear the lock state through a clear_locked dbus command. (V3) > > ### BMC Events > > @@ -316,6 +336,8 @@ MARK_WRITE_DIRTY 0x07 > WRITE_FLUSH 0x08 > BMC_EVENT_ACK 0x09 > > MARK_WRITE_ERASED 0x0a (V2) > > +GET_FLASH_NAME 0x0b (V3) > > +MARK_LOCKED 0x0c (V3) > ``` > > ### Responses > > @@ -329,13 +351,14 @@ TIMEOUT 5 > > > BUSY 6 (V2) > > > WINDOW_ERROR 7 (V2) > > > SEQ_ERROR 8 (V2) > > > +LOCKED_ERROR 9 (V3) > ``` > > ### Sequence Numbers > > Sequence numbers are included in messages for correlation of commands and > -responses. V1 and V2 of the protocol permit either zero or one commands to be > -in progress (yet to receive a response). > +responses. V1, V2 and V3 of the protocol permit either zero or one commands to > +be in progress (yet to receive a response). > > For generality, the host must generate a sequence number that is unique with > respect to the previous command (one that has received a response) and any > > @@ -368,6 +391,10 @@ BUSY - Daemon in suspended state (currently unable to access flash) > > WINDOW_ERROR - Command not valid for active window or no active window > > - Try opening an appropriate window and retrying the command > > > +SEQ_ERROR - Invalid sequence number supplied with command > + > > +LOCKED_ERROR - Tried to mark dirty or erased locked area of flash > + > ### Information > - All multibyte messages are LSB first (little endian) > - All responses must have a valid return code in byte 13 > @@ -381,6 +408,12 @@ allows us to specify larger values with fewer command and response fields. > > In V1 block size is hard coded to 4K. > In V2 it is variable and must be queried with the GET_MBOX_INFO command. > +In V3 the host can request a given block size however it is ultimately up to > +the daemon to choose a block size which is returned as part of the GET_MBOX_INFO > +command response. The host must respect the daemons choice. The ability for the > +host to request a block size is provided such that it can choose an appropriate > +size to be able to utilise commands which only operate at the block level. > + > Note that for simplicity block size must always be a power-of-2. > Block size must also be greater than or equal to 4K. This is due to the > fact that we have a 28-bit LPC address space and commands which return an > @@ -395,8 +428,7 @@ multiplying by the block size. > ``` > Command: > > RESET_STATE > > - Implemented in Versions: > > - V1, V2 > > > + Added in: V1 > > Arguments: > > - > > Response: > @@ -409,8 +441,7 @@ Command: > > Command: > > GET_MBOX_INFO > > - Implemented in Versions: > > - V1, V2 > > > + Added in: V1 > > Arguments: > > V1: > > Args 0: API version > @@ -418,6 +449,10 @@ Command: > > V2: > > Args 0: API version > > > + V3: > > + Args 0: API version > > + Args 1: Requested block size (shift) > + > > Response: > > V1: > > Args 0: API version > @@ -430,6 +465,14 @@ Command: > > Args 3-4: reserved > > Args 5: Block size as power of two (encoded as a shift) > > Args 6-7: Suggested Timeout (seconds) > + > > + V3: > > + Args 0: API version > > + Args 1-2: reserved > > + Args 3-4: reserved > > + Args 5: Block size as power of two (encoded as a shift) > > + Args 6-7: Suggested Timeout (seconds) > > + Args 8: Num Allocated Flash IDs > > Notes: > > The suggested timeout is a hint to the host as to how long > > it should wait after issuing a command to the BMC before it > @@ -439,25 +482,34 @@ Command: > > > the BMC does not wish to provide a hint in which case the host > > must choose some reasonable value. > > > + The host may desire a specific block size and thus can request > > + this by giving a hint to the daemon (may be zero). The daemon > > + may use this to select the block size which it will use however > > + is free to ignore it. The value in the response is the block > > + size which must be used for all further requests until a new > > > + size is negotiated by another call to GET_MBOX_INFO. (V3) > + > Command: > > GET_FLASH_INFO > > - Implemented in Versions: > > - V1, V2 > > > + Added in: V1 > > Arguments: > > + V1, V2: > > - > + > > + V3: > > + Args 0: Flash ID > > Response: > > V1: > > Args 0-3: Flash size (bytes) > > Args 4-7: Erase granule (bytes) > > > - V2: > > + V2, V3: > > Args 0-1: Flash size (blocks) > > Args 2-3: Erase granule (blocks) > > Command: > > CREATE_{READ/WRITE}_WINDOW > > - Implemented in Versions: > > - V1, V2 > > > + Added in: V1 > > Arguments: > > V1: > > Args 0-1: Requested flash offset (blocks) > @@ -466,11 +518,15 @@ Command: > > Args 0-1: Requested flash offset (blocks) > > Args 2-3: Requested flash size to access (blocks) > > > + V3: > > + Args 0-1: Requested flash offset (blocks) > > + Args 2-3: Requested flash size to access (blocks) > > + Args 4: Flash ID > > Response: > > V1: > > Args 0-1: LPC bus address of window (blocks) > > > - V2: > > + V2, V3: > > Args 0-1: LPC bus address of window (blocks) > > Args 2-3: Window size (blocks) > > Args 4-5: Flash offset mapped by window (blocks) > @@ -505,8 +561,7 @@ Command: > > Command: > > CLOSE_WINDOW > > - Implemented in Versions: > > - V1, V2 > > > + Added in: V1 > > Arguments: > > V1: > > - > @@ -534,8 +589,7 @@ Command: > > Command: > > MARK_WRITE_DIRTY > > - Implemented in Versions: > > - V1, V2 > > > + Added in: V1 > > Arguments: > > V1: > > Args 0-1: Flash offset to mark from base of flash (blocks) > @@ -544,6 +598,7 @@ Command: > > V2: > > Args 0-1: Window offset to mark (blocks) > > Args 2-3: Number to mark dirty at offset (blocks) > > + Args 4 : Don't Erase Before Write (V3) > > > Response: > > - > @@ -558,10 +613,16 @@ Command: > > block. If the offset + number exceeds the size of the active > > window then the command must not succeed. > > > + The host can give a hint to the daemon that is doesn't have to > > + erase a flash area before writing to it by setting ARG[4]. This > > + means that the daemon will blindly perform a write to that area > > + and will not try to erase it before hand. This can be used if > > + the host knows that a large area has already been erased for > > + example but then wants to perform many small writes. > + > Command > > WRITE_FLUSH > > - Implemented in Versions: > > - V1, V2 > > > + Added in: V1 > > Arguments: > > V1: > > Args 0-1: Flash offset to mark from base of flash (blocks) > @@ -586,8 +647,7 @@ Command > > Command: > > BMC_EVENT_ACK > > - Implemented in Versions: > > - V1, V2 > > > + Added in: V1 > > Arguments: > > > Args 0: Bits in the BMC status byte (mailbox data > > register 15) to ack > @@ -599,8 +659,7 @@ Command: > > Command: > > MARK_WRITE_ERASED > > - Implemented in Versions: > > - V2 > > > + Added in: V2 > > Arguments: > > V2: > > Args 0-1: Window offset to erase (blocks) > @@ -617,6 +676,38 @@ Command: > > 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. > + > +Command: > > + GET_FLASH_NAME > > > + Added in: V3 > > + Arguments: > > + Args 0: Flash ID > > + Response: > > + Args 0 : Flash Name Length (bytes) > > + Args 1-10: Flash Name / UID > > + Notes: > > + Describes a flash with some kind of identifier useful to the > > + host system. This is typically a null-padded string. > + > > + The length in the response is the number of response arguments > > + as part of the flash name field which the host should expect to > > + have been populated. > + > +Command: > > + MARK_LOCKED > > > + Added in: V3 > > + Arguments: > > + Args 0-1: Flash offset to lock (blocks) > > + Args 2-3: Number to lock at offset (blocks) > > + Args 4: Flash ID > > + Response: > > + - > > + Notes: > > + Lock an area of flash so that the host can't mark it dirty or > > + erased. If the requested area is within the current window and > > + that area is currently marked dirty or erased then this command > > + must fail with PARAM_ERROR. > + > ``` > > ### BMC Events in Detail: > @@ -627,7 +718,7 @@ on that register, or otherwise be polling it. > > #### Bit Definitions: > > -Events which should be ACKed: > +Events which must be ACKed: > ``` > 0x01: BMC Reboot > 0x02: BMC Windows Reset (V2)
Acked-by: Adriana Kobylak <anoo@us.ibm <mailto:anoo@us.ibm.com>.com <mailto:anoo@us.ibm.com>> > On Oct 5, 2017, at 1:10 AM, Andrew Jeffery <andrew@aj.id.au> wrote: > > On Wed, 2017-10-04 at 11:45 +1100, Suraj Jitindar Singh wrote: >> Version 3 of the mbox protocol makes four protocol changes: >> - Add a requested block size argument to GET_MBOX_INFO >> - Add a no erase argument to MARK_DIRTY >> - Add a GET_FLASH_NAME command and support multiple flash devices >> - Add a MARK_LOCKED command >> >> Requested Block Size: >> The requested block size argument has been added to the GET_MBOX_INFO >> command to allow the host to request a specified block size which might >> be required to allow data manipulation at a finer granularity. The >> daemon should take this into account when choosing a block size for use >> which it will specify in the response as before. The daemon has final >> say and the host must use the block size the daemon chooses. >> >> No Erase: >> The no erase argument to the mark dirty command allows a host to specify >> that an area of flash should not be erased before being written to, as is >> the default behaviour. This can be used when a host has already erased a >> large area and then performs many small writes which would normally mean >> many erases due to the implicit erase before write, making this slow. >> >> Add GET_FLASH_NAME command: >> The ability to support multiple flash devices has been added so that the >> mbox protocol can be used to arbitrate access from the host to a number >> of flash devices which the daemon has access to. To facilitate this the >> GET_FLASH_INFO, CREATE_{READ/WRITE}_WINDOW, and MARK_LOCKED commands now >> take a flash ID, with the number of flash IDs allocated returned by the >> GET_MBOX_INFO commands. There is also a new command GET_FLASH_NAME used >> to convert a flash ID to a flash name. >> >> Add MARK_LOCKED command: >> The MARK_LOCKED command has been added to allow an area(s) of flash to be >> locked, that is that area must be treated as read only and the host is >> not allowed to dirty or erase any windows which map that area of flash. >> Additionally another error code LOCKED_ERROR was added to be returned >> when the host does try to dirty or erase a locked area. >> >> The host cannot lock a currently dirty or erased area of the current >> write window as it is not defined if the clean/dirty/erased value is >> what should actually be "locked". >> >> A locked area of flash remains so until the daemon receives an >> mboxctl --clear-locked command and the locked areas are stored in a file >> on the BMC filesystem to ensure persistence across BMC reboots/daemon >> crashes. >> >> Multiple flash device support proposed and defined by: >>> William A. Kennington III <wak@google.com> >> >> Change-Id: I898698840dec221ae20e33943bb28e65abc4fe37 >> Signed-off-by: Suraj Jitindar Singh <sjitindarsingh@gmail.com> > > Reviewed-by: Andrew Jeffery <andrew@aj.id.au <mailto:andrew@aj.id.au>> > > But everyone else: please chime in. > > Cheers, > > Andrew > >> --- >> Documentation/mbox_protocol.md | 163 ++++++++++++++++++++++++++++++++--------- >> 1 file changed, 127 insertions(+), 36 deletions(-) >> >> diff --git a/Documentation/mbox_protocol.md b/Documentation/mbox_protocol.md >> index bcd70a8..797ac7b 100644 >> --- a/Documentation/mbox_protocol.md >> +++ b/Documentation/mbox_protocol.md >> @@ -17,19 +17,22 @@ limitations under the License. >> 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. >> +access to a flash device(s) 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). >> +Version specific protocol functionalities are represented by the version number >> +in brackets next to the definition of the functionality. (e.g. (V2) for version >> +2 specific funtionality). All version specific functionality must also be >> +implemented by proceeding versions up to and not including the version a command >> +was removed. >> >> ## 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. >> +for the host to control access to the flash device(s). >> >> 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. >> @@ -215,9 +218,11 @@ communicate a change in state. >> 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. >> +4K, in V2 the BMC chooses and in V3 the host is allowed to request a specific >> +block size with the actual size chosen communicated back 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. >> >> When invoking `MBOX_GET_INFO` the host must provide the BMC its highest >> supported version of the protocol. The BMC must respond with a protocol version >> @@ -231,10 +236,13 @@ version by issuing a subsequent `MBOX_GET_INFO` command. >> ### 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. >> +the flash offset it would like to access with the CREATE_{READ,WRITE}_WINDOW >> +commands. 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. On returning success to either of the create >> +window commands the BMC must guarantee that the window provided contains data >> +which correctly represents the state of flash at the time the response is given. >> >> 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 >> @@ -278,7 +286,19 @@ 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. >> +required before a write then the BMC must perform this itself (unless the >> +no_erase flag is set in the MARK_WRITE_DIRTY command in which case the BMC will >> +blindly write without a prior erase (V3)). >> + >> +The host may lock an area of flash using the MARK_LOCKED command. Any attempt >> +to mark dirty or erased this area of flash must fail with the LOCKED_ERROR >> +response code. The host may open a write window which contains a locked area >> +of flash however changes to a locked area of flash must never be written back >> +to the backing data source (i.e. that area of flash must be treated as read >> +only with respect to the backing store at all times). An attempt to lock an area >> +of flash which is not clean in the current window must fail with PARAM_ERROR. >> +Locked flash regions must persist across a BMC reboot or daemon restart. It is >> +only possible to clear the lock state through a clear_locked dbus command. (V3) >> >> ### BMC Events >> >> @@ -316,6 +336,8 @@ MARK_WRITE_DIRTY 0x07 >> WRITE_FLUSH 0x08 >> BMC_EVENT_ACK 0x09 >>> MARK_WRITE_ERASED 0x0a (V2) >>> +GET_FLASH_NAME 0x0b (V3) >>> +MARK_LOCKED 0x0c (V3) >> ``` >> >> ### Responses >>> @@ -329,13 +351,14 @@ TIMEOUT 5 >>>> BUSY 6 (V2) >>>> WINDOW_ERROR 7 (V2) >>>> SEQ_ERROR 8 (V2) >>>> +LOCKED_ERROR 9 (V3) >> ``` >> >> ### Sequence Numbers >> >> Sequence numbers are included in messages for correlation of commands and >> -responses. V1 and V2 of the protocol permit either zero or one commands to be >> -in progress (yet to receive a response). >> +responses. V1, V2 and V3 of the protocol permit either zero or one commands to >> +be in progress (yet to receive a response). >> >> For generality, the host must generate a sequence number that is unique with >> respect to the previous command (one that has received a response) and any >>> @@ -368,6 +391,10 @@ BUSY - Daemon in suspended state (currently unable to access flash) >>> WINDOW_ERROR - Command not valid for active window or no active window >>> - Try opening an appropriate window and retrying the command >> >>> +SEQ_ERROR - Invalid sequence number supplied with command >> + >>> +LOCKED_ERROR - Tried to mark dirty or erased locked area of flash >> + >> ### Information >> - All multibyte messages are LSB first (little endian) >> - All responses must have a valid return code in byte 13 >> @@ -381,6 +408,12 @@ allows us to specify larger values with fewer command and response fields. >> >> In V1 block size is hard coded to 4K. >> In V2 it is variable and must be queried with the GET_MBOX_INFO command. >> +In V3 the host can request a given block size however it is ultimately up to >> +the daemon to choose a block size which is returned as part of the GET_MBOX_INFO >> +command response. The host must respect the daemons choice. The ability for the >> +host to request a block size is provided such that it can choose an appropriate >> +size to be able to utilise commands which only operate at the block level. >> + >> Note that for simplicity block size must always be a power-of-2. >> Block size must also be greater than or equal to 4K. This is due to the >> fact that we have a 28-bit LPC address space and commands which return an >> @@ -395,8 +428,7 @@ multiplying by the block size. >> ``` >> Command: >>> RESET_STATE >>> - Implemented in Versions: >>> - V1, V2 >>>> + Added in: V1 >>> Arguments: >>> - >>> Response: >> @@ -409,8 +441,7 @@ Command: >> >> Command: >>> GET_MBOX_INFO >>> - Implemented in Versions: >>> - V1, V2 >>>> + Added in: V1 >>> Arguments: >>> V1: >>> Args 0: API version >> @@ -418,6 +449,10 @@ Command: >>> V2: >>> Args 0: API version >> >>> + V3: >>> + Args 0: API version >>> + Args 1: Requested block size (shift) >> + >>> Response: >>> V1: >>> Args 0: API version >> @@ -430,6 +465,14 @@ Command: >>> Args 3-4: reserved >>> Args 5: Block size as power of two (encoded as a shift) >>> Args 6-7: Suggested Timeout (seconds) >> + >>> + V3: >>> + Args 0: API version >>> + Args 1-2: reserved >>> + Args 3-4: reserved >>> + Args 5: Block size as power of two (encoded as a shift) >>> + Args 6-7: Suggested Timeout (seconds) >>> + Args 8: Num Allocated Flash IDs >>> Notes: >>> The suggested timeout is a hint to the host as to how long >>> it should wait after issuing a command to the BMC before it >> @@ -439,25 +482,34 @@ Command: >>>> the BMC does not wish to provide a hint in which case the host >>> must choose some reasonable value. >> >>> + The host may desire a specific block size and thus can request >>> + this by giving a hint to the daemon (may be zero). The daemon >>> + may use this to select the block size which it will use however >>> + is free to ignore it. The value in the response is the block >>> + size which must be used for all further requests until a new >>>> + size is negotiated by another call to GET_MBOX_INFO. (V3) >> + >> Command: >>> GET_FLASH_INFO >>> - Implemented in Versions: >>> - V1, V2 >>>> + Added in: V1 >>> Arguments: >>> + V1, V2: >>> - >> + >>> + V3: >>> + Args 0: Flash ID >>> Response: >>> V1: >>> Args 0-3: Flash size (bytes) >>> Args 4-7: Erase granule (bytes) >> >>> - V2: >>> + V2, V3: >>> Args 0-1: Flash size (blocks) >>> Args 2-3: Erase granule (blocks) >> >> Command: >>> CREATE_{READ/WRITE}_WINDOW >>> - Implemented in Versions: >>> - V1, V2 >>>> + Added in: V1 >>> Arguments: >>> V1: >>> Args 0-1: Requested flash offset (blocks) >> @@ -466,11 +518,15 @@ Command: >>> Args 0-1: Requested flash offset (blocks) >>> Args 2-3: Requested flash size to access (blocks) >> >>> + V3: >>> + Args 0-1: Requested flash offset (blocks) >>> + Args 2-3: Requested flash size to access (blocks) >>> + Args 4: Flash ID >>> Response: >>> V1: >>> Args 0-1: LPC bus address of window (blocks) >> >>> - V2: >>> + V2, V3: >>> Args 0-1: LPC bus address of window (blocks) >>> Args 2-3: Window size (blocks) >>> Args 4-5: Flash offset mapped by window (blocks) >> @@ -505,8 +561,7 @@ Command: >> >> Command: >>> CLOSE_WINDOW >>> - Implemented in Versions: >>> - V1, V2 >>>> + Added in: V1 >>> Arguments: >>> V1: >>> - >> @@ -534,8 +589,7 @@ Command: >> >> Command: >>> MARK_WRITE_DIRTY >>> - Implemented in Versions: >>> - V1, V2 >>>> + Added in: V1 >>> Arguments: >>> V1: >>> Args 0-1: Flash offset to mark from base of flash (blocks) >> @@ -544,6 +598,7 @@ Command: >>> V2: >>> Args 0-1: Window offset to mark (blocks) >>> Args 2-3: Number to mark dirty at offset (blocks) >>> + Args 4 : Don't Erase Before Write (V3) >> >>> Response: >>> - >> @@ -558,10 +613,16 @@ Command: >>> block. If the offset + number exceeds the size of the active >>> window then the command must not succeed. >> >>> + The host can give a hint to the daemon that is doesn't have to >>> + erase a flash area before writing to it by setting ARG[4]. This >>> + means that the daemon will blindly perform a write to that area >>> + and will not try to erase it before hand. This can be used if >>> + the host knows that a large area has already been erased for >>> + example but then wants to perform many small writes. >> + >> Command >>> WRITE_FLUSH >>> - Implemented in Versions: >>> - V1, V2 >>>> + Added in: V1 >>> Arguments: >>> V1: >>> Args 0-1: Flash offset to mark from base of flash (blocks) >> @@ -586,8 +647,7 @@ Command >> >> Command: >>> BMC_EVENT_ACK >>> - Implemented in Versions: >>> - V1, V2 >>>> + Added in: V1 >>> Arguments: >>>> Args 0: Bits in the BMC status byte (mailbox data >>> register 15) to ack >> @@ -599,8 +659,7 @@ Command: >> >> Command: >>> MARK_WRITE_ERASED >>> - Implemented in Versions: >>> - V2 >>>> + Added in: V2 >>> Arguments: >>> V2: >>> Args 0-1: Window offset to erase (blocks) >> @@ -617,6 +676,38 @@ Command: >>> 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. >> + >> +Command: >>> + GET_FLASH_NAME >>>> + Added in: V3 >>> + Arguments: >>> + Args 0: Flash ID >>> + Response: >>> + Args 0 : Flash Name Length (bytes) >>> + Args 1-10: Flash Name / UID >>> + Notes: >>> + Describes a flash with some kind of identifier useful to the >>> + host system. This is typically a null-padded string. >> + >>> + The length in the response is the number of response arguments >>> + as part of the flash name field which the host should expect to >>> + have been populated. >> + >> +Command: >>> + MARK_LOCKED >>>> + Added in: V3 >>> + Arguments: >>> + Args 0-1: Flash offset to lock (blocks) >>> + Args 2-3: Number to lock at offset (blocks) >>> + Args 4: Flash ID >>> + Response: >>> + - >>> + Notes: >>> + Lock an area of flash so that the host can't mark it dirty or >>> + erased. If the requested area is within the current window and >>> + that area is currently marked dirty or erased then this command >>> + must fail with PARAM_ERROR. >> + >> ``` >> >> ### BMC Events in Detail: >> @@ -627,7 +718,7 @@ on that register, or otherwise be polling it. >> >> #### Bit Definitions: >> >> -Events which should be ACKed: >> +Events which must be ACKed: >> ``` >> 0x01: BMC Reboot >> 0x02: BMC Windows Reset (V2) <html><head><meta http-equiv="Content-Type" content="text/html charset=us-ascii"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><span class="" style="font-family: ArialUnicodeMS;">Acked-by: Adriana Kobylak <</span><a href="mailto:anoo@us.ibm.com" class=""><font face="ArialUnicodeMS" class="" style="font-family: ArialUnicodeMS;">anoo@us.</font><font face="ArialUnicodeMS" class="">ibm</font></a><span style="font-family: ArialUnicodeMS;" class=""><a href="mailto:anoo@us.ibm.com" class="">.com</a>></span><div class=""><font face="ArialUnicodeMS" class=""><br class=""></font><div><blockquote type="cite" class=""><div class="">On Oct 5, 2017, at 1:10 AM, Andrew Jeffery <<a href="mailto:andrew@aj.id.au" class="">andrew@aj.id.au</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><span style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">On Wed, 2017-10-04 at 11:45 +1100, Suraj Jitindar Singh wrote:</span><br style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><blockquote type="cite" style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px;" class="">Version 3 of the mbox protocol makes four protocol changes:<br class=""> - Add a requested block size argument to GET_MBOX_INFO<br class=""> - Add a no erase argument to MARK_DIRTY<br class=""> - Add a GET_FLASH_NAME command and support multiple flash devices<br class=""> - Add a MARK_LOCKED command<br class=""><br class="">Requested Block Size:<br class="">The requested block size argument has been added to the GET_MBOX_INFO<br class="">command to allow the host to request a specified block size which might<br class="">be required to allow data manipulation at a finer granularity. The<br class="">daemon should take this into account when choosing a block size for use<br class="">which it will specify in the response as before. The daemon has final<br class="">say and the host must use the block size the daemon chooses.<br class=""><br class="">No Erase:<br class="">The no erase argument to the mark dirty command allows a host to specify<br class="">that an area of flash should not be erased before being written to, as is<br class="">the default behaviour. This can be used when a host has already erased a<br class="">large area and then performs many small writes which would normally mean<br class="">many erases due to the implicit erase before write, making this slow.<br class=""><br class="">Add GET_FLASH_NAME command:<br class="">The ability to support multiple flash devices has been added so that the<br class="">mbox protocol can be used to arbitrate access from the host to a number<br class="">of flash devices which the daemon has access to. To facilitate this the<br class="">GET_FLASH_INFO, CREATE_{READ/WRITE}_WINDOW, and MARK_LOCKED commands now<br class="">take a flash ID, with the number of flash IDs allocated returned by the<br class="">GET_MBOX_INFO commands. There is also a new command GET_FLASH_NAME used<br class="">to convert a flash ID to a flash name.<br class=""><br class="">Add MARK_LOCKED command:<br class="">The MARK_LOCKED command has been added to allow an area(s) of flash to be<br class="">locked, that is that area must be treated as read only and the host is<br class="">not allowed to dirty or erase any windows which map that area of flash.<br class="">Additionally another error code LOCKED_ERROR was added to be returned<br class="">when the host does try to dirty or erase a locked area.<br class=""><br class="">The host cannot lock a currently dirty or erased area of the current<br class="">write window as it is not defined if the clean/dirty/erased value is<br class="">what should actually be "locked".<br class=""><br class="">A locked area of flash remains so until the daemon receives an<br class="">mboxctl --clear-locked command and the locked areas are stored in a file<br class="">on the BMC filesystem to ensure persistence across BMC reboots/daemon<br class="">crashes.<br class=""><br class="">Multiple flash device support proposed and defined by:<br class=""><blockquote type="cite" class="">William A. Kennington III <<a href="mailto:wak@google.com" class="">wak@google.com</a>><br class=""></blockquote><br class="">Change-Id: I898698840dec221ae20e33943bb28e65abc4fe37<br class="">Signed-off-by: Suraj Jitindar Singh <<a href="mailto:sjitindarsingh@gmail.com" class="">sjitindarsingh@gmail.com</a>><br class=""></blockquote><br style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">Reviewed-by: Andrew Jeffery <</span><a href="mailto:andrew@aj.id.au" style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px;" class="">andrew@aj.id.au</a><span style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">></span><br style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><br style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">But everyone else: please chime in.</span><br style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><br style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">Cheers,</span><br style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><br style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">Andrew</span><br style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><br style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><blockquote type="cite" style="font-family: ArialUnicodeMS; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px;" class="">---<br class=""> Documentation/mbox_protocol.md | 163 ++++++++++++++++++++++++++++++++---------<br class=""> 1 file changed, 127 insertions(+), 36 deletions(-)<br class=""><br class="">diff --git a/Documentation/mbox_protocol.md b/Documentation/mbox_protocol.md<br class="">index bcd70a8..797ac7b 100644<br class="">--- a/Documentation/mbox_protocol.md<br class="">+++ b/Documentation/mbox_protocol.md<br class="">@@ -17,19 +17,22 @@ limitations under the License.<br class=""> This document describes a protocol for host to BMC communication via the<br class=""> mailbox registers present on the Aspeed 2400 and 2500 chips.<br class=""> This protocol is specifically designed to allow a host to request and manage<br class="">-access to the flash with the specifics of how the host is required to control<br class="">-this described below.<br class="">+access to a flash device(s) with the specifics of how the host is required to<br class="">+control this described below.<br class=""> <br class=""> ## Version<br class=""> <br class="">-Both version 1 and version 2 of the protocol are described below with version 2<br class="">-specificities represented with V2 in brackets - (V2).<br class="">+Version specific protocol functionalities are represented by the version number<br class="">+in brackets next to the definition of the functionality. (e.g. (V2) for version<br class="">+2 specific funtionality). All version specific functionality must also be<br class="">+implemented by proceeding versions up to and not including the version a command<br class="">+was removed.<br class=""> <br class=""> ## Problem Overview<br class=""> <br class=""> "mbox" is the name we use to represent a protocol we have established between<br class=""> the host and the BMC via the Aspeed mailbox registers. This protocol is used<br class="">-for the host to control the flash.<br class="">+for the host to control access to the flash device(s).<br class=""> <br class=""> Prior to the mbox protocol, the host uses a backdoor into the BMC address space<br class=""> (the iLPC-to-AHB bridge) to directly manipulate the BMCs own flash controller.<br class="">@@ -215,9 +218,11 @@ communicate a change in state.<br class=""> Given that a majority of command and response arguments are specified as a<br class=""> multiple of block size it is necessary for the host and BMC to agree on a<br class=""> protocol version as this determines the block size. In V1 it is hard coded at<br class="">-4K and in V2 the BMC chooses and specifies this to the host as a response<br class="">-argument to `MBOX_GET_INFO`. Thus the host must always call `MBOX_GET_INFO`<br class="">-before any other command which specifies an argument in block size.<br class="">+4K, in V2 the BMC chooses and in V3 the host is allowed to request a specific<br class="">+block size with the actual size chosen communicated back to the host as a<br class="">+response argument to `MBOX_GET_INFO`. Thus the host must always call<br class="">+`MBOX_GET_INFO` before any other command which specifies an argument in block<br class="">+size.<br class=""> <br class=""> When invoking `MBOX_GET_INFO` the host must provide the BMC its highest<br class=""> supported version of the protocol. The BMC must respond with a protocol version<br class="">@@ -231,10 +236,13 @@ version by issuing a subsequent `MBOX_GET_INFO` command.<br class=""> ### Window Management<br class=""> <br class=""> In order to access flash contents, the host must request a window be opened at<br class="">-the flash offset it would like to access. The host may give a hint as to how<br class="">-much data it would like to access or otherwise set this argument to zero. The<br class="">-BMC must respond with the LPC bus address to access this window and the<br class="">-window size. The host must not access past the end of the active window.<br class="">+the flash offset it would like to access with the CREATE_{READ,WRITE}_WINDOW<br class="">+commands. The host may give a hint as to how much data it would like to access<br class="">+or otherwise set this argument to zero. The BMC must respond with the LPC bus<br class="">+address to access this window and the window size. The host must not access<br class="">+past the end of the active window. On returning success to either of the create<br class="">+window commands the BMC must guarantee that the window provided contains data<br class="">+which correctly represents the state of flash at the time the response is given.<br class=""> <br class=""> There is only ever one active window which is the window created by the most<br class=""> recent CREATE_READ_WINDOW or CREATE_WRITE_WINDOW call which succeeded. Even<br class="">@@ -278,7 +286,19 @@ contents cannot be guaranteed.<br class=""> <br class=""> The host is not required to perform an erase before a write command and the<br class=""> BMC must ensure that a write performs as expected - that is if an erase is<br class="">-required before a write then the BMC must perform this itself.<br class="">+required before a write then the BMC must perform this itself (unless the<br class="">+no_erase flag is set in the MARK_WRITE_DIRTY command in which case the BMC will<br class="">+blindly write without a prior erase (V3)).<br class="">+<br class="">+The host may lock an area of flash using the MARK_LOCKED command. Any attempt<br class="">+to mark dirty or erased this area of flash must fail with the LOCKED_ERROR<br class="">+response code. The host may open a write window which contains a locked area<br class="">+of flash however changes to a locked area of flash must never be written back<br class="">+to the backing data source (i.e. that area of flash must be treated as read<br class="">+only with respect to the backing store at all times). An attempt to lock an area<br class="">+of flash which is not clean in the current window must fail with PARAM_ERROR.<br class="">+Locked flash regions must persist across a BMC reboot or daemon restart. It is<br class="">+only possible to clear the lock state through a clear_locked dbus command. (V3)<br class=""> <br class=""> ### BMC Events<br class=""> <br class="">@@ -316,6 +336,8 @@ MARK_WRITE_DIRTY 0x07<br class=""> WRITE_FLUSH 0x08<br class=""> BMC_EVENT_ACK 0x09<br class=""><blockquote type="cite" class=""> MARK_WRITE_ERASED 0x0a<span class="Apple-tab-span" style="white-space: pre;"> </span>(V2)<br class="">+GET_FLASH_NAME 0x0b<span class="Apple-tab-span" style="white-space: pre;"> </span>(V3)<br class="">+MARK_LOCKED 0x0c<span class="Apple-tab-span" style="white-space: pre;"> </span>(V3)<br class=""></blockquote> ```<br class=""> <br class=""> ### Responses<br class=""><blockquote type="cite" class="">@@ -329,13 +351,14 @@ TIMEOUT<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>5<br class=""><blockquote type="cite" class=""> BUSY<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>6<span class="Apple-tab-span" style="white-space: pre;"> </span>(V2)<br class=""> WINDOW_ERROR<span class="Apple-tab-span" style="white-space: pre;"> </span>7<span class="Apple-tab-span" style="white-space: pre;"> </span>(V2)<br class=""> SEQ_ERROR<span class="Apple-tab-span" style="white-space: pre;"> </span>8<span class="Apple-tab-span" style="white-space: pre;"> </span>(V2)<br class="">+LOCKED_ERROR<span class="Apple-tab-span" style="white-space: pre;"> </span>9<span class="Apple-tab-span" style="white-space: pre;"> </span>(V3)<br class=""></blockquote></blockquote> ```<br class=""> <br class=""> ### Sequence Numbers<br class=""> <br class=""> Sequence numbers are included in messages for correlation of commands and<br class="">-responses. V1 and V2 of the protocol permit either zero or one commands to be<br class="">-in progress (yet to receive a response).<br class="">+responses. V1, V2 and V3 of the protocol permit either zero or one commands to<br class="">+be in progress (yet to receive a response).<br class=""> <br class=""> For generality, the host must generate a sequence number that is unique with<br class=""> respect to the previous command (one that has received a response) and any<br class=""><blockquote type="cite" class="">@@ -368,6 +391,10 @@ BUSY<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>- Daemon in suspended state (currently unable to access flash)<br class=""> WINDOW_ERROR<span class="Apple-tab-span" style="white-space: pre;"> </span>- Command not valid for active window or no active window<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>- Try opening an appropriate window and retrying the command<br class=""></blockquote> <br class=""><blockquote type="cite" class="">+SEQ_ERROR<span class="Apple-tab-span" style="white-space: pre;"> </span>- Invalid sequence number supplied with command<br class=""></blockquote>+<br class=""><blockquote type="cite" class="">+LOCKED_ERROR<span class="Apple-tab-span" style="white-space: pre;"> </span>- Tried to mark dirty or erased locked area of flash<br class=""></blockquote>+<br class=""> ### Information<br class=""> - All multibyte messages are LSB first (little endian)<br class=""> - All responses must have a valid return code in byte 13<br class="">@@ -381,6 +408,12 @@ allows us to specify larger values with fewer command and response fields.<br class=""> <br class=""> In V1 block size is hard coded to 4K.<br class=""> In V2 it is variable and must be queried with the GET_MBOX_INFO command.<br class="">+In V3 the host can request a given block size however it is ultimately up to<br class="">+the daemon to choose a block size which is returned as part of the GET_MBOX_INFO<br class="">+command response. The host must respect the daemons choice. The ability for the<br class="">+host to request a block size is provided such that it can choose an appropriate<br class="">+size to be able to utilise commands which only operate at the block level.<br class="">+<br class=""> Note that for simplicity block size must always be a power-of-2.<br class=""> Block size must also be greater than or equal to 4K. This is due to the<br class=""> fact that we have a 28-bit LPC address space and commands which return an<br class="">@@ -395,8 +428,7 @@ multiplying by the block size.<br class=""> ```<br class=""> Command:<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span>RESET_STATE<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span>Implemented in Versions:<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1, V2<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>Added in:<span class="Apple-tab-span" style="white-space: pre;"> </span>V1<br class=""></blockquote> <span class="Apple-tab-span" style="white-space: pre;"> </span>Arguments:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>-<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span>Response:<br class=""></blockquote>@@ -409,8 +441,7 @@ Command:<br class=""> <br class=""> Command:<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span>GET_MBOX_INFO<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span>Implemented in Versions:<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1, V2<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>Added in:<span class="Apple-tab-span" style="white-space: pre;"> </span>V1<br class=""></blockquote> <span class="Apple-tab-span" style="white-space: pre;"> </span>Arguments:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0: API version<br class=""></blockquote>@@ -418,6 +449,10 @@ Command:<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V2:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0: API version<br class=""></blockquote> <br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V3:<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0: API version<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 1: Requested block size (shift)<br class=""></blockquote>+<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span>Response:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0: API version<br class=""></blockquote>@@ -430,6 +465,14 @@ Command:<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 3-4: reserved<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 5: Block size as power of two (encoded as a shift)<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 6-7: Suggested Timeout (seconds)<br class=""></blockquote>+<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V3:<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0: API version<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 1-2: reserved<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 3-4: reserved<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 5: Block size as power of two (encoded as a shift)<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 6-7: Suggested Timeout (seconds)<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 8: Num Allocated Flash IDs<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span>Notes:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>The suggested timeout is a hint to the host as to how long<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>it should wait after issuing a command to the BMC before it<br class=""></blockquote>@@ -439,25 +482,34 @@ Command:<br class=""><blockquote type="cite" class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>the BMC<span class="Apple-tab-span" style="white-space: pre;"> </span>does not wish to provide a hint in which case the host<br class=""></blockquote> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>must choose some reasonable value.<br class=""></blockquote> <br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>The host may desire a specific block size and thus can request<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>this by giving a hint to the daemon (may be zero). The daemon<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>may use this to select the block size which it will use however<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>is free to ignore it. The value in the response is the block<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>size which must be used for all further requests until a new<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>size is<span class="Apple-tab-span" style="white-space: pre;"> </span>negotiated by another call to GET_MBOX_INFO. (V3)<br class=""></blockquote></blockquote>+<br class=""> Command:<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span>GET_FLASH_INFO<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span>Implemented in Versions:<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1, V2<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>Added in:<span class="Apple-tab-span" style="white-space: pre;"> </span>V1<br class=""></blockquote> <span class="Apple-tab-span" style="white-space: pre;"> </span>Arguments:<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1, V2:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>-<br class=""></blockquote>+<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V3:<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0: Flash ID<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span>Response:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0-3: Flash size (bytes)<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 4-7: Erase granule (bytes)<br class=""></blockquote> <br class=""><blockquote type="cite" class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V2:<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V2, V3:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0-1: Flash size (blocks)<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 2-3: Erase granule (blocks)<br class=""></blockquote> <br class=""> Command:<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span>CREATE_{READ/WRITE}_WINDOW<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span>Implemented in Versions:<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1, V2<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>Added in:<span class="Apple-tab-span" style="white-space: pre;"> </span>V1<br class=""></blockquote> <span class="Apple-tab-span" style="white-space: pre;"> </span>Arguments:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0-1: Requested flash offset (blocks)<br class=""></blockquote>@@ -466,11 +518,15 @@ Command:<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0-1: Requested flash offset (blocks)<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 2-3: Requested flash size to access (blocks)<br class=""></blockquote> <br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V3:<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0-1: Requested flash offset (blocks)<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 2-3: Requested flash size to access (blocks)<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 4: Flash ID<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span>Response:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0-1: LPC bus address of window (blocks)<br class=""></blockquote> <br class=""><blockquote type="cite" class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V2:<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V2, V3:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0-1: LPC bus address of window (blocks)<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 2-3: Window size (blocks)<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 4-5: Flash offset mapped by window (blocks)<br class=""></blockquote>@@ -505,8 +561,7 @@ Command:<br class=""> <br class=""> Command:<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span>CLOSE_WINDOW<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span>Implemented in Versions:<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1, V2<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>Added in:<span class="Apple-tab-span" style="white-space: pre;"> </span>V1<br class=""></blockquote> <span class="Apple-tab-span" style="white-space: pre;"> </span>Arguments:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>-<br class=""></blockquote>@@ -534,8 +589,7 @@ Command:<br class=""> <br class=""> Command:<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span>MARK_WRITE_DIRTY<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span>Implemented in Versions:<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1, V2<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>Added in:<span class="Apple-tab-span" style="white-space: pre;"> </span>V1<br class=""></blockquote> <span class="Apple-tab-span" style="white-space: pre;"> </span>Arguments:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0-1: Flash offset to mark from base of flash (blocks)<br class=""></blockquote>@@ -544,6 +598,7 @@ Command:<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V2:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0-1: Window offset to mark (blocks)<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 2-3: Number to mark dirty at offset (blocks)<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 4 : Don't Erase Before Write (V3)<br class=""></blockquote> <br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span>Response:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>-<br class=""></blockquote>@@ -558,10 +613,16 @@ Command:<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>block. If the offset + number exceeds the size of the active<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>window then the command must not succeed.<br class=""></blockquote> <br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>The host can give a hint to the daemon that is doesn't have to<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>erase a flash area before writing to it by setting ARG[4]. This<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>means that the daemon will blindly perform a write to that area<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>and will not try to erase it before hand. This can be used if<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>the host knows that a large area has already been erased for<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>example but then wants to perform many small writes.<br class=""></blockquote>+<br class=""> Command<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span>WRITE_FLUSH<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span>Implemented in Versions:<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1, V2<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>Added in:<span class="Apple-tab-span" style="white-space: pre;"> </span>V1<br class=""></blockquote> <span class="Apple-tab-span" style="white-space: pre;"> </span>Arguments:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0-1: Flash offset to mark from base of flash (blocks)<br class=""></blockquote>@@ -586,8 +647,7 @@ Command<br class=""> <br class=""> Command:<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span>BMC_EVENT_ACK<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span>Implemented in Versions:<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V1, V2<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>Added in:<span class="Apple-tab-span" style="white-space: pre;"> </span>V1<br class=""></blockquote> <span class="Apple-tab-span" style="white-space: pre;"> </span>Arguments:<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0:<span class="Apple-tab-span" style="white-space: pre;"> </span>Bits in the BMC status byte (mailbox data<br class=""></blockquote> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>register 15) to ack<br class=""></blockquote>@@ -599,8 +659,7 @@ Command:<br class=""> <br class=""> Command:<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span>MARK_WRITE_ERASED<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span>Implemented in Versions:<br class="">-<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V2<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>Added in:<span class="Apple-tab-span" style="white-space: pre;"> </span>V2<br class=""></blockquote> <span class="Apple-tab-span" style="white-space: pre;"> </span>Arguments:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>V2:<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0-1: Window offset to erase (blocks)<br class=""></blockquote>@@ -617,6 +676,38 @@ Command:<br class=""><blockquote type="cite" class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>number is the number of blocks of the active window to erase<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>starting at offset. If the offset + number exceeds the size of<br class=""> <span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>the active window then the command must not succeed.<br class=""></blockquote>+<br class="">+Command:<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>GET_FLASH_NAME<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>Added in:<span class="Apple-tab-span" style="white-space: pre;"> </span>V3<br class=""></blockquote>+<span class="Apple-tab-span" style="white-space: pre;"> </span>Arguments:<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0: Flash ID<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>Response:<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0 : Flash Name Length (bytes)<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 1-10: Flash Name / UID<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>Notes:<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Describes a flash with some kind of identifier useful to the<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>host system. This is typically a null-padded string.<br class=""></blockquote>+<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>The length in the response is the number of response arguments<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>as part of the flash name field which the host should expect to<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>have been populated.<br class=""></blockquote>+<br class="">+Command:<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>MARK_LOCKED<br class=""><blockquote type="cite" class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>Added in:<span class="Apple-tab-span" style="white-space: pre;"> </span>V3<br class=""></blockquote>+<span class="Apple-tab-span" style="white-space: pre;"> </span>Arguments:<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 0-1: Flash offset to lock (blocks)<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 2-3: Number to lock at offset (blocks)<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Args 4: Flash ID<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>Response:<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>-<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span>Notes:<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>Lock an area of flash so that the host can't mark it dirty or<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>erased. If the requested area is within the current window and<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>that area is currently marked dirty or erased then this command<br class="">+<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>must fail with PARAM_ERROR.<br class=""></blockquote>+<br class=""> ```<br class=""> <br class=""> ### BMC Events in Detail:<br class="">@@ -627,7 +718,7 @@ on that register, or otherwise be polling it.<br class=""> <br class=""> #### Bit Definitions:<br class=""> <br class="">-Events which should be ACKed:<br class="">+Events which must be ACKed:<br class=""> ```<br class=""> 0x01: BMC Reboot<br class=""> 0x02: BMC Windows Reset (V2)</blockquote></div></blockquote></div><br class=""></div></body></html>
On Wed, 2017-10-04 at 11:45 +1100, Suraj Jitindar Singh wrote: > Version 3 of the mbox protocol makes four protocol changes: > - Add a requested block size argument to GET_MBOX_INFO > - Add a no erase argument to MARK_DIRTY > - Add a GET_FLASH_NAME command and support multiple flash devices > - Add a MARK_LOCKED command > > Requested Block Size: > The requested block size argument has been added to the GET_MBOX_INFO > command to allow the host to request a specified block size which might > be required to allow data manipulation at a finer granularity. The > daemon should take this into account when choosing a block size for use > which it will specify in the response as before. The daemon has final > say and the host must use the block size the daemon chooses. > > No Erase: > The no erase argument to the mark dirty command allows a host to specify > that an area of flash should not be erased before being written to, as is > the default behaviour. This can be used when a host has already erased a > large area and then performs many small writes which would normally mean > many erases due to the implicit erase before write, making this slow. > > Add GET_FLASH_NAME command: > The ability to support multiple flash devices has been added so that the > mbox protocol can be used to arbitrate access from the host to a number > of flash devices which the daemon has access to. To facilitate this the > GET_FLASH_INFO, CREATE_{READ/WRITE}_WINDOW, and MARK_LOCKED commands now > take a flash ID, with the number of flash IDs allocated returned by the > GET_MBOX_INFO commands. There is also a new command GET_FLASH_NAME used > to convert a flash ID to a flash name. > > Add MARK_LOCKED command: > The MARK_LOCKED command has been added to allow an area(s) of flash to be > locked, that is that area must be treated as read only and the host is > not allowed to dirty or erase any windows which map that area of flash. > Additionally another error code LOCKED_ERROR was added to be returned > when the host does try to dirty or erase a locked area. > > The host cannot lock a currently dirty or erased area of the current > write window as it is not defined if the clean/dirty/erased value is > what should actually be "locked". > > A locked area of flash remains so until the daemon receives an > mboxctl --clear-locked command and the locked areas are stored in a file > on the BMC filesystem to ensure persistence across BMC reboots/daemon > crashes. > > Multiple flash device support proposed and defined by: > William A. Kennington III <wak@google.com> > > Change-Id: I898698840dec221ae20e33943bb28e65abc4fe37 > Signed-off-by: Suraj Jitindar Singh <sjitindarsingh@gmail.com> William - any chance you can ack/review this? Cheers, Andrew
Reviewed-by: William A. Kennington III <wak@google.com>
On Wed, 2017-10-04 at 11:45 +1100, Suraj Jitindar Singh wrote: > Version 3 of the mbox protocol makes four protocol changes: > - Add a requested block size argument to GET_MBOX_INFO > - Add a no erase argument to MARK_DIRTY > - Add a GET_FLASH_NAME command and support multiple flash devices > - Add a MARK_LOCKED command > > Requested Block Size: > The requested block size argument has been added to the GET_MBOX_INFO > command to allow the host to request a specified block size which might > be required to allow data manipulation at a finer granularity. The > daemon should take this into account when choosing a block size for use > which it will specify in the response as before. The daemon has final > say and the host must use the block size the daemon chooses. > > No Erase: > The no erase argument to the mark dirty command allows a host to specify > that an area of flash should not be erased before being written to, as is > the default behaviour. This can be used when a host has already erased a > large area and then performs many small writes which would normally mean > many erases due to the implicit erase before write, making this slow. > > Add GET_FLASH_NAME command: > The ability to support multiple flash devices has been added so that the > mbox protocol can be used to arbitrate access from the host to a number > of flash devices which the daemon has access to. To facilitate this the > GET_FLASH_INFO, CREATE_{READ/WRITE}_WINDOW, and MARK_LOCKED commands now > take a flash ID, with the number of flash IDs allocated returned by the > GET_MBOX_INFO commands. There is also a new command GET_FLASH_NAME used > to convert a flash ID to a flash name. > > Add MARK_LOCKED command: > The MARK_LOCKED command has been added to allow an area(s) of flash to be > locked, that is that area must be treated as read only and the host is > not allowed to dirty or erase any windows which map that area of flash. > Additionally another error code LOCKED_ERROR was added to be returned > when the host does try to dirty or erase a locked area. > > The host cannot lock a currently dirty or erased area of the current > write window as it is not defined if the clean/dirty/erased value is > what should actually be "locked". > > A locked area of flash remains so until the daemon receives an > mboxctl --clear-locked command and the locked areas are stored in a file > on the BMC filesystem to ensure persistence across BMC reboots/daemon > crashes. > > Multiple flash device support proposed and defined by: > William A. Kennington III <wak@google.com> > > Change-Id: I898698840dec221ae20e33943bb28e65abc4fe37 > Signed-off-by: Suraj Jitindar Singh <sjitindarsingh@gmail.com> Applied with tags to openbmc/mboxbridge. Cheers, Andrew
diff --git a/Documentation/mbox_protocol.md b/Documentation/mbox_protocol.md index bcd70a8..797ac7b 100644 --- a/Documentation/mbox_protocol.md +++ b/Documentation/mbox_protocol.md @@ -17,19 +17,22 @@ limitations under the License. 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. +access to a flash device(s) 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). +Version specific protocol functionalities are represented by the version number +in brackets next to the definition of the functionality. (e.g. (V2) for version +2 specific funtionality). All version specific functionality must also be +implemented by proceeding versions up to and not including the version a command +was removed. ## 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. +for the host to control access to the flash device(s). 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. @@ -215,9 +218,11 @@ communicate a change in state. 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. +4K, in V2 the BMC chooses and in V3 the host is allowed to request a specific +block size with the actual size chosen communicated back 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. When invoking `MBOX_GET_INFO` the host must provide the BMC its highest supported version of the protocol. The BMC must respond with a protocol version @@ -231,10 +236,13 @@ version by issuing a subsequent `MBOX_GET_INFO` command. ### 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. +the flash offset it would like to access with the CREATE_{READ,WRITE}_WINDOW +commands. 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. On returning success to either of the create +window commands the BMC must guarantee that the window provided contains data +which correctly represents the state of flash at the time the response is given. 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 @@ -278,7 +286,19 @@ 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. +required before a write then the BMC must perform this itself (unless the +no_erase flag is set in the MARK_WRITE_DIRTY command in which case the BMC will +blindly write without a prior erase (V3)). + +The host may lock an area of flash using the MARK_LOCKED command. Any attempt +to mark dirty or erased this area of flash must fail with the LOCKED_ERROR +response code. The host may open a write window which contains a locked area +of flash however changes to a locked area of flash must never be written back +to the backing data source (i.e. that area of flash must be treated as read +only with respect to the backing store at all times). An attempt to lock an area +of flash which is not clean in the current window must fail with PARAM_ERROR. +Locked flash regions must persist across a BMC reboot or daemon restart. It is +only possible to clear the lock state through a clear_locked dbus command. (V3) ### BMC Events @@ -316,6 +336,8 @@ MARK_WRITE_DIRTY 0x07 WRITE_FLUSH 0x08 BMC_EVENT_ACK 0x09 MARK_WRITE_ERASED 0x0a (V2) +GET_FLASH_NAME 0x0b (V3) +MARK_LOCKED 0x0c (V3) ``` ### Responses @@ -329,13 +351,14 @@ TIMEOUT 5 BUSY 6 (V2) WINDOW_ERROR 7 (V2) SEQ_ERROR 8 (V2) +LOCKED_ERROR 9 (V3) ``` ### Sequence Numbers Sequence numbers are included in messages for correlation of commands and -responses. V1 and V2 of the protocol permit either zero or one commands to be -in progress (yet to receive a response). +responses. V1, V2 and V3 of the protocol permit either zero or one commands to +be in progress (yet to receive a response). For generality, the host must generate a sequence number that is unique with respect to the previous command (one that has received a response) and any @@ -368,6 +391,10 @@ BUSY - Daemon in suspended state (currently unable to access flash) WINDOW_ERROR - Command not valid for active window or no active window - Try opening an appropriate window and retrying the command +SEQ_ERROR - Invalid sequence number supplied with command + +LOCKED_ERROR - Tried to mark dirty or erased locked area of flash + ### Information - All multibyte messages are LSB first (little endian) - All responses must have a valid return code in byte 13 @@ -381,6 +408,12 @@ allows us to specify larger values with fewer command and response fields. In V1 block size is hard coded to 4K. In V2 it is variable and must be queried with the GET_MBOX_INFO command. +In V3 the host can request a given block size however it is ultimately up to +the daemon to choose a block size which is returned as part of the GET_MBOX_INFO +command response. The host must respect the daemons choice. The ability for the +host to request a block size is provided such that it can choose an appropriate +size to be able to utilise commands which only operate at the block level. + Note that for simplicity block size must always be a power-of-2. Block size must also be greater than or equal to 4K. This is due to the fact that we have a 28-bit LPC address space and commands which return an @@ -395,8 +428,7 @@ multiplying by the block size. ``` Command: RESET_STATE - Implemented in Versions: - V1, V2 + Added in: V1 Arguments: - Response: @@ -409,8 +441,7 @@ Command: Command: GET_MBOX_INFO - Implemented in Versions: - V1, V2 + Added in: V1 Arguments: V1: Args 0: API version @@ -418,6 +449,10 @@ Command: V2: Args 0: API version + V3: + Args 0: API version + Args 1: Requested block size (shift) + Response: V1: Args 0: API version @@ -430,6 +465,14 @@ Command: Args 3-4: reserved Args 5: Block size as power of two (encoded as a shift) Args 6-7: Suggested Timeout (seconds) + + V3: + Args 0: API version + Args 1-2: reserved + Args 3-4: reserved + Args 5: Block size as power of two (encoded as a shift) + Args 6-7: Suggested Timeout (seconds) + Args 8: Num Allocated Flash IDs Notes: The suggested timeout is a hint to the host as to how long it should wait after issuing a command to the BMC before it @@ -439,25 +482,34 @@ Command: the BMC does not wish to provide a hint in which case the host must choose some reasonable value. + The host may desire a specific block size and thus can request + this by giving a hint to the daemon (may be zero). The daemon + may use this to select the block size which it will use however + is free to ignore it. The value in the response is the block + size which must be used for all further requests until a new + size is negotiated by another call to GET_MBOX_INFO. (V3) + Command: GET_FLASH_INFO - Implemented in Versions: - V1, V2 + Added in: V1 Arguments: + V1, V2: - + + V3: + Args 0: Flash ID Response: V1: Args 0-3: Flash size (bytes) Args 4-7: Erase granule (bytes) - V2: + V2, V3: Args 0-1: Flash size (blocks) Args 2-3: Erase granule (blocks) Command: CREATE_{READ/WRITE}_WINDOW - Implemented in Versions: - V1, V2 + Added in: V1 Arguments: V1: Args 0-1: Requested flash offset (blocks) @@ -466,11 +518,15 @@ Command: Args 0-1: Requested flash offset (blocks) Args 2-3: Requested flash size to access (blocks) + V3: + Args 0-1: Requested flash offset (blocks) + Args 2-3: Requested flash size to access (blocks) + Args 4: Flash ID Response: V1: Args 0-1: LPC bus address of window (blocks) - V2: + V2, V3: Args 0-1: LPC bus address of window (blocks) Args 2-3: Window size (blocks) Args 4-5: Flash offset mapped by window (blocks) @@ -505,8 +561,7 @@ Command: Command: CLOSE_WINDOW - Implemented in Versions: - V1, V2 + Added in: V1 Arguments: V1: - @@ -534,8 +589,7 @@ Command: Command: MARK_WRITE_DIRTY - Implemented in Versions: - V1, V2 + Added in: V1 Arguments: V1: Args 0-1: Flash offset to mark from base of flash (blocks) @@ -544,6 +598,7 @@ Command: V2: Args 0-1: Window offset to mark (blocks) Args 2-3: Number to mark dirty at offset (blocks) + Args 4 : Don't Erase Before Write (V3) Response: - @@ -558,10 +613,16 @@ Command: block. If the offset + number exceeds the size of the active window then the command must not succeed. + The host can give a hint to the daemon that is doesn't have to + erase a flash area before writing to it by setting ARG[4]. This + means that the daemon will blindly perform a write to that area + and will not try to erase it before hand. This can be used if + the host knows that a large area has already been erased for + example but then wants to perform many small writes. + Command WRITE_FLUSH - Implemented in Versions: - V1, V2 + Added in: V1 Arguments: V1: Args 0-1: Flash offset to mark from base of flash (blocks) @@ -586,8 +647,7 @@ Command Command: BMC_EVENT_ACK - Implemented in Versions: - V1, V2 + Added in: V1 Arguments: Args 0: Bits in the BMC status byte (mailbox data register 15) to ack @@ -599,8 +659,7 @@ Command: Command: MARK_WRITE_ERASED - Implemented in Versions: - V2 + Added in: V2 Arguments: V2: Args 0-1: Window offset to erase (blocks) @@ -617,6 +676,38 @@ Command: 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. + +Command: + GET_FLASH_NAME + Added in: V3 + Arguments: + Args 0: Flash ID + Response: + Args 0 : Flash Name Length (bytes) + Args 1-10: Flash Name / UID + Notes: + Describes a flash with some kind of identifier useful to the + host system. This is typically a null-padded string. + + The length in the response is the number of response arguments + as part of the flash name field which the host should expect to + have been populated. + +Command: + MARK_LOCKED + Added in: V3 + Arguments: + Args 0-1: Flash offset to lock (blocks) + Args 2-3: Number to lock at offset (blocks) + Args 4: Flash ID + Response: + - + Notes: + Lock an area of flash so that the host can't mark it dirty or + erased. If the requested area is within the current window and + that area is currently marked dirty or erased then this command + must fail with PARAM_ERROR. + ``` ### BMC Events in Detail: @@ -627,7 +718,7 @@ on that register, or otherwise be polling it. #### Bit Definitions: -Events which should be ACKed: +Events which must be ACKed: ``` 0x01: BMC Reboot 0x02: BMC Windows Reset (V2)
Version 3 of the mbox protocol makes four protocol changes: - Add a requested block size argument to GET_MBOX_INFO - Add a no erase argument to MARK_DIRTY - Add a GET_FLASH_NAME command and support multiple flash devices - Add a MARK_LOCKED command Requested Block Size: The requested block size argument has been added to the GET_MBOX_INFO command to allow the host to request a specified block size which might be required to allow data manipulation at a finer granularity. The daemon should take this into account when choosing a block size for use which it will specify in the response as before. The daemon has final say and the host must use the block size the daemon chooses. No Erase: The no erase argument to the mark dirty command allows a host to specify that an area of flash should not be erased before being written to, as is the default behaviour. This can be used when a host has already erased a large area and then performs many small writes which would normally mean many erases due to the implicit erase before write, making this slow. Add GET_FLASH_NAME command: The ability to support multiple flash devices has been added so that the mbox protocol can be used to arbitrate access from the host to a number of flash devices which the daemon has access to. To facilitate this the GET_FLASH_INFO, CREATE_{READ/WRITE}_WINDOW, and MARK_LOCKED commands now take a flash ID, with the number of flash IDs allocated returned by the GET_MBOX_INFO commands. There is also a new command GET_FLASH_NAME used to convert a flash ID to a flash name. Add MARK_LOCKED command: The MARK_LOCKED command has been added to allow an area(s) of flash to be locked, that is that area must be treated as read only and the host is not allowed to dirty or erase any windows which map that area of flash. Additionally another error code LOCKED_ERROR was added to be returned when the host does try to dirty or erase a locked area. The host cannot lock a currently dirty or erased area of the current write window as it is not defined if the clean/dirty/erased value is what should actually be "locked". A locked area of flash remains so until the daemon receives an mboxctl --clear-locked command and the locked areas are stored in a file on the BMC filesystem to ensure persistence across BMC reboots/daemon crashes. Multiple flash device support proposed and defined by: William A. Kennington III <wak@google.com> Change-Id: I898698840dec221ae20e33943bb28e65abc4fe37 Signed-off-by: Suraj Jitindar Singh <sjitindarsingh@gmail.com> --- Documentation/mbox_protocol.md | 163 ++++++++++++++++++++++++++++++++--------- 1 file changed, 127 insertions(+), 36 deletions(-)