Arthur Heymans has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/37243 )
Change subject: Documentation: Add SMMSTORE documentation ......................................................................
Documentation: Add SMMSTORE documentation
This documents the smmstore API.
Change-Id: I992c04c0cf9b3f03755cf3fede2c82c6471a5ef4 Signed-off-by: Arthur Heymans arthur@aheymans.xyz --- M Documentation/drivers/index.md A Documentation/drivers/smmstore.md 2 files changed, 122 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/43/37243/1
diff --git a/Documentation/drivers/index.md b/Documentation/drivers/index.md index 60e90c3..807ed85 100644 --- a/Documentation/drivers/index.md +++ b/Documentation/drivers/index.md @@ -5,3 +5,4 @@ they allow to easily reuse existing code accross platforms.
* [IPMI KCS](ipmi_kcs.md) +* [SMMSTORE](smmstore.md) diff --git a/Documentation/drivers/smmstore.md b/Documentation/drivers/smmstore.md new file mode 100644 index 0000000..c58e855 --- /dev/null +++ b/Documentation/drivers/smmstore.md @@ -0,0 +1,121 @@ +# SMM based flash storage driver + +This documents the API exposed by the x86 system management based +storage driver. + +## SMMSTORE + +SMMSTORE is a smm mediated driver to read from, write to and erase a +predefined region in flash. It can be enabled by setting +`CONFIG_SMMTORE=y` in menuconfig. + +This can be used by the OS or the payload to implement persistent +storage to hold for instance configuration data, without needing +to implement a (platform specific) storage driver in the payload +itself. + +## API + +### Storage region + +By default SMMTORE will operate on a separate FMAP region called +`SMMSTORE`. The default generated FMAP will include such a region. +On systems with a locked FMAP, e.g. in an existing VBOOT setup +with a locked RO region, the option exists to add a cbfsfile +called `smm_store` in the `RW_LEGACY` (if CHROMEOS) or in the +`COREBOOT` FMAP regions. It is recommended for new builds using +a handcrafted FMD that intend to make use of SMMSTORE to include a +sufficiently large `SMMSTORE` FMAP region. It is recommended to +align the `SMMSTORE` region to 64KiB for the largest flash erase +op compatibility. + +When a default generated FMAP is used the size of the FMAP region +is equal to `CONFIG_SMMSTORE_SIZE`. UEFI payloads expect at least +64KiB. Given that the current implementation lacks a way to update +key-value pairs at least a plural of this is recommended. + +### generating the SMI + +SMMSTORE is called via an SMI, which is generated via a write to the +IO port defined in the smi_cmd entry of the FADT ACPI table. The API +is called in the following way. `%al` contains `APM_CNT_SMMSTORE=0xed` +and is written to the smi_cmd IO port. `%ah` contains the SMMSTORE +command. `%ebx` contains the parameter buffer to the SMMSTORE command. + +### Return values + +If a commands succeeds, SMMSTORE will return with +`SMMSTORE_RET_SUCCESS=0` on `%eax`. On failure SMMSTORE will +return `SMMSTORE_RET_FAILURE=1`. If a non supported SMMSTORE command +is provided `SMMSTORE_REG_UNSUPPORTED=2` is returned. + +**NOTE1**: The caller **must** check the return value and should make +no assumption on the returned data if `SMMSTORE_RET_SUCCESS` is not +returned. + +**NOTE2**: If no SMMSTORE smihandler is installed generally nothing +is returned at all. If the calling argument on `%ax` is the same after +the SMI, it can generally be assumed that there is no smihandler for +the SMMSTORE call. + +### API + +SMMSTORE supports 3 subcommands that are passed via `%ah`: + +#### - SMMSTORE_CMD_CLEAR = 1 + +This clears the `SMMSTORE` storage region. The argument in +`%ebx` is unused. + +#### - SMMSTORE_CMD_READ = 2 + +The additional parameter buffer `%ebx` contains a pointer to +the following struct: + +```C +struct smmstore_params_read { + void *buf; + ssize_t bufsize; +}; +``` + +INPUT: +- `buf`: is a pointer to where the data needs to be read +- `bufsize`: is the size of the buffer + +OUTPUT: +- `buf` +- `bufsize`: returns the amount of data that has actually been read. + +#### - SMMSTORE_CMD_APPEND = 3 + +SMMSTORE takes a key-value approach to appending data. key-value pairs +are never updated, they are always appended. It is up to the caller to +walk through the key-value pairs after reading SMMSTORE to find the +latest one. + +The additional parameter buffer `%ebx` contains a pointer to +the following struct: + +```C +struct smmstore_params_append { + void *key; + size_t keysize; + void *val; + size_t valsize; +}; +``` + +INPUT: +- `key`: pointer to the key data +- `keysize`: size of the key data +- `val`: pointer to the value data +- `valsize`: size of the value data + +**NOTE**: The size of the struct entries are in the native word size of +smihandler. + +## External links + +* [A Tour Beyond BIOS Implementing UEFI Authenticated Variables in SMM with EDKI](https://software.intel.com/sites/default/files/managed/cf/ea/a_tour_beyond_b...) +Note that this differs significantly from coreboot's implementation.
Hello Aaron Durbin, Patrick Georgi,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/37243
to look at the new patch set (#2).
Change subject: Documentation: Add SMMSTORE documentation ......................................................................
Documentation: Add SMMSTORE documentation
This documents the smmstore API.
Change-Id: I992c04c0cf9b3f03755cf3fede2c82c6471a5ef4 Signed-off-by: Arthur Heymans arthur@aheymans.xyz --- M Documentation/drivers/index.md A Documentation/drivers/smmstore.md 2 files changed, 122 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/43/37243/2
Arthur Heymans has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37243 )
Change subject: Documentation: Add SMMSTORE documentation ......................................................................
Patch Set 2:
(1 comment)
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... File Documentation/drivers/smmstore.md:
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 61: API should probably be called calling arguments.
Patrick Georgi has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37243 )
Change subject: Documentation: Add SMMSTORE documentation ......................................................................
Patch Set 2:
(10 comments)
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... File Documentation/drivers/smmstore.md:
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 10: SMMTOR SMMSTORE
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 16: I'd put a paragraph here that the API provides append-only semantics for key/value pairs.
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 21: SMMTORE SMMSTORE
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 34: lacks a way to update : key-value pairs "lacks a way to rewrite entries"?
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 35: plural multiple
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 40: The API : is called in the following way. Either end in a colon, or just drop the sentence, adapting the following to something like "%al must contain ..."
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 49: If a non supported SMMSTORE command : is provided "For unsupported SMMSTORE commands"
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 53: if `SMMSTORE_RET_SUCCESS` is not : returned. "if eax does not contain SMMSTORE_RET_SUCCESS"?
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 56: If no SMMSTORE smihandler is installed generally nothing : is returned at all. If the calling argument on `%ax` is the same after : the SMI, it can generally be assumed that there is no smihandler for : the SMMSTORE call. Too many "generally"s ;-)
Maybe: "If the SMI returns without changing %ax, assume that the SMMSTORE feature is not installed."?
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 77: void *buf; : ssize_t bufsize; note somewhere that these are 32bit?
Hello Aaron Durbin, build bot (Jenkins), Patrick Georgi,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/37243
to look at the new patch set (#3).
Change subject: Documentation: Add SMMSTORE documentation ......................................................................
Documentation: Add SMMSTORE documentation
This documents the smmstore API.
Change-Id: I992c04c0cf9b3f03755cf3fede2c82c6471a5ef4 Signed-off-by: Arthur Heymans arthur@aheymans.xyz --- M Documentation/drivers/index.md A Documentation/drivers/smmstore.md 2 files changed, 124 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/43/37243/3
Arthur Heymans has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37243 )
Change subject: Documentation: Add SMMSTORE documentation ......................................................................
Patch Set 3:
(11 comments)
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... File Documentation/drivers/smmstore.md:
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 10: SMMTOR
SMMSTORE
Done
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 16:
I'd put a paragraph here that the API provides append-only semantics for key/value pairs.
Done
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 21: SMMTORE
SMMSTORE
Done
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 35: plural
multiple
Done
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 34: lacks a way to update : key-value pairs
"lacks a way to rewrite entries"?
Done
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 40: The API : is called in the following way.
Either end in a colon, or just drop the sentence, adapting the following to something like "%al must […]
Done
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 49: If a non supported SMMSTORE command : is provided
"For unsupported SMMSTORE commands"
Done
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 53: if `SMMSTORE_RET_SUCCESS` is not : returned.
"if eax does not contain SMMSTORE_RET_SUCCESS"?
Done
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 56: If no SMMSTORE smihandler is installed generally nothing : is returned at all. If the calling argument on `%ax` is the same after : the SMI, it can generally be assumed that there is no smihandler for : the SMMSTORE call.
Too many "generally"s ;-) […]
Done
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 61: API
should probably be called calling arguments.
Done
https://review.coreboot.org/c/coreboot/+/37243/2/Documentation/drivers/smmst... PS2, Line 77: void *buf; : ssize_t bufsize;
note somewhere that these are 32bit?
It was done below, but I moved it upwards and made it explicitly say that it's 32bits most of the time.
Paul Menzel has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37243 )
Change subject: Documentation: Add SMMSTORE documentation ......................................................................
Patch Set 3:
(4 comments)
https://review.coreboot.org/c/coreboot/+/37243/3/Documentation/drivers/smmst... File Documentation/drivers/smmstore.md:
https://review.coreboot.org/c/coreboot/+/37243/3/Documentation/drivers/smmst... PS3, Line 8: smm SMM
https://review.coreboot.org/c/coreboot/+/37243/3/Documentation/drivers/smmst... PS3, Line 49: commands command
https://review.coreboot.org/c/coreboot/+/37243/3/Documentation/drivers/smmst... PS3, Line 73: `%ebx` is unused. Some of that fits on the line baove.
https://review.coreboot.org/c/coreboot/+/37243/3/Documentation/drivers/smmst... PS3, Line 123: Note that this differs significantly from coreboot's implementation. Note, this differs …
Hello Aaron Durbin, build bot (Jenkins), Patrick Georgi,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/37243
to look at the new patch set (#4).
Change subject: Documentation: Add SMMSTORE documentation ......................................................................
Documentation: Add SMMSTORE documentation
This documents the smmstore API.
Change-Id: I992c04c0cf9b3f03755cf3fede2c82c6471a5ef4 Signed-off-by: Arthur Heymans arthur@aheymans.xyz --- M Documentation/drivers/index.md A Documentation/drivers/smmstore.md 2 files changed, 124 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/43/37243/4
Arthur Heymans has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37243 )
Change subject: Documentation: Add SMMSTORE documentation ......................................................................
Patch Set 4:
(4 comments)
https://review.coreboot.org/c/coreboot/+/37243/3/Documentation/drivers/smmst... File Documentation/drivers/smmstore.md:
https://review.coreboot.org/c/coreboot/+/37243/3/Documentation/drivers/smmst... PS3, Line 8: smm
SMM
Done
https://review.coreboot.org/c/coreboot/+/37243/3/Documentation/drivers/smmst... PS3, Line 49: commands
command
Done
https://review.coreboot.org/c/coreboot/+/37243/3/Documentation/drivers/smmst... PS3, Line 73: `%ebx` is unused.
Some of that fits on the line baove.
Done
https://review.coreboot.org/c/coreboot/+/37243/3/Documentation/drivers/smmst... PS3, Line 123: Note that this differs significantly from coreboot's implementation.
Note, this differs …
Done
Patrick Georgi has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37243 )
Change subject: Documentation: Add SMMSTORE documentation ......................................................................
Patch Set 4: Code-Review+2
Patrick Georgi has submitted this change. ( https://review.coreboot.org/c/coreboot/+/37243 )
Change subject: Documentation: Add SMMSTORE documentation ......................................................................
Documentation: Add SMMSTORE documentation
This documents the smmstore API.
Change-Id: I992c04c0cf9b3f03755cf3fede2c82c6471a5ef4 Signed-off-by: Arthur Heymans arthur@aheymans.xyz Reviewed-on: https://review.coreboot.org/c/coreboot/+/37243 Tested-by: build bot (Jenkins) no-reply@coreboot.org Reviewed-by: Patrick Georgi pgeorgi@google.com --- M Documentation/drivers/index.md A Documentation/drivers/smmstore.md 2 files changed, 124 insertions(+), 0 deletions(-)
Approvals: build bot (Jenkins): Verified Patrick Georgi: Looks good to me, approved
diff --git a/Documentation/drivers/index.md b/Documentation/drivers/index.md index 60e90c3..807ed85 100644 --- a/Documentation/drivers/index.md +++ b/Documentation/drivers/index.md @@ -5,3 +5,4 @@ they allow to easily reuse existing code accross platforms.
* [IPMI KCS](ipmi_kcs.md) +* [SMMSTORE](smmstore.md) diff --git a/Documentation/drivers/smmstore.md b/Documentation/drivers/smmstore.md new file mode 100644 index 0000000..ecf937b --- /dev/null +++ b/Documentation/drivers/smmstore.md @@ -0,0 +1,123 @@ +# SMM based flash storage driver + +This documents the API exposed by the x86 system management based +storage driver. + +## SMMSTORE + +SMMSTORE is a SMM mediated driver to read from, write to and erase a +predefined region in flash. It can be enabled by setting +`CONFIG_SMMSTORE=y` in menuconfig. + +This can be used by the OS or the payload to implement persistent +storage to hold for instance configuration data, without needing +to implement a (platform specific) storage driver in the payload +itself. + +The API provides append-only semantics for key/value pairs. + +## API + +### Storage region + +By default SMMSTORE will operate on a separate FMAP region called +`SMMSTORE`. The default generated FMAP will include such a region. +On systems with a locked FMAP, e.g. in an existing VBOOT setup +with a locked RO region, the option exists to add a cbfsfile +called `smm_store` in the `RW_LEGACY` (if CHROMEOS) or in the +`COREBOOT` FMAP regions. It is recommended for new builds using +a handcrafted FMD that intend to make use of SMMSTORE to include a +sufficiently large `SMMSTORE` FMAP region. It is recommended to +align the `SMMSTORE` region to 64KiB for the largest flash erase +op compatibility. + +When a default generated FMAP is used the size of the FMAP region +is equal to `CONFIG_SMMSTORE_SIZE`. UEFI payloads expect at least +64KiB. Given that the current implementation lacks a way to rewrite +key-value pairs at least a multiple of this is recommended. + +### generating the SMI + +SMMSTORE is called via an SMI, which is generated via a write to the +IO port defined in the smi_cmd entry of the FADT ACPI table. `%al` +contains `APM_CNT_SMMSTORE=0xed` and is written to the smi_cmd IO +port. `%ah` contains the SMMSTORE command. `%ebx` contains the +parameter buffer to the SMMSTORE command. + +### Return values + +If a command succeeds, SMMSTORE will return with +`SMMSTORE_RET_SUCCESS=0` on `%eax`. On failure SMMSTORE will return +`SMMSTORE_RET_FAILURE=1`. For unsupported SMMSTORE commands +`SMMSTORE_REG_UNSUPPORTED=2` is returned. + +**NOTE1**: The caller **must** check the return value and should make +no assumption on the returned data if `%eax` does not contain +`SMMSTORE_RET_SUCCESS`. + +**NOTE2**: If the SMI returns without changing `%ax` assume that the +SMMSTORE feature is not installed. + +### Calling arguments + +SMMSTORE supports 3 subcommands that are passed via `%ah`, the additional +calling arguments are passed via `%ebx`. + +**NOTE**: The size of the struct entries are in the native word size of +smihandler. This means 32 bits in almost all cases. + + +#### - SMMSTORE_CMD_CLEAR = 1 + +This clears the `SMMSTORE` storage region. The argument in `%ebx` is +unused. + +#### - SMMSTORE_CMD_READ = 2 + +The additional parameter buffer `%ebx` contains a pointer to +the following struct: + +```C +struct smmstore_params_read { + void *buf; + ssize_t bufsize; +}; +``` + +INPUT: +- `buf`: is a pointer to where the data needs to be read +- `bufsize`: is the size of the buffer + +OUTPUT: +- `buf` +- `bufsize`: returns the amount of data that has actually been read. + +#### - SMMSTORE_CMD_APPEND = 3 + +SMMSTORE takes a key-value approach to appending data. key-value pairs +are never updated, they are always appended. It is up to the caller to +walk through the key-value pairs after reading SMMSTORE to find the +latest one. + +The additional parameter buffer `%ebx` contains a pointer to +the following struct: + +```C +struct smmstore_params_append { + void *key; + size_t keysize; + void *val; + size_t valsize; +}; +``` + +INPUT: +- `key`: pointer to the key data +- `keysize`: size of the key data +- `val`: pointer to the value data +- `valsize`: size of the value data + +## External links + +* [A Tour Beyond BIOS Implementing UEFI Authenticated Variables in SMM with EDKI](https://software.intel.com/sites/default/files/managed/cf/ea/a_tour_beyond_b...) +Note, this differs significantly from coreboot's implementation.
-
Arthur Heymans (Code Review) -
Patrick Georgi (Code Review)
-
Paul Menzel (Code Review)