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
