summaryrefslogtreecommitdiff
path: root/Documentation/util
diff options
context:
space:
mode:
authorSergii Dmytruk <sergii.dmytruk@3mdeb.com>2023-11-17 19:31:20 +0200
committerMartin L Roth <gaumless@gmail.com>2024-03-09 23:22:55 +0000
commit04bd9651435843ce4b03c9717f2965fe344fe5cc (patch)
tree0193502b26818c738206a60862c689485d533a50 /Documentation/util
parent7a51acfbe91c7f9d01837103341526abb6ea46f4 (diff)
util: add smmstoretool for editing SMMSTORE
Offline SMMSTORE variable modification tool. Can be used to pre-configure ROM image or debug EFI state stored in a dump. Change-Id: I6c1c06f1d0c39c13b5be76a3070f09b715aca6e0 Signed-off-by: Sergii Dmytruk <sergii.dmytruk@3mdeb.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/79080 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Michał Żygowski <michal.zygowski@3mdeb.com> Reviewed-by: Arthur Heymans <arthur@aheymans.xyz>
Diffstat (limited to 'Documentation/util')
-rw-r--r--Documentation/util/smmstoretool/index.md126
1 files changed, 126 insertions, 0 deletions
diff --git a/Documentation/util/smmstoretool/index.md b/Documentation/util/smmstoretool/index.md
new file mode 100644
index 0000000000..f7af60579d
--- /dev/null
+++ b/Documentation/util/smmstoretool/index.md
@@ -0,0 +1,126 @@
+# smmstoretool
+
+Offline SMMSTORE variable modification tool.
+
+## Operation
+
+### Storage initialization
+
+If SMMSTORE presence isn't detected and an update operation is requested, the
+store spanning the whole file is created automatically. Size of the store file
+must be a multiple of 64 KiB (block size in version 2 of SMMSTORE protocol),
+the variable storage itself will be 64 KiB in size. That's the way EDK2 makes
+use of it.
+
+Unlike online editing which mostly appends new variable entries each storage
+update with this tool drops all deleted or incomplete entries.
+
+### Unicode
+
+There is no actual support for it. ASCII bytes (or UTF-8 bytes if that was
+passed in) is just extended to 16 bits. And Unicode chars that are larger than
+8 bit are turned into `?`. Need UTF-8 to/from UTF-16 conversion functions for
+proper support.
+
+## Help
+
+Start with:
+
+```
+$ smmstoretool -h
+Usage: smmstoretool smm-store-file sub-command
+ smmstoretool -h|--help
+
+Sub-commands:
+ * get - display current value of a variable
+ * guids - show GUID to alias mapping
+ * help - provide built-in help
+ * list - list variables present in the store
+ * remove - remove a variable from the store
+ * set - add or updates a variable in the store
+```
+
+Then run `smmstoretool rom help sub-command-name` to get more details.
+
+## Data types
+
+EFI variables in the storage don't have an associated data type and it needs to
+be specified on reading/writing variables. Several basic types that correspond
+to typical configuration values are supported:
+
+ * `bool` (`true`, `false`)
+ * `uint8` (0-255)
+ * `uint16` (0-65535)
+ * `uint32` (0-4294967295)
+ * `ascii` (NUL-terminated)
+ * `unicode` (widened and NUL-terminated)
+ * `raw` (output only; raw bytes on output)
+
+## Examples
+
+`SMMSTORE` is the name of a file containing SMMSTORE data.
+
+### Variable listing
+
+```
+$ smmstoretool SMMSTORE list
+dasharo :NetworkBoot (1 byte)
+c076ec0c-7028-4399-a07271ee5c448b9f:CustomMode (1 byte)
+d9bee56e-75dc-49d9-b4d7b534210f637a:certdb (4 bytes)
+9073e4e0-60ec-4b6e-99034c223c260f3c:VendorKeysNv (1 byte)
+6339d487-26ba-424b-9a5d687e25d740bc:TCG2_DEVICE_DETECTION (1 byte)
+6339d487-26ba-424b-9a5d687e25d740bc:TCG2_CONFIGURATION (1 byte)
+6339d487-26ba-424b-9a5d687e25d740bc:TCG2_VERSION (16 bytes)
+global :Boot0000 (66 bytes)
+global :Timeout (2 bytes)
+global :PlatformLang (3 bytes)
+global :Lang (4 bytes)
+global :Key0000 (14 bytes)
+global :Boot0001 (102 bytes)
+global :Key0001 (14 bytes)
+04b37fe8-f6ae-480b-bdd537d98c5e89aa:VarErrorFlag (1 byte)
+dasharo :Type1UUID (16 bytes)
+dasharo :Type2SN (10 bytes)
+global :Boot0002 (90 bytes)
+global :BootOrder (8 bytes)
+global :Boot0003 (76 bytes)
+...
+```
+
+### Variable reading
+
+```
+$ smmstoretool SMMSTORE get -g dasharo -n UsbDriverStack -t bool
+false
+```
+
+### Variable writing
+
+```
+$ smmstoretool SMMSTORE set -g dasharo -n UsbDriverStack -t bool -v true
+```
+
+### Variable deletion
+
+```
+$ smmstoretool SMMSTORE remove -g dasharo -n NetworkBoot
+```
+
+### Real-world usage
+
+If one edits a newly generated Dasharo `coreboot.rom`:
+
+```bash
+cbfstool coreboot.rom read -r SMMSTORE -f SMMSTORE
+smmstoretool SMMSTORE set -g dasharo -n NetworkBoot -t bool -v true
+cbfstool coreboot.rom write -r SMMSTORE -f SMMSTORE
+```
+
+On the first boot, "Network Boot" setting will already be enabled.
+
+Can also read SMMSTORE from a flash and examine some of its contents for
+debugging purposes without adding new logging code or powering on the hardware:
+
+```bash
+smmstoretool SMMSTORE get -g global -n BootOrder -t raw | hexdump -C
+```