OrgZephyr/zephyr
OrgZephyr
/
zephyr
mirror of https://github.com/zephyrproject-rtos/zephyr.git
1
0
Fork 0
Code Issues Releases Wiki Activity
zephyr/doc/guides/dts/design.rst

92 lines
3.3 KiB
ReStructuredText
Raw Normal View History

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>
2020-02-19 09:28:41 +08:00
.. _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
========
devicetree: remove DT_HAS_NODE_STATUS_OKAY Several reviewers agreed that DT_HAS_NODE_STATUS_OKAY(...) was an undesirable API for the following reasons: - it's inconsistent with the rest of the DT_NODE_HAS_FOO names - DT_NODE_HAS_FOO_BAR_BAZ(node) was agreed upon as a shorthand for macros which are equivalent to DT_NODE_HAS_FOO(node) && DT_NODE_HAS_BAR(node) && - DT_NODE_HAS_BAZ(node), and DT_HAS_NODE_STATUS_OKAY is an odd duck - DT_NODE_HAS_STATUS(..., okay) was viewed as more readable anyway - it is seen as a somewhat aesthetically challenged name Replace all users with DT_NODE_HAS_STATUS(..., okay), which is semantically equivalent. This is mostly done with sed, but a few remaining cases were done by hand, along with whitespace, docs, and comment changes. These special cases include the Nordic SOC static assert files. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
2020-05-12 02:56:08 +08:00
- New device drivers shall use devicetree APIs to determine which :ref:`devices
to create <dt-create-devices>` if possible.
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>
2020-02-19 09:28:41 +08:00
- 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
======================
doc: dts: revisit documentation This is joint work with Kumar Gala (see signed-off-by). Document the changes to the generated node macros in macros.bnf, moving the old file to legacy-macros.bnf and putting it in its own section. The actual generated macros are now a low-level detail, so rewrite the foregoing sections as examples in terms of the new <devicetree.h> APIs. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no> Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
2020-03-11 09:16:25 +08:00
- Zephyr's :ref:`sanitycheck_script` currently use :file:`board.yaml` files to
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>
2020-02-19 09:28:41 +08:00
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.
doc: dts: update guides Give the guides a once-over in preparation for the v2.3 release. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
2020-05-23 03:45:26 +08:00
- Due to inflexibility in the bindings language, Zephyr cannot support the full
set of bindings supported by Linux.
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>
2020-02-19 09:28:41 +08:00
- 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.