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.