Documentation/drivers/smmstorev2.md

   1 # SMM based flash storage driver Version 2
   2
   3 This documents the API exposed by the x86 system management based
   4 storage driver.
   5
   6 ## SMMSTOREv2
   7
   8 SMMSTOREv2 is a [SMM] mediated driver to read from, write to and erase
   9 a predefined region in flash. It can be enabled by setting
  10 `CONFIG_SMMSTORE=y` and `CONFIG_SMMSTORE_V2=y` in menuconfig.
  11
  12 This can be used by the OS or the payload to implement persistent
  13 storage to hold for instance configuration data, without needing to
  14 implement a (platform specific) storage driver in the payload itself.
  15
  16 ### Storage size and alignment
  17
  18 SMMSTORE version 2 requires a minimum alignment of 64 KiB, which should
  19 be supported by all flash chips. Not having to perform read-modify-write
  20 operations is desired, as it reduces complexity and potential for bugs.
  21
  22 This can be used by a FTW (FaultTolerantWrite) implementation that uses
  23 at least two regions in an A/B update scheme. The FTW implementation in
  24 EDK2 uses three different regions in the store:
  25
  26 - The variable store
  27 - The FTW spare block
  28 - The FTW working block
  29
  30 All regions must be block-aligned, and the FTW spare size must be larger
  31 than that of the variable store. FTW working block can be much smaller.
  32 With 64 KiB as block size, the minimum size of the FTW-enabled store is:
  33
  34 - The variable store: 1 block = 64 KiB
  35 - The FTW spare block: 2 blocks = 2 * 64 KiB
  36 - The FTW working block: 1 block = 64 KiB
  37
  38 Therefore, the minimum size for EDK2 FTW is 4 blocks, or 256 KiB.
  39
  40 ## API
  41
  42 The API provides read and write access to an unformatted block storage.
  43
  44 ### Storage region
  45
  46 By default SMMSTOREv2 will operate on a separate FMAP region called
  47 `SMMSTORE`. The default generated FMAP will include such a region. On
  48 systems with a locked FMAP, e.g. in an existing vboot setup with a
  49 locked RO region, the option exists to add a cbfsfile called `smm_store`
  50 in the `RW_LEGACY` (if CHROMEOS) or in the `COREBOOT` FMAP regions. It
  51 is recommended for new builds using a handcrafted FMD that intend to
  52 make use of SMMSTORE to include a sufficiently large `SMMSTORE` FMAP
  53 region. It is mandatory to align the `SMMSTORE` region to 64KiB for
  54 compatibility with the largest flash erase operation.
  55
  56 When a default generated FMAP is used, the size of the FMAP region is
  57 equal to `CONFIG_SMMSTORE_SIZE`. UEFI payloads expect at least 64 KiB.
  58 To support a fault tolerant write mechanism, at least a multiple of
  59 this size is recommended.
  60
  61 ### Communication buffer
  62
  63 To prevent malicious ring0 code to access arbitrary memory locations,
  64 SMMSTOREv2 uses a communication buffer in CBMEM/HOB for all transfers.
  65 This buffer has to be at least 64 KiB in size and must be installed
  66 before calling any of the SMMSTORE read or write operations. Usually,
  67 coreboot will install this buffer to transfer data between ring0 and
  68 the [SMM] handler.
  69
  70 In order to get the communication buffer address, the payload or OS
  71 has to read the coreboot table with tag `0x0039`, containing:
  72
  73 ```C
  74 struct lb_smmstorev2 {
  75         uint32_t tag;
  76         uint32_t size;
  77         uint32_t num_blocks;    /* Number of writeable blocks in SMM */
  78         uint32_t block_size;    /* Size of a block in byte. Default: 64 KiB */
  79         uint32_t mmap_addr;     /* MMIO address of the store for read only access */
  80         uint32_t com_buffer;    /* Physical address of the communication buffer */
  81         uint32_t com_buffer_size;       /* Size of the communication buffer in byte */
  82         uint8_t apm_cmd;        /* The command byte to write to the APM I/O port */
  83         uint8_t unused[3];      /* Set to zero */
  84 };
  85 ```
  86
  87 The absence of this coreboot table entry indicates that there's no
  88 SMMSTOREv2 support.
  89
  90 ### Blocks
  91
  92 The SMMSTOREv2 splits the SMMSTORE FMAP partition into smaller chunks
  93 called *blocks*. Every block is at least the size of 64KiB to support
  94 arbitrary NOR flash erase ops. A payload or OS must make no further
  95 assumptions about the block or communication buffer size.
  96
  97 ### Generating the SMI
  98
  99 SMMSTOREv2 is called via an SMI, which is generated via a write to the
 100 IO port defined in the smi_cmd entry of the FADT ACPI table. `%al`
 101 contains `APM_CNT_SMMSTORE=0xed` and is written to the smi_cmd IO
 102 port. `%ah` contains the SMMSTOREv2 command. `%ebx` contains the
 103 parameter buffer to the SMMSTOREv2 command.
 104
 105 ### Return values
 106
 107 If a command succeeds, SMMSTOREv2 will return with
 108 `SMMSTORE_RET_SUCCESS=0` in `%eax`. On failure SMMSTORE will return
 109 `SMMSTORE_RET_FAILURE=1`. For unsupported SMMSTORE commands
 110 `SMMSTORE_REG_UNSUPPORTED=2` is returned.
 111
 112 **NOTE 1**: The caller **must** check the return value and should make
 113 no assumption on the returned data if `%eax` does not contain
 114 `SMMSTORE_RET_SUCCESS`.
 115
 116 **NOTE 2**: If the SMI returns without changing `%ax`, it can be assumed
 117 that the SMMSTOREv2 feature is not installed.
 118
 119 ### Calling arguments
 120
 121 SMMSTOREv2 supports 3 subcommands that are passed via `%ah`, the
 122 additional calling arguments are passed via `%ebx`.
 123
 124 **NOTE**: The size of the struct entries are in the native word size of
 125 smihandler. This means 32 bits in almost all cases.
 126
 127 #### - SMMSTORE_CMD_INIT = 4
 128
 129 This installs the communication buffer to use and thus enables the
 130 SMMSTORE handler. This command can only be executed once and is done
 131 by the firmware. Calling this function at runtime has no effect.
 132
 133 The additional parameter buffer `%ebx` contains a pointer to the
 134 following struct:
 135
 136 ```C
 137 struct smmstore_params_init {
 138         uint32_t com_buffer;
 139         uint32_t com_buffer_size;
 140 } __packed;
 141 ```
 142
 143 INPUT:
 144 - `com_buffer`: Physical address of the communication buffer (CBMEM)
 145 - `com_buffer_size`: Size in bytes of the communication buffer
 146
 147 #### - SMMSTORE_CMD_RAW_READ = 5
 148
 149 SMMSTOREv2 allows reading arbitrary data. It is up to the caller to
 150 initialize the store with meaningful data before using it.
 151
 152 The additional parameter buffer `%ebx` contains a pointer to the
 153 following struct:
 154
 155 ```C
 156 struct smmstore_params_raw_read {
 157         uint32_t bufsize;
 158         uint32_t bufoffset;
 159         uint32_t block_id;
 160 } __packed;
 161 ```
 162
 163 INPUT:
 164 - `bufsize`: Size of data to read within the communication buffer
 165 - `bufoffset`: Offset within the communication buffer
 166 - `block_id`: Block to read from
 167
 168 #### - SMMSTORE_CMD_RAW_WRITE = 6
 169
 170 SMMSTOREv2 allows writing arbitrary data. It is up to the caller to
 171 erase a block before writing it.
 172
 173 The additional parameter buffer `%ebx` contains a pointer to
 174 the following struct:
 175
 176 ```C
 177 struct smmstore_params_raw_write {
 178         uint32_t bufsize;
 179         uint32_t bufoffset;
 180         uint32_t block_id;
 181 } __packed;
 182 ```
 183
 184 INPUT:
 185 - `bufsize`: Size of data to write within the communication buffer
 186 - `bufoffset`: Offset within the communication buffer
 187 - `block_id`: Block to write to
 188
 189 #### - SMMSTORE_CMD_RAW_CLEAR = 7
 190
 191 SMMSTOREv2 allows clearing blocks. A cleared block will read as `0xff`.
 192 By providing multiple blocks the caller can implement a fault tolerant
 193 write mechanism. It is up to the caller to clear blocks before writing
 194 to them.
 195
 196
 197 ```C
 198 struct smmstore_params_raw_clear {
 199         uint32_t block_id;
 200 } __packed;
 201 ```
 202
 203 INPUT:
 204 - `block_id`: Block to erase
 205
 206 #### Security
 207
 208 Pointers provided by the payload or OS are checked to not overlap with
 209 SMM. This protects the SMM handler from being compromised.
 210
 211 As all information is exchanged using the communication buffer and
 212 coreboot tables, there's no risk that a malicious application capable
 213 of issuing SMIs could extract arbitrary data or modify the currently
 214 running kernel.
 215
 216 ## External links
 217
 218 * [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)
 219 Note that this differs significantly from coreboot's implementation.
 220
 221 [SMM]: ../security/smm.md