README: Update the documentation given new approach
Given the new design, update the README document.
Change-Id: I74a025981606329bd19944f9104d14fbeaca198b
Signed-off-by: Patrick Venture <venture@google.com>
diff --git a/README.md b/README.md
index 22da4f0..34fa32c 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,8 @@
This document describes the OpenBmc software implementing the secure flash
update mechanism.
+The primary details are [here](https://github.com/openbmc/docs/blob/master/designs/firmware_update_via_blobs.md).
+
## Introduction
This supports two methods of providing the image to stage. You can send the
@@ -10,12 +12,7 @@
~3 hours to send via this method. This can be done in <1 minutes via the PCI
bridge, or just a few minutes via LPC depending on the size of the mapped area.
-This is implemented in the Google OEM number space: **11129**.
-This is also implemented under the Firmware netfn.
-
-It is command: **127**
-
-The OpenBmc tool, not yet upstreamed, supports this approach.
+This is implemented as a phosphor blob handler.
The image must be signed via the production or development keys, the former
being required for production builds. The image itself and the image signature
@@ -43,43 +40,6 @@
TODO: Flesh out the UBI approach.
-## Primary Implementation Approaches
-
-To determine if the bridge sequence is supported you can send the
-`FlashRequestRegion` subcommand and see if it returns success with an address.
-However, for the sake of sanity, there is also a `FlashVersion` subcommand
-that'll return the version of the protocol.
-
-### Data over IPMI Sequence
-
-If you're updating the image entirely over IPMI, then you should expect to send
-the following sequence of commands:
-
-1. `FlashStartTransfer`
-1. `FlashDataBlock` (for each piece of the image)
-1. `FlashDataFinish`
-1. `FlashStartHash`
-1. `FlashHashData` (for each piece of the hash)
-1. `FlashHashFinish`
-1. `FlashDataVerify`
-1. `FlashVerifyCheck` (repeatedly until it results with 3-5s sleeps)
-
-### Data over Bridge Sequence
-
-If you're using some region to send the image and hash, you should expect to
-send the following sequences of commands:
-
-1. `FlashStartTransfer`
-1. `FlashMapRegionLpc`(if necessary)
-1. `FlashRequestRegion`
-1. `FlashDataExtBlock` (for each piece of the image)
-1. `FlashDataFinish`
-1. `FlashStartHash`
-1. `FlashHashExtData` (for each piece of the hash)
-1. `FlashHashFinish`
-1. `FlashDataVerify`
-1. `FlashVerifyCheck` (repeatedly until it results with 3-5s sleeps)
-
## Bridge Options
### P2A
@@ -104,213 +64,7 @@
mapping request subcommand. The host can then read the _actual_ LPC address at
which the BMC was able to map, checking that it's usable.
-### USB
-
-As future work, USB should be considered an option for staging the image to be
-copied to the BMC.
-
-## Commands
-
-The following details each subcommand with which you'll lead the body of the
-command. Unlike some designs, the responses don't necessarily include the
-corresponding sub-command, partially because this protocol is meant to be used
-by one user at a time and trying to use otherwise can have negative effects and
-is not supported.
-
-In the following, any reference to the command body starts after the 3 bytes of
-OEM header, and the 1-byte subcommand.
-
-*This will now also go after the firmware function.*
-
-### FlashStartTransfer (0)
-
-The FlashStartTransfer command expects to receive a body of:
-
-```
-struct StartTx
-{
- uint32_t length; /* Maximum image length is 4GiB */
-};
-```
-
-However, this data is presently ignored.
-
-This command will first close out and abort any previous attempt at updating
-the flash.
-
-On success it will return 1 byte of `0x00`, in the body, after the 3-byte OEM
-portion.
-
-### FlashDataBlock (1)
-
-This command expects to receive a body of:
-
-```
-struct ChunkHdr
-{
- uint32_t offset; /* The byte sequence start, (0 based). */
-};
-```
-
-However, this data is presently ignored.
-
-Immediately following this structure are the bytes to write. The length of the
-entire packet is variable and handled at a higher level, therefore the number
-of bytes to write is the size of the command body less the sub-command (1 byte)
-and less the structure size (4 bytes).
-
-On success it will return 1 byte of `0x00`, in the body, after the 3-byte OEM
-portion.
-
-### FlashDataFinish (2)
-
-This command expects the body to be empty.
-
-On success it will return 1 byte of `0x00`, in the body, after the 3-byte OEM
-portion.
-
-### FlashStartHash (3)
-
-The FlashStartHash command expects to receive a body of:
-
-```
-struct StartTx
-{
- uint32_t length; /* Maximum image length is 4GiB */
-};
-```
-
-This is used! But it's only checked to see that it's non-zero.
-
-On success it will return 1 byte of `0x00`, in the body, after the 3-byte OEM
-portion.
-
-### FlashHashData (4)
-
-This command expects to receive a body of:
-
-```
-struct ChunkHdr
-{
- uint32_t offset; /* The byte sequence start, (0 based). */
-};
-```
-
-However, this data is presently ignored.
-
-Immediately following this structure are the bytes to write. The length of the
-entire packet is variable and handled at a higher level, therefore the number
-of bytes to write is the size of the command body less the sub-command (1 byte)
-and less the structure size (4 bytes).
-
-On success it will return 1 byte of `0x00`, in the body, after the 3-byte OEM
-portion.
-
-### FlashHashFinish (5)
-
-This command expects the body to be empty.
-
-On success it will return 1 byte of `0x00`, in the body, after the 3-byte OEM
-portion.
-
-### FlashDataVerify (6)
-
-This command expects the body to be empty.
-
-This will start the `verify_image` systemd service.
-
-On success it will return 1 byte of `0x00`, in the body, after the 3-byte OEM
-portion.
-
-### FlashAbort (7)
-
-This command expects the body to be empty.
-
-This command deletes any temporary files or flash image, hashes, etc.
-
-On success it will return 1 byte of `0x00`, in the body, after the 3-byte OEM
-portion.
-
-### FlashVerifyCheck (8)
-
-This command expects the body to be empty.
-
-This command opens the verification result file and checks to see if it
-contains: "`running`", "`success`" or "`failed`". This then packs that as a 1
-byte of result of:
-
-```
-enum VerifyCheckResponses
-{
- VerifyRunning = 0x00,
- VerifySuccess = 0x01,
- VerifyFailed = 0x02,
- VerifyOther = 0x03,
-};
-```
-
-### FlashVersion (9)
-
-This command expects the body to be empty.
-
-Returns 16-bit version sequence (little endian), in the body, after the 3-byte
-OEM portion.
-
-### FlashRequestRegion (10)
-
-Should **_return type string "LPC" or "P2A"_** but does not yet. We need to
-add this into another command, such as **_FlashRegionSupportedType_**
-
-returns 32-bit address (little endian) of either the BMC's memory buffer in BAR
-space (P2A bridge) or in LPC FW space (LPC bridge).
-
-### FlashDataExtBlock (11)
-
-This command expects to receive:
-
-```
-struct ExtChunkHdr
-{
- uint32_t length; /* Length of the data queued (little endian). */
-};
-```
-
-A design limitation of this is that it expects to be able to copy and write the
-data before the IPMI command times out, which should be completely possible.
-
-On success it will return 1 byte of `0x00`, in the body, after the 3-byte OEM
-portion.
-
-### FlashHashExtData (12)
-
-This command expects to receive:
-
-```
-struct ExtChunkHdr
-{
- uint32_t length; /* Length of the data queued (little endian). */
-};
-```
-
-A design limitation of this is that it expects to be able to copy and write the
-data before the IPMI command times out, which should be completely possible.
-
-On success it will return 1 byte of `0x00`, in the body, after the 3-byte OEM
-portion.
-
-### FlashMapRegionLpc (13)
-
-This command maps a chunk (size specified by host) of the BMC memory into LPC
-space at a specified address. It expects to receive:
-
-```
-struct LpcRegion
-{
- uint32_t address; /* Host LPC address where the chunk is to be mapped. */
- uint32_t length; /* Size of the chunk to be mapped. */
-};
-```
-
+**Note: Not yet implemented for Stat metadata**
The command will return 1 byte in the response body with value:
* 0x00 on success (1 byte)
@@ -321,3 +75,9 @@
After a success map to LPC space, the host can use FlashRequestRegion to read
the LPC address of the chunk mapped, which should match that requested.
+
+### USB
+
+As future work, USB should be considered an option for staging the image to be
+copied to the BMC.
+