doc: dts: add design goals defining the scope of DT
Add a page describing the high-level design goals for how Zephyr should use DT, with examples and counter-examples from current practice. Add a TBD section for code generation. It's not clear (to me at least) where the discussion on that has landed. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This commit is contained in:
parent
a20241540b
commit
3a2417443f
4 changed files with 97 additions and 0 deletions
92
doc/guides/dts/design.rst
Normal file
92
doc/guides/dts/design.rst
Normal file
|
@ -0,0 +1,92 @@
|
|||
.. _dt-design:
|
||||
|
||||
Design goals
|
||||
############
|
||||
|
||||
Zephyr's use of devicetree has evolved significantly over time, and further
|
||||
changes are expected. The following are the general design goals, along with
|
||||
specific examples about how they impact Zephyr's source code, and areas where
|
||||
more work remains to be done.
|
||||
|
||||
Single source for all hardware information
|
||||
******************************************
|
||||
|
||||
Zephyr shall obtain its hardware descriptions exclusively from devicetree.
|
||||
|
||||
Examples
|
||||
========
|
||||
|
||||
- New device drivers shall use :ref:`existence macros <dt-existence-macros>` to
|
||||
determine whether a device is available and enabled.
|
||||
|
||||
- In-tree sample applications shall use :ref:`aliases <dt-alias-chosen>` to
|
||||
determine which of multiple possible generic devices of a given type will be
|
||||
used in the current build. For example, the :ref:`blinky-sample` uses this to
|
||||
determine the LED to blink.
|
||||
|
||||
Example remaining work
|
||||
======================
|
||||
|
||||
- Zephyr's :ref:`sanitycheck_script` currently uses :file:`board.yaml` files to
|
||||
determine the hardware supported by a board. This should be obtained from
|
||||
devicetree instead.
|
||||
|
||||
- Various device drivers currently use Kconfig to determine which instances of a
|
||||
particular compatible are enabled. This can and should be done with devicetree
|
||||
overlays instead.
|
||||
|
||||
- Board-level documentation still contains tables of hardware support which are
|
||||
generated and maintained by hand. This can and should be obtained from the
|
||||
board level devicetree instead.
|
||||
|
||||
- Runtime determination of ``struct device`` relationships should be done using
|
||||
information obtained from devicetree, e.g. for device power management.
|
||||
|
||||
- Pin muxing and pin control, at least at boot time, should be accomplished via
|
||||
devicetree.
|
||||
|
||||
Source compatibility with other operating systems
|
||||
*************************************************
|
||||
|
||||
Zephyr's devicetree tooling is based on a generic layer which is interoperable
|
||||
with other devicetree users, such as the Linux kernel.
|
||||
|
||||
Zephyr's binding language *semantics* can support Zephyr-specific attributes,
|
||||
but shall not express Zephyr-specific relationships.
|
||||
|
||||
Examples
|
||||
========
|
||||
|
||||
- Zephyr's devicetree source parser, :ref:`dtlib.py <dt-scripts>`, is
|
||||
source-compatible with other tools like `dtc`_ in both directions:
|
||||
:file:`dtlib.py` can parse ``dtc`` output, and ``dtc`` can parse
|
||||
:file:`dtlib.py` output.
|
||||
|
||||
- Zephyr's "extended dtlib" library, :file:`edtlib.py`, shall not include
|
||||
Zephyr-specific features. Its purpose is to provide a higher-level view of the
|
||||
devicetree for common elements like interrupts and buses.
|
||||
|
||||
Only the high-level :file:`gen_defines.py` script, which is built on top of
|
||||
:file:`edtlib.py`, contains Zephyr-specific knowledge and features.
|
||||
|
||||
.. _dtc: https://git.kernel.org/pub/scm/utils/dtc/dtc.git/about/
|
||||
|
||||
Example remaining work
|
||||
======================
|
||||
|
||||
- Zephyr has a custom :ref:`dt-bindings` language *syntax*. While Linux's
|
||||
dtschema does not yet meet Zephyr's needs, we should try to follow what it is
|
||||
capable of representing in Zephyr's own bindings.
|
||||
|
||||
- Due to namespace collisions and inflexibility in the bindings language,
|
||||
Zephyr-specific :ref:`dt-macros` do not support the full set of possible node
|
||||
paths and bindings supported by Linux.
|
||||
|
||||
- Devicetree source sharing between Zephyr and Linux is not done.
|
||||
|
||||
To be determined
|
||||
****************
|
||||
|
||||
The scope and amount of code generation for device instantiation has been the
|
||||
subject of extended discussion and prototyping without reaching a firm
|
||||
conclusion.
|
|
@ -15,6 +15,7 @@ configuration.
|
|||
:maxdepth: 2
|
||||
|
||||
intro.rst
|
||||
design.rst
|
||||
bindings.rst
|
||||
macros.rst
|
||||
howtos.rst
|
||||
|
|
|
@ -268,6 +268,8 @@ build/zephyr/zephyr.dts
|
|||
The final merged devicetree. This file is specifically output as a
|
||||
debugging aid, and is unused otherwise.
|
||||
|
||||
.. _dt-scripts:
|
||||
|
||||
The following libraries and scripts, located in :zephyr_file:`scripts/dts/`,
|
||||
are used to generate C headers from the devicetree and its bindings. Note that
|
||||
the source code has extensive comments and documentation.
|
||||
|
|
|
@ -570,6 +570,8 @@ will get generated for ``spi-slave@0``:
|
|||
#define DT_<node>_CS_GPIOS_CONTROLLER "GPIOA"
|
||||
#define DT_<node>_CS_GPIOS_PIN 1
|
||||
|
||||
.. _dt-existence-macros:
|
||||
|
||||
Compatible-string and node existence macros
|
||||
*******************************************
|
||||
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue