Documentation/util/smmstoretool/index.md

   1 # smmstoretool
   2
   3 Offline SMMSTORE variable modification tool.
   4
   5 ## Operation
   6
   7 ### File formats
   8
   9 To discover SMMSTORE, the tool first looks for FMAP header and, if found, for
  10 SMMSTORE region.  If FMAP is found but it has no SMMSTORE region, that's an
  11 error.  If there is no FMAP, the whole file is assumed to be SMMSTORE
  12 region (e.g., extracted via `cbfstool`).
  13
  14 ### Storage initialization
  15
  16 If SMMSTORE presence isn't detected and an update operation is requested, the
  17 store spanning the whole region is created automatically.  Size of the store
  18 region must be a multiple of 64 KiB (block size in version 2 of SMMSTORE
  19 protocol), the variable storage itself will be 64 KiB in size.  That's the way
  20 EDK2 makes use of it.
  21
  22 Unlike online editing which mostly appends new variable entries each storage
  23 update with this tool drops all deleted or incomplete entries.
  24
  25 ### Unicode
  26
  27 There is no actual support for it.  ASCII bytes (or UTF-8 bytes if that was
  28 passed in) is just extended to 16 bits.  And Unicode chars that are larger than
  29 8 bit are turned into `?`.  Need UTF-8 to/from UTF-16 conversion functions for
  30 proper support.
  31
  32 ## Help
  33
  34 Start with:
  35
  36 ```
  37 $ smmstoretool -h
  38 Usage: smmstoretool smm-store-file|rom sub-command
  39        smmstoretool -h|--help
  40
  41 Sub-commands:
  42  * get    - display current value of a variable
  43  * guids  - show GUID to alias mapping
  44  * help   - provide built-in help
  45  * list   - list variables present in the store
  46  * remove - remove a variable from the store
  47  * set    - add or updates a variable in the store
  48 ```
  49
  50 Then run `smmstoretool rom help sub-command-name` to get more details.
  51
  52 ## Data types
  53
  54 EFI variables in the storage don't have an associated data type and it needs to
  55 be specified on reading/writing variables.  Several basic types that correspond
  56 to typical configuration values are supported:
  57
  58  * `bool` (`true`, `false`)
  59  * `uint8` (0-255)
  60  * `uint16` (0-65535)
  61  * `uint32` (0-4294967295)
  62  * `ascii` (NUL-terminated)
  63  * `unicode` (widened and NUL-terminated)
  64  * `raw` (output only; raw bytes on output)
  65
  66 ## Examples
  67
  68 `SMMSTORE` is the name of a file containing SMMSTORE data or a full ROM image
  69 with FMAP that includes SMMSTORE region.
  70
  71 ### Variable listing
  72
  73 ```
  74 $ smmstoretool SMMSTORE list
  75 dasharo                            :NetworkBoot (1 byte)
  76 c076ec0c-7028-4399-a07271ee5c448b9f:CustomMode (1 byte)
  77 d9bee56e-75dc-49d9-b4d7b534210f637a:certdb (4 bytes)
  78 9073e4e0-60ec-4b6e-99034c223c260f3c:VendorKeysNv (1 byte)
  79 6339d487-26ba-424b-9a5d687e25d740bc:TCG2_DEVICE_DETECTION (1 byte)
  80 6339d487-26ba-424b-9a5d687e25d740bc:TCG2_CONFIGURATION (1 byte)
  81 6339d487-26ba-424b-9a5d687e25d740bc:TCG2_VERSION (16 bytes)
  82 global                             :Boot0000 (66 bytes)
  83 global                             :Timeout (2 bytes)
  84 global                             :PlatformLang (3 bytes)
  85 global                             :Lang (4 bytes)
  86 global                             :Key0000 (14 bytes)
  87 global                             :Boot0001 (102 bytes)
  88 global                             :Key0001 (14 bytes)
  89 04b37fe8-f6ae-480b-bdd537d98c5e89aa:VarErrorFlag (1 byte)
  90 dasharo                            :Type1UUID (16 bytes)
  91 dasharo                            :Type2SN (10 bytes)
  92 global                             :Boot0002 (90 bytes)
  93 global                             :BootOrder (8 bytes)
  94 global                             :Boot0003 (76 bytes)
  95 ...
  96 ```
  97
  98 ### Variable reading
  99
 100 ```
 101 $ smmstoretool SMMSTORE get -g dasharo -n UsbDriverStack -t bool
 102 false
 103 ```
 104
 105 ### Variable writing
 106
 107 ```
 108 $ smmstoretool SMMSTORE set -g dasharo -n UsbDriverStack -t bool -v true
 109 ```
 110
 111 ### Variable deletion
 112
 113 ```
 114 $ smmstoretool SMMSTORE remove -g dasharo -n NetworkBoot
 115 ```
 116
 117 ### Real-world usage
 118
 119 If one edits a newly generated Dasharo `coreboot.rom`:
 120
 121 ```bash
 122 # editing exported storage
 123 cbfstool coreboot.rom read -r SMMSTORE -f SMMSTORE
 124 smmstoretool SMMSTORE set -g dasharo -n NetworkBoot -t bool -v true
 125 cbfstool coreboot.rom write -r SMMSTORE -f SMMSTORE
 126
 127 # editing in-place storage
 128 smmstoretool coreboot.rom set -g dasharo -n NetworkBoot -t bool -v true
 129 ```
 130
 131 On the first boot, "Network Boot" setting will already be enabled.
 132
 133 Can also read SMMSTORE from a flash and examine some of its contents for
 134 debugging purposes without adding new logging code or powering on the hardware:
 135
 136 ```bash
 137 smmstoretool SMMSTORE get -g global -n BootOrder -t raw | hexdump -C
 138 ```