Arthur Heymans has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/37244 )
Change subject: Documentation/4.12-relnotes.md: Add SMMSTORE as production ready
......................................................................
Documentation/4.12-relnotes.md: Add SMMSTORE as production ready
Change-Id: I9fa0473dd8ab9d0476400fc2f40c684db0188fc3
Signed-off-by: Arthur Heymans <arthur(a)aheymans.xyz>
---
M Documentation/releases/coreboot-4.12-relnotes.md
1 file changed, 5 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/44/37244/1
diff --git a/Documentation/releases/coreboot-4.12-relnotes.md b/Documentation/releases/coreboot-4.12-relnotes.md
index f9c5f7e..155dc13 100644
--- a/Documentation/releases/coreboot-4.12-relnotes.md
+++ b/Documentation/releases/coreboot-4.12-relnotes.md
@@ -13,4 +13,9 @@
Significant changes
-------------------
+### SMMSTORE is now production ready
+
+See [smmstore](../drivers/smmstore.md) for the documentation on the API.
+
### Add significant changes here
+
--
To view, visit https://review.coreboot.org/c/coreboot/+/37244
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-Change-Id: I9fa0473dd8ab9d0476400fc2f40c684db0188fc3
Gerrit-Change-Number: 37244
Gerrit-PatchSet: 1
Gerrit-Owner: Arthur Heymans <arthur(a)aheymans.xyz>
Gerrit-MessageType: newchange
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(a)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_b…
+Note that this differs significantly from coreboot's implementation.
--
To view, visit https://review.coreboot.org/c/coreboot/+/37243
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-Change-Id: I992c04c0cf9b3f03755cf3fede2c82c6471a5ef4
Gerrit-Change-Number: 37243
Gerrit-PatchSet: 1
Gerrit-Owner: Arthur Heymans <arthur(a)aheymans.xyz>
Gerrit-MessageType: newchange