Received-SPF: pass (google.com: domain of linux-kernel+bounces-186852-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:40f1:3f00::1 as permitted sender) client-ip=2604:1380:40f1:3f00::1;
From: Elliot Berman <quic_eberman@quicinc.com>
To: Elliot Berman <quic_eberman@quicinc.com>
CC: Conor Dooley <conor@kernel.org>, Rob Herring <robh+dt@kernel.org>,
        "Frank
 Rowand" <frowand.list@gmail.com>,
        Krzysztof Kozlowski
	<krzysztof.kozlowski+dt@linaro.org>,
        Conor Dooley <conor+dt@kernel.org>,
        Bjorn Andersson <andersson@kernel.org>,
        Konrad Dybcio
	<konrad.dybcio@linaro.org>,
        Amrit Anand <quic_amrianan@quicinc.com>,
        "Peter
 Griffin" <peter.griffin@linaro.org>,
        Caleb Connolly
	<caleb.connolly@linaro.org>,
        Andy Gross <agross@kernel.org>, Doug Anderson
	<dianders@chromium.org>,
        Simon Glass <sjg@chromium.org>, Chen-Yu Tsai
	<wenst@chromium.org>,
        Julius Werner <jwerner@chromium.org>,
        "Humphreys,
 Jonathan" <j-humphreys@ti.com>,
        Sumit Garg <sumit.garg@linaro.org>,
        "Michal
 Simek" <michal.simek@amd.com>,
        <boot-architecture@lists.linaro.org>, <devicetree@vger.kernel.org>,
        <linux-kernel@vger.kernel.org>, <linux-arm-kernel@lists.infradead.org>,
        <linux-arm-msm@vger.kernel.org>
Subject: [PATCH RFC v3 2/9] dt-bindings: board: Introduce board-id
Date: Wed, 22 May 2024 16:54:23 -0700
Message-ID: <20240522-board-ids-v4-2-a173277987f5@quicinc.com>
In-Reply-To: <20240522162545887-0700.eberman@hu-eberman-lv.qualcomm.com>
References: <20240522162545887-0700.eberman@hu-eberman-lv.qualcomm.com>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit

Device manufcturers frequently ship multiple boards or SKUs under a
single softwre package. These software packages ship multiple devicetree
blobs and require some mechanims to pick the correct DTB for the boards
that use the software package. This patch introduces a common language
for adding board identifiers to devicetrees.

Signed-off-by: Elliot Berman <quic_eberman@quicinc.com>
---
 .../devicetree/bindings/board/board-id.yaml        | 71 ++++++++++++++++++++++
 1 file changed, 71 insertions(+)

diff --git a/Documentation/devicetree/bindings/board/board-id.yaml b/Documentation/devicetree/bindings/board/board-id.yaml
new file mode 100644
index 000000000000..894c1e310cbd
--- /dev/null
+++ b/Documentation/devicetree/bindings/board/board-id.yaml
@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/board/board-id.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Board identifiers
+description: |
+  This node contains a list of identifier values for the board(s) supported by
+  this devicetree. Identifier values are either N-tuples of integers or a
+  string. The number of items for an N-tuple identifer is determined by the
+  property name. String identifiers must be suffixed with "-string".
+
+  Every identifier in the devicetree must have a matching value from the board
+  to be considered a valid devicetree for the board. In other words: if
+  multiple identifiers are present in the board-id and one identifier doesn't
+  match against the board, then the devicetree is not applicable. Note this is
+  not the case where the the board can provide more identifiers than the
+  devicetree describes: those additional identifers can be ignored.
+
+  Identifiers in the devicetree can describe multiple possible valid values,
+  such as revision 1 and revision 2.
+
+maintainers:
+  - Elliot Berman <quic_eberman@quicinc.com>
+
+properties:
+  $nodename:
+    const: '/'
+  board-id:
+    type: object
+    patternProperties:
+      "^.*(?<!-string)$":
+        $ref: /schemas/types.yaml#/definitions/uint32-matrix
+        description: |
+          List of values that match boards this devicetree applies to.
+          A bootloader checks whether any of the values in this list
+          match against the board's value.
+
+          The number of items per tuple is determined by the property name,
+          see the vendor-specific board-id bindings.
+      "^.*-string$":
+        $ref: /schemas/types.yaml#/definitions/string-array
+        description: |
+          List of strings that match boards this devicetree applies to.
+          A bootloader checks whether any of the strings in this list
+          match against the board's string representation.
+
+          String-based matching requires properties to be suffixed with
+          -string so that a bootloader can match values without otherwise
+          knowing the meaning of the identifier.
+
+examples:
+  - |
+    / {
+      #address-cells = <1>;
+      #size-cells = <1>;
+      compatible = "example";
+      board-id {
+        // this works with any boards where:
+        // some-hw-id = 1, other-hw-id = 1, some-id-string = "cat"
+        // some-hw-id = 1, other-hw-id = 1, some-id-string = "kitten"
+        // some-hw-id = 1, other-hw-id = 2, some-id-string = "cat"
+        // some-hw-id = 1, other-hw-id = 2, some-id-string = "kitten"
+        some-hw-id = <1>; // some-hw-id must be "1"
+        other-hw-id = <1>, <2>; // other-hw-id must be "1" or "2"
+        some-id-string = "cat", "kitten"; // some-id-string must be "cat" or "kitten"
+      };
+    };
+
+additionalProperties: true

-- 
2.34.1