# In depth Device Tree Questions



## Phishfry (Dec 28, 2022)

I have some fundamental questions understanding the Device Tree syntax.

Question One:

Device Node numbers. Like this snippet:


```
uart@20000000 {
              interrupt-parent = < 1 >;
      };
```

Where is the number 20000000 coming from? Where is this assigned from?
I don't see it in the dts or dtsi source code.
It is shown in `ofwdump -a` output from the board.


----------



## Phishfry (Dec 28, 2022)

So the technical term is unit-address.


> Every node must have a name in the form <name>[@<unit-address>]








						Device Tree Usage - eLinux.org
					






					elinux.org
				









						2. The Devicetree — Devicetree Specification unknown-rev documentation
					






					devicetree-specification.readthedocs.io


----------



## bakul (Dec 28, 2022)

A specific device tree describes real hardware so `uart@20000000` says there is a uart device at address 0x20000000 -- that number comes from the processor or board spec.  The device tree format is pretty simple. I wrote a minimal decompiler (dtb -> dts but doesn't deal with overlays) that I can put up on github. It won't teach you much about dt but you can experiment and read the code. The dtb reading code is about 350 LoC, the decompiler code about 250 LoC


----------



## Phishfry (Dec 28, 2022)

bakul said:


> says there is a uart device at address 0x20000000


OK really simple. What is address is that? A machine register address? A pointer? A memory address.
I understand that it is common among CPU devices. For example iMX6 would all use the same unit number for devices like uart and i2c.


----------



## bakul (Dec 28, 2022)

Phishfry said:


> A machine register address? A pointer? A memory address.


That depends on what it is! AFAIK the DT spec doesn’t help there or care. All it does is basically give you a symbolic way to use various h/w facilities but you still have to know from other sources what a number means in a given context. It could be a register or a memory or device address or an interrupt vector or just a flip flop.


----------



## Phishfry (Dec 29, 2022)

bakul said:


> It could be a register or a memory or device address or an interrupt vector or just a flip flop.


Or even a cpu... cpu0: cpu@0

I think I understand now.
Some excellent unit address examples here:





						Introduction to devicetree — Zephyr Project Documentation
					






					docs.zephyrproject.org


----------



## Phishfry (Jan 1, 2023)

OK I want to move on to a second question.

Compiling Device Tree Overlays.

Commonly I find overlays that have an #include /dt-bindings/gpio/gpio.h or similar includes needed.
How do you compile these overlays with the includes?
Device Tree Compiler? Gmake? make_dtbs ?
Do you have to compile from a certain directory to use includes?
For example the following directory contains overlays.
/usr/src/sys/dts/arm64/overlays/

Yet the device tree bindings are here:
/usr/src/sys/gnu/dts/include/dt-bindings/gpio/gpio.h
With Clang I would use an Include on the command line but I am not sure with dtc.


----------



## bakul (Jan 1, 2023)

#include are processed by cpp, while /include/ are processed by dtc. So for #include cpp rules apply. /include/ seems to look in the current directory but I think you can specify -i flag for include dir path. Do a make -n in the overlays dir. and follow the breadcrumbs from there. In particular sys/tools/fdt/make_dtbo.sh


----------



## Jose (Jan 1, 2023)

bakul said:


> #include are processed by cpp, while /include/ are processed by dtc. So for #include cpp rules apply.


Interestingly, C preprocessor includes are not mentioned in the devicetree spec (section 6.1).


----------



## bakul (Jan 1, 2023)

They have their own /include/ but Unix guys tend to rely on cpp even though it is not a great fit here!


----------



## Phishfry (Jan 1, 2023)

bakul said:


> I think you can specify -i flag for include dir path.


Wow I missed that.
I thought -I and -O were input/output.
I missed the -i flag.






						dtc(1)
					






					www.freebsd.org
				



*-i* _include___path_


----------



## Phishfry (Jan 1, 2023)

Thanks for all the wise advice bakul
I have another procedural question.

What do 'symbols' do in the `dtc -@` flag context? The handbook seems to indicate they denote an overlay.
I thought the flag had something to do with including symbols. Later in the document it says this:


> When the *-@* flag is used to write symbols, nodes with labels will be con-
> sidered referenced



What does writing symbols here mean?


----------



## Phishfry (Jan 1, 2023)

I find it interesting to use a u-boot ports build to look at the dts build procedure. The *.pre files are kept.


----------



## Phishfry (Jan 1, 2023)

> A __symbols__    node will be included so that overlays
> may be applied to it.


What is a symbols node? Is this just a branch in the tree? Is there content or a stub?
Is this debugging information?


----------



## bakul (Jan 1, 2023)

Have you read https://www.kernel.org/doc/Documentation/devicetree/overlay-notes.txt? It should answer your question. Also poke around in the parent dir. /devicetree/


----------



## Phishfry (Jan 1, 2023)

Yes I was just looking at the initial commit.
It looks more like a list of labels or alias to me.

```
+    };
+    __symbols__ {
+        res="/res";
+        ocp="/ocp";
+    };
```



			dtc: Dynamic symbols & fixup support


----------



## DavidMarec (Jan 4, 2023)

bakul said:


> A specific device tree describes real hardware so `uart@20000000` says there is a uart device at address 0x20000000 -



That is not exactly the case, @unit address acts as an id. It's an address within the device tree.
The common way to define a register address is to setup the  reg property in the device node.

However, as one usually do, @unit address follows the register address.


----------

