chid: doc: Describe how the CHID feature works
Provide some developer documentation for this new feature. Signed-off-by: Simon Glass <sjg@chromium.org>
This commit is contained in:
Simon Glass
@@ -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
|
||||
----------
|
||||
|
||||
Reference in New Issue
Block a user