1# CBFS SMBIOS hooks 2 3The document describes the coreboot options how to make CBFS files populate 4platform-unique SMBIOS data. 5 6## SMBIOS Serial Number 7 8The [DMTF SMBIOS specification] defines a field in the type 1 System 9Information and type 2 Baseboard Information called Serial Number. It 10is a null-terminated string field assumed to be unique per platform. Certain 11mainboard ports have SMBIOS hooks to generate the Serial Numbers from external 12data, e.g. Lenovo Thinkpads (see DRIVER_LENOVO_SERIALS). This driver aims to 13provide an option to populate the Serial Numbers from CBFS for boards that 14can't generate the it from any source. 15 16### Usage 17 18In the coreboot configuration menu (`make menuconfig`) go to `Generic Drivers` 19and select an option `Serial number in CBFS`. The Kconfig system will enable 20`DRIVERS_GENERIC_CBFS_SERIAL` and the relevant code parts will be compiled into 21coreboot image. 22 23After the coreboot build for your board completes, use the cbfstool to include 24the file containing the serial number: 25 26```shell 27./build/cbfstool build/coreboot.rom add -n serial_number -t raw -f /path/to/serial_file.txt 28``` 29 30Where `serial_file.txt` is the unterminated string representation of the SMBIOS 31type 1 or type 2 Serial Number, e.g. `5Q4Q7Y1`. If you use vboot with 1 or 2 RW 32partitions you will have to specify the RW regions where the file is going to 33be added too. By default the RW CBFS partitions are truncated, so the files 34would probably not fit, one needs to expand them first. 35 36```shell 37./build/cbfstool build/coreboot.rom expand -r FW_MAIN_A 38./build/cbfstool build/coreboot.rom add -n serial_number -t raw \ 39 -f /path/to/serial_file.txt -r FW_MAIN_A 40./build/cbfstool build/coreboot.rom truncate -r FW_MAIN_A 41 42./build/cbfstool build/coreboot.rom expand -r FW_MAIN_B 43./build/cbfstool build/coreboot.rom add -n serial_number -t raw \ 44 -f /path/to/serial_file.txt -r FW_MAIN_B 45./build/cbfstool build/coreboot.rom truncate -r FW_MAIN_B 46``` 47 48By default cbfstool adds files to COREBOOT region only, so when vboot is 49enabled and the platform is booting from RW partition, the file would not be 50picked up by the driver. 51 52One may retrieve the Serial Number from running system (if it exists) using one 53of the following commands: 54 55```shell 56# Type 1 57echo -n `sudo dmidecode -s system-serial-number` > serial_file.txt 58# OR Type 2 59echo -n `sudo dmidecode -s baseboard-serial-number` > serial_file.txt 60``` 61 62Ensure the file does not end with whitespaces like LF and/or CR. The above 63commands will not add any whitespaces. The driver automatically terminates the 64Serial Number with the NULL character. If the CBFS file is not present, the 65driver will fall back to the string defined in `MAINBOARD_SERIAL_NUMBER` build 66option. 67 68Please note that this driver provides `smbios_mainboard_serial_number` hook 69overriding the default implementation which returns `MAINBOARD_SERIAL_NUMBER` 70build option. If you wish to populate only type 2 Serial Number field your 71board code needs to implement `smbios_system_serial_number`, otherwise the weak 72implementation of `smbios_system_serial_number` will call 73`smbios_mainboard_serial_number` from the `DRIVERS_GENERIC_CBFS_SERIAL` 74implementation overriding it. So selecting the `DRIVERS_GENERIC_CBFS_SERIAL` 75has a side-effect of populating both SMBIOS type 1 and type 2 Serial Numbers 76if the board does not implement its own `smbios_system_serial_number`. 77 78There is also SMBIOS type 3 Chassis Information Serial Number, but it is not 79populated by `DRIVERS_GENERIC_CBFS_SERIAL` nor by the default weak 80implementation (returns empty string). If you wish to populate type 3 Serial 81Number, your board code should override the default 82`smbios_chassis_serial_number` weak implementation. 83 84## SMBIOS System UUID 85 86The [DMTF SMBIOS specification] defines a field in the type 1 System 87Information Structure called System UUID. It is a 16 bytes value compliant with 88[RFC4122] and assumed to be unique per platform. Certain mainboard ports have 89SMBIOS hooks to generate the UUID from external data, e.g. Lenovo Thinkpads 90(see DRIVER_LENOVO_SERIALS). This driver aims to provide an option to populate 91the UUID from CBFS for boards that can't generate the UUID from any source. 92 93### Usage 94 95In the coreboot configuration menu (`make menuconfig`) go to `Generic Drivers` 96and select an option `System UUID in CBFS`. The Kconfig system will enable 97`DRIVERS_GENERIC_CBFS_UUID` and the relevant code parts will be compiled into 98coreboot image. 99 100After the coreboot build for your board completes, use the cbfstool to include 101the file containing the UUID: 102 103```shell 104./build/cbfstool build/coreboot.rom add -n system_uuid -t raw -f /path/to/uuid_file.txt 105``` 106 107Where `uuid_file.txt` is the unterminated string representation of the SMBIOS 108type 1 UUID, e.g. `4c4c4544-0051-3410-8051-b5c04f375931`. If you use vboot with 1091 or 2 RW partitions you will have to specify the RW regions where the file is 110going to be added too. By default the RW CBFS partitions are truncated, so the 111files would probably not fit, one needs to expand them first. 112 113```shell 114./build/cbfstool build/coreboot.rom expand -r FW_MAIN_A 115./build/cbfstool build/coreboot.rom add -n system_uuid -t raw \ 116 -f /path/to/uuid_file.txt -r FW_MAIN_A 117./build/cbfstool build/coreboot.rom truncate -r FW_MAIN_A 118 119./build/cbfstool build/coreboot.rom expand -r FW_MAIN_B 120./build/cbfstool build/coreboot.rom add -n system_uuid -t raw \ 121 -f /path/to/uuid_file.txt -r FW_MAIN_B 122./build/cbfstool build/coreboot.rom truncate -r FW_MAIN_B 123``` 124 125By default cbfstool adds files to COREBOOT region only, so when vboot is 126enabled and the platform is booting from RW partition, the file would not be 127picked up by the driver. 128 129One may retrieve the UUID from running system (if it exists) using the 130following command: 131 132```shell 133echo -n `sudo dmidecode -s system-uuid` > uuid_file.txt 134``` 135 136The above command ensures the file does not end with whitespaces like LF and/or 137CR. The above command will not add any whitespaces. But the driver will handle 138situations where up to 2 additional bytes like CR and LF will be included in 139the file. Any more than that will make the driver fail to populate UUID in 140SMBIOS. 141 142[DMTF SMBIOS specification]: https://www.dmtf.org/standards/smbios 143[RFC4122]: https://www.ietf.org/rfc/rfc4122.txt 144