doc: build: dts: Remove refs to label property
Removes references to the label property in devicetree, replacing them with node label where appropriate. Signed-off-by: Kevin Townsend <kevin.townsend@linaro.org>
This commit is contained in:
Kevin Townsend
Kumar Gala
parent
8588fdc7b3
commit
0e560bf8e9
5 changed files with 28 additions and 156 deletions
7
doc/build/dts/bindings.rst
vendored
7
doc/build/dts/bindings.rst
vendored
|
|
@ -298,10 +298,6 @@ For example, a binding for a UART peripheral might look something like this:
|
|||
type: int
|
||||
description: current baud rate
|
||||
required: true
|
||||
label:
|
||||
type: string
|
||||
description: human-readable name
|
||||
required: false
|
||||
|
||||
The properties in the following node would be validated by the above binding:
|
||||
|
||||
|
|
@ -311,7 +307,6 @@ The properties in the following node would be validated by the above binding:
|
|||
compatible = "manufacturer,serial";
|
||||
reg = <0xdeadbeef 0x1000>;
|
||||
current-speed = <115200>;
|
||||
label = "UART_0";
|
||||
};
|
||||
|
||||
This is used to check that required properties appear, and to control the
|
||||
|
|
@ -445,7 +440,7 @@ for more details about writing values of each type in a DTS file.
|
|||
|
||||
* - ``string``
|
||||
- exactly one string
|
||||
- ``label = "UART_0";``
|
||||
- ``status = "disabled";``
|
||||
|
||||
* - ``int``
|
||||
- exactly one 32-bit value (cell)
|
||||
|
|
|
|||
11
doc/build/dts/howtos.rst
vendored
11
doc/build/dts/howtos.rst
vendored
|
|
@ -122,21 +122,18 @@ that the device is ready to be used before passing it to any API functions.
|
|||
|
||||
In some situations the device cannot be known at build-time, e.g., if it depends
|
||||
on user input like in a shell application. In this case you can get the
|
||||
``struct device`` by combining :c:func:`DT_LABEL` with
|
||||
:c:func:`device_get_binding`:
|
||||
``struct device`` by combining :c:func:`device_get_binding` with the device
|
||||
name:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
const struct device *uart_dev = device_get_binding(DT_LABEL(MY_SERIAL));
|
||||
const char *dev_name = /* TODO: insert device name from user */;
|
||||
const struct device *uart_dev = device_get_binding(dev_name);
|
||||
|
||||
You can then use ``uart_dev`` with :ref:`uart_api` API functions like
|
||||
:c:func:`uart_configure`. Similar code will work for other device types; just
|
||||
make sure you use the correct API for the device.
|
||||
|
||||
There's no need to override the ``label`` property to something else: just make
|
||||
a node identifier and pass it to ``DT_LABEL`` to get the right string to pass
|
||||
to ``device_get_binding()``.
|
||||
|
||||
If you're having trouble, see :ref:`dt-trouble`. The first thing to check is
|
||||
that the node has ``status = "okay"``, like this:
|
||||
|
||||
|
|
|
|||
38
doc/build/dts/intro.rst
vendored
38
doc/build/dts/intro.rst
vendored
|
|
@ -69,7 +69,6 @@ Here is an example DTS file:
|
|||
a-node {
|
||||
subnode_nodelabel: a-sub-node {
|
||||
foo = <3>;
|
||||
label = "SUBNODE";
|
||||
};
|
||||
};
|
||||
};
|
||||
|
|
@ -87,8 +86,9 @@ The tree has three *nodes*:
|
|||
|
||||
Nodes can be assigned *node labels*, which are unique shorthands that can be
|
||||
used to refer to the labeled node elsewhere in the devicetree. Above,
|
||||
``a-sub-node`` has the *node label* ``subnode_nodelabel``. A node can have zero,
|
||||
one, or multiple *node labels*.
|
||||
``a-sub-node`` has the *node label* ``subnode_nodelabel``, which can be
|
||||
accessed via ``DT_NODELABEL(subnode_nodelabel)``. A node can have zero, one, or
|
||||
multiple *node labels*.
|
||||
|
||||
Devicetree nodes have *paths* identifying their locations in the tree. Like
|
||||
Unix file system paths, devicetree paths are strings separated by slashes
|
||||
|
|
@ -105,10 +105,6 @@ Node ``a-sub-node`` has a property named ``foo``, whose value is a cell with
|
|||
value 3. The size and type of ``foo``\ 's value are implied by the enclosing
|
||||
angle brackets (``<`` and ``>``) in the DTS.
|
||||
|
||||
Node ``a-sub-node`` has an additional property named ``label``, whose value is a
|
||||
string containing the value "SUBNODE". Note that the ``label`` property is
|
||||
distinct from the *node label*.
|
||||
|
||||
See :ref:`dt-writing-property-values` below for more example property values.
|
||||
|
||||
In practice, devicetree nodes usually correspond to some hardware, and the node
|
||||
|
|
@ -168,22 +164,18 @@ This is the corresponding DTS:
|
|||
soc {
|
||||
i2c@40003000 {
|
||||
compatible = "nordic,nrf-twim";
|
||||
label = "I2C_0";
|
||||
reg = <0x40003000 0x1000>;
|
||||
|
||||
apds9960@39 {
|
||||
compatible = "avago,apds9960";
|
||||
label = "APDS9960";
|
||||
reg = <0x39>;
|
||||
};
|
||||
ti_hdc@43 {
|
||||
compatible = "ti,hdc", "ti,hdc1010";
|
||||
label = "HDC1010";
|
||||
reg = <0x43>;
|
||||
};
|
||||
mma8652fc@1d {
|
||||
compatible = "nxp,fxos8700", "nxp,mma8652fc";
|
||||
label = "MMA8652FC";
|
||||
reg = <0x1d>;
|
||||
};
|
||||
};
|
||||
|
|
@ -285,20 +277,6 @@ compatible
|
|||
|
||||
Within Zephyr's bindings syntax, this property has type ``string-array``.
|
||||
|
||||
label
|
||||
The device's name according to Zephyr's :ref:`device_model_api`. The value
|
||||
can be passed to :c:func:`device_get_binding()` to retrieve the
|
||||
corresponding driver-level :ref:`struct device* <device_struct>`. This
|
||||
pointer can then be passed to the correct driver API by application code to
|
||||
interact with the device. For example, calling
|
||||
``device_get_binding("I2C_0")`` would return a pointer to a device
|
||||
structure which could be passed to :ref:`I2C API <i2c_api>` functions like
|
||||
:c:func:`i2c_transfer()`. The generated C header will also contain a macro
|
||||
which expands to this string.
|
||||
|
||||
Note that the ``label`` property is distinct from the :ref:`node
|
||||
label <dt-node-labels>`.
|
||||
|
||||
reg
|
||||
Information used to address the device. The value is specific to the device
|
||||
(i.e. is different depending on the compatible property).
|
||||
|
|
@ -350,6 +328,16 @@ interrupts
|
|||
|
||||
.. highlight:: none
|
||||
|
||||
.. note::
|
||||
|
||||
Earlier versions of Zephyr made frequent use of the ``label`` property,
|
||||
which is distinct from the standard :ref:`node label <dt-node-labels>`.
|
||||
Use of the label *property* in new devicetree bindings, as well as use of
|
||||
the :c:macro:`DT_LABEL` macro in new code, are actively discouraged. Label
|
||||
properties continue to persist for historical reasons in some existing
|
||||
bindings and overlays, but should not be used in new bindings or device
|
||||
implementations.
|
||||
|
||||
.. _dt-writing-property-values:
|
||||
|
||||
Writing property values
|
||||
|
|
|
|||
BIN
doc/build/dts/zephyr_dt_i2c_example.png
vendored
BIN
doc/build/dts/zephyr_dt_i2c_example.png
vendored
Binary file not shown.
|
Before Width: | Height: | Size: 46 KiB After Width: | Height: | Size: 39 KiB |
128
doc/build/dts/zephyr_dt_i2c_example.svg
generated
vendored
128
doc/build/dts/zephyr_dt_i2c_example.svg
generated
vendored
|
|
@ -230,42 +230,9 @@
|
|||
x="80">compatible = "nordic,nrf-twim"</text>
|
||||
</switch>
|
||||
</g>
|
||||
<g
|
||||
id="g54"
|
||||
transform="translate(272.68201,266.75)">
|
||||
<switch
|
||||
id="switch52">
|
||||
<foreignObject
|
||||
requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"
|
||||
height="12"
|
||||
width="80"
|
||||
pointer-events="all"
|
||||
style="overflow:visible;">
|
||||
<xhtml:div
|
||||
style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 22px; max-width: 350px; width: 81px; white-space: normal; overflow-wrap: normal; text-align: left;">
|
||||
<xhtml:div
|
||||
style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">
|
||||
<xhtml:div>label = "I2C_0"</xhtml:div>
|
||||
</xhtml:div>
|
||||
</xhtml:div>
|
||||
</foreignObject>
|
||||
<text
|
||||
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12px;font-family:Helvetica;-inkscape-font-specification:'Helvetica, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#000000"
|
||||
id="text50"
|
||||
font-size="12px"
|
||||
y="12"
|
||||
x="40">
|
||||
<tspan
|
||||
y="12"
|
||||
x="40"
|
||||
sodipodi:role="line"
|
||||
id="tspan289">label = "I2C_0"</tspan>
|
||||
</text>
|
||||
</switch>
|
||||
</g>
|
||||
<g
|
||||
id="g60"
|
||||
transform="translate(277.75,292.75)">
|
||||
transform="translate(272,267)">
|
||||
<switch
|
||||
id="switch58">
|
||||
<foreignObject
|
||||
|
|
@ -275,7 +242,7 @@
|
|||
pointer-events="all"
|
||||
style="overflow:visible;">
|
||||
<xhtml:div
|
||||
style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 22px; max-width: 350px; width: 145px; white-space: normal; overflow-wrap: normal; text-align: left;">
|
||||
style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 22px; max-width: 350px; width: 190px; white-space: normal; overflow-wrap: normal; text-align: left;">
|
||||
<xhtml:div
|
||||
style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">reg = <0x4003000 0x1000></xhtml:div>
|
||||
</xhtml:div>
|
||||
|
|
@ -420,7 +387,7 @@
|
|||
pointer-events="all"
|
||||
style="overflow:visible;">
|
||||
<xhtml:div
|
||||
style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 22px; max-width: 342px; width: 251px; white-space: normal; overflow-wrap: normal; text-align: left;">
|
||||
style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 22px; max-width: 342px; width: 340px; white-space: normal; overflow-wrap: normal; text-align: left;">
|
||||
<xhtml:div
|
||||
style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">compatible = "nxp,fxos8700", "nxp,mma8652fc"</xhtml:div>
|
||||
</xhtml:div>
|
||||
|
|
@ -433,34 +400,9 @@
|
|||
x="125">compatible = "nxp,fxos8700", "nxp,mma8652fc"</text>
|
||||
</switch>
|
||||
</g>
|
||||
<g
|
||||
id="g118"
|
||||
transform="translate(524.25,440.5)">
|
||||
<switch
|
||||
id="switch116">
|
||||
<foreignObject
|
||||
requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"
|
||||
height="12"
|
||||
width="118"
|
||||
pointer-events="all"
|
||||
style="overflow:visible;">
|
||||
<xhtml:div
|
||||
style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 22px; max-width: 342px; width: 119px; white-space: normal; overflow-wrap: normal; text-align: left;">
|
||||
<xhtml:div
|
||||
style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">label = "MMA8652FC"</xhtml:div>
|
||||
</xhtml:div>
|
||||
</foreignObject>
|
||||
<text
|
||||
style="font-size:12px;font-family:Helvetica;text-anchor:middle;fill:#000000"
|
||||
id="text114"
|
||||
font-size="12px"
|
||||
y="12"
|
||||
x="59">label = "MMA8652FC"</text>
|
||||
</switch>
|
||||
</g>
|
||||
<g
|
||||
id="g124"
|
||||
transform="translate(524.25,466.5)">
|
||||
transform="translate(524,440)">
|
||||
<switch
|
||||
id="switch122">
|
||||
<foreignObject
|
||||
|
|
@ -470,7 +412,7 @@
|
|||
pointer-events="all"
|
||||
style="overflow:visible;">
|
||||
<xhtml:div
|
||||
style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 22px; max-width: 342px; width: 71px; white-space: normal; overflow-wrap: normal; text-align: left;">
|
||||
style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 22px; max-width: 342px; width: 150px; white-space: normal; overflow-wrap: normal; text-align: left;">
|
||||
<xhtml:div
|
||||
style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">reg = <0x1d></xhtml:div>
|
||||
</xhtml:div>
|
||||
|
|
@ -558,34 +500,9 @@
|
|||
x="90">compatible = "ti,hdc", "ti,hdc1010"</text>
|
||||
</switch>
|
||||
</g>
|
||||
<g
|
||||
id="g148"
|
||||
transform="translate(299,658.5)">
|
||||
<switch
|
||||
id="switch146">
|
||||
<foreignObject
|
||||
requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"
|
||||
height="12"
|
||||
width="100"
|
||||
pointer-events="all"
|
||||
style="overflow:visible;">
|
||||
<xhtml:div
|
||||
style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 22px; max-width: 342px; width: 101px; white-space: normal; overflow-wrap: normal; text-align: left;">
|
||||
<xhtml:div
|
||||
style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">label = "HDC1010"</xhtml:div>
|
||||
</xhtml:div>
|
||||
</foreignObject>
|
||||
<text
|
||||
style="font-size:12px;font-family:Helvetica;text-anchor:middle;fill:#000000"
|
||||
id="text144"
|
||||
font-size="12px"
|
||||
y="12"
|
||||
x="50">label = "HDC1010"</text>
|
||||
</switch>
|
||||
</g>
|
||||
<g
|
||||
id="g154"
|
||||
transform="translate(299,684.5)">
|
||||
transform="translate(299,658)">
|
||||
<switch
|
||||
id="switch152">
|
||||
<foreignObject
|
||||
|
|
@ -595,7 +512,7 @@
|
|||
pointer-events="all"
|
||||
style="overflow:visible;">
|
||||
<xhtml:div
|
||||
style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 22px; max-width: 342px; width: 71px; white-space: normal; overflow-wrap: normal; text-align: left;">
|
||||
style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 22px; max-width: 342px; width: 150px; white-space: normal; overflow-wrap: normal; text-align: left;">
|
||||
<xhtml:div
|
||||
style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">reg = <0x43></xhtml:div>
|
||||
</xhtml:div>
|
||||
|
|
@ -673,7 +590,7 @@
|
|||
pointer-events="all"
|
||||
style="overflow:visible;">
|
||||
<xhtml:div
|
||||
style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 22px; max-width: 342px; width: 168px; white-space: normal; overflow-wrap: normal; text-align: left;">
|
||||
style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 22px; max-width: 342px; width: 250px; white-space: normal; overflow-wrap: normal; text-align: left;">
|
||||
<xhtml:div
|
||||
style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">compatible = "avago,apds9960"</xhtml:div>
|
||||
</xhtml:div>
|
||||
|
|
@ -686,34 +603,9 @@
|
|||
x="84">compatible = "avago,apds9960"</text>
|
||||
</switch>
|
||||
</g>
|
||||
<g
|
||||
id="g178"
|
||||
transform="translate(5.5,521.5)">
|
||||
<switch
|
||||
id="switch176">
|
||||
<foreignObject
|
||||
requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"
|
||||
height="12"
|
||||
width="106"
|
||||
pointer-events="all"
|
||||
style="overflow:visible;">
|
||||
<xhtml:div
|
||||
style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 22px; max-width: 342px; width: 107px; white-space: normal; overflow-wrap: normal; text-align: left;">
|
||||
<xhtml:div
|
||||
style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">label = "APDS9960"</xhtml:div>
|
||||
</xhtml:div>
|
||||
</foreignObject>
|
||||
<text
|
||||
style="font-size:12px;font-family:Helvetica;text-anchor:middle;fill:#000000"
|
||||
id="text174"
|
||||
font-size="12px"
|
||||
y="12"
|
||||
x="53">label = "APDS9960"</text>
|
||||
</switch>
|
||||
</g>
|
||||
<g
|
||||
id="g184"
|
||||
transform="translate(5.5,547.5)">
|
||||
transform="translate(5.5,522)">
|
||||
<switch
|
||||
id="switch182">
|
||||
<foreignObject
|
||||
|
|
@ -723,7 +615,7 @@
|
|||
pointer-events="all"
|
||||
style="overflow:visible;">
|
||||
<xhtml:div
|
||||
style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 22px; max-width: 342px; width: 71px; white-space: normal; overflow-wrap: normal; text-align: left;">
|
||||
style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 22px; max-width: 342px; width: 150px; white-space: normal; overflow-wrap: normal; text-align: left;">
|
||||
<xhtml:div
|
||||
style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">reg = <0x39></xhtml:div>
|
||||
</xhtml:div>
|
||||
|
|
|
|||
|
Before Width: | Height: | Size: 32 KiB After Width: | Height: | Size: 27 KiB |
Loading…
Reference in a new issue