ukify: Switch to JSON HWID description format (#35208)

Fixes #35176

2 files changed, 39 insertions, 0 deletions

diff --git a/man/ukify.xml b/man/ukify.xml
index c634e0bdee..c3b8d920d1 100644
--- a/man/ukify.xml
+++ b/man/ukify.xml
@@ -71,6 +71,8 @@
       <varname>Cmdline=</varname>/<option>--cmdline=</option>,
       <varname>OSRelease=</varname>/<option>--os-release=</option>,
       <varname>DeviceTree=</varname>/<option>--devicetree=</option>,
+      <varname>DeviceTreeAuto=</varname>/<option>--devicetree-auto=</option>,
+      <varname>HWIDs=</varname>/<option>--hwids=</option>,
       <varname>Splash=</varname>/<option>--splash=</option>,
       <varname>PCRPKey=</varname>/<option>--pcrpkey=</option>,
       <varname>Uname=</varname>/<option>--uname=</option>,
@@ -375,6 +377,35 @@
         </varlistentry>
 
         <varlistentry>
+          <term><varname>DeviceTreeAuto=<replaceable>PATH</replaceable>...</varname></term>
+          <term><option>--devicetree-auto=<replaceable>PATH</replaceable></option></term>
+
+          <listitem><para>Zero or more automatically selectable DeviceTree files. In the configuration file, items are separated by
+          whitespace. Each DeviceTree will be in a separate <literal>.dtbauto</literal> section.</para>
+
+          <xi:include href="version-info.xml" xpointer="v257"/></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>HWIDs=<replaceable>PATH</replaceable></varname></term>
+          <term><option>--hwids=<replaceable>PATH</replaceable></option></term>
+
+          <listitem><para>The hardware ID device table (the <literal>.hwids</literal> section). The argument is a
+          path to a directory with JSON HWID device description files. Each file needs to contain a single JSON object with a <literal>name</literal>, <literal>compatible</literal> and <literal>hwids</literal> keys. The <literal>name</literal> and <literal>compatible</literal> keys must have string values and the <literal>hwids</literal> key must have a list of strings as value, where the strings must be valid UUIDs that represent CHIDs/HWIDs.
+          Example:
+          <programlisting><xi:include href="ukify_hwid.json.example" parse="text" /></programlisting>
+          Here <literal>Example Laptop 16 Gen 7</literal> is the device <literal>name</literal> (as defined by the manufacturer),
+          <literal>example,laptop-16-g7</literal> is the <literal>compatible</literal> (as defined by the kernel) and <literal>hwids</literal>
+          is an array of CHIDs/HWIDs (extracted i.e. from <command>fwupdtool hwids</command> output).
+          If not specified, the section will not be present. It is recommended to specify this parameter if automatically
+          selectable DeviceTrees are to be used.
+
+          </para>
+
+          <xi:include href="version-info.xml" xpointer="v257"/></listitem>
+        </varlistentry>
+
+        <varlistentry>
           <term><varname>Uname=<replaceable>VERSION</replaceable></varname></term>
           <term><option>--uname=<replaceable>VERSION</replaceable></option></term>
 
diff --git a/man/ukify_hwid.json.example b/man/ukify_hwid.json.example
new file mode 100644
index 0000000000..83921b5d93
--- /dev/null
+++ b/man/ukify_hwid.json.example
@@ -0,0 +1,8 @@
+{
+    "name": "Example Laptop 16 Gen 7",
+    "compatible": "example,laptop-16-g7",
+    "hwids": [
+        "5dc05bf4-01f6-4089-b464-a08c47ea9295",
+        "3e3f8f3c-2003-46f2-811c-85554f7d5952"
+    ]
+}