Documentation/drivers/cbfs_smbios.md: Describe CBFS serial number

Signed-off-by: Michał Żygowski <michal.zygowski@3mdeb.com>
Change-Id: I6f0963417c7c580f903922ac88c95569c8782bdb
Reviewed-on: https://review.coreboot.org/c/coreboot/+/65702
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Krystian Hebel <krystian.hebel@3mdeb.com>

1 files changed, 78 insertions, 0 deletions

diff --git a/Documentation/drivers/cbfs_smbios.md b/Documentation/drivers/cbfs_smbios.md
index 54b7ca4179..b11f64cf08 100644
--- a/Documentation/drivers/cbfs_smbios.md
+++ b/Documentation/drivers/cbfs_smbios.md
@@ -3,6 +3,84 @@
 The document describes the coreboot options how to make CBFS files populate
 platform-unique SMBIOS data.
 
+## SMBIOS Serial Number
+
+The [DMTF SMBIOS specification] defines a field in the type 1 System
+Information and type 2 Baseboard Information called Serial Number. It
+is a null-terminated string field assumed to be unique per platform. Certain
+mainboard ports have SMBIOS hooks to generate the Serial Numbers from external
+data, e.g. Lenovo Thinkpads (see DRIVER_LENOVO_SERIALS). This driver aims to
+provide an option to populate the Serial Numbers from CBFS for boards that
+can't generate the it from any source.
+
+### Usage
+
+In the coreboot configuration menu (`make menuconfig`) go to `Generic Drivers`
+and select an option `Serial number in CBFS`. The Kconfig system will enable
+`DRIVERS_GENERIC_CBFS_SERIAL` and the relevant code parts will be compiled into
+coreboot image.
+
+After the coreboot build for your board completes, use the cbfstool to include
+the file containing the serial number:
+
+```shell
+./build/cbfstool build/coreboot.rom add -n serial_number -t raw -f /path/to/serial_file.txt
+```
+
+Where `serial_file.txt` is the unterminated string representation of the SMBIOS
+type 1 or type 2 Serial Number, e.g. `5Q4Q7Y1`. If you use vboot with 1 or 2 RW
+partitions you will have to specify the RW regions where the file is going to
+be added too. By default the RW CBFS partitions are truncated, so the files
+would probably not fit, one needs to expand them first.
+
+```shell
+./build/cbfstool build/coreboot.rom expand -r FW_MAIN_A
+./build/cbfstool build/coreboot.rom add -n serial_number -t raw \
+	-f /path/to/serial_file.txt -r FW_MAIN_A
+./build/cbfstool build/coreboot.rom truncate -r FW_MAIN_A
+
+./build/cbfstool build/coreboot.rom expand -r FW_MAIN_B
+./build/cbfstool build/coreboot.rom add -n serial_number -t raw \
+	-f /path/to/serial_file.txt -r FW_MAIN_B
+./build/cbfstool build/coreboot.rom truncate -r FW_MAIN_B
+```
+
+By default cbfstool adds files to COREBOOT region only, so when vboot is
+enabled and the platform is booting from RW partition, the file would not be
+picked up by the driver.
+
+One may retrieve the Serial Number from running system (if it exists) using one
+of the following commands:
+
+```shell
+# Type 1
+echo -n `sudo dmidecode -s system-serial-number` > serial_file.txt
+# OR Type 2
+echo -n `sudo dmidecode -s baseboard-serial-number` > serial_file.txt
+```
+
+Ensure the file does not end with whitespaces like LF and/or CR. The above
+commands will not add any whitespaces. The driver automatically terminates the
+Serial Number with the NULL character. If the CBFS file is not present, the
+driver will fall back to the string defined in `MAINBOARD_SERIAL_NUMBER` build
+option.
+
+Please note that this driver provides `smbios_mainboard_serial_number` hook
+overriding the default implementation which returns `MAINBOARD_SERIAL_NUMBER`
+build option. If you wish to populate only type 2 Serial Number field your
+board code needs to implement `smbios_system_serial_number`, otherwise the weak
+implementation of `smbios_system_serial_number` will call
+`smbios_mainboard_serial_number` from the `DRIVERS_GENERIC_CBFS_SERIAL`
+implementation overriding it. So selecting the `DRIVERS_GENERIC_CBFS_SERIAL`
+has a side-effect of populating both SMBIOS type 1 and type 2 Serial Numbers
+if the board does not implement its own `smbios_system_serial_number`.
+
+There is also SMBIOS type 3 Chassis Information Serial Number, but it is not
+populated by `DRIVERS_GENERIC_CBFS_SERIAL` nor by the default weak
+implementation (returns empty string). If you wish to populate type 3 Serial
+Number, your board code should override the default
+`smbios_chassis_serial_number` weak implementation.
+
 ## SMBIOS System UUID
 
 The [DMTF SMBIOS specification] defines a field in the type 1 System