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  ```