2019-10-28 16:46:29 +01:00
|
|
|
description: |
|
2019-11-19 10:38:25 +01:00
|
|
|
Free-form description of the device/node. Can have multiple
|
2019-10-28 16:46:29 +01:00
|
|
|
lines/paragraphs.
|
|
|
|
|
|
|
|
See https://yaml-multiline.info/ for formatting help.
|
2017-05-24 07:26:04 +02:00
|
|
|
|
2019-08-19 20:32:25 +02:00
|
|
|
# Used to map nodes to bindings
|
|
|
|
compatible: "manufacturer,device"
|
|
|
|
|
|
|
|
# The 'compatible' above would match this node:
|
|
|
|
#
|
|
|
|
# device {
|
|
|
|
# compatible = "manufacturer,device";
|
|
|
|
# ...
|
|
|
|
# };
|
|
|
|
#
|
|
|
|
# Assuming no binding has 'compatible: "manufacturer,device-v2"', it would also
|
|
|
|
# match this node:
|
|
|
|
#
|
|
|
|
# device {
|
|
|
|
# compatible = "manufacturer,device-v2", "manufacturer,device";
|
|
|
|
# ...
|
|
|
|
# };
|
|
|
|
#
|
|
|
|
# Strings in 'compatible' properties on nodes are tried from left to right, and
|
|
|
|
# the first binding found is used.
|
|
|
|
#
|
|
|
|
# If more than one binding for a compatible is found, an error is raised.
|
|
|
|
|
2019-10-29 20:29:50 +01:00
|
|
|
# Bindings can include other files, which can be used to share common
|
|
|
|
# definitions between bindings.
|
|
|
|
#
|
|
|
|
# Included files are merged into bindings with a simple recursive dictionary
|
|
|
|
# merge. It is up to the binding author to make sure that the final merged
|
|
|
|
# binding is well-formed, though it is checked by the code as well.
|
|
|
|
#
|
|
|
|
# It is an error if a key appears with a different value in a binding and in a
|
|
|
|
# file it includes, with one exception: A binding can have 'required: true' for
|
|
|
|
# some property for which the included file has 'required: false' (see the
|
|
|
|
# description of 'properties' below). The 'required: true' from the binding
|
|
|
|
# takes precedence, allowing bindings to strengthen requirements from included
|
|
|
|
# files.
|
|
|
|
#
|
|
|
|
# Note that weakening requirements by having 'required: false' where the
|
|
|
|
# included file has 'required: true' is an error. This is meant to keep the
|
2019-09-10 19:17:29 +02:00
|
|
|
# organization clean.
|
|
|
|
#
|
2019-10-29 20:29:50 +01:00
|
|
|
# The file base.yaml contains definitions for many common properties. When
|
|
|
|
# writing a new binding, it is a good idea to check if base.yaml already
|
|
|
|
# defines some of the needed properties, and including it in that case. Note
|
|
|
|
# that you can make a property defined in base.yaml obligatory like this
|
|
|
|
# (taking 'reg' as an example):
|
|
|
|
#
|
|
|
|
# reg:
|
|
|
|
# required: true
|
|
|
|
#
|
|
|
|
# This relies on the dictionary merge to fill in the other keys for 'reg', like
|
|
|
|
# 'type'.
|
|
|
|
#
|
2019-09-10 19:17:29 +02:00
|
|
|
# When including multiple files, any overlapping 'required' keys on properties
|
|
|
|
# in the included files are ORed together. This makes sure that a
|
|
|
|
# 'required: true' is always respected.
|
scripts: dts: Improve syntax and code for including binding files
Have
include: foo.dts
include: [foo.dts, bar.dts]
instead of
inherits:
!include foo.dts
inherits:
!include [foo.dts, bar.dts]
This is a nicer and shorter and less cryptic syntax, and will make it
possible to get rid of the custom PyYAML constructor for '!include'
later.
'inherits: !include ...' is still supported for backwards compatibility
for now. Later on, I'm planning to mass-replace it, add a deprecation
warning if it's used, and document 'include:'. Then the '!include'
implementation can be removed a bit later.
'!include' has caused issues in the past (see the comment above the
add_constructor() call), gets iffy with multiple EDT instances, and
makes the code harder to follow.
I'm guessing '!include' might've been intended to be useful outside of
'inherits:' originally, but that's the only place where it's used. It's
undocumented that it's possible to put it elsewhere.
To implement the backwards compatibility, the code just transforms
inherits:
!include foo.dts
into
inherits:
- foo.dts
and treats 'inherits:' similarly to 'include:'. Previously, !include
inserted the contents of the included file instead.
Some more sanity checks for 'include:'/'inherits:' are included as well.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
2019-08-21 16:41:03 +02:00
|
|
|
include: other.yaml # or [other1.yaml, other2.yaml]
|
2017-10-19 16:31:44 +02:00
|
|
|
|
2019-11-26 22:19:55 +01:00
|
|
|
# If the node describes a bus, then the bus type should be given, like below
|
|
|
|
bus: <string describing bus type, e.g. "i2c">
|
2017-10-19 16:31:44 +02:00
|
|
|
|
2019-07-26 15:53:58 +02:00
|
|
|
# If the node appears on a bus, then the bus type should be given, like below.
|
2019-06-21 08:29:57 +02:00
|
|
|
#
|
2019-07-26 15:53:58 +02:00
|
|
|
# When looking for a binding for a node, the code checks if the binding for the
|
2019-11-26 22:19:55 +01:00
|
|
|
# parent node contains 'bus: <bus type>'. If it does, then only bindings with a
|
|
|
|
# matching 'on-bus: <bus type>' are considered. This allows the same type of
|
|
|
|
# device to have different bindings depending on what bus it appears on.
|
|
|
|
on-bus: <string describing bus type, e.g. "i2c">
|
2019-06-21 08:29:57 +02:00
|
|
|
|
2019-07-26 15:53:58 +02:00
|
|
|
# 'properties' describes properties on the node, e.g.
|
|
|
|
#
|
|
|
|
# reg = <1 2>;
|
|
|
|
# current-speed = <115200>;
|
|
|
|
# label = "foo";
|
|
|
|
#
|
|
|
|
# This is used to check that required properties appear, and to
|
|
|
|
# control the format of output generated for them. Except for some
|
|
|
|
# special-cased properties like 'reg', only properties listed here will
|
|
|
|
# generate output.
|
|
|
|
#
|
2019-02-14 04:32:39 +01:00
|
|
|
# A typical property entry looks like this:
|
|
|
|
#
|
2019-07-26 15:53:58 +02:00
|
|
|
# <property name>:
|
2019-08-28 00:22:01 +02:00
|
|
|
# required: <true | false>
|
2019-08-13 11:52:10 +02:00
|
|
|
# type: <string | int | boolean | array | uint8-array | string-array |
|
2020-02-09 00:47:19 +01:00
|
|
|
# phandle | phandles | phandle-array | path | compound>
|
2019-07-26 15:53:58 +02:00
|
|
|
# description: <description of the property>
|
2019-08-10 14:44:31 +02:00
|
|
|
# enum:
|
|
|
|
# - <item1>
|
|
|
|
# - <item2>
|
|
|
|
# ...
|
|
|
|
# - <itemN>
|
2019-08-09 23:03:46 +02:00
|
|
|
# const: <string | int>
|
2019-08-29 22:21:33 +02:00
|
|
|
# default: <default>
|
2019-02-14 04:32:39 +01:00
|
|
|
#
|
scripts: dts: Generalize handling of phandle-array types
Generating generic information for 'type: phandle-array' properties in
edtlib was difficult due to defining phandle-array as just a list of
phandles and numbers. To make sense of a phandle-array property like
'pwms', you have to know that #pwm-cells is expected to appear on
each referenced controller, and that the binding for the controller has
a #cells.
Because of this, handling of various 'type: phandle-array' properties
was previously hardcoded in edtlib and exposed through properties like
Node.pwms, instead of through the generic Node.props (though with a lot
of shared code).
In practice, it turns out that all 'type: phandle-array' properties in
Zephyr work exactly the same way: They all have names that end in -s,
the 's' is removed to derive the name of related properties, and they
all look up #cells in the binding for the controller, which gives names
to the data values.
Strengthen the definition of 'type: phandle-array' to mean a property
that works exactly like the existing phandle-array properties (which
also means requiring that the name ends in -s). This removes a ton of
hardcoding from edtlib and allows new 'type: phandle-array' properties
to be added without making any code changes.
If we ever need a property type that's a list of phandles and numbers
but that doesn't follow this scheme, then we could add a separate type
for it. We should check if the standard scheme is fine first though.
The only property type for which no information is generated is now
'compound'.
There's some inconsistency in how we generate identifiers for clocks
compared to other 'type: phandle-array' properties, so keep
special-casing them for now in gen_defines.py (see the comment in
write_clocks()).
This change also enabled a bunch of other simplifications, like reusing
the ControllerAndData class for interrupts.
Piggyback generalization of *-map properties so that they work for any
phandle-array properties. It's now possible to have things like
'io-channel-map', if you need to.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
2019-09-23 09:10:22 +02:00
|
|
|
# These types are available:
|
2019-09-09 13:13:01 +02:00
|
|
|
#
|
2020-02-09 00:47:19 +01:00
|
|
|
# - 'type: string' is for properties that are assigned a single string, like
|
|
|
|
#
|
|
|
|
# ident = "foo";
|
|
|
|
#
|
2019-10-28 16:09:04 +01:00
|
|
|
# - 'type: int' is for properties that are assigned a single 32-bit value,
|
|
|
|
# like
|
|
|
|
#
|
|
|
|
# frequency = <100>;
|
|
|
|
#
|
2020-02-09 00:47:19 +01:00
|
|
|
# - 'type: boolean' is for properties used as flags that don't take a value,
|
|
|
|
# like
|
|
|
|
#
|
|
|
|
# hw-flow-control;
|
|
|
|
#
|
|
|
|
# The macro generated for the property gets set to 1 if the property exists
|
|
|
|
# on the node, and to 0 otherwise. When combined with 'required: true',
|
|
|
|
# this type just forces the flag to appear on the node. The output will
|
|
|
|
# always be 1 in that case.
|
|
|
|
#
|
|
|
|
# Warning: Since a macro is always generated for 'type: boolean'
|
|
|
|
# properties, don't use #ifdef in tests. Do this instead:
|
|
|
|
#
|
|
|
|
# #if DT_SOME_BOOLEAN_PROP == 1
|
|
|
|
#
|
2019-10-28 16:09:04 +01:00
|
|
|
# - 'type: array' is for properties that are assigned zero or more 32-bit
|
|
|
|
# values, like
|
|
|
|
#
|
|
|
|
# pin-config = <1 2 3>;
|
|
|
|
#
|
|
|
|
# - 'type: uint8-array' is for properties that are assigned zero or more
|
|
|
|
# bytes with the [] syntax, like
|
|
|
|
#
|
|
|
|
# lookup-table = [89 AB CD EF];
|
|
|
|
#
|
|
|
|
# Each byte is given in hex.
|
2019-07-08 13:16:33 +02:00
|
|
|
#
|
2019-10-28 16:09:04 +01:00
|
|
|
# This type is called 'bytestring' in the Devicetree specification.
|
|
|
|
#
|
|
|
|
# - 'type: string-array' if for properties that are assigned zero or more
|
|
|
|
# strings, like
|
|
|
|
#
|
|
|
|
# idents = "foo", "bar", "baz";
|
|
|
|
#
|
scripts: dts: Generalize handling of phandle-array types
Generating generic information for 'type: phandle-array' properties in
edtlib was difficult due to defining phandle-array as just a list of
phandles and numbers. To make sense of a phandle-array property like
'pwms', you have to know that #pwm-cells is expected to appear on
each referenced controller, and that the binding for the controller has
a #cells.
Because of this, handling of various 'type: phandle-array' properties
was previously hardcoded in edtlib and exposed through properties like
Node.pwms, instead of through the generic Node.props (though with a lot
of shared code).
In practice, it turns out that all 'type: phandle-array' properties in
Zephyr work exactly the same way: They all have names that end in -s,
the 's' is removed to derive the name of related properties, and they
all look up #cells in the binding for the controller, which gives names
to the data values.
Strengthen the definition of 'type: phandle-array' to mean a property
that works exactly like the existing phandle-array properties (which
also means requiring that the name ends in -s). This removes a ton of
hardcoding from edtlib and allows new 'type: phandle-array' properties
to be added without making any code changes.
If we ever need a property type that's a list of phandles and numbers
but that doesn't follow this scheme, then we could add a separate type
for it. We should check if the standard scheme is fine first though.
The only property type for which no information is generated is now
'compound'.
There's some inconsistency in how we generate identifiers for clocks
compared to other 'type: phandle-array' properties, so keep
special-casing them for now in gen_defines.py (see the comment in
write_clocks()).
This change also enabled a bunch of other simplifications, like reusing
the ControllerAndData class for interrupts.
Piggyback generalization of *-map properties so that they work for any
phandle-array properties. It's now possible to have things like
'io-channel-map', if you need to.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
2019-09-23 09:10:22 +02:00
|
|
|
# - 'type: phandle' is for properties that are assigned a single phandle,
|
2019-10-28 16:09:04 +01:00
|
|
|
# like
|
2019-08-13 11:52:10 +02:00
|
|
|
#
|
2019-10-28 16:09:04 +01:00
|
|
|
# foo = <&label>;
|
2019-08-13 11:52:10 +02:00
|
|
|
#
|
2019-10-28 16:09:04 +01:00
|
|
|
# - 'type: phandles' is for properties that are assigned zero or more
|
|
|
|
# phandles, like
|
2019-08-13 11:52:10 +02:00
|
|
|
#
|
2019-10-28 16:09:04 +01:00
|
|
|
# foo = <&label1 &label2 ...>;
|
2019-08-13 11:52:10 +02:00
|
|
|
#
|
scripts: dts: Generalize handling of phandle-array types
Generating generic information for 'type: phandle-array' properties in
edtlib was difficult due to defining phandle-array as just a list of
phandles and numbers. To make sense of a phandle-array property like
'pwms', you have to know that #pwm-cells is expected to appear on
each referenced controller, and that the binding for the controller has
a #cells.
Because of this, handling of various 'type: phandle-array' properties
was previously hardcoded in edtlib and exposed through properties like
Node.pwms, instead of through the generic Node.props (though with a lot
of shared code).
In practice, it turns out that all 'type: phandle-array' properties in
Zephyr work exactly the same way: They all have names that end in -s,
the 's' is removed to derive the name of related properties, and they
all look up #cells in the binding for the controller, which gives names
to the data values.
Strengthen the definition of 'type: phandle-array' to mean a property
that works exactly like the existing phandle-array properties (which
also means requiring that the name ends in -s). This removes a ton of
hardcoding from edtlib and allows new 'type: phandle-array' properties
to be added without making any code changes.
If we ever need a property type that's a list of phandles and numbers
but that doesn't follow this scheme, then we could add a separate type
for it. We should check if the standard scheme is fine first though.
The only property type for which no information is generated is now
'compound'.
There's some inconsistency in how we generate identifiers for clocks
compared to other 'type: phandle-array' properties, so keep
special-casing them for now in gen_defines.py (see the comment in
write_clocks()).
This change also enabled a bunch of other simplifications, like reusing
the ControllerAndData class for interrupts.
Piggyback generalization of *-map properties so that they work for any
phandle-array properties. It's now possible to have things like
'io-channel-map', if you need to.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
2019-09-23 09:10:22 +02:00
|
|
|
# - 'type: phandle-array' is for properties that take a list of phandles and
|
2019-10-28 16:09:04 +01:00
|
|
|
# (possibly) 32-bit numbers, like
|
scripts: dts: Generalize handling of phandle-array types
Generating generic information for 'type: phandle-array' properties in
edtlib was difficult due to defining phandle-array as just a list of
phandles and numbers. To make sense of a phandle-array property like
'pwms', you have to know that #pwm-cells is expected to appear on
each referenced controller, and that the binding for the controller has
a #cells.
Because of this, handling of various 'type: phandle-array' properties
was previously hardcoded in edtlib and exposed through properties like
Node.pwms, instead of through the generic Node.props (though with a lot
of shared code).
In practice, it turns out that all 'type: phandle-array' properties in
Zephyr work exactly the same way: They all have names that end in -s,
the 's' is removed to derive the name of related properties, and they
all look up #cells in the binding for the controller, which gives names
to the data values.
Strengthen the definition of 'type: phandle-array' to mean a property
that works exactly like the existing phandle-array properties (which
also means requiring that the name ends in -s). This removes a ton of
hardcoding from edtlib and allows new 'type: phandle-array' properties
to be added without making any code changes.
If we ever need a property type that's a list of phandles and numbers
but that doesn't follow this scheme, then we could add a separate type
for it. We should check if the standard scheme is fine first though.
The only property type for which no information is generated is now
'compound'.
There's some inconsistency in how we generate identifiers for clocks
compared to other 'type: phandle-array' properties, so keep
special-casing them for now in gen_defines.py (see the comment in
write_clocks()).
This change also enabled a bunch of other simplifications, like reusing
the ControllerAndData class for interrupts.
Piggyback generalization of *-map properties so that they work for any
phandle-array properties. It's now possible to have things like
'io-channel-map', if you need to.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
2019-09-23 09:10:22 +02:00
|
|
|
#
|
2019-10-28 16:09:04 +01:00
|
|
|
# pwms = <&ctrl-1 1 2 &ctrl-2 3 4>;
|
scripts: dts: Generalize handling of phandle-array types
Generating generic information for 'type: phandle-array' properties in
edtlib was difficult due to defining phandle-array as just a list of
phandles and numbers. To make sense of a phandle-array property like
'pwms', you have to know that #pwm-cells is expected to appear on
each referenced controller, and that the binding for the controller has
a #cells.
Because of this, handling of various 'type: phandle-array' properties
was previously hardcoded in edtlib and exposed through properties like
Node.pwms, instead of through the generic Node.props (though with a lot
of shared code).
In practice, it turns out that all 'type: phandle-array' properties in
Zephyr work exactly the same way: They all have names that end in -s,
the 's' is removed to derive the name of related properties, and they
all look up #cells in the binding for the controller, which gives names
to the data values.
Strengthen the definition of 'type: phandle-array' to mean a property
that works exactly like the existing phandle-array properties (which
also means requiring that the name ends in -s). This removes a ton of
hardcoding from edtlib and allows new 'type: phandle-array' properties
to be added without making any code changes.
If we ever need a property type that's a list of phandles and numbers
but that doesn't follow this scheme, then we could add a separate type
for it. We should check if the standard scheme is fine first though.
The only property type for which no information is generated is now
'compound'.
There's some inconsistency in how we generate identifiers for clocks
compared to other 'type: phandle-array' properties, so keep
special-casing them for now in gen_defines.py (see the comment in
write_clocks()).
This change also enabled a bunch of other simplifications, like reusing
the ControllerAndData class for interrupts.
Piggyback generalization of *-map properties so that they work for any
phandle-array properties. It's now possible to have things like
'io-channel-map', if you need to.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
2019-09-23 09:10:22 +02:00
|
|
|
#
|
|
|
|
# This type requires that the property works in the standard way that
|
|
|
|
# devicetree properties like pwms, clocks, *-gpios, and io-channels work.
|
|
|
|
# Taking 'pwms' as an example, the final -s is stripped from the property
|
|
|
|
# name, and #pwm-cells is looked up in the node for the controller
|
|
|
|
# (&ctrl-1/&ctrl-2) to determine the number of data values after the
|
2019-09-26 20:34:13 +02:00
|
|
|
# phandle. The binding for each controller must also have a *-cells key
|
|
|
|
# (e.g. pwm-cells), giving names to data values. See below for an
|
|
|
|
# explanation of *-cells.
|
scripts: dts: Generalize handling of phandle-array types
Generating generic information for 'type: phandle-array' properties in
edtlib was difficult due to defining phandle-array as just a list of
phandles and numbers. To make sense of a phandle-array property like
'pwms', you have to know that #pwm-cells is expected to appear on
each referenced controller, and that the binding for the controller has
a #cells.
Because of this, handling of various 'type: phandle-array' properties
was previously hardcoded in edtlib and exposed through properties like
Node.pwms, instead of through the generic Node.props (though with a lot
of shared code).
In practice, it turns out that all 'type: phandle-array' properties in
Zephyr work exactly the same way: They all have names that end in -s,
the 's' is removed to derive the name of related properties, and they
all look up #cells in the binding for the controller, which gives names
to the data values.
Strengthen the definition of 'type: phandle-array' to mean a property
that works exactly like the existing phandle-array properties (which
also means requiring that the name ends in -s). This removes a ton of
hardcoding from edtlib and allows new 'type: phandle-array' properties
to be added without making any code changes.
If we ever need a property type that's a list of phandles and numbers
but that doesn't follow this scheme, then we could add a separate type
for it. We should check if the standard scheme is fine first though.
The only property type for which no information is generated is now
'compound'.
There's some inconsistency in how we generate identifiers for clocks
compared to other 'type: phandle-array' properties, so keep
special-casing them for now in gen_defines.py (see the comment in
write_clocks()).
This change also enabled a bunch of other simplifications, like reusing
the ControllerAndData class for interrupts.
Piggyback generalization of *-map properties so that they work for any
phandle-array properties. It's now possible to have things like
'io-channel-map', if you need to.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
2019-09-23 09:10:22 +02:00
|
|
|
#
|
|
|
|
# A *-names (e.g. pwm-names) property can appear on the node as well,
|
|
|
|
# giving a name to each entry (the 'pwms' example above has two entries,
|
|
|
|
# <&ctrl-1 1 2> and <&ctrl-2 3 4>).
|
|
|
|
#
|
|
|
|
# Because other property names are derived from the name of the property by
|
|
|
|
# removing the final -s, the property name must end in -s. An error is
|
|
|
|
# raised if it doesn't.
|
|
|
|
#
|
|
|
|
# *-gpios properties are special-cased so that e.g. foo-gpios resolves to
|
|
|
|
# #gpio-cells rather than #foo-gpio-cells.
|
|
|
|
#
|
|
|
|
# All phandle-array properties support mapping through *-map properties,
|
|
|
|
# e.g. gpio-map. See the devicetree spec.
|
|
|
|
#
|
2019-12-30 22:52:11 +01:00
|
|
|
# - 'type: path' is for properties that are assigned a path. Usually, this
|
|
|
|
# would be done with a path reference:
|
|
|
|
#
|
|
|
|
# foo = &label;
|
|
|
|
#
|
|
|
|
# Plain strings are accepted too, and are verified to be a path to an
|
|
|
|
# existing node:
|
|
|
|
#
|
|
|
|
# foo = "/path/to/some/node";
|
|
|
|
#
|
scripts: dts: Generalize handling of phandle-array types
Generating generic information for 'type: phandle-array' properties in
edtlib was difficult due to defining phandle-array as just a list of
phandles and numbers. To make sense of a phandle-array property like
'pwms', you have to know that #pwm-cells is expected to appear on
each referenced controller, and that the binding for the controller has
a #cells.
Because of this, handling of various 'type: phandle-array' properties
was previously hardcoded in edtlib and exposed through properties like
Node.pwms, instead of through the generic Node.props (though with a lot
of shared code).
In practice, it turns out that all 'type: phandle-array' properties in
Zephyr work exactly the same way: They all have names that end in -s,
the 's' is removed to derive the name of related properties, and they
all look up #cells in the binding for the controller, which gives names
to the data values.
Strengthen the definition of 'type: phandle-array' to mean a property
that works exactly like the existing phandle-array properties (which
also means requiring that the name ends in -s). This removes a ton of
hardcoding from edtlib and allows new 'type: phandle-array' properties
to be added without making any code changes.
If we ever need a property type that's a list of phandles and numbers
but that doesn't follow this scheme, then we could add a separate type
for it. We should check if the standard scheme is fine first though.
The only property type for which no information is generated is now
'compound'.
There's some inconsistency in how we generate identifiers for clocks
compared to other 'type: phandle-array' properties, so keep
special-casing them for now in gen_defines.py (see the comment in
write_clocks()).
This change also enabled a bunch of other simplifications, like reusing
the ControllerAndData class for interrupts.
Piggyback generalization of *-map properties so that they work for any
phandle-array properties. It's now possible to have things like
'io-channel-map', if you need to.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
2019-09-23 09:10:22 +02:00
|
|
|
# - 'type: compound' is a catch-all for more complex types, e.g.
|
|
|
|
#
|
2019-12-30 22:52:11 +01:00
|
|
|
# foo = <&label>, [01 02];
|
2019-08-13 11:52:10 +02:00
|
|
|
#
|
|
|
|
# 'type: array' and the other array types also allow splitting the value into
|
|
|
|
# several <> blocks, e.g. like this:
|
|
|
|
#
|
2019-10-28 16:09:04 +01:00
|
|
|
# foo = <1 2>, <3 4>; // Okay for 'type: array'
|
|
|
|
# foo = <&label1 &label2>, <&label3 &label4>; // Okay for 'type: phandles'
|
|
|
|
# foo = <&label1 1 2>, <&label2 3 4>; // Okay for 'type: phandle-array'
|
|
|
|
# etc.
|
2019-08-29 22:21:33 +02:00
|
|
|
#
|
|
|
|
# The optional 'default:' setting gives a value that will be used if the
|
|
|
|
# property is missing from the device tree node. If 'default: <default>' is
|
|
|
|
# given for a property <prop> and <prop> is missing, then the output will be as
|
|
|
|
# if '<prop> = <default>' had appeared (except YAML data types are used for the
|
|
|
|
# default value).
|
|
|
|
#
|
|
|
|
# Note that it only makes sense to combine 'default:' with 'required: false'.
|
|
|
|
# Combining it with 'required: true' will raise an error.
|
|
|
|
#
|
|
|
|
# See below for examples of 'default:'. Putting 'default:' on any property type
|
|
|
|
# besides those used in the examples will raise an error.
|
2019-07-26 15:53:58 +02:00
|
|
|
properties:
|
|
|
|
# Describes a property like 'current-speed = <115200>;'. We pretend that
|
2019-08-28 00:22:01 +02:00
|
|
|
# it's obligatory for the example node and set 'required: true'.
|
2019-07-26 15:53:58 +02:00
|
|
|
current-speed:
|
|
|
|
type: int
|
2019-08-28 00:22:01 +02:00
|
|
|
required: true
|
2019-07-26 15:53:58 +02:00
|
|
|
description: Initial baud rate for bar-device
|
2017-05-24 07:26:04 +02:00
|
|
|
|
2019-07-26 15:53:58 +02:00
|
|
|
# Describes an optional property like 'keys = "foo", "bar";'
|
|
|
|
keys:
|
|
|
|
type: string-array
|
2019-08-28 00:22:01 +02:00
|
|
|
required: false
|
2019-07-26 15:53:58 +02:00
|
|
|
description: Keys for bar-device
|
2017-05-24 07:26:04 +02:00
|
|
|
|
2019-08-10 14:44:31 +02:00
|
|
|
# Describes an optional property like 'maximum-speed = "full-speed";
|
|
|
|
# the enum specifies known values that the string property may take
|
|
|
|
maximum-speed:
|
dts: edtlib: Sanity-check the final merged binding only
Sanity-checking each !included file separately was inherited from the
old scripts. It makes it messy to check that combinations of fields make
sense, e.g. to check 'const:' or 'default:' against 'type:', since those
fields might come from different files (this is handy, since it makes
sense to just add/change a 'const:' value, for example).
Drop the requirement that each !included file is a complete binding in
itself, and treat them as binding fragments instead. Only check the
final merged binding.
This also means that !included files no longer need to have a
'description:' or 'title:' (those have always been unused for !included
files), so remove those, and add comments that explain what the
fragments are for instead. That should demystify bindings a bit.
Also fix the descriptions of i2c.yaml, i2s.yaml, spi.yaml, and
uart.yaml. They're for controllers, not devices. These are copy-paste
error from the corresponding device .yaml files.
Piggyback some indentation consistency nits in binding-template.yaml.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
2019-08-15 14:06:15 +02:00
|
|
|
type: string
|
2019-08-28 00:22:01 +02:00
|
|
|
required: false
|
dts: edtlib: Sanity-check the final merged binding only
Sanity-checking each !included file separately was inherited from the
old scripts. It makes it messy to check that combinations of fields make
sense, e.g. to check 'const:' or 'default:' against 'type:', since those
fields might come from different files (this is handy, since it makes
sense to just add/change a 'const:' value, for example).
Drop the requirement that each !included file is a complete binding in
itself, and treat them as binding fragments instead. Only check the
final merged binding.
This also means that !included files no longer need to have a
'description:' or 'title:' (those have always been unused for !included
files), so remove those, and add comments that explain what the
fragments are for instead. That should demystify bindings a bit.
Also fix the descriptions of i2c.yaml, i2s.yaml, spi.yaml, and
uart.yaml. They're for controllers, not devices. These are copy-paste
error from the corresponding device .yaml files.
Piggyback some indentation consistency nits in binding-template.yaml.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
2019-08-15 14:06:15 +02:00
|
|
|
description: Configures USB controllers to work up to a specific speed.
|
|
|
|
enum:
|
|
|
|
- "low-speed"
|
|
|
|
- "full-speed"
|
|
|
|
- "high-speed"
|
|
|
|
- "super-speed"
|
2019-08-10 14:44:31 +02:00
|
|
|
|
2019-08-09 23:03:46 +02:00
|
|
|
# Describes a required property '#address-cells = <1>'; the const
|
|
|
|
# specifies that the value for the property is expected to be the value 1
|
|
|
|
"#address-cells":
|
dts: edtlib: Sanity-check the final merged binding only
Sanity-checking each !included file separately was inherited from the
old scripts. It makes it messy to check that combinations of fields make
sense, e.g. to check 'const:' or 'default:' against 'type:', since those
fields might come from different files (this is handy, since it makes
sense to just add/change a 'const:' value, for example).
Drop the requirement that each !included file is a complete binding in
itself, and treat them as binding fragments instead. Only check the
final merged binding.
This also means that !included files no longer need to have a
'description:' or 'title:' (those have always been unused for !included
files), so remove those, and add comments that explain what the
fragments are for instead. That should demystify bindings a bit.
Also fix the descriptions of i2c.yaml, i2s.yaml, spi.yaml, and
uart.yaml. They're for controllers, not devices. These are copy-paste
error from the corresponding device .yaml files.
Piggyback some indentation consistency nits in binding-template.yaml.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
2019-08-15 14:06:15 +02:00
|
|
|
type: int
|
2019-08-28 00:22:01 +02:00
|
|
|
required: true
|
dts: edtlib: Sanity-check the final merged binding only
Sanity-checking each !included file separately was inherited from the
old scripts. It makes it messy to check that combinations of fields make
sense, e.g. to check 'const:' or 'default:' against 'type:', since those
fields might come from different files (this is handy, since it makes
sense to just add/change a 'const:' value, for example).
Drop the requirement that each !included file is a complete binding in
itself, and treat them as binding fragments instead. Only check the
final merged binding.
This also means that !included files no longer need to have a
'description:' or 'title:' (those have always been unused for !included
files), so remove those, and add comments that explain what the
fragments are for instead. That should demystify bindings a bit.
Also fix the descriptions of i2c.yaml, i2s.yaml, spi.yaml, and
uart.yaml. They're for controllers, not devices. These are copy-paste
error from the corresponding device .yaml files.
Piggyback some indentation consistency nits in binding-template.yaml.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
2019-08-15 14:06:15 +02:00
|
|
|
const: 1
|
2019-08-09 23:03:46 +02:00
|
|
|
|
2019-08-29 22:21:33 +02:00
|
|
|
int-with-default:
|
|
|
|
type: int
|
|
|
|
required: false
|
|
|
|
default: 123
|
|
|
|
|
|
|
|
array-with-default:
|
|
|
|
type: array
|
|
|
|
required: false
|
|
|
|
default: [1, 2, 3] # Same as 'array-with-default = <1 2 3>'
|
|
|
|
|
|
|
|
string-with-default:
|
|
|
|
type: string
|
|
|
|
required: false
|
|
|
|
default: "foo"
|
|
|
|
|
|
|
|
string-array-with-default:
|
|
|
|
type: string-array
|
|
|
|
required: false
|
|
|
|
default: ["foo", "bar"] # Same as 'string-array-with-default = "foo", "bar"'
|
|
|
|
|
|
|
|
uint8-array-with-default:
|
|
|
|
type: uint8-array
|
|
|
|
required: false
|
|
|
|
default: [0x12, 0x34] # Same as 'uint8-array-with-default = [12 34]'
|
|
|
|
|
2019-09-17 18:24:30 +02:00
|
|
|
# 'child-binding' can be used when a node has children that all share the same
|
|
|
|
# properties. Each child gets the contents of 'child-binding' as its binding
|
|
|
|
# (though an explicit 'compatible = ...' on the child node takes precedence, if
|
|
|
|
# a binding is found for it).
|
|
|
|
#
|
|
|
|
# The example below is for a binding for PWM LEDs, where the child nodes are
|
|
|
|
# required to have a 'pwms' property. It corresponds to this .dts structure
|
|
|
|
# (assuming the binding has 'compatible: "pwm-leds"'):
|
|
|
|
#
|
|
|
|
# pwmleds {
|
|
|
|
# compatible = "pwm-leds";
|
|
|
|
#
|
|
|
|
# red_pwm_led {
|
|
|
|
# pwms = <&pwm3 4 15625000>;
|
|
|
|
# };
|
|
|
|
# green_pwm_led {
|
|
|
|
# pwms = <&pwm3 0 15625000>;
|
|
|
|
# };
|
|
|
|
# ...
|
|
|
|
# };
|
|
|
|
child-binding:
|
|
|
|
description: LED that uses PWM
|
|
|
|
|
|
|
|
properties:
|
|
|
|
pwms:
|
|
|
|
type: phandle-array
|
|
|
|
required: true
|
|
|
|
|
|
|
|
# 'child-binding' also works recursively. For example, the binding below would
|
|
|
|
# provide a binding for the 'grandchild' node in this .dts (assuming
|
|
|
|
# 'compatible: "foo"'):
|
|
|
|
#
|
|
|
|
# parent {
|
|
|
|
# compatible = "foo";
|
|
|
|
# child {
|
|
|
|
# grandchild {
|
|
|
|
# prop = <123>;
|
|
|
|
# };
|
|
|
|
# };
|
|
|
|
# }
|
|
|
|
child-binding:
|
|
|
|
description: ...
|
|
|
|
|
|
|
|
...
|
|
|
|
|
|
|
|
child-binding:
|
|
|
|
description: ...
|
|
|
|
|
|
|
|
properties:
|
|
|
|
prop:
|
|
|
|
type: int
|
|
|
|
required: true
|
|
|
|
|
2019-07-09 22:51:12 +02:00
|
|
|
# If the binding describes an interrupt controller, GPIO controller, pinmux
|
scripts: dts: Generalize handling of phandle-array types
Generating generic information for 'type: phandle-array' properties in
edtlib was difficult due to defining phandle-array as just a list of
phandles and numbers. To make sense of a phandle-array property like
'pwms', you have to know that #pwm-cells is expected to appear on
each referenced controller, and that the binding for the controller has
a #cells.
Because of this, handling of various 'type: phandle-array' properties
was previously hardcoded in edtlib and exposed through properties like
Node.pwms, instead of through the generic Node.props (though with a lot
of shared code).
In practice, it turns out that all 'type: phandle-array' properties in
Zephyr work exactly the same way: They all have names that end in -s,
the 's' is removed to derive the name of related properties, and they
all look up #cells in the binding for the controller, which gives names
to the data values.
Strengthen the definition of 'type: phandle-array' to mean a property
that works exactly like the existing phandle-array properties (which
also means requiring that the name ends in -s). This removes a ton of
hardcoding from edtlib and allows new 'type: phandle-array' properties
to be added without making any code changes.
If we ever need a property type that's a list of phandles and numbers
but that doesn't follow this scheme, then we could add a separate type
for it. We should check if the standard scheme is fine first though.
The only property type for which no information is generated is now
'compound'.
There's some inconsistency in how we generate identifiers for clocks
compared to other 'type: phandle-array' properties, so keep
special-casing them for now in gen_defines.py (see the comment in
write_clocks()).
This change also enabled a bunch of other simplifications, like reusing
the ControllerAndData class for interrupts.
Piggyback generalization of *-map properties so that they work for any
phandle-array properties. It's now possible to have things like
'io-channel-map', if you need to.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
2019-09-23 09:10:22 +02:00
|
|
|
# device, or any other node referenced by other nodes via 'phandle-array'
|
2019-09-26 20:34:13 +02:00
|
|
|
# properties, then *-cells should be given.
|
2019-08-19 20:32:25 +02:00
|
|
|
#
|
2019-09-26 20:34:13 +02:00
|
|
|
# To understand the purpose of *-cells, assume that some node has
|
2019-08-19 20:32:25 +02:00
|
|
|
#
|
2019-09-26 20:34:13 +02:00
|
|
|
# pwms = <&pwm-ctrl 1 2>;
|
2019-08-19 20:32:25 +02:00
|
|
|
#
|
2019-09-26 20:34:13 +02:00
|
|
|
# , where &pwm-ctrl refers to a node whose binding is this file.
|
2019-08-19 20:32:25 +02:00
|
|
|
#
|
|
|
|
# The <1 2> part of the property value is called a *specifier* (this
|
|
|
|
# terminology is from the devicetree specification), and contains additional
|
|
|
|
# data associated with the GPIO. Here, the specifier has two cells, and the
|
2019-09-26 20:34:13 +02:00
|
|
|
# node pointed at by &gpio-ctrl is expected to have '#pwm-cells = <2>'.
|
2019-08-19 20:32:25 +02:00
|
|
|
#
|
2019-09-26 20:34:13 +02:00
|
|
|
# *-cells gives a name to each cell in the specifier. These names are used when
|
|
|
|
# generating identifiers.
|
2019-08-19 20:32:25 +02:00
|
|
|
#
|
|
|
|
# In this example, assume that 1 refers to a pin and that 2 is a flag value.
|
2019-09-26 20:34:13 +02:00
|
|
|
# This gives a *-cells assignment like below.
|
|
|
|
pwm-cells:
|
|
|
|
- channel # name of first cell
|
|
|
|
- period # name of second cell
|
|
|
|
|
|
|
|
# If the specifier is empty (e.g. '#clock-cells = <0>'), then *-cells can
|
|
|
|
# either be omitted (recommended) or set to an empty array. Note that an empty
|
|
|
|
# array is specified as e.g. 'clock-cells: []' in YAML.
|
2019-08-19 20:32:25 +02:00
|
|
|
|
2019-09-26 20:34:13 +02:00
|
|
|
# As a special case, all *-gpio properties map to the key 'gpio-cells',
|
|
|
|
# regardless of prefix
|
|
|
|
gpio-cells:
|
|
|
|
- pin
|
|
|
|
- flags
|