[Concept,24/25] chid: doc: Describe how the CHID feature works
Commit Message
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(-)
@@ -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
----------
@@ -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