[PATCH RFC v3 2/9] dt-bindings: board: Introduce board-id

[Elliot Berman]

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@xxxxxxxxxxx>
---
 .../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@xxxxxxxxxxx>
+
+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