# Device Tree
Device tree is for describe the peripheral HW. It not noly can describe the detectable devices, but also can be used for ==non-detectable== devices
:::info
non-detectable device: Like memory information, flash information, UARTs, GPIOs ...etc.
:::

## Device Tree Source (.dts)

### root
* **/**: This is root for device tree.

/ {
    
    name = "device-tree-example";
    model = "device model name";
    compatiable = "deive-tree";
    #address-cells = <2>;
    #size-cells = <2>;
    # linux,phandle = <0>;
}

### node

[aliae_name:] node-name[@unit-address] {
    [properties definitions]
    [child nodes]
};

[]: means option
* **[aliae_name:] node-name[@unit-address]** :
* unit-address: indicate the address mapping to device.
* if the node doesn't have =="reg"== property, the unit-address can't be exist.
* **properties definitions**:
* describe the node property
* the property can be no assigned value. e.g ==properties = [value]==
* **value** :
* can be a value or multiple value.

            address = <1>;
            address2 = [0x00001 0x20000];

* can be string lists

            device_type = "memory";
            name = "PowerPC,970";

[Property value](https://devicetree-specification.readthedocs.io/en/v0.3/devicetree-basics.html#properties)
* properties attirbute:
[Standard Properties](https://devicetree-specification.readthedocs.io/en/v0.3/devicetree-basics.html#standard-properties)
Here are list some special properites.
1. address-cells and #size-cells :
:::info
The ==#address-cells== and ==#size-cells== properties may be used in any device node that has children in the devicetree hierarchy and describes how child device nodes should be addressed.

The ==#address-cells== property defines the number of <u32> cells used to encode the address field in a child node’s reg property.

The ==#size-cells== property defines the number of <u32> cells used to encode the size field in a child node’s reg property

            e.g: 
            #address-cells = <2>;
            #size-celss = <2>;
            memory@0 {
                device_type = "memory";
                reg = <0x000000000 0x00000000 0x00000000 0x80000000>;
            };

reg will use <address1, size1, address2, size2, ...>
:::

2. phandle:
:::info
A phandle value is a way to reference another node in the devicetree
1. In an array, the "&" reference will expand to a phandle.

        mydevice: mydev {
            compatiable = "mydevice_list";
            pincontrol = <&my_pin_ctrl>;
        }
        
        maybe in another dtsi
        
        my_pin_ctrl: my_pin_ctrl {
            ....
        };

2. Outside an arry, the "&" reference will expand to the path of the node you're referring to.

        label:node {
            #address-cell = <1>;
            #size-cells = <0>;
        }

        &label {
            ...;
        };

This means

        label:node {
            #address-cell = <1>;
            #size-cells = <0>;
            ....;
        }

:::
## Device tree code trace and How to load into kernel
[TBD]

## how to build

$ dtc -@ -I dts -O dtb -o <output>.dtbo <src>.dts

## ref
[Introduction to Linux kernel
driver programming](https://events19.linuxfoundation.org/wp-content/uploads/2017/12/Introduction-to-Linux-Kernel-Driver-Programming-Michael-Opdenacker-Bootlin-.pdf)
[Device Tree（二）：基本概念](http://www.wowotech.net/linux_kenrel/dt_basic_concept.html)
[Device Tree（三）：代码分析]( http://www.wowotech.net/linux_kenrel/dt-code-analysis.html)
[Device Tree（四）：文件结构解析](http://www.wowotech.net/device_model/dt-code-file-struct-parse.html)
[example in linux kernel](https://elixir.bootlin.com/linux/v6.11/source/arch/arm/boot/dts/marvell/armada-370-c200-v2.dts)

* dtsi example
* dts example
* Device Tree PIN defineitions
* Device match to device driver