Skip to contentSkip to conversation

Proposed Protocol Changes for MBOX V3

RFC In review Suraj Jitindar Singh 4 participants 10 messages Sep 7, 2017 – Oct 10, 2017 Documentation

lore
Share & tools
lore
#0 lore raw

The patch that follows contains proposed changes for a mbox version 3 protocol definition.

This is the combination of changes proposed by myself and William A. Kennington III <[email protected]>.

These changes are being posted to both the skiboot and openbmc lists for discussion.

Suraj Jitindar Singh (1):
docs: Specify V3 of the mbox protocol

 Documentation/mbox_protocol.md | 127 ++++++++++++++++++++++++++++++-----------
 1 file changed, 93 insertions(+), 34 deletions(-)
Signature · 1 line
2.9.4
#1 lore raw

RFC 1/1 docs: Specify V3 of the mbox protocol

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 --reset 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 <[email protected]>

---
 Documentation/mbox_protocol.md | 127 ++++++++++++++++++++++++++++++-----------
 1 file changed, 93 insertions(+), 34 deletions(-)
Documentation/mbox_protocol.md +93 -34
index bcd70a8..74863a7 100644
@@ -17,19 +17,21 @@ 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 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.
 
 ## 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.
@@ -280,6 +282,14 @@ 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.
 
+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). An attempt to lock an area of flash which is not clean in the current
+window must fail with PARAM_ERROR. (V3)
+
 ### BMC Events
 
 The BMC can raise events with the host asynchronously to communicate to the
@@ -316,6 +326,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,6 +341,7 @@ TIMEOUT		5
 BUSY		6	(V2)
 WINDOW_ERROR	7	(V2)
 SEQ_ERROR	8	(V2)
+LOCKED_ERROR	9	(V3)
 ```
 
 ### Sequence Numbers
@@ -368,6 +381,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
@@ -394,9 +411,7 @@ Sizes and addresses specified in blocks must be converted to bytes by
 multiplying by the block size.
 ```
 Command:
-	RESET_STATE
-	Implemented in Versions:
-		V1, V2
+	RESET_STATE (V1)
 	Arguments:
 		-
 	Response:
@@ -408,9 +423,7 @@ Command:
 		pre mailbox protocol. Final behavior is still TBD.
 
 Command:
-	GET_MBOX_INFO
-	Implemented in Versions:
-		V1, V2
+	GET_MBOX_INFO (V1)
 	Arguments:
 		V1:
 		Args 0: API version
@@ -418,6 +431,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 +447,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 +464,32 @@ Command:
 		the BMC	does not wish to provide a hint in which case the host
 		must choose some reasonable value.
 
+		The host may require 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 this. 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
+	GET_FLASH_INFO (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
+	CREATE_{READ/WRITE}_WINDOW (V1)
 	Arguments:
 		V1:
 		Args 0-1: Requested flash offset (blocks)
@@ -466,11 +498,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)
@@ -504,9 +540,7 @@ Command:
 		window.
 
 Command:
-	CLOSE_WINDOW
-	Implemented in Versions:
-		V1, V2
+	CLOSE_WINDOW (V1)
 	Arguments:
 		V1:
 		-
@@ -533,9 +567,7 @@ Command:
 				evicted from the cache.
 
 Command:
-	MARK_WRITE_DIRTY
-	Implemented in Versions:
-		V1, V2
+	MARK_WRITE_DIRTY (V1)
 	Arguments:
 		V1:
 		Args 0-1: Flash offset to mark from base of flash (blocks)
@@ -544,6 +576,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 +591,15 @@ 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
+	WRITE_FLUSH (V1)
 	Arguments:
 		V1:
 		Args 0-1: Flash offset to mark from base of flash (blocks)
@@ -585,9 +623,7 @@ Command
 
 
 Command:
-	BMC_EVENT_ACK
-	Implemented in Versions:
-		V1, V2
+	BMC_EVENT_ACK (V1)
 	Arguments:
 		Args 0:	Bits in the BMC status byte (mailbox data
 			register 15) to ack
@@ -598,9 +634,7 @@ Command:
 		supplied in mailbox register 15.
 
 Command:
-	MARK_WRITE_ERASED
-	Implemented in Versions:
-		V2
+	MARK_WRITE_ERASED (V2)
 	Arguments:
 		V2:
 		Args 0-1: Window offset to erase (blocks)
@@ -617,6 +651,31 @@ 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 (V3)
+	Arguments:
+		Args 0: Flash ID
+	Response:
+		Args 0-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.
+
+Command:
+	MARK_LOCKED (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.
+
 ```
 
 ### BMC Events in Detail:
Signature · 1 line
2.9.4
#2 lore raw

Re: [RFC] docs: Specify V3 of the mbox protocol

Quoted 68 lines · Suraj Jitindar Singh

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 --reset 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:

Quoted 1 line

William A. Kennington III <[email protected]>

Quoted 1 line

---
 Documentation/mbox_protocol.md | 127 ++++++++++++++++++++++++++++++-----------

 1 file changed, 93 insertions(+), 34 deletions(-)

Documentation/mbox_protocol.md +0 -0
index bcd70a8..74863a7 100644
@@ -17,19 +17,21 @@ 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

Documentation/mbox_protocol.md +2 -2
-access to the flash with the specifics of how the host is required to control
-this described below.
+access to a flash device with the specifics of how the host is required to
+control this described below.


 ## Version

Documentation/mbox_protocol.md limitations under the License. · line 28

Quoted 6 lines
Documentation/mbox_protocol.md +4 -2
-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.

I don't know that this is something we want to lock ourselves into. We never want to remove functionality? What if a command turns out to be dangerous?

Quoted 14 lines


 ## 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

Documentation/mbox_protocol.md +1 -1
-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.

Documentation/mbox_protocol.md +0 -0
@@ -280,6 +282,14 @@ 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.

Documentation/mbox_protocol.md The host is not required to perform an erase before a write command and the · line 291

Quoted 7 lines
Documentation/mbox_protocol.md +7 -0
+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). An attempt to lock an area of flash which is not clean in the current
+window must fail with PARAM_ERROR. (V3)

I think we need to consider how locked regions interact with the in-memory caching of the flash data.

The BMC doesn't know that the memory backing the LPC window has been written until it receives a MARK_DIRTY from the host. MARK_DIRTY is not valid on a read window or a locked region, but that doesn't mean that changes to a locked region can't persist in memory due to caching to avoid flash access (which was a part of the motivation for memory-based booting to begin with). This may naively fool host firmware into thinking it is accessing unmolested data as the region is locked, whereas the region could contain anything, just it will never be written to flash.

Should we require window requests intersecting a locked region always have at least the locked region positively match the on-flash data? That way the firmware that requested a region be locked could ensure it has whatever was on the flash at the time it was locked by explicitly closing the window (read or write) once finished with it, which requires a window be opened again for any subsequent access. At that point (open) we can do the locked region intesection calculation and check the data in the window as necessary.

Locked regions could thus be a performance hit if we always load the locked regions from flash, but surely we prefer (some) integrity over performance.

Alternatively, you could cryptographically hash the per-block content of the on-flash locked region during the MARK_LOCKED operation, then stash the hash values away. On a CREATE_{READ,WRITE}_WINDOW operation you could hash any intersecting, in-cache locked blocks and compare to the stashed hash values to incur only one set of flash accesses (initial hash calculations) rather than n.

Quoted 36 lines

+
 ### BMC Events

 The BMC can raise events with the host asynchronously to communicate to the

Documentation/mbox_protocol.md +0 -0
@@ -316,6 +326,8 @@ MARK_WRITE_DIRTY     0x07

 WRITE_FLUSH          0x08
 BMC_EVENT_ACK        0x09
 MARK_WRITE_ERASED    0x0a (V2)

Documentation/mbox_protocol.md +2 -0
+GET_FLASH_NAME       0x0b	(V3)
+MARK_LOCKED          0x0c	(V3)

 ```

 ### Responses

Documentation/mbox_protocol.md +1 -0
@@ -329,6 +341,7 @@ TIMEOUT		5
  BUSY		6	(V2)
  WINDOW_ERROR	7	(V2)
  SEQ_ERROR	8	(V2)
+LOCKED_ERROR	9	(V3)

 ```

 ### Sequence Numbers

Documentation/mbox_protocol.md +0 -0
@@ -368,6 +381,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

Documentation/mbox_protocol.md +4 -0
+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

Documentation/mbox_protocol.md +0 -0
@@ -394,9 +411,7 @@ Sizes and addresses specified in blocks must be converted to bytes by

 multiplying by the block size.
 ```
 Command:

Documentation/mbox_protocol.md Sizes and addresses specified in blocks must be converted to bytes by · line 399

Quoted 3 lines
Documentation/mbox_protocol.md +0 -3
-	RESET_STATE
-	Implemented in Versions:
-		V1, V2

Addressing my concern above about locking ourselves in, I prefer we allow for a set of statements like:

    Added in: V1
    Removed in: V4

I guess we continue to annotate the command argument registers as we have been already.

Quoted 45 lines
Documentation/mbox_protocol.md +1 -0
+	RESET_STATE (V1)

  Arguments:
  -
  Response:

Documentation/mbox_protocol.md +0 -0
@@ -408,9 +423,7 @@ Command:

  pre mailbox protocol. Final behavior is still TBD.
 Command:

Documentation/mbox_protocol.md +1 -3
-	GET_MBOX_INFO
-	Implemented in Versions:
-		V1, V2
+	GET_MBOX_INFO (V1)

  Arguments:
  V1:
  Args 0: API version

Documentation/mbox_protocol.md +0 -0
@@ -418,6 +431,10 @@ Command:

  V2:
  Args 0: API version

Documentation/mbox_protocol.md +4 -0
+		V3:
+		Args 0: API version
+		Args 1: Requested block size (shift)
+

  Response:
  V1:
  Args 0: API version

Documentation/mbox_protocol.md +0 -0
@@ -430,6 +447,14 @@ Command:

  Args 3-4: reserved
  Args 5: Block size as power of two (encoded as a shift) Args 6-7: Suggested Timeout (seconds)

Documentation/mbox_protocol.md +8 -0
+
+		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

Documentation/mbox_protocol.md +0 -0
@@ -439,25 +464,32 @@ Command:

  the BMC does not wish to provide a hint in which case the host
  must choose some reasonable value.

Documentation/mbox_protocol.md

Quoted 1 line
Documentation/mbox_protocol.md +1 -0
+		The host may require

I'd use 'desire' instead of 'require', because the host must obey the BMC's response regarding the blocksize.

Documentation/mbox_protocol.md Command:

Quoted 4 lines

  a specific block size and thus can request

Documentation/mbox_protocol.md +3 -0
+		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 this.

Maybe 'it' instead of 'this' at the end of the sentence?

Quoted 125 lines

The value in the response is the block

Documentation/mbox_protocol.md +3 -0
+		size which must be used for all further requests until a new
+		size is	negotiated by another call to GET_MBOX_INFO. (V3)
+

 Command:

Documentation/mbox_protocol.md +1 -3
-	GET_FLASH_INFO
-	Implemented in Versions:
-		V1, V2
+	GET_FLASH_INFO (V1)

  Arguments:

Documentation/mbox_protocol.md +1 -0
+		V1, V2:

  -

Documentation/mbox_protocol.md +3 -0
+
+		V3:
+		Args 0: Flash ID

  Response:
  V1:
  Args 0-3: Flash size (bytes)
  Args 4-7: Erase granule (bytes)

Documentation/mbox_protocol.md +1 -1
-		V2:
+		V2, V3:

  Args 0-1: Flash size (blocks)
  Args 2-3: Erase granule (blocks)

 Command:

Documentation/mbox_protocol.md +1 -3
-	CREATE_{READ/WRITE}_WINDOW
-	Implemented in Versions:
-		V1, V2
+	CREATE_{READ/WRITE}_WINDOW (V1)

  Arguments:
  V1:
  Args 0-1: Requested flash offset (blocks)

Documentation/mbox_protocol.md +0 -0
@@ -466,11 +498,15 @@ Command:
  		Args 0-1: Requested flash offset (blocks)
  		Args 2-3: Requested flash size to access (blocks)

Documentation/mbox_protocol.md +4 -0
+		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)

