From patchwork Wed Sep 3 13:36:18 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 206 Return-Path: X-Original-To: u-boot-concept@u-boot.org Delivered-To: u-boot-concept@u-boot.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1756906667; bh=tNQMXmaUqkXcDmfyujNjOGA8waWotT4LDBY5Ren1w3M=; h=From:To:Date:In-Reply-To:References:CC:Subject:List-Id: List-Archive:List-Help:List-Owner:List-Post:List-Subscribe: List-Unsubscribe:From; b=eBOJvMRDfixfiLiEVq8g+xVxD2QGZHt1cfmxmCDBP3ugayKD6NCtyQufhmbq0wZGW 0BM9vaJmPXQVVghZgf69ix3fBhXMAb73ZR8QJO3RpI3Vzo6K+jQXZlvUUpImK1kvzu 4dUs/SZJQeJ76yVFYku5CfaeMHU5iIebSy3l692CPpTqBkL7fZ5bVChmWQ49zdw8bB 60yzzdL6ZtaHVSpx3OCZGdfXZQjYjCvcC8EDzAQ3k8TqbQYNS/hxLteYk4zAXXA5fF BySqkQyVVU3YvqWUgoGEragz56NXbf61IvhMKoshytnExHZHOfIIIqu8cSAb8ep64u qKHdIiKZaPE8Q== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 98C8B5FE1B for ; Wed, 3 Sep 2025 07:37:47 -0600 (MDT) X-Virus-Scanned: Debian amavis at Received: from mail.u-boot.org ([127.0.0.1]) by localhost (mail.u-boot.org [127.0.0.1]) (amavis, port 10024) with ESMTP id Bx74RlAaNoHp for ; Wed, 3 Sep 2025 07:37:47 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1756906667; bh=tNQMXmaUqkXcDmfyujNjOGA8waWotT4LDBY5Ren1w3M=; h=From:To:Date:In-Reply-To:References:CC:Subject:List-Id: List-Archive:List-Help:List-Owner:List-Post:List-Subscribe: List-Unsubscribe:From; b=eBOJvMRDfixfiLiEVq8g+xVxD2QGZHt1cfmxmCDBP3ugayKD6NCtyQufhmbq0wZGW 0BM9vaJmPXQVVghZgf69ix3fBhXMAb73ZR8QJO3RpI3Vzo6K+jQXZlvUUpImK1kvzu 4dUs/SZJQeJ76yVFYku5CfaeMHU5iIebSy3l692CPpTqBkL7fZ5bVChmWQ49zdw8bB 60yzzdL6ZtaHVSpx3OCZGdfXZQjYjCvcC8EDzAQ3k8TqbQYNS/hxLteYk4zAXXA5fF BySqkQyVVU3YvqWUgoGEragz56NXbf61IvhMKoshytnExHZHOfIIIqu8cSAb8ep64u qKHdIiKZaPE8Q== Received: from mail.u-boot.org (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 880F067819 for ; Wed, 3 Sep 2025 07:37:47 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1756906665; bh=1SNNjFqRzIy0nzd0Mv75p7pSIaUC2Zh6O68Sd8nyyAw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FN3om1FBQQaqGqNLbuAxANAQqAAODW5gK7EUFVW3VMpj9l8/bGUdUCHePo0J3T+ye tflGL1nihG9rM1jMRtUYx628MbU/5gVY5Jcw90B7aVc2uTvyij5qYTNCIQfs+aVuiN HZ2IjkgW8VCh7sIwR49yi6/xHDQmgipBCnc//HArCGmU9idq2SM5djIDcqLoFtJ0Qf Vs02V8bZQkeF/rFBTQxoyq/fRfhVHHZgb9qRLWbhJoq912/1vaA65um8Gdo+MsqRJk 6C89NOEqaAh8A3+6eBajl5fVYkWiwDjeLLpM6uB8jVAvyESFo+IClpT2c2s3AbwxWp p/jjTXG5bmAww== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 9392F67915; Wed, 3 Sep 2025 07:37:45 -0600 (MDT) X-Virus-Scanned: Debian amavis at Received: from mail.u-boot.org ([127.0.0.1]) by localhost (mail.u-boot.org [127.0.0.1]) (amavis, port 10026) with ESMTP id rEnRwonMpN03; Wed, 3 Sep 2025 07:37:45 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1756906661; bh=a1iJbIwfAtVhaxXv9TrLAowl2ImWsvEJXVAt6x26mY4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nvIlclSei4JKn+NhTq30NBhnClHCiyobmpPHZC8pLNjuU1tbQapgCZIONaPcrNAwL Rf+bZFRfSTOm28HDfNShIAwQnPAAg5sghDCVZkxtfioWcC+2Zcat2/geigjOAJoyVY /AqU6tsWXzkuTmQj3dSGFc6kMOQSGiBz6smffQNgga44FKlLklGBQ8vnbXrNtPyeUH AIEzKc2DkkzC3+GpsppD2zyq5V9yXYFuD+ghe8O6C9E8DH2Gzs5yG2W4jZLMSLIOJg 5WTP06lzBzPGIQP9lgcjymL9SQtvjLxDt6ivmrbLY04rp2o+8yK8v8RdfXD3P6L4mk ksZjVgYXxLnxw== Received: from u-boot.org (unknown [73.34.74.121]) by mail.u-boot.org (Postfix) with ESMTPSA id 42ED667819; Wed, 3 Sep 2025 07:37:41 -0600 (MDT) From: Simon Glass To: U-Boot Concept Date: Wed, 3 Sep 2025 07:36:18 -0600 Message-ID: <20250903133639.3235920-19-sjg@u-boot.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20250903133639.3235920-1-sjg@u-boot.org> References: <20250903133639.3235920-1-sjg@u-boot.org> MIME-Version: 1.0 Message-ID-Hash: 2DU4H6O3LJYUQLNLYP6LF3IOGBMWHZJJ X-Message-ID-Hash: 2DU4H6O3LJYUQLNLYP6LF3IOGBMWHZJJ X-MailFrom: sjg@u-boot.org X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: Simon Glass , Claude X-Mailman-Version: 3.3.10 Precedence: list Subject: [Concept] [PATCH 18/25] chid: Provide some developer docs List-Id: Discussion and patches related to U-Boot Concept Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: From: Simon Glass Describe how this feature works and provide some helpful links. Co-developed-by: Claude Signed-off-by: Simon Glass --- 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 `_ +* `Microsoft Hardware ID Specification `_ +* `Reverse Engineering Blog Post `_ 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