From: Simon Glass <sjg@chromium.org> Provide some developer documentation for this new feature. Signed-off-by: Simon Glass <sjg@chromium.org> --- 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>` - SMBIOS table information -- 2.43.0