Documentation/mbox_protocol.md +1 -1
-		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)

Documentation/mbox_protocol.md +0 -0
@@ -504,9 +540,7 @@ Command:

  window.

 Command:

Documentation/mbox_protocol.md +1 -3
-	CLOSE_WINDOW
-	Implemented in Versions:
-		V1, V2
+	CLOSE_WINDOW (V1)

  Arguments:
  V1:
  -

Documentation/mbox_protocol.md +0 -0
@@ -533,9 +567,7 @@ Command:

  evicted from the cache.
 Command:

Documentation/mbox_protocol.md +1 -3
-	MARK_WRITE_DIRTY
-	Implemented in Versions:
-		V1, V2
+	MARK_WRITE_DIRTY (V1)

  Arguments:
  V1:
  Args 0-1: Flash offset to mark from base of flash (blocks)

Documentation/mbox_protocol.md +0 -0
@@ -544,6 +576,7 @@ Command:

  V2:
  Args 0-1: Window offset to mark (blocks) Args 2-3: Number to mark dirty at offset (blocks)

Documentation/mbox_protocol.md +1 -0
+		Args 4  : Don't Erase Before Write (V3)


  Response:
  -

Documentation/mbox_protocol.md +0 -0
@@ -558,10 +591,15 @@ Command:

  block. If the offset + number exceeds the size of the active window then the command must not succeed.

Documentation/mbox_protocol.md +7 -0
+		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

Documentation/mbox_protocol.md +1 -3
-	WRITE_FLUSH
-	Implemented in Versions:
-		V1, V2
+	WRITE_FLUSH (V1)

  Arguments:
  V1:
  Args 0-1: Flash offset to mark from base of flash (blocks)

Documentation/mbox_protocol.md +0 -0
@@ -585,9 +623,7 @@ Command



 Command:

Documentation/mbox_protocol.md +1 -3
-	BMC_EVENT_ACK
-	Implemented in Versions:
-		V1, V2
+	BMC_EVENT_ACK (V1)

  Arguments:
  Args 0: Bits in the BMC status byte (mailbox data
  register 15) to ack

Documentation/mbox_protocol.md +0 -0
@@ -598,9 +634,7 @@ Command:

  supplied in mailbox register 15.

 Command:

Documentation/mbox_protocol.md +1 -3
-	MARK_WRITE_ERASED
-	Implemented in Versions:
-		V2
+	MARK_WRITE_ERASED (V2)

  Arguments:
  V2:
  Args 0-1: Window offset to erase (blocks)

Documentation/mbox_protocol.md +0 -0
@@ -617,6 +651,31 @@ 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.

Documentation/mbox_protocol.md Command: · line 660

Quoted 7 lines
Documentation/mbox_protocol.md +7 -0
+
+Command:
+	GET_FLASH_NAME (V3)
+	Arguments:
+		Args 0: Flash ID
+	Response:
+		Args 0-10: Flash Name / UID

Hopefully 11 bytes is enough. Well, 10 I guess - should we specify that the value at index 10 be '\0'? I feel like not requiring that could lead to undesirable implementations.

I guess we don't want to go down the path of continued responses or magic windows to accommodate larger names?

Documentation/mbox_protocol.md Command: · line 669

Quoted 9 lines
Documentation/mbox_protocol.md +9 -0
+	Notes:
+		Describes a flash with some kind of identifier useful to the
+		host system. This is typically a null-padded string.
+
+Command:
+	MARK_LOCKED (V3)
+	Arguments:
+		Args 0-1: Flash offset to lock (blocks)
+		Args 2-3: Number to lock at offset (blocks)

I guess it's hard to get away from using block-sized granuality. Do we currently have any partitions that we might lock that are less than a block size? Or are all partitions expected to be block-size aligned?

Cheers,

Andrew

