Device Tree - How to find structure and definitions

RE: Device Tree - How to find structure and definitions

Marte Myrvold — Tue, 31 Oct 2023 08:43:12 GMT

Hi,

Your feedback and experience with using Zephyr has been forwarded.

[quote user="sfjklsdvmwoir"]Things are scattered across the project folder structure so you need to know or you are just in the dark.

In my workspace under ...\external\zephyr\drivers\CMakeLists.txt includes drivers with add_subdirectory_ifdef
Under each driver folder is another CMakeLists.txt with the same structure for individual drivers of that class.
At this point the Kconfig of each driver appears to take over and define if it is enabled or not. How the system chooses a driver (hopefully the one you want) after that is unclear as alot of defines and dependencies are scattered across the build.

[/quote]

As you have found, the drivers are located under for example <NCS_installation_dir>/nrf/drivers and <NCS_installation_dir>/zephyr/drivers. The CMakeLists.txt files add the relevant driver files to your project depending on what is enabled.
The Kconfig files defines the configurations for a specific device, both ones that are user-configurable and some that are not. Often they have a default value that you can override by setting it to something else in your project configuration (prj.conf) if they are user-configurable.

How the system chooses a driver is decided by the "compatible" field of the enabled devicetree node and the Kconfig options of the driver. Take for example SPI. Setting CONFIG_SPI=y in prj.conf will enable SPI. For the nRF5340 DK you might have SPI4 enabled in devicetree (status = "okay") as it is in nrf5340_cpuapp_common.dtsi:

arduino_spi: &spi4 {
	compatible = "nordic,nrf-spim";
	status = "okay";
	cs-gpios = <&arduino_header 16 GPIO_ACTIVE_LOW>; /* D10 */
	pinctrl-0 = <&spi4_default>;
	pinctrl-1 = <&spi4_sleep>;
	pinctrl-names = "default", "sleep";
};

Here the compatible field is nordic,nrf-spim, which means it is the nRF SPIM driver that will be used. You can see this in the drivers Kconfig file, zephyr/drivers/spi/Kconfig.nrfx:

config SPI_NRFX_SPIM
	def_bool y
	depends on DT_HAS_NORDIC_NRF_SPIM_ENABLED

The config option DT_HAS_NORDIC_NRF_SPIM_ENABLED is generated from the devicetree node when 'compatible = "nordic,nrf-spim' and 'status = "okay"'. SPI_NRFX_SPIM is set to 'y' by default, but it depends on DT_HAS_NORDIC_NRF_SPIM_ENABLED, so it is only set to 'y' if DT_HAS_NORDIC_NRF_SPIM_ENABLED is enabled, that is, if a node with nrf-spim is enabled in devicetree.

[quote user="sfjklsdvmwoir"]...\external\zephyr\dts\arm\nordic contains the base nodes for all of the peripherals on the Nordic board.[/quote]

Correct. These are the base devicetree files describing the chips themselves. The ones under boards/arm are for the DKs.

[quote user="sfjklsdvmwoir"]...\external\zephyr\dts\bindings\ Holds yaml files that will explain some of the settings for a peripheral. That said its layered and does not seem well documented so only use if you cant find the definitions externally. [/quote]

These are the bindings I wrote about in my first reply:

[quote user="Marte.M"]If you want to find the required properties of a specific devicetree node you can look at the bindings for that node, for example, nordic,nrf-spi. This shows which base and node specific properties the node has, the data types of the properties, and a description for each property. [/quote]

And these pages: Devicetree bindings syntax and Devicetree bindings.

[quote user="sfjklsdvmwoir"]From what I can tell drivers like LED driver do not have an official definition (In the devicetree spec) so maybe this is were you can find that kind of information (here or under the link provided in the official answer above).[/quote]

The most common LEDs are gpio-leds and pwm-leds.

As you can see in most of our samples, we use the DK Buttons and LEDs library.

Best regards,
Marte

RE: Device Tree - How to find structure and definitions

sfjklsdvmwoir — Mon, 30 Oct 2023 14:55:05 GMT

