example-schema.yaml 8.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249
  1. # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
  2. # Copyright 2018 Linaro Ltd.
  3. %YAML 1.2
  4. ---
  5. # All the top-level keys are standard json-schema keywords except for
  6. # 'maintainers' and 'select'
  7. # $id is a unique identifier based on the filename. There may or may not be a
  8. # file present at the URL.
  9. $id: http://devicetree.org/schemas/example-schema.yaml#
  10. # $schema is the meta-schema this schema should be validated with.
  11. $schema: http://devicetree.org/meta-schemas/core.yaml#
  12. title: An example schema annotated with jsonschema details
  13. maintainers:
  14. - Rob Herring <robh@kernel.org>
  15. description: |
  16. A more detailed multi-line description of the binding.
  17. Details about the hardware device and any links to datasheets can go here.
  18. Literal blocks are marked with the '|' at the beginning. The end is marked by
  19. indentation less than the first line of the literal block. Lines also cannot
  20. begin with a tab character.
  21. select: false
  22. # 'select' is a schema applied to a DT node to determine if this binding
  23. # schema should be applied to the node. It is optional and by default the
  24. # possible compatible strings are extracted and used to match.
  25. # In this case, a 'false' schema will never match.
  26. properties:
  27. # A dictionary of DT properties for this binding schema
  28. compatible:
  29. # More complicated schema can use oneOf (XOR), anyOf (OR), or allOf (AND)
  30. # to handle different conditions.
  31. # In this case, it's needed to handle a variable number of values as there
  32. # isn't another way to express a constraint of the last string value.
  33. # The boolean schema must be a list of schemas.
  34. oneOf:
  35. - items:
  36. # items is a list of possible values for the property. The number of
  37. # values is determined by the number of elements in the list.
  38. # Order in lists is significant, order in dicts is not
  39. # Must be one of the 1st enums followed by the 2nd enum
  40. #
  41. # Each element in items should be 'enum' or 'const'
  42. - enum:
  43. - vendor,soc4-ip
  44. - vendor,soc3-ip
  45. - vendor,soc2-ip
  46. - enum:
  47. - vendor,soc1-ip
  48. # additionalItems being false is implied
  49. # minItems/maxItems equal to 2 is implied
  50. - items:
  51. # 'const' is just a special case of an enum with a single possible value
  52. - const: vendor,soc1-ip
  53. reg:
  54. # The core schema already checks that reg values are numbers, so device
  55. # specific schema don't need to do those checks.
  56. # The description of each element defines the order and implicitly defines
  57. # the number of reg entries.
  58. items:
  59. - description: core registers
  60. - description: aux registers
  61. # minItems/maxItems equal to 2 is implied
  62. reg-names:
  63. # The core schema enforces this (*-names) is a string array
  64. items:
  65. - const: core
  66. - const: aux
  67. clocks:
  68. # Cases that have only a single entry just need to express that with maxItems
  69. maxItems: 1
  70. description: bus clock. A description is only needed for a single item if
  71. there's something unique to add.
  72. The items should have a fixed order, so pattern matching names are
  73. discouraged.
  74. clock-names:
  75. items:
  76. - const: bus
  77. interrupts:
  78. # Either 1 or 2 interrupts can be present
  79. minItems: 1
  80. maxItems: 2
  81. items:
  82. - description: tx or combined interrupt
  83. - description: rx interrupt
  84. description:
  85. A variable number of interrupts warrants a description of what conditions
  86. affect the number of interrupts. Otherwise, descriptions on standard
  87. properties are not necessary.
  88. The items should have a fixed order, so pattern matching names are
  89. discouraged.
  90. interrupt-names:
  91. # minItems must be specified here because the default would be 2
  92. minItems: 1
  93. maxItems: 2
  94. items:
  95. - const: tx irq
  96. - const: rx irq
  97. # Property names starting with '#' must be quoted
  98. '#interrupt-cells':
  99. # A simple case where the value must always be '2'.
  100. # The core schema handles that this must be a single integer.
  101. const: 2
  102. interrupt-controller: true
  103. # The core checks this is a boolean, so just have to list it here to be
  104. # valid for this binding.
  105. clock-frequency:
  106. # The type is set in the core schema. Per device schema only need to set
  107. # constraints on the possible values.
  108. minimum: 100
  109. maximum: 400000
  110. # The value that should be used if the property is not present
  111. default: 200
  112. foo-gpios:
  113. maxItems: 1
  114. description: A connection of the 'foo' gpio line.
  115. # *-supply is always a single phandle, so nothing more to define.
  116. foo-supply: true
  117. # Vendor specific properties
  118. #
  119. # Vendor specific properties have slightly different schema requirements than
  120. # common properties. They must have at least a type definition and
  121. # 'description'.
  122. vendor,int-property:
  123. description: Vendor specific properties must have a description
  124. $ref: /schemas/types.yaml#/definitions/uint32
  125. enum: [2, 4, 6, 8, 10]
  126. vendor,bool-property:
  127. description: Vendor specific properties must have a description. Boolean
  128. properties are one case where the json-schema 'type' keyword can be used
  129. directly.
  130. type: boolean
  131. vendor,string-array-property:
  132. description: Vendor specific properties should reference a type in the
  133. core schema.
  134. $ref: /schemas/types.yaml#/definitions/string-array
  135. items:
  136. - enum: [foo, bar]
  137. - enum: [baz, boo]
  138. vendor,property-in-standard-units-microvolt:
  139. description: Vendor specific properties having a standard unit suffix
  140. don't need a type.
  141. enum: [ 100, 200, 300 ]
  142. child-node:
  143. description: Child nodes are just another property from a json-schema
  144. perspective.
  145. type: object # DT nodes are json objects
  146. properties:
  147. vendor,a-child-node-property:
  148. description: Child node properties have all the same schema
  149. requirements.
  150. type: boolean
  151. required:
  152. - vendor,a-child-node-property
  153. # Describe the relationship between different properties
  154. dependencies:
  155. # 'vendor,bool-property' is only allowed when 'vendor,string-array-property'
  156. # is present
  157. vendor,bool-property: [ 'vendor,string-array-property' ]
  158. # Expressing 2 properties in both orders means all of the set of properties
  159. # must be present or none of them.
  160. vendor,string-array-property: [ 'vendor,bool-property' ]
  161. required:
  162. - compatible
  163. - reg
  164. - interrupts
  165. - interrupt-controller
  166. # if/then schema can be used to handle conditions on a property affecting
  167. # another property. A typical case is a specific 'compatible' value changes the
  168. # constraints on other properties.
  169. #
  170. # For multiple 'if' schema, group them under an 'allOf'.
  171. #
  172. # If the conditionals become too unweldy, then it may be better to just split
  173. # the binding into separate schema documents.
  174. allOf:
  175. - if:
  176. properties:
  177. compatible:
  178. contains:
  179. const: vendor,soc2-ip
  180. then:
  181. required:
  182. - foo-supply
  183. # Altering schema depending on presence of properties is usually done by
  184. # dependencies (see above), however some adjustments might require if:
  185. - if:
  186. required:
  187. - vendor,bool-property
  188. then:
  189. properties:
  190. vendor,int-property:
  191. enum: [2, 4, 6]
  192. # Ideally, the schema should have this line otherwise any other properties
  193. # present are allowed. There's a few common properties such as 'status' and
  194. # 'pinctrl-*' which are added automatically by the tooling.
  195. #
  196. # This can't be used in cases where another schema is referenced
  197. # (i.e. allOf: [{$ref: ...}]).
  198. # If and only if another schema is referenced and arbitrary children nodes can
  199. # appear, "unevaluatedProperties: false" could be used. A typical example is
  200. # an I2C controller where no name pattern matching for children can be added.
  201. additionalProperties: false
  202. examples:
  203. # Examples are now compiled with dtc and validated against the schemas
  204. #
  205. # Examples have a default #address-cells and #size-cells value of 1. This can
  206. # be overridden or an appropriate parent bus node should be shown (such as on
  207. # i2c buses).
  208. #
  209. # Any includes used have to be explicitly included.
  210. - |
  211. node@1000 {
  212. compatible = "vendor,soc4-ip", "vendor,soc1-ip";
  213. reg = <0x1000 0x80>,
  214. <0x3000 0x80>;
  215. reg-names = "core", "aux";
  216. interrupts = <10>;
  217. interrupt-controller;
  218. };