Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: dt: Clarify the relationship between DT and Kconfig #8507

Merged
merged 1 commit into from
Jun 25, 2018
Merged

doc: dt: Clarify the relationship between DT and Kconfig #8507

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion doc/application/application.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1093,7 +1093,9 @@ Device Tree Overlays

As described in :ref:`device-tree`, Zephyr uses Device Tree to
describe the hardware it runs on. This section describes how you can
modify an application build's device tree using overlay files.
modify an application build's device tree using overlay files. For additional
information regarding the relationship between Device Tree and Kconfig see
:ref:`dt_vs_kconfig`.

Overlay files, which customarily have the :file:`.overlay` extension,
contain device tree fragments which add to or modify the device tree
Expand Down
73 changes: 63 additions & 10 deletions doc/devices/dts/device_tree.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,9 @@ Information about the system is extracted from the compiled DTS and used to
create the application image.

Device tree uses a specific format to describe the device nodes in a system.
This format is described in `EPAPR document`_.
This format is described in the `Device Tree Specification`_.

.. _EPAPR document: https://www.devicetree.org/downloads/devicetree-specification-v0.1-20160524.pdf
.. _Device Tree Specification: https://github.com/devicetree-org/devicetree-specification/releases

More device tree information can be found at the `device tree repository`_.

Expand All @@ -57,14 +57,9 @@ information is intended to augment the device tree descriptions. The main
reason for this is to leverage existing device tree files that a SoC vendor may
already have defined for a given platform.

Today, configuration in Zephyr comes from a number of different places. It can
come from Kconfig files, CMSIS header files, vendor header files, prj.conf
files, and other miscellaneous sources. The intent of using device tree is to
replace or curtail the use of Kconfig files throughout the system, and instead
use device tree files to describe the configuration of device nodes. CMSIS and
vendor header files can be used in conjunction with the device tree to fully
describe hardware. Device tree is not intended to replace CMSIS or vendor
include files.
Device Tree provides a unified description of a hardware system used in an
application. It is used in Zephyr to describe hardware and provide a boot-time
configuration of this hardware.

The device tree files are compiled using the device tree compiler. The compiler
runs the .dts file through the C preprocessor to resolve any macro or #defines
Expand All @@ -80,6 +75,64 @@ This .fixup file by default resides in the board directory and is named
dts.fixup. This fixup file maps the generated include information to the
current driver/source usage.

.. _dt_vs_kconfig:

Device Tree vs Kconfig
**********************

As mentioned above there are several tools used to configure the build with
Zephyr.
The two main ones, Device Tree and Kconfig, might seem to overlap in purpose,
but in fact they do not. This section serves as a reference to help you decide
whether to place configuration items in Device Tree or Kconfig.

The scope of each configuration tool can be summarized as follows:

* Device Tree is used to describe the **hardware** and its **boot-time
configuration**.
* Kconfig is used to describe which **software features** will be built into
the final image, and their **configuration**.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While I agree to this general stating, I think we should clarify the use of 'chosen' node:

	chosen {
		zephyr,console = &uart0;
		zephyr,uart-mcumgr = &uart0;
		zephyr,sram = &sram0;
		zephyr,flash = &flash0;
	};

Device Tree specification provides the following definition:
"3.5 /chosen Node:
The /chosen node does not represent a real device in the system but describes parameters chosen or specified by the system firmware at run time. It shall be a child of the root node."

This lis kind of SW oriented configuration.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a good point. Where do you think we should add this information? I would not want to include it in those first 2 lines, but rather add it as a precision later?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added this now a bit below

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

firmware features?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I chose to phrase this differently, see last version of the commit


Hence Device Tree deals mostly with hardware and Kconfig with software.
A couple of noteworthy exceptions are:

* Device Tree's ``chosen`` keyword, which allows the user to select a
particular instance of a hardware device to be used for a concrete purpose
by the software. An example of this is selecting a particular UART for use as
the system's console.
* Device Tree's ``status`` keyword, which allows the user to enable or disable
a particular instance of a hardware device in the Device Tree file itself.
This takes precedence over Kconfig.

To further clarify this separation, let's use a particular, well-known
example to illustrate this: serial ports a.k.a. UARTs. Let's consider a
board containing a SoC with 2 UART instances:

* The fact that the target hardware **contains** 2 UARTs is described with Device
Tree. This includes the UART type, its driver compatibility and certain
immutable (i.e. not software-configurable) settings such as the base address
of the hardware peripheral in memory or its interrupt line.
* Additionally, **hardware boot-time configuration** is also described with Device
Tree. This includes things such as the IRQ priority and boot-time UART
baudrate. These may also be modifiable at runtime later, but their boot-time
default configuration is described in Device Tree.
* The fact that the user intends to include **software support** for UART in the
build is described in Kconfig. Through the use of Kconfig, users can opt not
to include support for this particular hardware item if they don't require it.

Another example is a device with a 2.4GHz, multi-protocol radio supporting
both the Bluetooth Low Energy and 802.15.4 wireless technologies. In this case:

* Device Tree describes the presence of a radio peripheral compatible with a
certain radio driver.
* Additional hardware boot-time configuration settings may also be present
in the Device Tree files. In this particular case it could be a
default TX power in dBm if the hardware does have a simple, cross-wireless
technology register for that.
* Kconfig will describe which **protocol stack** is to be used with that radio.
The user may decide to select BLE or 802.15.4, which will both depend on
the presence of a compatible radio in the Device Tree files.

Device tree file formats
************************

Expand Down