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

Elliot Berman
2024-05-22T23:54:52Z

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