135 lines
4.2 KiB
Markdown
135 lines
4.2 KiB
Markdown
# 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
|
|
|
|
#### Security
|
|
|
|
Pointers provided by the payload or OS are checked to not overlap with the SMM.
|
|
That protects the SMM handler from being manipulated.
|
|
|
|
*However there's no validation done on the source or destination pointing to
|
|
DRAM. A malicious application that is able to issue SMIs could extract arbitrary
|
|
data or modify the currently running kernel.*
|
|
|
|
## 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_bios_implementing_uefi_authenticated_variables_in_smm_with_edkii.pdf)
|
|
Note, this differs significantly from coreboot's implementation.
|
|
|
|
[SMM]: ../security/smm.md
|