From patchwork Wed Sep 3 13:36:24 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 211 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=1756906685; bh=B2Bytmv9M04mmUAqrY3YWL7jinJGYCHQ2jqnpPy1Ojc=; 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=XOa8nprBI9VQrxbfVUvvfWot/JwxU2zzqdPh+jacwFx7IXYzxyn1R7Yg8RZtMAGsT CKuKq9P2/PYEWX2i4OgIaVUKTMn9FRje5gwaSW2J9vN916um43sSCGzBlOOAMy2T50 +dgCk3DHXXrxOFWibL3b3vmwhtHESJ7nj+Rc0UYk2GRvvMa1ijIo6stBle890Q82iL oeLqJ86eBwd9V6vfs6CE/D1IH9wOSVoQId7oYPVdpKL4Vxa299ne8pYqEIbd4eoB1z w7Q8TXGcChHQVJzt3wsZmB0XwH3bf443AGpufxUH6cCGH0J3UgC5vVLNlwzwDWcNbi RfD2SGtHuBdMA== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id ACD9967924 for ; Wed, 3 Sep 2025 07:38:05 -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 ZEVhM5wY8CkN for ; Wed, 3 Sep 2025 07:38:05 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1756906685; bh=B2Bytmv9M04mmUAqrY3YWL7jinJGYCHQ2jqnpPy1Ojc=; 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=XOa8nprBI9VQrxbfVUvvfWot/JwxU2zzqdPh+jacwFx7IXYzxyn1R7Yg8RZtMAGsT CKuKq9P2/PYEWX2i4OgIaVUKTMn9FRje5gwaSW2J9vN916um43sSCGzBlOOAMy2T50 +dgCk3DHXXrxOFWibL3b3vmwhtHESJ7nj+Rc0UYk2GRvvMa1ijIo6stBle890Q82iL oeLqJ86eBwd9V6vfs6CE/D1IH9wOSVoQId7oYPVdpKL4Vxa299ne8pYqEIbd4eoB1z w7Q8TXGcChHQVJzt3wsZmB0XwH3bf443AGpufxUH6cCGH0J3UgC5vVLNlwzwDWcNbi RfD2SGtHuBdMA== Received: from mail.u-boot.org (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 9CBD86774F for ; Wed, 3 Sep 2025 07:38:05 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1756906682; bh=5EIn0nE97+dYNVDH43ws6ntrdU+rBiTtucrRr+8krN0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Yqw0ljH9Hj0M8qeu3owMZkHmlcbspRVSuixq97jPOkrySPHblHRTnYi8KH2uGA44p tjKnjzmcJX89tuNdMmP6lpwPpp9kqJcv5huy8ii0LhMt/1ZuDaZWkJWvLik7QYifuz U2n2hK6FxMJxum+sjYutGiYKUX3/FzclyOUejHjUWR+rlpIyWDcUfzzK6HRZfjMPZM 2mhBNp4VikQAP9uPeP16Lf/6dfA3JMh2c8Q1ieVxlc4TirxYfvJeEi8apVPE6S2RBF WTtkIZri4+3KhG7CAxoE7JtMDOhjqyJpr8AVZwGfTNL3KRAKl2oSNGZKG7dSBSpaAs 5UHKccanpVhjw== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id ACBD96774F; Wed, 3 Sep 2025 07:38:02 -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 W0zsjGzcM09d; Wed, 3 Sep 2025 07:38:02 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1756906678; bh=SoK4+WhbjcQQITzogKlE3H/2o4T3l+mROyYvD1tG1xM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=R3nC+vxPuwMgR9cez2l2AThs9wd+FFRWkLjTV3gbE6VyqSZXBUASl+NJzXMZbYa8I ceHgbS/SnLEGm71p+WYHhzsXFoyEN2AzaIeHhEl3Y0tza1d6wdZtI8b3c3uZkudBG+ aB//2LxncO0xlgiphEhrFUeU14QfznogTdR7Gg/5k/Rw/z1PfplxGzPsG7MDyioI0R 2iJx1pwbs5wmiZISl+mLyOsFMMEuAoScxyYWVmGvHo+AGvQFFHaJ0kiqu/hAW54Kf3 K+z/uCAcSzpGQymFxM5aCZuP0T5G4SKDlQusJJ/1iLD992XI1H696ihTMHgbcaeHoQ g0l3liLKL0KFw== Received: from u-boot.org (unknown [73.34.74.121]) by mail.u-boot.org (Postfix) with ESMTPSA id 5F7B95FE1B; Wed, 3 Sep 2025 07:37:58 -0600 (MDT) From: Simon Glass To: U-Boot Concept Date: Wed, 3 Sep 2025 07:36:24 -0600 Message-ID: <20250903133639.3235920-25-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: 4FC4ZXICD23YZXCJ2NQBEARA4IZ6S63Q X-Message-ID-Hash: 4FC4ZXICD23YZXCJ2NQBEARA4IZ6S63Q 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 X-Mailman-Version: 3.3.10 Precedence: list Subject: [Concept] [PATCH 24/25] chid: doc: Describe how the CHID feature works 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 Provide some developer documentation for this new feature. Signed-off-by: Simon Glass --- doc/develop/chid.rst | 130 ++++++++++++++++++++++++++++++++++++++++- doc/usage/cmd/chid.rst | 1 + 2 files changed, 130 insertions(+), 1 deletion(-) diff --git a/doc/develop/chid.rst b/doc/develop/chid.rst index abf6d1efd94..4926600e39b 100644 --- a/doc/develop/chid.rst +++ b/doc/develop/chid.rst @@ -190,6 +190,132 @@ Command Interface See :doc:`/usage/cmd/chid`. +Devicetree Generation Script +----------------------------- + +The ``scripts/hwids_to_dtsi.py`` script converts HWIDS text files containing +computer information and hardware IDs to devicetree source (.dtsi) files. This +enables embedding CHID data directly in devicetree for platforms that need it. + +Usage +~~~~~ + +**Single File Mode**:: + + python scripts/hwids_to_dtsi.py board/efi/hwids/device.txt -o device.dtsi + +**Multi-Board Mode**:: + + python scripts/hwids_to_dtsi.py -m board/efi/hwids/compatible.hwidmap -o hwids.dtsi + +The script processes HWIDS files generated by Microsoft's ComputerHardwareIds.exe +utility and creates devicetree nodes containing: + +* SMBIOS computer information as devicetree properties +* Hardware ID arrays as binary CHID data +* Compatible strings for device matching + +Input Format +~~~~~~~~~~~~ + +HWIDS files contain computer information and hardware ID sections:: + + Computer Information + -------------------- + BiosVendor: ACME Corp + BiosVersion: V1.0 + Manufacturer: ACME + ProductName: Test Device + ... + + Hardware IDs + ------------ + {12345678-1234-5678-9abc-123456789abc} <- Field description + {87654321-4321-8765-cba9-987654321cba} <- Field description + ... + +The script parses both sections and generates corresponding devicetree properties +and CHID arrays. + +Output Format +~~~~~~~~~~~~~ + +The output consists of a node for each device. Within that node the compatible +string is provided, along the SMBIOS information to match against. Then there is +a subnode for each CHID variant, containing the variant number, a bitmask +indicating which fields are included in that variant and finally the CHID +itself (16 bytes). + +For example:: + + // SPDX-License-Identifier: GPL-2.0+ + + // Computer Hardware IDs for multiple boards + // Generated from board/efi/hwids/ + + / { + chid: chid {}; + }; + + &chid { + device-name { + compatible = "vendor,device"; + + // SMBIOS Computer Information + manufacturer = "ACME"; + product-name = "Test Device"; + bios-vendor = "ACME Corp"; + + // Hardware IDs (CHIDs) + hardware-id-00 { + variant = <0>; + fields = <0x3cf>; + chid = [12 34 56 78 12 34 56 78 9a bc 12 34 56 78 9a bc]; + }; + }; + }; + +**Devicetree Properties** + +The generated devicetree contains the following properties: + +========================= ========== =========================================== +Property Type Purpose +========================= ========== =========================================== +compatible string Device identification for matching +manufacturer string SMBIOS System Manufacturer +family string SMBIOS System Family +product-name string SMBIOS System Product Name +product-sku string SMBIOS System SKU Number +baseboard-manufacturer string SMBIOS Board Manufacturer +baseboard-product string SMBIOS Board Product Name +bios-vendor string SMBIOS BIOS Vendor +bios-version string SMBIOS BIOS Version +bios-major-release u32 SMBIOS BIOS Major Release +bios-minor-release u32 SMBIOS BIOS Minor Release +firmware-major-release u32 SMBIOS Firmware Major Release (EFI only) +firmware-minor-release u32 SMBIOS Firmware Minor Release (EFI only) +enclosure-kind u32 SMBIOS Chassis Type (hex format) +variant u32 CHID variant number (0-14). Omitted if + there is no variant. +fields u32 Bitmask of fields used in CHID generation +chid byte-array 16-byte CHID UUID in binary format +========================= ========== =========================================== + +Compatible Mapping +~~~~~~~~~~~~~~~~~~ + +Multi-board mode uses a ``compatible.hwidmap`` file to map device names to +compatible strings:: + + # Device mapping file + device1: vendor,device1 + device2: vendor,device2 + special-board: none # Skip this board + +Lines starting with ``#`` are comments. Use ``none`` as the compatible string +to skip processing a particular board. + Testing ------- @@ -197,9 +323,11 @@ Tests are provided in: * ``test/lib/chid.c`` - Library function tests * ``test/cmd/chid.c`` - Command interface tests +* ``test/scripts/test_hwids_to_dtsi.py`` - Script functionality tests Tests validate against real Microsoft ComputerHardwareIds.exe output -to ensure exact compatibility. +to ensure exact compatibility. The script tests verify HWIDS file parsing, +devicetree generation, and error handling. References ---------- diff --git a/doc/usage/cmd/chid.rst b/doc/usage/cmd/chid.rst index 77e6f57654d..e96101928d8 100644 --- a/doc/usage/cmd/chid.rst +++ b/doc/usage/cmd/chid.rst @@ -96,4 +96,5 @@ The return value $? is 0 (true) on success, 1 (false) on failure. See also -------- +* :doc:`/develop/chid` - CHID developer documentation * :doc:`smbios ` - SMBIOS table information