chid: Provide some developer docs
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>
This commit is contained in:
Simon Glass
210
doc/develop/chid.rst
Normal file
210
doc/develop/chid.rst
Normal file
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user