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

carlescufi · 2018-06-21T10:10:45Z

Try to clarify the scope of Device Tree vs Kconfig in order to allow
Zephyr users to identify where a particular configuration option when
developing an application, board support or SoC support.

Fixes #7230

Signed-off-by: Carles Cufi [email protected]

carlescufi · 2018-06-21T10:15:01Z

cc @b0661

carlescufi · 2018-06-21T10:15:59Z

I put this together in the context of a discussion in the TSC call where we decided to track the changes required to DT and Kconfig in order to achieve better integration. See #8499 for more details.

ulfalizer

Besides the nit, looks good to me.

DTS describes stuff, Kconfig configures stuff.

ulfalizer · 2018-06-21T10:15:59Z

doc/devices/dts/device_tree.rst

+
+As mentioned above there are several tools used to configuring the build with
+Zephyr.
+The two main ones, Device Tree and Kconfig might seem to overlap in its purpose,


Remove "its".

Fixed, thank you.

SebastianBoe

This is a good description of how we are using DeviceTree and it resolves #7230.

This isn't IMHO what the relationship between DT and Kconfig 'should' be, but that is another matter :)

codecov-io · 2018-06-21T11:03:54Z

Codecov Report

Merging #8507 into master will increase coverage by <.01%.
The diff coverage is n/a.

@@            Coverage Diff            @@
##           master   #8507      +/-   ##
=========================================
+ Coverage    63.8%   63.8%   +<.01%     
=========================================
  Files         426     426              
  Lines       40890   40890              
  Branches     6921    6921              
=========================================
+ Hits        26088   26089       +1     
  Misses      11666   11666              
+ Partials     3136    3135       -1

