[Concept,18/25] chid: Provide some developer docs
Commit Message
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
new file mode 100644
@@ -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/>`_
@@ -32,6 +32,7 @@ Implementation
directories
bloblist
bootstd/index
+ chid
ci_testing
commands
config_binding