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>

2 files changed, 128 insertions, 0 deletions

diff --git a/Documentation/util.md b/Documentation/util.md
index b4ebc92263..fe460d9155 100644
--- a/Documentation/util.md
+++ b/Documentation/util.md
@@ -144,6 +144,7 @@ from the local git repository for auditing or release `Bash`
 Does not show variants. `Shell`
 	* _ucode_h_to_bin.sh_ - Microcode conversion tool `Bash`
 	* _update_submodules_ - Check all submodules for updates `Bash`
+* __smmstoretool__ - Offline SMMSTORE variable modification tool `C`
 * __spdtool__ - Dumps SPD ROMs from a given blob to separate files
 using known patterns and reserved bits. Useful for analysing firmware
 that holds SPDs on boards that have soldered down DRAM. `python`
@@ -171,6 +172,7 @@ the documentation `Bash`
 * [cbfstool](util/cbfstool/index.md)
 * [ifdtool](util/ifdtool/index.md)
 * [intelp2m](util/intelp2m/index.md)
+* [smmstoretool](util/smmstoretool/index.md)
 
 ## Generated documentation
 
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
+```