1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. Copyright (C) 2019 Vijay Kumar Banerjee <vijaykumar9597@gmail.com> |
---|
4 | |
---|
5 | .. _DeviceTree: |
---|
6 | |
---|
7 | Device Tree |
---|
8 | =========== |
---|
9 | .. index:: Device Tree |
---|
10 | |
---|
11 | A Device Tree is a data structure that is used to describe properties of |
---|
12 | non-discoverable hardware instead of hardcoding them in the kernel. The device |
---|
13 | tree data is generally stored in a `.dts` or a Device Tree Source (DTS) file. |
---|
14 | This file is then compiled into a binary format called Device Tree Blob (DTB) |
---|
15 | with `.dtb` extension. RTEMS preferably uses a DTB built from the FreeBSD source |
---|
16 | tree matching the freebsd-org HEAD commit hash in libBSD. |
---|
17 | |
---|
18 | Building the DTB |
---|
19 | ---------------- |
---|
20 | |
---|
21 | A single DTB file can be built using the `dtc` tool in libfdt using the |
---|
22 | following command: |
---|
23 | |
---|
24 | .. code-block:: none |
---|
25 | |
---|
26 | dtc -@ -I dts -O dtb -o my-devicetree.dtb my-devicetree.dts |
---|
27 | |
---|
28 | For building the DTB from the FreeBSD source, the `make_dtb.sh` script |
---|
29 | from `freebsd/sys/tools/fdt` must be used as most of the DTS files in FreeBSD |
---|
30 | have included `.dtsi` files from their source tree. An example is given below as |
---|
31 | a reference for how to build the device tree from the FreeBSD source. |
---|
32 | |
---|
33 | `NOTE: The following example uses FreeBSD master branch from github mirror as |
---|
34 | an example. It is advised to always use the source from the commit matching the |
---|
35 | freebsd-org HEAD in libBSD.` |
---|
36 | |
---|
37 | .. code-block:: shell |
---|
38 | :linenos: |
---|
39 | |
---|
40 | #We're using the script from freebsd/sys/tools/make_dtb.sh |
---|
41 | #Target device: Beaglebone Black. |
---|
42 | #Architecture: Arm. |
---|
43 | #DTS source name: am335x-boneblack.dts |
---|
44 | |
---|
45 | #The make_dtb.sh script uses environment variable MACHINE |
---|
46 | export MACHINE='arm' |
---|
47 | |
---|
48 | SCRIPT_DIR=$HOME/freebsd/sys/tools/fdt |
---|
49 | |
---|
50 | #The arguments to the script are |
---|
51 | # $1 -> Build Tree (This is the path to freebsd/sys/ directory) |
---|
52 | # $2 -> DTS source file |
---|
53 | # $3 -> output path of the DTB file |
---|
54 | |
---|
55 | ${SCRIPT_DIR}/make_dtb.sh ${SCRIPT_DIR}/../../ \ |
---|
56 | ${SCRIPT_DIR}/../../gnu/dts/arm/am335x-boneblack.dts \ |
---|
57 | $(pwd) |
---|
58 | |
---|
59 | Using Device Tree Overlay |
---|
60 | ------------------------- |
---|
61 | |
---|
62 | Device tree overlay is used either to add properties or devices to the existing |
---|
63 | device tree. Adding any property to DTS using an overlay will override the |
---|
64 | current values in the DTB. The Overlays enable us to modify the device tree |
---|
65 | using a small maintainable plugin without having to edit the whole Base Tree. |
---|
66 | |
---|
67 | There are two ways of applying an overlay on top of the built DTB. |
---|
68 | |
---|
69 | #. Use fdtoverlay from libfdt |
---|
70 | |
---|
71 | #. Add the overlay in the root partition of the SD card and apply it using U-Boot |
---|
72 | |
---|
73 | The fdtoverlay command can be used as follows: |
---|
74 | |
---|
75 | .. code-block:: none |
---|
76 | |
---|
77 | fdtoverlay -i my-base-tree.dtb -o output-tree.dtb my-overlay.dtbo |
---|
78 | |
---|
79 | To apply it from U-Boot during system initialization we have to add the device |
---|
80 | tree overlay file in the root directory of the SD card and use U-Boot commands |
---|
81 | to apply the overlay. |
---|
82 | |
---|
83 | Below is given the series of U-Boot commands that can be used to apply the |
---|
84 | overlay, given that the overlay blob (.dtbo) file is already in the card. |
---|
85 | |
---|
86 | .. code-block:: shell |
---|
87 | |
---|
88 | fatload mmc 0:1 0x80800000 rtems-app.img |
---|
89 | fatload mmc 0:1 0x88000000 my-base-tree.dtb |
---|
90 | fdt addr 0x88000000 |
---|
91 | fatload mmc 0:1 0x88100000 my-overlay.dtbo |
---|
92 | fdt resize 0x1000 |
---|
93 | fdt apply 0x88100000 |
---|
94 | bootm 0x80800000-0x88000000 |
---|