Quoted 12 lines
Documentation/mbox_protocol.md +9 -0
+		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.
+

 ```

 ### BMC Events in Detail:

#3 lore raw

Re: [RFC] docs: Specify V3 of the mbox protocol

+Cyril because I can't type ".com" :p

Hi,

Quoted 107 lines · Andrew Jeffery
Quoted 106 lines · Suraj Jitindar Singh

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 --reset 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:

Quoted 1 line

William A. Kennington III <[email protected]>

Quoted 1 line

---
 Documentation/mbox_protocol.md | 127
++++++++++++++++++++++++++++++-----------

 1 file changed, 93 insertions(+), 34 deletions(-)

Documentation/mbox_protocol.md +0 -0
index bcd70a8..74863a7 100644
@@ -17,19 +17,21 @@ 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

Documentation/mbox_protocol.md +1 -1
-this described below.
+access to a flash device 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

Documentation/mbox_protocol.md +1 -1
-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

Quoted 8 lines
Quoted 3 lines

+2 specific funtionality). All version specific functionality must also be
+implemented by proceeding versions.

I don't know that this is something we want to lock ourselves into. We
never want to remove functionality? What if a command turns out to be dangerous?

Good point :)

Quoted 39 lines
Quoted 26 lines


 ## 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

Documentation/mbox_protocol.md +1 -1
-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.

Documentation/mbox_protocol.md +0 -0
@@ -280,6 +282,14 @@ 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.
+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

Quoted 8 lines

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). An attempt to lock an area of flash which is not clean in the current
+window must fail with PARAM_ERROR. (V3)

I think we need to consider how locked regions interact with the in- memory
caching of the flash data.

Quoted 12 lines

The BMC doesn't know that the memory backing the LPC window has been written until it receives a MARK_DIRTY from the host. MARK_DIRTY is not
valid on a read window or a locked region, but that doesn't mean that changes to a locked region can't persist in memory due to caching to avoid flash access (which was a part of the motivation for memory- based
booting to begin with). This may naively fool host firmware into thinking it is
accessing unmolested data as the region is locked, whereas the region could
contain anything, just it will never be written to flash.

Correct

Quoted 14 lines

Should we require window requests intersecting a locked region always have at
least the locked region positively match the on-flash data? That way the
firmware that requested a region be locked could ensure it has whatever was on
the flash at the time it was locked by explicitly closing the window (read or
write) once finished with it, which requires a window be opened again for any
subsequent access. At that point (open) we can do the locked region intesection
calculation and check the data in the window as necessary.

I guess this brings about an interesting question, when a window is requested is it guaranteed that the window provided in return by the BMC contains the same contents as the flash for the requested area? It would seem intuitively that it should. The first time a window is opened that is true, but with in memory caching the host could make a change that it never tells the bmc about and the contents diverge, and (assuming the window isn't evicted) persist across window close/open calls.

Is this the desired behaviour? It's kind of the only behaviour which makes the in-memory caching an effective performance improvement, if we reloaded every window every time then we may as well only have one window in memory anyway. Maybe we can do this a better way (see below).

It's worth noting that the current flash locking daemon implementation will explicitly reload an entire window whenever one which contains any locked regions is requested - ensuring (for at least as long as the access to the flash device is exclusive) the integrity of the locked regions. This could of course be optimised to only reload the locked region.

Quoted 6 lines

Locked regions could thus be a performance hit if we always load the locked
regions from flash, but surely we prefer (some) integrity over performance.

Quoted 10 lines

Alternatively, you could cryptographically hash the per-block content of the
on-flash locked region during the MARK_LOCKED operation, then stash the hash
values away. On a CREATE_{READ,WRITE}_WINDOW operation you could hash any
intersecting, in-cache locked blocks and compare to the stashed hash values to
incur only one set of flash accesses (initial hash calculations) rather than n.

This seems like a nice balance between performance and data integrity.

I guess this brings about the question again as to whether we care about data changes we aren't told about. Do we store a hash of every window and before providing a cached copy verify the hash and reload the entire window from flash again if there is a discrepancy. The host isn't allowed to rely on the persistence of data it never tells the BMC about, but is this something the BMC should be checking?

Quoted 50 lines
Quoted 43 lines

+
 ### BMC Events

 The BMC can raise events with the host asynchronously to communicate to the

Documentation/mbox_protocol.md +0 -0
@@ -316,6 +326,8 @@ MARK_WRITE_DIRTY     0x07

 WRITE_FLUSH          0x08
 BMC_EVENT_ACK        0x09
 MARK_WRITE_ERASED    0x0a (V2)

Documentation/mbox_protocol.md +2 -0
+GET_FLASH_NAME       0x0b	(V3)
+MARK_LOCKED          0x0c	(V3)

 ```

 ### Responses

Documentation/mbox_protocol.md +1 -0
@@ -329,6 +341,7 @@ TIMEOUT		5
  BUSY		6	(V2)
  WINDOW_ERROR	7	(V2)
  SEQ_ERROR	8	(V2)
+LOCKED_ERROR	9	(V3)

 ```

 ### Sequence Numbers

Documentation/mbox_protocol.md +0 -0
@@ -368,6 +381,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

Documentation/mbox_protocol.md +3 -0
+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

Documentation/mbox_protocol.md +0 -0
@@ -394,9 +411,7 @@ Sizes and addresses specified in blocks must be

converted to bytes by
 multiplying by the block size.
 ```
 Command:

Documentation/mbox_protocol.md Sizes and addresses specified in blocks must be converted to bytes by · line 399

Quoted 3 lines
Documentation/mbox_protocol.md +0 -3
-	RESET_STATE
-	Implemented in Versions:
-		V1, V2

Addressing my concern above about locking ourselves in, I prefer we allow for a set of statements like:

Quoted 2 lines

    Added in: V1
    Removed in: V4

I support this idea.

Quoted 60 lines

I guess we continue to annotate the command argument registers as we have been
already.

Quoted 50 lines
Documentation/mbox_protocol.md +1 -0
+	RESET_STATE (V1)

  Arguments:
  -
  Response:

Documentation/mbox_protocol.md +0 -0
@@ -408,9 +423,7 @@ Command:

  pre mailbox protocol. Final behavior is still TBD.
 Command:

Documentation/mbox_protocol.md +1 -3
-	GET_MBOX_INFO
-	Implemented in Versions:
-		V1, V2
+	GET_MBOX_INFO (V1)

  Arguments:
  V1:
  Args 0: API version

Documentation/mbox_protocol.md +0 -0
@@ -418,6 +431,10 @@ Command:

  V2:
  Args 0: API version

Documentation/mbox_protocol.md +4 -0
+		V3:
+		Args 0: API version
+		Args 1: Requested block size (shift)
+

  Response:
  V1:
  Args 0: API version

Documentation/mbox_protocol.md +0 -0
@@ -430,6 +447,14 @@ Command:

  Args 3-4: reserved
  Args 5: Block size as power of two (encoded as a shift)
  Args 6-7: Suggested Timeout (seconds)

Documentation/mbox_protocol.md +6 -0
+
+		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)

Documentation/mbox_protocol.md +2 -0
+		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

Documentation/mbox_protocol.md +0 -0
@@ -439,25 +464,32 @@ Command:

  the BMC does not wish to provide a hint in
which case the host
  must choose some reasonable value.

Documentation/mbox_protocol.md

Quoted 1 line
Documentation/mbox_protocol.md +1 -0
+		The host may require

I'd use 'desire' instead of 'require', because the host must obey the BMC's response regarding the blocksize.

Quoted 8 lines

Documentation/mbox_protocol.md

Quoted 6 lines

  a specific block size and thus can request

Documentation/mbox_protocol.md +1 -0
+		this by giving a hint to the daemon (may be zero).

The daemon

Documentation/mbox_protocol.md +1 -0
+		may use this to select the block size which it

will use however

Documentation/mbox_protocol.md +1 -0
+		is free to ignore this.

Maybe 'it' instead of 'this' at the end of the sentence?

Yep

Quoted 146 lines
Quoted 146 lines

The value in the response is the block

Documentation/mbox_protocol.md +1 -0
+		size which must be used for all further requests

until a new

Documentation/mbox_protocol.md +1 -0
+		size is	negotiated by another call to

GET_MBOX_INFO. (V3)
+
 Command:

Documentation/mbox_protocol.md +1 -3
-	GET_FLASH_INFO
-	Implemented in Versions:
-		V1, V2
+	GET_FLASH_INFO (V1)

  Arguments:

Documentation/mbox_protocol.md +1 -0
+		V1, V2:

  -

Documentation/mbox_protocol.md +3 -0
+
+		V3:
+		Args 0: Flash ID

  Response:
  V1:
  Args 0-3: Flash size (bytes)
  Args 4-7: Erase granule (bytes)

Documentation/mbox_protocol.md +1 -1
-		V2:
+		V2, V3:

  Args 0-1: Flash size (blocks)
  Args 2-3: Erase granule (blocks)

 Command:

Documentation/mbox_protocol.md +1 -3
-	CREATE_{READ/WRITE}_WINDOW
-	Implemented in Versions:
-		V1, V2
+	CREATE_{READ/WRITE}_WINDOW (V1)

  Arguments:
  V1:
  Args 0-1: Requested flash offset (blocks)

Documentation/mbox_protocol.md +0 -0
@@ -466,11 +498,15 @@ Command:
  		Args 0-1: Requested flash offset (blocks)
  		Args 2-3: Requested flash size to access (blocks)

Documentation/mbox_protocol.md +4 -0
+		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)

Documentation/mbox_protocol.md +1 -1
-		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)

Documentation/mbox_protocol.md +0 -0
@@ -504,9 +540,7 @@ Command:

  window.

 Command:

Documentation/mbox_protocol.md +1 -3
-	CLOSE_WINDOW
-	Implemented in Versions:
-		V1, V2
+	CLOSE_WINDOW (V1)

  Arguments:
  V1:
  -

Documentation/mbox_protocol.md +0 -0
@@ -533,9 +567,7 @@ Command:

  evicted from the cache.
 Command:

Documentation/mbox_protocol.md +1 -3
-	MARK_WRITE_DIRTY
-	Implemented in Versions:
-		V1, V2
+	MARK_WRITE_DIRTY (V1)

  Arguments:
  V1:
  Args 0-1: Flash offset to mark from base of flash (blocks)

Documentation/mbox_protocol.md +0 -0
@@ -544,6 +576,7 @@ Command:

  V2:
  Args 0-1: Window offset to mark (blocks) Args 2-3: Number to mark dirty at offset (blocks)

Documentation/mbox_protocol.md +1 -0
+		Args 4  : Don't Erase Before Write (V3)


  Response:
  -

Documentation/mbox_protocol.md +0 -0
@@ -558,10 +591,15 @@ Command:

  block. If the offset + number exceeds the size of the active
  window then the command must not succeed.

Documentation/mbox_protocol.md +1 -0
+		The host can give a hint to the daemon that is

doesn't have to

Documentation/mbox_protocol.md +1 -0
+		erase a flash area before writing to it by setting

ARG[4]. This

Documentation/mbox_protocol.md +1 -0
+		means that the daemon will blindly perform a write

to that area

Documentation/mbox_protocol.md +1 -0
+		and will not try to erase it before hand. This can

be used if

Documentation/mbox_protocol.md +1 -0
+		the host knows that a large area has already been

erased for

Documentation/mbox_protocol.md +1 -0
+		example but then wants to perform many small

writes.
+
 Command

Documentation/mbox_protocol.md +1 -3
-	WRITE_FLUSH
-	Implemented in Versions:
-		V1, V2
+	WRITE_FLUSH (V1)

  Arguments:
  V1:
  Args 0-1: Flash offset to mark from base of flash (blocks)

Documentation/mbox_protocol.md +0 -0
@@ -585,9 +623,7 @@ Command



 Command:

Documentation/mbox_protocol.md +1 -3
-	BMC_EVENT_ACK
-	Implemented in Versions:
-		V1, V2
+	BMC_EVENT_ACK (V1)

  Arguments:
  Args 0: Bits in the BMC status byte
(mailbox data
  register 15) to ack

Documentation/mbox_protocol.md +0 -0
@@ -598,9 +634,7 @@ Command:

  supplied in mailbox register 15.

 Command:

Documentation/mbox_protocol.md +1 -3
-	MARK_WRITE_ERASED
-	Implemented in Versions:
-		V2
+	MARK_WRITE_ERASED (V2)

  Arguments:
  V2:
  Args 0-1: Window offset to erase (blocks)

Documentation/mbox_protocol.md +0 -0
@@ -617,6 +651,31 @@ 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.

Documentation/mbox_protocol.md +5 -0
+
+Command:
+	GET_FLASH_NAME (V3)
+	Arguments:
+		Args 0: Flash ID
Quoted 8 lines

Documentation/mbox_protocol.md Command: · line 660

Quoted 2 lines
Documentation/mbox_protocol.md +2 -0
+	Response:
+		Args 0-10: Flash Name / UID

Hopefully 11 bytes is enough. Well, 10 I guess - should we specify that the
value at index 10 be '\0'? I feel like not requiring that could lead to
undesirable implementations.

Depends on whether we require names be 11 bytes, be null terminated, or just contain trailing nulls for names shorter than 11 bytes.

If we're going to waste an argument on the null terminator we may as well just make the first argument the length of the name.

Is this something the protocol should care about. Maybe it's just up to the daemon and host implementation to put something here that they both understand.

Quoted 4 lines

I guess we don't want to go down the path of continued responses or magic
windows to accommodate larger names?

I'd prefer not :)

Quoted 10 lines
Quoted 10 lines
Documentation/mbox_protocol.md +2 -0
+	Notes:
+		Describes a flash with some kind of identifier

useful to the

Documentation/mbox_protocol.md +1 -0
+		host system. This is typically a null-padded

string.

Documentation/mbox_protocol.md +4 -0
+
+Command:
+	MARK_LOCKED (V3)
+	Arguments:
Quoted 8 lines

Documentation/mbox_protocol.md Command: · line 669

Quoted 2 lines
Documentation/mbox_protocol.md +2 -0
+		Args 0-1: Flash offset to lock (blocks)
+		Args 2-3: Number to lock at offset (blocks)

I guess it's hard to get away from using block-sized granuality. Do we
currently have any partitions that we might lock that are less than a block
size? Or are all partitions expected to be block-size aligned?

This was the motivation for allowing the host to request a block size, so that they can hopefully request something which allows locking at the required granularity. Currently all partitions are aligned to flash erase size (which is what we set block size to anyway).

It's not really worth allowing locking at a finer granularity than block size since this is how changes (mark dirty) are specified and so it would be impossible to write back any part of a block if a single byte in that block were locked. I'm in favour of using block size for now and changing it in a later version if this becomes an issue.

Thanks,
Suraj

Quoted 20 lines

Cheers,

Andrew

Quoted 15 lines
Documentation/mbox_protocol.md +5 -0
+		Args 4: Flash ID
+	Response:
+		-
+	Notes:
+		Lock an area of flash so that the host can't mark

it dirty or

Documentation/mbox_protocol.md +1 -0
+		erased. If the requested area is within the

current window and

Documentation/mbox_protocol.md +1 -0
+		that area is currently marked dirty or erased then

this command