Impacted Files	Coverage Δ
boards/posix/native_posix/timer_model.c	`95.16% <0%> (+1.61%)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7a7e4f5...d06895e. Read the comment docs.

erwango · 2018-06-21T11:08:20Z

doc/devices/dts/device_tree.rst

+* 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**.


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.

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?

I added this now a bit below

ioannisg

basically style comments, but some other content-related comments, too

ioannisg · 2018-06-21T10:56:14Z

doc/devices/dts/device_tree.rst

+replace or curtail the use of some 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 Kconfig, CMSIS


to fully replace?

well, it doesn't replace it at all. I will rephrase instead

ioannisg · 2018-06-21T10:56:42Z

doc/devices/dts/device_tree.rst

+Device Tree vs Kconfig
+**********************
+
+As mentioned above there are several tools used to configuring the build with


to configure

ioannisg · 2018-06-21T10:56:56Z

doc/devices/dts/device_tree.rst

+
+As mentioned above there are several tools used to configuring the build with
+Zephyr.
+The two main ones, Device Tree and Kconfig might seem to overlap in purpose,


ioannisg · 2018-06-21T10:57:11Z

doc/devices/dts/device_tree.rst

+As mentioned above there are several tools used to configuring 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 is intended to serve as a reference when


ioannisg · 2018-06-21T11:04:44Z

doc/devices/dts/device_tree.rst

+
+The scope of each configuration tool can be summarized as follows:
+
+* Device Tree is used to describe the **hardware** and its **boot-time


or build-time

actually, this might be a bit confusing, since Kconfig is also determining the build-time configuration.
So maybe
Device Tree is used to describe the hardware capabilities and configuration at build time.

Well actually I disagree, I think my original wording (taken form Erwan) is clearer. Boot-time here really means that, when the hardware boots. Compilation and build time are really irrelevant IMHO

OK, I see the "its" refers to "hardware, This clarifies it.
In principle, "software" also has "boot-time" configuration.

ioannisg · 2018-06-21T11:08:43Z

doc/devices/dts/device_tree.rst

+* 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**.


firmware features?

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

ioannisg · 2018-06-21T11:09:26Z

doc/devices/dts/device_tree.rst

+  of the hardware peripheral in memory or its interrupt line.
+* Additional, **hardware boot-time configuration** is also described with Device
+  Tree. This includes things like the interrupt line and IRQ priority. These
+  might also be modifiable at runtime later, but their boot-time "default"


ioannisg · 2018-06-21T11:10:16Z

doc/devices/dts/device_tree.rst

+  might 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. In this way users can opt not to include


Through Kconfig, the users can opt to....

ioannisg · 2018-06-21T11:10:35Z

doc/devices/dts/device_tree.rst

+
+* Device Tree describes the presence of a radio peripheral compatible with a
+  certain radio driver.
+* Additional hardware boot-time configuration settings might also be present


ioannisg · 2018-06-21T11:10:52Z

doc/devices/dts/device_tree.rst

+  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 might decide to select BLE or 802.15.4, which will both depend on


dbkinder · 2018-06-22T06:03:38Z

doc/devices/dts/device_tree.rst

+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 inteds to serve as a reference when


Change to: (and removing the misspelled "intends")

This section serves as a reference to help you decide whether to place configuration items in Device Tree or Kconfig.

dbkinder · 2018-06-22T06:05:39Z

doc/devices/dts/device_tree.rst

+  the final image, and their **configuration**.
+
+Hence Device Tree deals mostly with hardware and Kconfig with software. A
+noteworthy exception is Device Tree's `chosen` keyword, which allows the user


use two backticks:

``chosen``

dbkinder · 2018-06-22T06:07:36Z

doc/devices/dts/device_tree.rst

+Hence Device Tree deals mostly with hardware and Kconfig with software. A
+noteworthy exception is 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 using this keyword to select


How about:

An example of this is selecting a particular UART for use as the system's console.

I like it. Fixed.

dbkinder · 2018-06-22T06:08:32Z

doc/devices/dts/device_tree.rst

+purpose by the software. An example of this is using this keyword to select
+a particular UART to be used as the system's console.
+
+In order to further clarify this separation, let's use a particular, well-known


Delete the "In order":

To further clarify this separation, ...

dbkinder · 2018-06-22T06:09:48Z

doc/devices/dts/device_tree.rst

+  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.
+* Additional, **hardware boot-time configuration** is also described with Device


Change to Additionally,

dbkinder · 2018-06-22T06:10:33Z

doc/devices/dts/device_tree.rst

+  "immutable" (i.e. not software-configurable) settings such as the base address
+  of the hardware peripheral in memory or its interrupt line.
+* Additional, **hardware boot-time configuration** is also described with Device
+  Tree. This includes things like the interrupt line and IRQ priority. These


change like to such as

dbkinder · 2018-06-22T06:12:55Z

doc/devices/dts/device_tree.rst

+
+* 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


I'd delete the quotes on immutable. Using the quotes implies that it might not be immutable, such as saying, Bob and his "wife" went out to dinner.

I agree, thank you. Fixed.

dbkinder · 2018-06-22T06:13:26Z

doc/devices/dts/device_tree.rst

+  of the hardware peripheral in memory or its interrupt line.
+* Additional, **hardware boot-time configuration** is also described with Device
+  Tree. This includes things like the interrupt line and IRQ priority. These
+  may also be modifiable at runtime later, but their boot-time "default"


Same here, no need for the quotes on default

dbkinder · 2018-06-22T06:15:10Z

doc/devices/dts/device_tree.rst

+  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 could be a device with a 2.4GHz, multi-protocol radio supporting


change could be to is

dbkinder · 2018-06-22T06:16:49Z

doc/devices/dts/device_tree.rst

+* 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 perhaps a


I'd delete the word perhaps

erwango · 2018-06-22T07:27:14Z

doc/devices/dts/device_tree.rst

-describe hardware.  Device tree is not intended to replace CMSIS or vendor
-include files.
+replace or curtail the use of some Kconfig files throughout the system, and
+instead use device tree files to describe the configuration of device nodes.


"replace or curtail the use of some Kconfig files throughout the system, and instead use device tree files to describe the configuration of device nodes"
Isn't it rather a temporary side effect of device tree introduction?
While it makes sense to us, this might be unclear for a future Zephyr user.
I think we'd rather remove this part or provide a generic description with no reference with Kconfig, as:
"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."

Additionnaly, we might want to add a reference to specification, if not already present (http://www.devicetre.org/)

I agree with you. Will make the change

erwango · 2018-06-22T07:33:13Z

doc/devices/dts/device_tree.rst

+  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.


Maybe this part should be clarified as it eludes the device tree "status" property.
Should we use it?
If we use it (which I think we should do), we should mention it will take precedence and then Kconfig will be able to amend only if status is "okay". If "status" is "disabled" it won't be available in Kconfig.
If we don't use it, we'll need to change the (device tree extract scripts) code.

I will add a comment about this

tbursztyka

tiny comment

tbursztyka · 2018-06-22T07:58:49Z

doc/devices/dts/device_tree.rst

+  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 interrupt line and IRQ priority. These


That's a very particular example, changing irq/prio at runtime is going to be very rare. Use the i2c clock-frequency instead, since it's very common to change it at runtime.

I've amended this now using UART baudrate

Try to clarify the scope of Device Tree vs Kconfig in order to allow Zephyr users to identify where a particular configuration option when developing an application, board support or SoC support. Fixes zephyrproject-rtos#7230 Signed-off-by: Carles Cufi <[email protected]>

carlescufi · 2018-06-22T09:35:43Z

@ioannisg @erwango @tbursztyka @dbkinder addressed your comments

dbkinder

+1, thanks!

agross-oss

looks nice

carlescufi requested review from mbolivar and agross-oss June 21, 2018 10:10

carlescufi requested a review from dbkinder as a code owner June 21, 2018 10:10

carlescufi requested review from tbursztyka, erwango, galak, nashif and SebastianBoe June 21, 2018 10:10

ulfalizer suggested changes Jun 21, 2018

View reviewed changes

carlescufi force-pushed the dt_doc branch from 9edf11d to 94b0024 Compare June 21, 2018 10:33

carlescufi requested review from MaureenHelm and dleach02 June 21, 2018 10:34

carlescufi force-pushed the dt_doc branch from 94b0024 to 539776d Compare June 21, 2018 10:34

carlescufi requested a review from ioannisg June 21, 2018 10:35

carlescufi mentioned this pull request Jun 21, 2018

Device Tree support overhaul #8499

Closed

6 tasks

carlescufi force-pushed the dt_doc branch from 539776d to 8e2edbc Compare June 21, 2018 10:37

carlescufi added area: Devicetree area: Configuration System area: Documentation labels Jun 21, 2018

carlescufi added this to the v1.13.0 milestone Jun 21, 2018

ulfalizer approved these changes Jun 21, 2018

View reviewed changes

SebastianBoe approved these changes Jun 21, 2018

View reviewed changes

erwango reviewed Jun 21, 2018

View reviewed changes

ioannisg requested changes Jun 21, 2018

View reviewed changes

carlescufi force-pushed the dt_doc branch 2 times, most recently from c44d86e to d8ae655 Compare June 21, 2018 16:11

dbkinder suggested changes Jun 22, 2018

View reviewed changes

erwango requested changes Jun 22, 2018

View reviewed changes

carlescufi force-pushed the dt_doc branch from d8ae655 to 618e03f Compare June 22, 2018 07:50

tbursztyka reviewed Jun 22, 2018

View reviewed changes

carlescufi force-pushed the dt_doc branch from 618e03f to d06895e Compare June 22, 2018 09:33

erwango approved these changes Jun 22, 2018

View reviewed changes

dbkinder approved these changes Jun 22, 2018

View reviewed changes

ioannisg approved these changes Jun 22, 2018

View reviewed changes

agross-oss approved these changes Jun 22, 2018

View reviewed changes

carlescufi merged commit 4574505 into zephyrproject-rtos:master Jun 25, 2018


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

		* Device Tree is used to describe the hardware and its **boot-time

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

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

Conversation

carlescufi commented Jun 21, 2018 • edited Loading

carlescufi commented Jun 21, 2018

carlescufi commented Jun 21, 2018

ulfalizer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SebastianBoe left a comment

Choose a reason for hiding this comment

codecov-io commented Jun 21, 2018 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ioannisg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

erwango Jun 22, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tbursztyka left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carlescufi commented Jun 22, 2018

dbkinder left a comment

Choose a reason for hiding this comment

agross-oss left a comment

Choose a reason for hiding this comment

carlescufi commented Jun 21, 2018 •

edited

Loading

codecov-io commented Jun 21, 2018 •

edited

Loading

erwango Jun 22, 2018 •

edited

Loading