For those who are also lost here is a few things I have discovered lately:

Things are scattered across the project folder structure so you need to know or you are just in the dark.
- In my workspace under ...\external\zephyr\drivers\CMakeLists.txt includes drivers with add_subdirectory_ifdef
- Under each driver folder is another CMakeLists.txt with the same structure for individual drivers of that class.
- At this point the Kconfig of each driver appears to take over and define if it is enabled or not. How the system chooses a driver (hopefully the one you want) after that is unclear as alot of defines and dependencies are scattered across the build.
...\external\zephyr\dts\arm\nordic contains the base nodes for all of the peripherals on the Nordic board.
Ever wonder about the definitions of the macros in devicetree files: ...\external\zephyr\include\zephyr\dt-bindings\ holds those, or at least all of the ones I have looked up so far. nrf-pinctrl.h holds all those functional definitions for GPIOs.
...\external\zephyr\dts\bindings\ Holds yaml files that will explain some of the settings for a peripheral. That said its layered and does not seem well documented so only use if you cant find the definitions externally.
- From what I can tell drivers like LED driver do not have an official definition (In the devicetree spec) so maybe this is were you can find that kind of information (here or under the link provided in the official answer above).
devicetree.org has a specification that I am assuming is the official base.

It some one knows better please correct my statements. Clearly I am not in the know.

RE: Device Tree - How to find structure and definitions

sfjklsdvmwoir — Mon, 30 Oct 2023 14:07:49 GMT

Thank you. We will keep reading or just blindly coping and pasting. I know that Zephyr is not run by the Nordic team but it is a contributor so maybe you can take a little partition. I(out team) think devicetree violates the KISS principle. Adding more syntax, layers, files, and complexity to the problem (especially when the core solution does not change) is not a good solution. When we started the project all we wanted to do was set a GPIO and that took hours vs the few mins it has taken in the STM or NXP environments. On a personal note I find it detracts from understanding the hardware and confidence that the system is setup and running the way you configured it. Confidence is further detracted when often a SDK update appears to break something in the devicetree macros... Its a pain to track those problems down. Why not just implement the solution in C (that is were it ends up anyways after all the layers unravel).

RE: Device Tree - How to find structure and definitions

Marte Myrvold — Thu, 26 Oct 2023 08:21:53 GMT

Hi,

Devicetree has a steep learning curve and can be difficult when getting started.

I know you said that little of the documentation is useful, but I still want to mention some pages which I have found to be helpful: Devicetree - Syntax and structure, Devicetree bindings syntax, Devicetree bindings and Devicetree HOWTOs.

[quote user=""]The question is were do you find the definitions and structure to properly setup nodes in a device tree? [/quote]

This is where the syntax pages are really helpful. The first one explains devicetree nodes and properties, and shows some important properties. The second explains the same for bindings.

[quote user=""]Each hardware type will have its own structure and flags/data. [/quote]

If you want to find the required properties of a specific devicetree node you can look at the bindings for that node, for example, nordic,nrf-spi. This shows which base and node specific properties the node has, the data types of the properties, and a description for each property. Another option is to look at how it is used in other devicetree files, for example the nrf-spi node here:

&spi1 {
	compatible = "nordic,nrf-spi";
	status = "okay";
	pinctrl-0 = <&spi1_default>;
	pinctrl-1 = <&spi1_sleep>;
	pinctrl-names = "default", "sleep";
};

[quote user=""]Or if I wanted to setup a driver that has no example in DT ( examples are how I currently guess what should be done) where would I find the structure and definitions?[/quote]

This is described in the links above, but I have also made a simple example specifically for creating your own custom device with devicetree bindings and devicetree nodes. You can find it here: https://github.com/martelmy/NCS_examples/tree/main/devicetree/devicetree_custom_device. Please note that this is not an official example, so it has not been tested extensively and is provided as-is.

[quote user=""]Even better is it feasible to not use DT?[/quote]

No, devicetree is necessary to describe hardware in Zephyr.

Best regards,
Marte