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>

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       &nbs= p;  0x08
BMC_EVENT_ACK       &n= bsp;0x09
MARK_WRITE_ERASED    0x0a (V2)
+GET_FLASH_NAME       0x0b = (V3)
+MARK_LOCKED        &nb= sp; 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)