Documentation/drivers/cbfs_smbios.md

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