31a90a0e7d
Add some introductory text to these driver helpers which makes it more clear how they are defined in terms of the generic APIs, which allows removing some boilerplate from doxygen. This also gives us a chance to call out the exceptional cases and add some more documentation to those. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
327 lines
10 KiB
ReStructuredText
327 lines
10 KiB
ReStructuredText
.. _devicetree_api:
|
|
|
|
Devicetree
|
|
##########
|
|
|
|
This page contains reference documentation for ``<devicetree.h>``. See
|
|
:ref:`dt-guide` for an introduction. Use of these macros has no impact on
|
|
scheduling. They can be used from any calling context and at file scope.
|
|
|
|
Some of these require a special macro named ``DT_DRV_COMPAT`` to be defined
|
|
before they can be used; these are discussed individually below. These macros
|
|
are generally meant for use within :ref:`device drivers <device_model_api>`,
|
|
though they can be used outside of drivers with appropriate care.
|
|
|
|
.. _devicetree-generic-apis:
|
|
|
|
Generic APIs
|
|
************
|
|
|
|
The APIs in this section can be used anywhere and do not require
|
|
``DT_DRV_COMPAT`` to be defined.
|
|
|
|
Node identifiers
|
|
================
|
|
|
|
A *node identifier* is a way to refer to a devicetree node at C preprocessor
|
|
time. While node identifiers are not C values, you can use them to access
|
|
devicetree data in C rvalue form using, for example, the
|
|
:ref:`devicetree-property-access` API.
|
|
|
|
The root node ``/`` has node identifier ``DT_ROOT``. You can create node
|
|
identifiers for other devicetree nodes using :c:func:`DT_PATH`,
|
|
:c:func:`DT_NODELABEL`, :c:func:`DT_ALIAS`, and :c:func:`DT_INST`.
|
|
|
|
There are also :c:func:`DT_PARENT` and :c:func:`DT_CHILD` macros which can be
|
|
used to create node identifiers for a given node's parent node or a particular
|
|
child node, respectively.
|
|
|
|
.. doxygengroup:: devicetree-generic-id
|
|
:project: Zephyr
|
|
|
|
.. _devicetree-property-access:
|
|
|
|
Property access
|
|
===============
|
|
|
|
The following general-purpose macros can be used to access node properties.
|
|
There are special-purpose APIs for accessing the :ref:`devicetree-reg-property`
|
|
and :ref:`devicetree-interrupts-property`.
|
|
|
|
Property values can be read using these macros even if the node is disabled,
|
|
as long as it has a matching binding.
|
|
|
|
.. doxygengroup:: devicetree-generic-prop
|
|
:project: Zephyr
|
|
|
|
.. _devicetree-reg-property:
|
|
|
|
``reg`` property
|
|
================
|
|
|
|
Use these APIs instead of :ref:`devicetree-property-access` to access the
|
|
``reg`` property. Because this property's semantics are defined by the
|
|
devicetree specification, these macros can be used even for nodes without
|
|
matching bindings.
|
|
|
|
.. doxygengroup:: devicetree-reg-prop
|
|
:project: Zephyr
|
|
|
|
.. _devicetree-interrupts-property:
|
|
|
|
``interrupts`` property
|
|
=======================
|
|
|
|
Use these APIs instead of :ref:`devicetree-property-access` to access the
|
|
``interrupts`` property.
|
|
|
|
Because this property's semantics are defined by the devicetree specification,
|
|
some of these macros can be used even for nodes without matching bindings. This
|
|
does not apply to macros which take cell names as arguments.
|
|
|
|
.. doxygengroup:: devicetree-interrupts-prop
|
|
:project: Zephyr
|
|
|
|
For-each macros
|
|
===============
|
|
|
|
There is currently only one "generic" for-each macro,
|
|
:c:func:`DT_FOREACH_CHILD`, which allows iterating over the children of a
|
|
devicetree node.
|
|
|
|
There are special-purpose for-each macros, like
|
|
:c:func:`DT_INST_FOREACH_STATUS_OKAY`, but these require ``DT_DRV_COMPAT`` to
|
|
be defined before use.
|
|
|
|
.. doxygengroup:: devicetree-generic-foreach
|
|
:project: Zephyr
|
|
|
|
Existence checks
|
|
================
|
|
|
|
This section documents miscellaneous macros that can be used to test if a node
|
|
exists, how many nodes of a certain type exist, whether a node has certain
|
|
properties, etc. Some macros used for special purposes (such as
|
|
:c:func:`DT_IRQ_HAS_IDX` and all macros which require ``DT_DRV_COMPAT``) are
|
|
documented elsewhere on this page.
|
|
|
|
.. doxygengroup:: devicetree-generic-exist
|
|
:project: Zephyr
|
|
|
|
Bus helpers
|
|
===========
|
|
|
|
Zephyr's devicetree bindings language supports a ``bus:`` key which allows
|
|
bindings to declare that nodes with a given compatible describe system buses.
|
|
In this case, child nodes are considered to be on a bus of the given type, and
|
|
the following APIs may be used.
|
|
|
|
.. doxygengroup:: devicetree-generic-bus
|
|
:project: Zephyr
|
|
|
|
.. _devicetree-inst-apis:
|
|
|
|
Instance-based APIs
|
|
*******************
|
|
|
|
These are recommended for use within device drivers. To use them, define
|
|
``DT_DRV_COMPAT`` to the lowercase-and-underscores compatible the device driver
|
|
implements support for. Here is an example devicetree fragment:
|
|
|
|
.. code-block:: DTS
|
|
|
|
serial@40001000 {
|
|
compatible = "vnd,serial";
|
|
status = "okay";
|
|
current-speed = <115200>;
|
|
};
|
|
|
|
Example usage, assuming serial@40001000 is the only enabled node
|
|
with compatible "vnd,serial":
|
|
|
|
.. code-block:: c
|
|
|
|
#define DT_DRV_COMPAT vnd_serial
|
|
DT_DRV_INST(0) // node identifier for serial@40001000
|
|
DT_INST_PROP(0, current_speed) // 115200
|
|
|
|
.. warning::
|
|
|
|
Be careful making assumptions about instance numbers. See :c:func:`DT_INST`
|
|
for the API guarantees.
|
|
|
|
As shown above, the ``DT_INST_*`` APIs are conveniences for addressing nodes by
|
|
instance number. They are almost all defined in terms of one of the
|
|
:ref:`devicetree-generic-apis`. The equivalent generic API can be found by
|
|
removing ``INST_`` from the macro name. For example, ``DT_INST_PROP(inst,
|
|
prop)`` is equivalent to ``DT_PROP(DT_DRV_INST(inst), prop)``. Similarly,
|
|
``DT_INST_REG_ADDR(inst)`` is equivalent to ``DT_REG_ADDR(DT_DRV_INST(inst))``,
|
|
and so on. There are some exceptions: :c:func:`DT_ANY_INST_ON_BUS_STATUS_OKAY`
|
|
and :c:func:`DT_INST_FOREACH_STATUS_OKAY` are special-purpose helpers without
|
|
straightforward generic equivalents.
|
|
|
|
Since ``DT_DRV_INST()`` requires ``DT_DRV_COMPAT`` to be defined, it's an error
|
|
to use any of these without that macro defined.
|
|
|
|
Note that there are also helpers available for
|
|
specific hardware; these are documented in :ref:`devicetree-hw-api`.
|
|
|
|
.. doxygengroup:: devicetree-inst
|
|
:project: Zephyr
|
|
|
|
.. _devicetree-hw-api:
|
|
|
|
Hardware specific APIs
|
|
**********************
|
|
|
|
The following APIs can also be used by including ``<devicetree.h>``;
|
|
no additional include is needed.
|
|
|
|
ADC
|
|
===
|
|
|
|
These are commonly used by sensor device drivers which need to use an ADC
|
|
channel for conversion.
|
|
|
|
.. doxygengroup:: devicetree-adc
|
|
:project: Zephyr
|
|
|
|
Clocks
|
|
======
|
|
|
|
These conveniences may be used for nodes which describe clock sources, and
|
|
properties related to them.
|
|
|
|
.. doxygengroup:: devicetree-clocks
|
|
:project: Zephyr
|
|
|
|
DMA
|
|
===
|
|
|
|
These conveniences may be used for nodes which describe direct memory access
|
|
controllers or channels, and properties related to them.
|
|
|
|
.. doxygengroup:: devicetree-dmas
|
|
:project: Zephyr
|
|
|
|
.. _devicetree-flash-api:
|
|
|
|
Fixed flash partitions
|
|
======================
|
|
|
|
These conveniences may be used for the special-purpose ``fixed-partitions``
|
|
compatible used to encode information about flash memory partitions in the
|
|
device tree.
|
|
|
|
.. doxygengroup:: devicetree-fixed-partition
|
|
:project: Zephyr
|
|
|
|
.. _devicetree-gpio-api:
|
|
|
|
GPIO
|
|
====
|
|
|
|
These conveniences may be used for nodes which describe GPIO controllers/pins,
|
|
and properties related to them.
|
|
|
|
.. doxygengroup:: devicetree-gpio
|
|
:project: Zephyr
|
|
|
|
PWM
|
|
===
|
|
|
|
These conveniences may be used for nodes which describe PWM controllers and
|
|
properties related to them.
|
|
|
|
.. doxygengroup:: devicetree-pwms
|
|
:project: Zephyr
|
|
|
|
SPI
|
|
===
|
|
|
|
These conveniences may be used for nodes which describe either SPI controllers
|
|
or devices, depending on the case.
|
|
|
|
.. doxygengroup:: devicetree-spi
|
|
:project: Zephyr
|
|
|
|
.. _devicetree-chosen-nodes:
|
|
|
|
Chosen nodes
|
|
************
|
|
|
|
The special ``/chosen`` node contains properties whose values describe
|
|
system-wide settings. The :c:func:`DT_CHOSEN()` macro can be used to get a node
|
|
identifier for a chosen node.
|
|
|
|
.. doxygengroup:: devicetree-generic-chosen
|
|
:project: Zephyr
|
|
|
|
There are also conveniences for commonly used zephyr-specific properties of the
|
|
``/chosen`` node. (These may also be set in :file:`dts_fixup.h` files for now,
|
|
though this mechanism is deprecated.)
|
|
|
|
.. doxygengroup:: devicetree-zephyr
|
|
:project: Zephyr
|
|
|
|
The following table documents some commonly used Zephyr-specific chosen nodes.
|
|
|
|
Often, a chosen node's label property will be used to set the default value of
|
|
a Kconfig option which in turn configures a hardware-specific subsystem
|
|
setting. This is usually for backwards compatibility in cases when the Kconfig
|
|
option predates devicetree support in Zephyr. In other cases, there is no
|
|
Kconfig option, and the devicetree node's label property is used directly in
|
|
the source code to specify a device name.
|
|
|
|
.. Documentation maintainers: please keep this sorted by property name
|
|
|
|
.. list-table:: Zephyr-specific chosen properties
|
|
:header-rows: 1
|
|
|
|
* - Property
|
|
- Purpose
|
|
* - zephyr,bt-c2h-uart
|
|
- Sets default :option:`CONFIG_BT_CTLR_TO_HOST_UART_DEV_NAME`
|
|
* - zephyr,bt-mon-uart
|
|
- Sets default :option:`CONFIG_BT_MONITOR_ON_DEV_NAME`
|
|
* - zephyr,bt-uart
|
|
- Sets default :option:`CONFIG_BT_UART_ON_DEV_NAME`
|
|
* - zephyr,can-primary
|
|
- Sets the primary CAN controller
|
|
* - zephyr,ccm
|
|
- Core-Coupled Memory node on some STM32 SoCs
|
|
* - zephyr,code-partition
|
|
- Flash partition that the Zephyr image's text section should be linked
|
|
into
|
|
* - zephyr,console
|
|
- Sets default :option:`CONFIG_UART_CONSOLE_ON_DEV_NAME`
|
|
* - zephyr,dtcm
|
|
- Data Tightly Coupled Memory node on some Arm SoCs
|
|
* - zephyr,entropy
|
|
- A device which can be used as a system-wide entropy source
|
|
* - zephyr,flash
|
|
- A node whose ``reg`` is sometimes used to set the defaults for
|
|
:option:`CONFIG_FLASH_BASE_ADDRESS` and :option:`CONFIG_FLASH_SIZE`
|
|
* - zephyr,flash-controller
|
|
- The node corresponding to the flash controller device for
|
|
the ``zephyr,flash`` node
|
|
* - zephyr,ipc
|
|
- Used by the OpenAMP subsystem to specify the inter-process communication
|
|
(IPC) device
|
|
* - zephyr,ipc_shm
|
|
- A node whose ``reg`` is used by the OpenAMP subsystem to determine the
|
|
base address and size of the shared memory (SHM) usable for
|
|
interprocess-communication (IPC)
|
|
* - zephyr,shell-uart
|
|
- Sets default :option:`CONFIG_UART_SHELL_ON_DEV_NAME`
|
|
* - zephyr,sram
|
|
- A node whose ``reg`` sets the base address and size of SRAM memory
|
|
available to the Zephyr image, used during linking
|
|
* - zephyr,uart-mcumgr
|
|
- UART used for :ref:`device_mgmt`
|
|
* - zephyr,uart-pipe
|
|
- Sets default :option:`CONFIG_UART_PIPE_ON_DEV_NAME`
|
|
* - zephyr,usb-device
|
|
- USB device node. If defined and has a ``vbus-gpios`` property, these
|
|
will be used by the USB subsystem to enable/disable VBUS
|