tree 8ec513159b16819826ec31bde3072f9589929910
parent 7760fd8f8e6939231ea819ec4744535d019a2d4c
author Suraj Jitindar Singh <sjitindarsingh@gmail.com> 1507077920 +1100
committer Andrew Jeffery <andrew@aj.id.au> 1508478505 +1030

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 --clear-locked command and the locked areas are stored in a file
on the BMC filesystem to ensure persistence across BMC reboots/daemon
crashes.

Multiple flash device support proposed and defined by:
William A. Kennington III <wak@google.com>

Change-Id: I898698840dec221ae20e33943bb28e65abc4fe37
Signed-off-by: Suraj Jitindar Singh <sjitindarsingh@gmail.com>
Reviewed-by: Andrew Jeffery <andrew@aj.id.au>
Acked-by: Adriana Kobylak <anoo@us.ibm.com>
Reviewed-by: William A. Kennington III <wak@google.com>
Signed-off-by: Andrew Jeffery <andrew@aj.id.au>