Documentation/mbox_protocol.md +2 -0
+		must fail.
+

 ```

 ### BMC Events in Detail:

#4 lore raw

Re: [RFC] docs: Specify V3 of the mbox protocol

Quoted 49 lines
Quoted 19 lines
Quoted 14 lines

+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). An attempt to lock an area of flash which is not clean in the current
+window must fail with PARAM_ERROR. (V3)

I think we need to consider how locked regions interact with the in- memory
caching of the flash data.

Quoted 12 lines

The BMC doesn't know that the memory backing the LPC window has been written until it receives a MARK_DIRTY from the host. MARK_DIRTY is not
valid on a read window or a locked region, but that doesn't mean that changes to a locked region can't persist in memory due to caching to avoid flash access (which was a part of the motivation for memory- based
booting to begin with). This may naively fool host firmware into thinking it is
accessing unmolested data as the region is locked, whereas the region could
contain anything, just it will never be written to flash.

Correct

Quoted 14 lines

Should we require window requests intersecting a locked region always have at
least the locked region positively match the on-flash data? That way the
firmware that requested a region be locked could ensure it has whatever was on
the flash at the time it was locked by explicitly closing the window (read or
write) once finished with it, which requires a window be opened again for any
subsequent access. At that point (open) we can do the locked region intesection
calculation and check the data in the window as necessary.

Quoted 3 lines

I guess this brings about an interesting question, when a window is requested is it guaranteed that the window provided in return by the BMC contains the same contents as the flash for the requested area?

I think expecting otherwise would be strange. What way would the host have to validate that? It could keep its own hashes of window content, but it would need to hash the content itself after opening the window which may be a circular problem (e.g. host reboot if the daemon doesn't invalidate the cache across the reboot operation).

Quoted 6 lines

It
would seem intuitively that it should. The first time a window is opened that is true, but with in memory caching the host could make a change that it never tells the bmc about and the contents diverge, and (assuming the window isn't evicted) persist across window close/open calls.

Yep.

Quoted 2 lines

Is this the desired behaviour?

No, not in my opinion. It doesn't fit the principle of least surprise.

Quoted 11 lines

It's kind of the only behaviour which
makes the in-memory caching an effective performance improvement, if we reloaded every window every time then we may as well only have one window in memory anyway. Maybe we can do this a better way (see below).

It's worth noting that the current flash locking daemon implementation will explicitly reload an entire window whenever one which contains any locked regions is requested - ensuring (for at least as long as the access to the flash device is exclusive) the integrity of the locked regions. This could of course be optimised to only reload the locked region.

Right, and if we take up the techniques discussed below we may even be able to eliminate that.

Quoted 18 lines
Quoted 7 lines

Locked regions could thus be a performance hit if we always load the locked
regions from flash, but surely we prefer (some) integrity over performance.

Quoted 10 lines

Alternatively, you could cryptographically hash the per-block content of the
on-flash locked region during the MARK_LOCKED operation, then stash the hash
values away. On a CREATE_{READ,WRITE}_WINDOW operation you could hash any
intersecting, in-cache locked blocks and compare to the stashed hash values to
incur only one set of flash accesses (initial hash calculations) rather than n.

Quoted 8 lines

This seems like a nice balance between performance and data integrity.

I guess this brings about the question again as to whether we care about data changes we aren't told about. Do we store a hash of every window and before providing a cached copy verify the hash and reload the entire window from flash again if there is a discrepancy. The host isn't allowed to rely on the persistence of data it never tells the BMC about, but is this something the BMC should be checking?

I think so, again in support of the principle of least surprise, and the possible security implications. I proposed verifying the integrity of only the locked regions but it might be worth extending that to entire windows depending on the performance. We should do some measurements.

I think implementations also need to be noisy in the case of a discrepancy, logging on the BMC side and possibly issuing a BMC Event (taking another one of our reserved bits for the purpose). The modifications are pretty much limited to accidental scribbling (bugs), or malicious intent (probably enabled by more bugs). Either way, someone should be notified.

Quoted 13 lines
Quoted 12 lines

Documentation/mbox_protocol.md Command: · line 660

Quoted 6 lines

+Command:

Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Documentation/mbox_protocol.md +4 -0
+	GET_FLASH_NAME (V3)
+	Arguments:
+		Args 0: Flash ID
+	Response:
Documentation/mbox_protocol.md +1 -0
+		Args 0-10: Flash Name / UID

Hopefully 11 bytes is enough. Well, 10 I guess - should we specify that the
value at index 10 be '\0'? I feel like not requiring that could lead to
undesirable implementations.

Quoted 5 lines

Depends on whether we require names be 11 bytes, be null terminated, or just contain trailing nulls for names shorter than 11 bytes.

If we're going to waste an argument on the null terminator we may as well just make the first argument the length of the name.

I think that's a better idea generally. It doesn't assume C-string semantics, though it's likely that the implementations will require them, which was what I was looking out for.

Quoted 4 lines

Is this something the protocol should care about. Maybe it's just up to the daemon and host implementation to put something here that they both understand.

Probably not, it was just a thought. It's a balance against avoiding potential vulnerabilities and over-specifying behaviour.

Quoted 8 lines
Quoted 5 lines

I guess we don't want to go down the path of continued responses or magic
windows to accommodate larger names?

I'd prefer not :)

Same :) Just throwing the question out there for discussion

Quoted 19 lines
Quoted 8 lines
Quoted 8 lines
Quoted 3 lines
Quoted 3 lines

Review

Quoted 3 lines
(quoted diff) +2 -0
+	Notes:
+		Describes a flash with some kind of identifier

useful to the

Quoted 1 line
Quoted 1 line

Review

Quoted 1 line
(quoted diff) +1 -0
+		host system. This is typically a null-padded

string.

(quoted diff) +2 -0
+
+Command:
Quoted 10 lines

Documentation/mbox_protocol.md Command: · line 669

Quoted 4 lines
Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
Documentation/mbox_protocol.md +3 -0
+	MARK_LOCKED (V3)
+	Arguments:
+		Args 0-1: Flash offset to lock (blocks)
Documentation/mbox_protocol.md +1 -0
+		Args 2-3: Number to lock at offset (blocks)

I guess it's hard to get away from using block-sized granuality. Do we
currently have any partitions that we might lock that are less than a block
size? Or are all partitions expected to be block-size aligned?

Quoted 4 lines

This was the motivation for allowing the host to request a block size, so that they can hopefully request something which allows locking at the required granularity. Currently all partitions are aligned to flash erase size (which is what we set block size to anyway).

Okay. It might be worth making a note in the documentation for MBOX_GET_INFO saying as much.

Quoted 6 lines

It's not really worth allowing locking at a finer granularity than block size since this is how changes (mark dirty) are specified and so it would be impossible to write back any part of a block if a single byte in that block were locked. I'm in favour of using block size for now and changing it in a later version if this becomes an issue.

Right, it's either blocks for everything or bytes for everything. Consistency is good. I don't think we want to go through the effort of changing that aspect of the spec right now.

Cheers,

Andrew

#5 lore raw

Re: [RFC] docs: Specify V3 of the mbox protocol

@wak:

As per Andrews suggestion below, how do you feel about making the first arg in the response for get flash name the length?

@andrew:

Since your comments regarding flash integrity aren't really relevant at the protocol level do you think it's something which needs to be mentioned in this document or is just common sense (unless you're me and didn't implement it that way :p)...

Quoted 274 lines · Andrew Jeffery
Quoted 64 lines
Quoted 33 lines
Quoted 9 lines

+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

Quoted 8 lines

be
written back
+to the backing data source (i.e. that area of flash must be treated as read
+only). An attempt to lock an area of flash which is not clean in
the current
+window must fail with PARAM_ERROR. (V3)

I think we need to consider how locked regions interact with the in-
memory
caching of the flash data.

The BMC doesn't know that the memory backing the LPC window has been
written until it receives a MARK_DIRTY from the host. MARK_DIRTY is
not
valid on a read window or a locked region, but that doesn't mean that
changes to a locked region can't persist in memory due to caching to
avoid flash access (which was a part of the motivation for

Quoted 8 lines

memory-
based
booting to begin with). This may naively fool host firmware into thinking it is
accessing unmolested data as the region is locked, whereas the region
could
contain anything, just it will never be written to flash.

Correct

Quoted 11 lines

Should we require window requests intersecting a locked region always
have at
least the locked region positively match the on-flash data? That way
the
firmware that requested a region be locked could ensure it has whatever was on
the flash at the time it was locked by explicitly closing the window

Quoted 8 lines

(read or
write) once finished with it, which requires a window be opened again
for any
subsequent access. At that point (open) we can do the locked region
intesection
calculation and check the data in the window as necessary.

Quoted 4 lines

I guess this brings about an interesting question, when a window is requested is it guaranteed that the window provided in return by the
BMC contains the same contents as the flash for the requested area?

I think expecting otherwise would be strange. What way would the host have to validate that? It could keep its own hashes of window content,
but it would need to hash the content itself after opening the window which may be a circular problem (e.g. host reboot if the daemon doesn't
invalidate the cache across the reboot operation).

Quoted 9 lines

 It
would seem intuitively that it should. The first time a window is opened that is true, but with in memory caching the host could make a
change that it never tells the bmc about and the contents diverge, and
(assuming the window isn't evicted) persist across window close/open
calls.

Yep.

Quoted 2 lines

Is this the desired behaviour?

No, not in my opinion. It doesn't fit the principle of least surprise.

Quoted 7 lines

It's kind of the only behaviour which
makes the in-memory caching an effective performance improvement, if we
reloaded every window every time then we may as well only have one window in memory anyway. Maybe we can do this a better way (see below).

Quoted 10 lines

It's worth noting that the current flash locking daemon implementation
will explicitly reload an entire window whenever one which contains any
locked regions is requested - ensuring (for at least as long as the access to the flash device is exclusive) the integrity of the locked
regions. This could of course be optimised to only reload the locked
region.

Right, and if we take up the techniques discussed below we may even be
able to eliminate that.

Quoted 26 lines
Quoted 8 lines

Locked regions could thus be a performance hit if we always load the
locked
regions from flash, but surely we prefer (some) integrity over performance.

Quoted 14 lines

Alternatively, you could cryptographically hash the per-block content
of the
on-flash locked region during the MARK_LOCKED operation, then stash
the hash
values away. On a CREATE_{READ,WRITE}_WINDOW operation you could hash
any
intersecting, in-cache locked blocks and compare to the stashed hash
values to
incur only one set of flash accesses (initial hash calculations) rather than n.

This seems like a nice balance between performance and data integrity.

Quoted 10 lines

I guess this brings about the question again as to whether we care about data changes we aren't told about. Do we store a hash of every
window and before providing a cached copy verify the hash and reload
the entire window from flash again if there is a discrepancy. The host
isn't allowed to rely on the persistence of data it never tells the BMC
about, but is this something the BMC should be checking?

I think so, again in support of the principle of least surprise, and the possible security implications. I proposed verifying the integrity
of only the locked regions but it might be worth extending that to entire windows depending on the performance. We should do some measurements.

I think implementations also need to be noisy in the case of a discrepancy, logging on the BMC side and possibly issuing a BMC Event (taking another one of our reserved bits for the purpose). The modifications are pretty much limited to accidental scribbling (bugs),
or malicious intent (probably enabled by more bugs). Either way, someone should be notified.

Quoted 16 lines
Quoted 15 lines

Documentation/mbox_protocol.md Command: · line 660

Quoted 7 lines

+Command:

Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Documentation/mbox_protocol.md +4 -0
+	GET_FLASH_NAME (V3)
+	Arguments:
+		Args 0: Flash ID
+	Response:
Documentation/mbox_protocol.md +1 -0
+		Args 0-10: Flash Name / UID

Hopefully 11 bytes is enough. Well, 10 I guess - should we specify
that the
value at index 10 be '\0'? I feel like not requiring that could lead
to
undesirable implementations.

Quoted 7 lines

Depends on whether we require names be 11 bytes, be null terminated, or
just contain trailing nulls for names shorter than 11 bytes.

If we're going to waste an argument on the null terminator we may as
well just make the first argument the length of the name.

I think that's a better idea generally. It doesn't assume C-string semantics, though it's likely that the implementations will require them, which was what I was looking out for.

Quoted 6 lines

Is this something the protocol should care about. Maybe it's just up to
the daemon and host implementation to put something here that they both
understand.

Probably not, it was just a thought. It's a balance against avoiding potential vulnerabilities and over-specifying behaviour.

Quoted 9 lines
Quoted 6 lines

I guess we don't want to go down the path of continued responses or
magic
windows to accommodate larger names?

I'd prefer not :)

Same :) Just throwing the question out there for discussion

Quoted 26 lines
Quoted 12 lines
Quoted 12 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
(quoted diff) +2 -0
+	Notes:
+		Describes a flash with some kind of

identifier

useful to the

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
(quoted diff) +1 -0
+		host system. This is typically a null-

padded

string.

(quoted diff) +2 -0
+
+Command:
Quoted 13 lines

Documentation/mbox_protocol.md Command: · line 669

Quoted 5 lines
Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
Documentation/mbox_protocol.md +3 -0
+	MARK_LOCKED (V3)
+	Arguments:
+		Args 0-1: Flash offset to lock (blocks)
Documentation/mbox_protocol.md +1 -0
+		Args 2-3: Number to lock at offset (blocks)

I guess it's hard to get away from using block-sized granuality. Do
we
currently have any partitions that we might lock that are less than a
block
size? Or are all partitions expected to be block-size aligned?

Quoted 7 lines

This was the motivation for allowing the host to request a block size,
so that they can hopefully request something which allows locking at
the required granularity. Currently all partitions are aligned to flash
erase size (which is what we set block size to anyway).

Okay. It might be worth making a note in the documentation for MBOX_GET_INFO saying as much.

Quoted 9 lines

It's not really worth allowing locking at a finer granularity than block size since this is how changes (mark dirty) are specified and so
it would be impossible to write back any part of a block if a single
byte in that block were locked. I'm in favour of using block size for
now and changing it in a later version if this becomes an issue.

Right, it's either blocks for everything or bytes for everything. Consistency is good. I don't think we want to go through the effort of
changing that aspect of the spec right now.

Cheers,

Andrew

#6 lore raw

Re: [RFC] docs: Specify V3 of the mbox protocol

Quoted 5 lines · Suraj Jitindar Singh

@wak:

As per Andrews suggestion below, how do you feel about making the first arg in the response for get flash name the length?

Quoted 7 lines

@andrew:

Since your comments regarding flash integrity aren't really relevant at the protocol level do you think it's something which needs to be mentioned in this document or is just common sense (unless you're me and didn't implement it that way :p)...

I'd say that the fact that you didn't implement it off the bat means that others won't either, so I think it deserves some attention.

If we choose to do a host alert on the BMC detecting an error then that obviously needs to be specified here.

But winding back a bit, I'd suggest it's important to *specify* flash integrity, even though the spec shouldn't enforce a particular implementation. It should be enough to say something like:

CREATE_{READ,WRITE}_WINDOW must provide a window containing data that is known to represent the state of the flash at the time the window is opened.

Maybe we need to make provisions for implementation suggestions in the spec as well. I might do some reading around to see what other specs do in this regard.

Cheers,

Andrew

#7 lore raw

Re: [RFC] docs: Specify V3 of the mbox protocol

In reply to Suraj Jitindar Singh

@wak ping,

Thoughts on using the first arg in the response of get flash name as a length argument?

Quoted 322 lines · Suraj Jitindar Singh

@wak:

As per Andrews suggestion below, how do you feel about making the first
arg in the response for get flash name the length?

@andrew:

Since your comments regarding flash integrity aren't really relevant at
the protocol level do you think it's something which needs to be mentioned in this document or is just common sense (unless you're me and didn't implement it that way :p)...

Quoted 307 lines · Andrew Jeffery
Quoted 74 lines
Quoted 42 lines
Quoted 13 lines

+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

Quoted 8 lines

written back
+to the backing data source (i.e. that area of flash must be treated as read
+only). An attempt to lock an area of flash which is not clean
in
the current
+window must fail with PARAM_ERROR. (V3)

I think we need to consider how locked regions interact with the
in-
memory
caching of the flash data.

The BMC doesn't know that the memory backing the LPC window has been
written until it receives a MARK_DIRTY from the host. MARK_DIRTY
is
not
valid on a read window or a locked region, but that doesn't mean
that
changes to a locked region can't persist in memory due to caching
to
avoid flash access (which was a part of the motivation for memory-

Quoted 8 lines

based
booting to begin with). This may naively fool host firmware into
thinking it is
accessing unmolested data as the region is locked, whereas the region
could
contain anything, just it will never be written to flash.

Correct

Quoted 12 lines

Should we require window requests intersecting a locked region always
have at
least the locked region positively match the on-flash data? That
way
the
firmware that requested a region be locked could ensure it has whatever was on
the flash at the time it was locked by explicitly closing the window

Quoted 8 lines

(read or
write) once finished with it, which requires a window be opened again
for any
subsequent access. At that point (open) we can do the locked region
intesection
calculation and check the data in the window as necessary.

Quoted 6 lines

I guess this brings about an interesting question, when a window is
requested is it guaranteed that the window provided in return by the
BMC contains the same contents as the flash for the requested area?

I think expecting otherwise would be strange. What way would the host
have to validate that? It could keep its own hashes of window content,
but it would need to hash the content itself after opening the window
which may be a circular problem (e.g. host reboot if the daemon doesn't
invalidate the cache across the reboot operation).

Quoted 11 lines

 It
would seem intuitively that it should. The first time a window is opened that is true, but with in memory caching the host could make
a
change that it never tells the bmc about and the contents diverge,
and
(assuming the window isn't evicted) persist across window close/open
calls.

Yep.

Quoted 2 lines

Is this the desired behaviour?

No, not in my opinion. It doesn't fit the principle of least surprise.

Quoted 8 lines

It's kind of the only behaviour which
makes the in-memory caching an effective performance improvement, if we
reloaded every window every time then we may as well only have one
window in memory anyway. Maybe we can do this a better way (see below).

Quoted 12 lines

It's worth noting that the current flash locking daemon implementation
will explicitly reload an entire window whenever one which contains
any
locked regions is requested - ensuring (for at least as long as the
access to the flash device is exclusive) the integrity of the locked
regions. This could of course be optimised to only reload the locked
region.

Right, and if we take up the techniques discussed below we may even be
able to eliminate that.

Quoted 29 lines
Quoted 9 lines

Locked regions could thus be a performance hit if we always load
the
locked
regions from flash, but surely we prefer (some) integrity over performance.

Quoted 16 lines

Alternatively, you could cryptographically hash the per-block content
of the
on-flash locked region during the MARK_LOCKED operation, then stash
the hash
values away. On a CREATE_{READ,WRITE}_WINDOW operation you could
hash
any
intersecting, in-cache locked blocks and compare to the stashed hash
values to
incur only one set of flash accesses (initial hash calculations)
rather than n.

This seems like a nice balance between performance and data integrity.

Quoted 12 lines

I guess this brings about the question again as to whether we care
about data changes we aren't told about. Do we store a hash of every
window and before providing a cached copy verify the hash and reload
the entire window from flash again if there is a discrepancy. The host
isn't allowed to rely on the persistence of data it never tells the
BMC
about, but is this something the BMC should be checking?

I think so, again in support of the principle of least surprise, and
the possible security implications. I proposed verifying the integrity
of only the locked regions but it might be worth extending that to entire windows depending on the performance. We should do some measurements.

I think implementations also need to be noisy in the case of a discrepancy, logging on the BMC side and possibly issuing a BMC Event
(taking another one of our reserved bits for the purpose). The modifications are pretty much limited to accidental scribbling (bugs),
or malicious intent (probably enabled by more bugs). Either way, someone should be notified.

Quoted 16 lines
Quoted 15 lines

Documentation/mbox_protocol.md Command: · line 660

Quoted 7 lines

+Command:

Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Documentation/mbox_protocol.md +4 -0
+	GET_FLASH_NAME (V3)
+	Arguments:
+		Args 0: Flash ID
+	Response:
Documentation/mbox_protocol.md +1 -0
+		Args 0-10: Flash Name / UID

Hopefully 11 bytes is enough. Well, 10 I guess - should we specify
that the
value at index 10 be '\0'? I feel like not requiring that could lead
to
undesirable implementations.

Quoted 7 lines

Depends on whether we require names be 11 bytes, be null terminated, or
just contain trailing nulls for names shorter than 11 bytes.

If we're going to waste an argument on the null terminator we may as
well just make the first argument the length of the name.

I think that's a better idea generally. It doesn't assume C-string semantics, though it's likely that the implementations will require them, which was what I was looking out for.

Quoted 7 lines

Is this something the protocol should care about. Maybe it's just up to
the daemon and host implementation to put something here that they
both
understand.

Probably not, it was just a thought. It's a balance against avoiding
potential vulnerabilities and over-specifying behaviour.

Quoted 10 lines
Quoted 7 lines

I guess we don't want to go down the path of continued responses
or
magic
windows to accommodate larger names?

I'd prefer not :)

Same :) Just throwing the question out there for discussion

Quoted 28 lines
Quoted 12 lines
Quoted 12 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
(quoted diff) +2 -0
+	Notes:
+		Describes a flash with some kind of

identifier

useful to the

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
(quoted diff) +1 -0
+		host system. This is typically a null-

padded

string.

(quoted diff) +2 -0
+
+Command:
Quoted 15 lines

Documentation/mbox_protocol.md Command: · line 669

Quoted 6 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Documentation/mbox_protocol.md +3 -0
+	MARK_LOCKED (V3)
+	Arguments:
+		Args 0-1: Flash offset to lock

(blocks)

Documentation/mbox_protocol.md +1 -0
+		Args 2-3: Number to lock at offset (blocks)

I guess it's hard to get away from using block-sized granuality.
Do
we
currently have any partitions that we might lock that are less than a
block
size? Or are all partitions expected to be block-size aligned?

Quoted 7 lines

This was the motivation for allowing the host to request a block size,
so that they can hopefully request something which allows locking at
the required granularity. Currently all partitions are aligned to flash
erase size (which is what we set block size to anyway).

Okay. It might be worth making a note in the documentation for MBOX_GET_INFO saying as much.

Quoted 11 lines

It's not really worth allowing locking at a finer granularity than
block size since this is how changes (mark dirty) are specified and
so
it would be impossible to write back any part of a block if a single
byte in that block were locked. I'm in favour of using block size for
now and changing it in a later version if this becomes an issue.

Right, it's either blocks for everything or bytes for everything. Consistency is good. I don't think we want to go through the effort of
changing that aspect of the spec right now.

Cheers,

Andrew

#8 lore raw

Re: [RFC] docs: Specify V3 of the mbox protocol

Yeah, go ahead and change it to that

Quoted 329 lines · Suraj Jitindar Singh

@wak ping,

Thoughts on using the first arg in the response of get flash name as a length argument?

Quoted 322 lines · Suraj Jitindar Singh

@wak:

As per Andrews suggestion below, how do you feel about making the first
arg in the response for get flash name the length?

@andrew:

Since your comments regarding flash integrity aren't really relevant at
the protocol level do you think it's something which needs to be mentioned in this document or is just common sense (unless you're me and didn't implement it that way :p)...

Quoted 307 lines · Andrew Jeffery
Quoted 74 lines
Quoted 42 lines
Quoted 13 lines

+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

Quoted 8 lines

written back
+to the backing data source (i.e. that area of flash must be treated as read
+only). An attempt to lock an area of flash which is not clean
in
the current
+window must fail with PARAM_ERROR. (V3)

I think we need to consider how locked regions interact with the
in-
memory
caching of the flash data.

The BMC doesn't know that the memory backing the LPC window has been
written until it receives a MARK_DIRTY from the host. MARK_DIRTY
is
not
valid on a read window or a locked region, but that doesn't mean
that
changes to a locked region can't persist in memory due to caching
to
avoid flash access (which was a part of the motivation for memory-

Quoted 8 lines

based
booting to begin with). This may naively fool host firmware into
thinking it is
accessing unmolested data as the region is locked, whereas the region
could
contain anything, just it will never be written to flash.

Correct

Quoted 12 lines

Should we require window requests intersecting a locked region always
have at
least the locked region positively match the on-flash data? That
way
the
firmware that requested a region be locked could ensure it has whatever was on
the flash at the time it was locked by explicitly closing the window

Quoted 8 lines

(read or
write) once finished with it, which requires a window be opened again
for any
subsequent access. At that point (open) we can do the locked region
intesection
calculation and check the data in the window as necessary.

Quoted 6 lines

I guess this brings about an interesting question, when a window is
requested is it guaranteed that the window provided in return by the
BMC contains the same contents as the flash for the requested area?

I think expecting otherwise would be strange. What way would the host
have to validate that? It could keep its own hashes of window content,
but it would need to hash the content itself after opening the window
which may be a circular problem (e.g. host reboot if the daemon doesn't
invalidate the cache across the reboot operation).

Quoted 11 lines

It
would seem intuitively that it should. The first time a window is opened that is true, but with in memory caching the host could make
a
change that it never tells the bmc about and the contents diverge,
and
(assuming the window isn't evicted) persist across window close/open
calls.

Yep.

Quoted 2 lines

Is this the desired behaviour?

No, not in my opinion. It doesn't fit the principle of least surprise.

Quoted 8 lines

It's kind of the only behaviour which
makes the in-memory caching an effective performance improvement, if we
reloaded every window every time then we may as well only have one
window in memory anyway. Maybe we can do this a better way (see below).

Quoted 12 lines

It's worth noting that the current flash locking daemon implementation
will explicitly reload an entire window whenever one which contains
any
locked regions is requested - ensuring (for at least as long as the
access to the flash device is exclusive) the integrity of the locked
regions. This could of course be optimised to only reload the locked
region.

Right, and if we take up the techniques discussed below we may even be
able to eliminate that.

Quoted 29 lines
Quoted 9 lines

Locked regions could thus be a performance hit if we always load
the
locked
regions from flash, but surely we prefer (some) integrity over performance.

Quoted 16 lines

Alternatively, you could cryptographically hash the per-block content
of the
on-flash locked region during the MARK_LOCKED operation, then stash
the hash
values away. On a CREATE_{READ,WRITE}_WINDOW operation you could
hash
any
intersecting, in-cache locked blocks and compare to the stashed hash
values to
incur only one set of flash accesses (initial hash calculations)
rather than n.

This seems like a nice balance between performance and data integrity.

Quoted 12 lines

I guess this brings about the question again as to whether we care
about data changes we aren't told about. Do we store a hash of every
window and before providing a cached copy verify the hash and reload
the entire window from flash again if there is a discrepancy. The host
isn't allowed to rely on the persistence of data it never tells the
BMC
about, but is this something the BMC should be checking?

I think so, again in support of the principle of least surprise, and
the possible security implications. I proposed verifying the integrity
of only the locked regions but it might be worth extending that to entire windows depending on the performance. We should do some measurements.

I think implementations also need to be noisy in the case of a discrepancy, logging on the BMC side and possibly issuing a BMC Event
(taking another one of our reserved bits for the purpose). The modifications are pretty much limited to accidental scribbling (bugs),
or malicious intent (probably enabled by more bugs). Either way, someone should be notified.

Quoted 16 lines
Quoted 8 lines
Quoted 7 lines

+Command:

Quoted 4 lines
Quoted 4 lines

Documentation/mbox_protocol.md Command: · line 659

Quoted 4 lines
Documentation/mbox_protocol.md +4 -0
+       GET_FLASH_NAME (V3)
+       Arguments:
+               Args 0: Flash ID
+       Response:

+ Args 0-10: Flash Name / UID

Quoted 7 lines

Hopefully 11 bytes is enough. Well, 10 I guess - should we specify
that the
value at index 10 be '\0'? I feel like not requiring that could lead
to
undesirable implementations.

Quoted 7 lines

Depends on whether we require names be 11 bytes, be null terminated, or
just contain trailing nulls for names shorter than 11 bytes.

If we're going to waste an argument on the null terminator we may as
well just make the first argument the length of the name.

I think that's a better idea generally. It doesn't assume C-string semantics, though it's likely that the implementations will require them, which was what I was looking out for.

Quoted 7 lines

Is this something the protocol should care about. Maybe it's just up to
the daemon and host implementation to put something here that they
both
understand.

Probably not, it was just a thought. It's a balance against avoiding
potential vulnerabilities and over-specifying behaviour.

Quoted 10 lines
Quoted 7 lines

I guess we don't want to go down the path of continued responses
or
magic
windows to accommodate larger names?

I'd prefer not :)

Same :) Just throwing the question out there for discussion

Quoted 28 lines
Quoted 19 lines
Quoted 17 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
(quoted diff) +2 -0
+       Notes:
+               Describes a flash with some kind of

identifier

useful to the

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

+ host system. This is typically a null-
padded

string.

(quoted diff) +2 -0
+
+Command:
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Documentation/mbox_protocol.md +3 -0
+       MARK_LOCKED (V3)
+       Arguments:
+               Args 0-1: Flash offset to lock

(blocks)

Quoted 1 line

+ Args 2-3: Number to lock at offset (blocks)

Quoted 8 lines

I guess it's hard to get away from using block-sized granuality.
Do
we
currently have any partitions that we might lock that are less than a
block
size? Or are all partitions expected to be block-size aligned?

Quoted 7 lines

This was the motivation for allowing the host to request a block size,
so that they can hopefully request something which allows locking at
the required granularity. Currently all partitions are aligned to flash
erase size (which is what we set block size to anyway).

Okay. It might be worth making a note in the documentation for MBOX_GET_INFO saying as much.

Quoted 11 lines

It's not really worth allowing locking at a finer granularity than
block size since this is how changes (mark dirty) are specified and
so
it would be impossible to write back any part of a block if a single
byte in that block were locked. I'm in favour of using block size for
now and changing it in a later version if this becomes an issue.

Right, it's either blocks for everything or bytes for everything. Consistency is good. I don't think we want to go through the effort of
changing that aspect of the spec right now.

Cheers,

Andrew

#9 lore raw

Re: [RFC] docs: Specify V3 of the mbox protocol

Acked-by Adriana Kobylak <[email protected] <mailto:[email protected]>.com>
Quoted 333 lines · William Kennington

Yeah, go ahead and change it to that

On Mon, Oct 2, 2017 at 9:26 PM Suraj Jitindar Singh <[email protected] <mailto:[email protected]>> wrote:
@wak ping,

Thoughts on using the first arg in the response of get flash name as a length argument?

Quoted 322 lines · Suraj Jitindar Singh

@wak:

As per Andrews suggestion below, how do you feel about making the first
arg in the response for get flash name the length?

@andrew:

Since your comments regarding flash integrity aren't really relevant at
the protocol level do you think it's something which needs to be mentioned in this document or is just common sense (unless you're me and didn't implement it that way :p)...

Quoted 307 lines · Andrew Jeffery
Quoted 74 lines
Quoted 42 lines
Quoted 13 lines

+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

Quoted 8 lines

written back
+to the backing data source (i.e. that area of flash must be treated as read
+only). An attempt to lock an area of flash which is not clean
in
the current
+window must fail with PARAM_ERROR. (V3)

I think we need to consider how locked regions interact with the
in-
memory
caching of the flash data.

The BMC doesn't know that the memory backing the LPC window has been
written until it receives a MARK_DIRTY from the host. MARK_DIRTY
is
not
valid on a read window or a locked region, but that doesn't mean
that
changes to a locked region can't persist in memory due to caching
to
avoid flash access (which was a part of the motivation for memory-

Quoted 8 lines

based
booting to begin with). This may naively fool host firmware into
thinking it is
accessing unmolested data as the region is locked, whereas the region
could
contain anything, just it will never be written to flash.

Correct

Quoted 12 lines

Should we require window requests intersecting a locked region always
have at
least the locked region positively match the on-flash data? That
way
the
firmware that requested a region be locked could ensure it has whatever was on
the flash at the time it was locked by explicitly closing the window

Quoted 8 lines

(read or
write) once finished with it, which requires a window be opened again
for any
subsequent access. At that point (open) we can do the locked region
intesection
calculation and check the data in the window as necessary.

Quoted 6 lines

I guess this brings about an interesting question, when a window is
requested is it guaranteed that the window provided in return by the
BMC contains the same contents as the flash for the requested area?

I think expecting otherwise would be strange. What way would the host
have to validate that? It could keep its own hashes of window content,
but it would need to hash the content itself after opening the window
which may be a circular problem (e.g. host reboot if the daemon doesn't
invalidate the cache across the reboot operation).

Quoted 11 lines

It
would seem intuitively that it should. The first time a window is opened that is true, but with in memory caching the host could make
a
change that it never tells the bmc about and the contents diverge,
and
(assuming the window isn't evicted) persist across window close/open
calls.

Yep.

Quoted 2 lines

Is this the desired behaviour?

No, not in my opinion. It doesn't fit the principle of least surprise.

Quoted 8 lines

It's kind of the only behaviour which
makes the in-memory caching an effective performance improvement, if we
reloaded every window every time then we may as well only have one
window in memory anyway. Maybe we can do this a better way (see below).

Quoted 12 lines

It's worth noting that the current flash locking daemon implementation
will explicitly reload an entire window whenever one which contains
any
locked regions is requested - ensuring (for at least as long as the
access to the flash device is exclusive) the integrity of the locked
regions. This could of course be optimised to only reload the locked
region.

Right, and if we take up the techniques discussed below we may even be
able to eliminate that.

Quoted 29 lines
Quoted 9 lines

Locked regions could thus be a performance hit if we always load
the
locked
regions from flash, but surely we prefer (some) integrity over performance.

Quoted 16 lines

Alternatively, you could cryptographically hash the per-block content
of the
on-flash locked region during the MARK_LOCKED operation, then stash
the hash
values away. On a CREATE_{READ,WRITE}_WINDOW operation you could
hash
any
intersecting, in-cache locked blocks and compare to the stashed hash
values to
incur only one set of flash accesses (initial hash calculations)
rather than n.

This seems like a nice balance between performance and data integrity.

Quoted 12 lines

I guess this brings about the question again as to whether we care
about data changes we aren't told about. Do we store a hash of every
window and before providing a cached copy verify the hash and reload
the entire window from flash again if there is a discrepancy. The host
isn't allowed to rely on the persistence of data it never tells the
BMC
about, but is this something the BMC should be checking?

I think so, again in support of the principle of least surprise, and
the possible security implications. I proposed verifying the integrity
of only the locked regions but it might be worth extending that to entire windows depending on the performance. We should do some measurements.

I think implementations also need to be noisy in the case of a discrepancy, logging on the BMC side and possibly issuing a BMC Event
(taking another one of our reserved bits for the purpose). The modifications are pretty much limited to accidental scribbling (bugs),
or malicious intent (probably enabled by more bugs). Either way, someone should be notified.

Quoted 16 lines
Quoted 8 lines
Quoted 7 lines

+Command:

Quoted 4 lines
Quoted 4 lines

Review

Quoted 4 lines
(quoted diff) +4 -0
+       GET_FLASH_NAME (V3)
+       Arguments:
+               Args 0: Flash ID
+       Response:

+ Args 0-10: Flash Name / UID

Quoted 7 lines

Hopefully 11 bytes is enough. Well, 10 I guess - should we specify
that the
value at index 10 be '\0'? I feel like not requiring that could lead
to
undesirable implementations.

Quoted 7 lines

Depends on whether we require names be 11 bytes, be null terminated, or
just contain trailing nulls for names shorter than 11 bytes.

If we're going to waste an argument on the null terminator we may as
well just make the first argument the length of the name.

I think that's a better idea generally. It doesn't assume C-string semantics, though it's likely that the implementations will require them, which was what I was looking out for.

Quoted 7 lines

Is this something the protocol should care about. Maybe it's just up to
the daemon and host implementation to put something here that they
both
understand.

Probably not, it was just a thought. It's a balance against avoiding
potential vulnerabilities and over-specifying behaviour.

Quoted 10 lines
Quoted 7 lines

I guess we don't want to go down the path of continued responses
or
magic
windows to accommodate larger names?

I'd prefer not :)

Same :) Just throwing the question out there for discussion

Quoted 28 lines
Quoted 19 lines
Quoted 17 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
(quoted diff) +2 -0
+       Notes:
+               Describes a flash with some kind of

identifier

useful to the

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

+ host system. This is typically a null-
padded

string.

(quoted diff) +2 -0
+
+Command:
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
(quoted diff) +3 -0
+       MARK_LOCKED (V3)
+       Arguments:
+               Args 0-1: Flash offset to lock

(blocks)

Quoted 1 line

+ Args 2-3: Number to lock at offset (blocks)

Quoted 8 lines

I guess it's hard to get away from using block-sized granuality.
Do
we
currently have any partitions that we might lock that are less than a
block
size? Or are all partitions expected to be block-size aligned?

Quoted 7 lines

This was the motivation for allowing the host to request a block size,
so that they can hopefully request something which allows locking at
the required granularity. Currently all partitions are aligned to flash
erase size (which is what we set block size to anyway).

Okay. It might be worth making a note in the documentation for MBOX_GET_INFO saying as much.

Quoted 11 lines

It's not really worth allowing locking at a finer granularity than
block size since this is how changes (mark dirty) are specified and
so
it would be impossible to write back any part of a block if a single
byte in that block were locked. I'm in favour of using block size for
now and changing it in a later version if this becomes an issue.

Right, it's either blocks for everything or bytes for everything. Consistency is good. I don't think we want to go through the effort of
changing that aspect of the spec right now.

Cheers,

Andrew