From: Simon Glass <sjg@chromium.org> Describe how this feature works and provide some helpful links. Co-developed-by: Claude <noreply@anthropic.com> Signed-off-by: Simon Glass <sjg@chromium.org> --- doc/develop/chid.rst | 210 ++++++++++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 2 files changed, 211 insertions(+) create mode 100644 doc/develop/chid.rst diff --git a/doc/develop/chid.rst b/doc/develop/chid.rst new file mode 100644 index 00000000000..abf6d1efd94 --- /dev/null +++ b/doc/develop/chid.rst @@ -0,0 +1,210 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Computer Hardware IDs (CHID) +============================= + +Overview +-------- + +Computer Hardware IDs (CHIDs) are Microsoft-defined identifiers used by +Windows Update and Linux fwupd for hardware identification and firmware +update targeting. CHIDs provide a standardized way to uniquely identify +hardware platforms using SMBIOS information. + +U-Boot implements CHID generation following Microsoft's specification to +enable compatibility with firmware update ecosystems that rely on these +identifiers. + +CHID Generation Algorithm +------------------------- + +CHIDs are generated using the following process: + +1. **Field Selection**: Based on the variant (0-14), select which SMBIOS + fields to include +2. **String Building**: Concatenate selected fields with '&' separators +3. **String Trimming**: Remove leading/trailing whitespace from each field +4. **UTF-16LE Conversion**: Convert the concatenated string to UTF-16LE + encoding +5. **UUID Generation**: Generate a UUID v5 using Microsoft's namespace + UUID and the UTF-16LE data + +CHID Variants +------------- + +Microsoft defines 15 CHID variants (HardwareID-00 through HardwareID-14), +ordered from most specific to least specific: + +=================== ==================================================== +Variant Fields Used +=================== ==================================================== +HardwareID-00 Manufacturer + Family + ProductName + ProductSku + + BiosVendor + BiosVersion + BiosMajorRelease + + BiosMinorRelease +HardwareID-01 Manufacturer + Family + ProductName + BiosVendor + + BiosVersion + BiosMajorRelease + BiosMinorRelease +HardwareID-02 Manufacturer + ProductName + BiosVendor + + BiosVersion + BiosMajorRelease + BiosMinorRelease +HardwareID-03 Manufacturer + Family + ProductName + ProductSku + + BaseboardManufacturer + BaseboardProduct +HardwareID-04 Manufacturer + Family + ProductName + ProductSku +HardwareID-05 Manufacturer + Family + ProductName +HardwareID-06 Manufacturer + ProductSku + BaseboardManufacturer + + BaseboardProduct +HardwareID-07 Manufacturer + ProductSku +HardwareID-08 Manufacturer + ProductName + BaseboardManufacturer + + BaseboardProduct +HardwareID-09 Manufacturer + ProductName +HardwareID-10 Manufacturer + Family + BaseboardManufacturer + + BaseboardProduct +HardwareID-11 Manufacturer + Family +HardwareID-12 Manufacturer + EnclosureKind +HardwareID-13 Manufacturer + BaseboardManufacturer + + BaseboardProduct +HardwareID-14 Manufacturer +=================== ==================================================== + +SMBIOS Field Mapping +-------------------- + +CHIDs use the following SMBIOS table fields: + +================= ================= =========== +CHID Field SMBIOS Table Field +================= ================= =========== +Manufacturer Type 1 (System) Manufacturer +Family Type 1 (System) Family +ProductName Type 1 (System) Product Name +ProductSku Type 1 (System) SKU Number +BaseboardManuf Type 2 (Board) Manufacturer +BaseboardProduct Type 2 (Board) Product Name +BiosVendor Type 0 (BIOS) Vendor +BiosVersion Type 0 (BIOS) Version +BiosMajorRelease Type 0 (BIOS) Major Release +BiosMinorRelease Type 0 (BIOS) Minor Release +EnclosureKind Type 3 (Chassis) Type +================= ================= =========== + +Technical Details +----------------- + +The CHID generation algorithm follows Microsoft's exact specification to ensure +compatibility with Windows Update and fwupd. The process begins by concatenating +the selected SMBIOS fields with '&' separators, creating strings like +``Manufacturer&Family&ProductName&ProductSku``. These strings are then converted +to UTF-16LE encoding to properly handle international characters. + +UUID generation uses the SHA-1 based UUID v5 algorithm with Microsoft's specific +namespace UUID ``70ffd812-4c7f-4c7d-0000-000000000000``. The implementation +generates big-endian UUIDs to match Microsoft's ComputerHardwareIds.exe output +exactly, ensuring byte-for-byte compatibility with the reference implementation. + +API Reference +------------- + +Core Functions +~~~~~~~~~~~~~~ + +.. c:function:: int chid_from_smbios(struct chid_data *chid) + + Extract CHID-relevant data from SMBIOS tables. + + :param chid: Pointer to structure to fill with SMBIOS data + :returns: 0 on success, negative error code on failure + +.. c:function:: int chid_generate(int variant, const struct chid_data *data, u8 chid[16]) + + Generate a specific CHID variant. + + :param variant: CHID variant number (0-14) + :param data: SMBIOS data structure + :param chid: Output buffer for 16-byte CHID + :returns: 0 on success, negative error code on failure + +Utility Functions +~~~~~~~~~~~~~~~~~ + +.. c:function:: const char *chid_get_field_name(enum chid_field_t field) + + Get display name for a CHID field. + + :param field: CHID field identifier + :returns: Human-readable field name + +.. c:function:: u32 chid_get_variant_fields(int variant) + + Get bitmask of fields used by a CHID variant. + + :param variant: CHID variant number (0-14) + :returns: Bitmask of fields (BIT(CHID_xxx) values) + +.. c:function:: const char *chid_get_variant_name(int variant) + + Get name of a CHID variant. + + :param variant: CHID variant number (0-14) + :returns: Variant name (e.g., "HardwareID-00") + +Data Structures +~~~~~~~~~~~~~~~ + +**struct chid_data** + + Contains SMBIOS field values for CHID generation:: + + struct chid_data { + const char *manuf; + const char *family; + const char *product_name; + const char *product_sku; + const char *board_manuf; + const char *board_product; + const char *bios_vendor; + const char *bios_version; + u8 bios_major; + u8 bios_minor; + u8 enclosure_type; + }; + +**enum chid_field_t** + + CHID field identifiers:: + + enum chid_field_t { + CHID_MANUF, + CHID_FAMILY, + CHID_PRODUCT_NAME, + CHID_PRODUCT_SKU, + CHID_BOARD_MANUF, + CHID_BOARD_PRODUCT, + CHID_BIOS_VENDOR, + CHID_BIOS_VERSION, + CHID_BIOS_MAJOR, + CHID_BIOS_MINOR, + CHID_ENCLOSURE_TYPE, + CHID_COUNT, + }; + +Command Interface +----------------- + +See :doc:`/usage/cmd/chid`. + +Testing +------- + +Tests are provided in: + +* ``test/lib/chid.c`` - Library function tests +* ``test/cmd/chid.c`` - Command interface tests + +Tests validate against real Microsoft ComputerHardwareIds.exe output +to ensure exact compatibility. + +References +---------- + +* :doc:`smbios` - SMBIOS table information used by CHIDs +* `fwupd Hardware IDs <https://github.com/fwupd/fwupd/blob/main/docs/hwids.md>`_ +* `Microsoft Hardware ID Specification <https://docs.microsoft.com/en-us/windows-hardware/drivers/install/specifying-hardware-ids-for-a-computer>`_ +* `Reverse Engineering Blog Post <https://blogs.gnome.org/hughsie/2017/04/25/reverse-engineering-computerhardwareids-exe-with-winedbg/>`_ diff --git a/doc/develop/index.rst b/doc/develop/index.rst index aebfd428277..592736331f2 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -32,6 +32,7 @@ Implementation directories bloblist bootstd/index + chid ci_testing commands config_binding -- 2.43.0