[[PageOutline]]

= Linux Device Tree support =
The modern linux kernel uses a system called 'devicetree' to describe hardware in a consistent fashion to avoid needing custom 'board support' files for boards.

Typically the bootloader will pass a 'flattened device tree' (a compiled binary representation of a device-tree) to the kernel so that the kernel can configure all the components on the board. 


== Device Tree Terminology ==
 * dts - Board level definitions
 * dtsi - SoC level definitions
 * dtb - Binary blob of device tree loaded by bootloader


== Example Device Tree File ==
You can find the device tree files in arch/arm/boot/dts

For the Gateworks Venice platform, the device tree files are at arch/arm64/boot/dts/freescale/
 - Note device tree source code (eg GW7200) is located in kernel source code at path: linux-venice/arch/arm64/boot/dts/freescale/imx8mm-venice-gw72xx.dtsi
 - Link for the Venice kernel source code [https://github.com/Gateworks/linux-venice here]

For an example, see [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/arm/boot/dts/imx6qdl-gw54xx.dtsi imx6qdl-gw54xx.dtsi]


== Accessing devicetree from the Bootloader ==
The Ventana u-boot has fdt support enabled and uses this through default bootscripts to load an fdt (based on the board model) from the filesystem of the boot media.  The bootloader then modifies the devicetree to disable components that are possible on the board, but perhaps not loaded on the bill-of-materials (for example, a Gateworks Special build).

If desired you can use the ftd u-boot command to access/modify the devicetree before the kernel is booted.

Examples:
 * display the fdt of a Ventana board (loaded from NAND flash ubifs):
{{{#!bash
setenv fsload 'ubifsload'
ubi part rootfs && ubifsmount ubi0:rootfs
run loadfdt && fdt addr ${fdt_addr} && fdt boardsetup
fdt print
}}}
 * disable PCI via device-tree:
{{{#!bash
setenv fsload 'ubifsload'
ubi part rootfs && ubifsmount ubi0:rootfs
run loadfdt && fdt addr ${fdt_addr} && fdt boardsetup
fdt resize
fdt set /soc/pcie@0x01000000 status disabled
}}}

Note the Ventana bootloader has a '''fixfdt''' script that can make integrating fixups like this into the boot process easy. See [http://trac.gateworks.com/wiki/ventana/bootloader#Specifyinganalternatedevice-treeblobDTB here] for details.


== Accessing devicetree from Linux ==
If the kernel is configured with CONFIG_PROC_DEVICETREE (which the Ventana OpenWrt BSP does configure) and procfs is enabled, you can access the devicetree via /proc/device-tree.  This can be useful to obtain information about the board that the bootloader configured, such as board model and serial number.

Examples:
 * show board model:
{{{#!bash
echo $(cat /proc/device-tree/board)
}}}
 * show board serialnumber
{{{#!bash
echo $(cat /proc/device-tree/serial-number)
}}}
 * show devicetree compatible node (this describes which device-tree was used as there is one per base-board design):
{{{#!bash
echo $(cat /proc/device-tree/compatible)
}}}
 * show chosen bootargs (the bootargs passed in by the bootloader, same as /proc/cmdline):
{{{#!bash
echo $(cat /proc/device-tree/chosen/bootargs)
}}}


== Specifying the Device-tree that is used ==
The [wiki:/linux/bootloader bootloader] is responsible for loading the device-tree blob (DTB) and executing the kernel 
The Gateworks ventana bootloader in a way that it knows where the DTB is loaded.

Therefore, its the bootloader that decides which DTB to load and from where.

See [wiki:/ventana/bootloader] for details on how the DTB filename is chosen and loaded.

== Adding New Devices to the Device Tree 
For customers interested in adding a new device to an existing controller, see the [wiki:/SPI SPI] wiki page for an example of the process.

=== Compiling the Device Tree
If you need to change the device-tree you can easily compile it on a Linux system using the dtc app from the device-tree-compiler package:
{{{#!bash
apt-get install device-tree-compiler
dtc -O dtb -o imx6dl-gw51xx.dtb imqx6dl-gw51xx.dts
}}}

=== De-Compiling the Device Tree
You can also de-compile a dtb back to a dts:
{{{#!bash
dtc -I dtb -O dts imx6dl-gw51xx.dtb > imx6dl-gw51xx.dts
}}}
You can also decompile the device tree of a running system:
{{{#!bash
dtc -I fs -O dts /sys/firmware/devicetree/base > MySBC.dts
}}}