Jump to content

Device Tree (dtb): Difference between revisions

From postmarketOS Wiki
MayeulC (talk | contribs)
Created page with "The device tree blob (or binary) is a file containing information about the board and its hardware. == Why is it needed? == Most embedded platforms do not provide a way of d..."
 
Skye (talk | contribs)
 
(28 intermediate revisions by 9 users not shown)
Line 1: Line 1:
The device tree blob (or binary) is a file containing information about the board and its hardware.
The Device Tree Blob (or binary) is a file containing information about the board and its hardware.
 


== Why is it needed? ==
== Why is it needed? ==
Line 19: Line 18:


== Where can I find a dts for my device? ==
== Where can I find a dts for my device? ==
Those are generally present in the kernel fork your device uses. Look in the <code>boards/</code> directory, or in <code>arch/your_device_arch/boot/dts</code>.
=== Extract the dts from a boot.img ===
When a dts is not present in the kernel source code at all, or when it is not immediately apparent which file is the correct one for your device, a dts can be extracted from a boot.img for your device.
 
This is done with <code>extract-dtb</code> and <code>unpackbootimg</code> (both packaged in postmarketOS). The resulting dtb can be converted back to a source file with the <code>dtc</code> compiler (though the comments will be lost, as well as the includes).
 
If <code>dtc</code> gives this error:
 
<code>FATAL ERROR: Blob has incorrect magic number</code>
 
Then you are likely working with a dtb that has an offset (Samsung does this). The offset can be identified with <code>binwalk</code>. For Samsung dtb, it is 0x40. The following command will remove the 0x40 offset and use <code>dtc</code> to create a file called dts from an input file called dtb.img:
 
<code>dd if=dtb.img skip=$((0x40)) iflag=skip_bytes | dtc -I dtb -o dts</code>
 
If all else fails, you can always use <code>strings</code> on the dtb file. The output will be messy and not directly useful, but may give you keywords (such as a model number) to look for within the kernel source code to help you locate and identify the correct .dts file.
 
=== Locate the dts in the kernel source ===
The dts files are generally present in the kernel fork your device uses. Look in the <code>boards/</code> directory, or in <code>arch/your_device_arch/boot/dts</code>.  
 
When a board is mainlined, the corresponding dts file is mainlined as well (though those may be put in a separate repository in the future).
When a board is mainlined, the corresponding dts file is mainlined as well (though those may be put in a separate repository in the future).
If you cannot immediately find or identify the correct .dts in your downstream kernel source, analyse the boot.img as described above. You can use the information contained in the extracted dts, such as the model name, to find a matching file in the kernel source. Note that the .dts in the kernel source will almost definitely <i>not</i> look like the extracted dts. It will be much shorter, as most of the code comes from the includes.
== Writing a device tree ==
When [[Mainlining Guide | mainlining]] a board, it is often needed to write one's own device tree (see also [[Mainlining_Guide#Device_Tree_Source]]). Indeed, while the physical description part won't change, the name of the drivers will probably. Thus, you need to find kernel drivers that are compatible with your own device, and put them in the device tree (assuming there is one). You should at least read carefully the description [https://elinux.org/Device_Tree_Usage on elinux.org]. Another good tutorial to writing your device trees is present on [http://xillybus.com/tutorials/device-tree-zynq-1 xillybus.com].


== See also ==
== See also ==
[[Dtbtool]], a tool to compile dtb in the [[qcdt]] format.
* [[Dtbtool]], a tool to compile dtb in the [[QCDT]] format.
* <code>extract-dtb</code> (<code>pmbootstrap build extract-dtb</code>) to extract <code>dtb</code> files from Linux kernels and QCDT-style boot.img files
* [[Mainlining_Guide#Device_Tree_Source | The dedicated section in the mainlining guide]]


== Links ==
== Links ==


[http://www.informit.com/articles/article.aspx?p=1647051&seqNum=5]
* [http://www.informit.com/articles/article.aspx?p=1647051&seqNum=5 Device Tree Blob (Flat Device Tree)]
* [https://github.com/torvalds/linux/blob/master/Documentation/arm/booting.rst Linux documentation on the ARM boot process]
* [https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tree/Documentation/manual.txt DTC (device tree compiler) manual]
* [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/usage-model.rst Linux kernel docs Documentation/devicetree/usage-model.rst]
* [https://community.arm.com/developer/tools-software/oss-platforms/w/docs/525/device-tree Device Tree on ARM]
* YouTube: [https://www.youtube.com/watch?v=m_NyYEBxfn8 Device Tree for Dummies! - Thomas Petazzoni, Free Electrons]
* YouTube: [https://www.youtube.com/watch?v=PgQezmlst0w Device Tree: Past, Present, and Future]
 
[[Category:Technical Reference]]

Latest revision as of 20:32, 26 September 2023

The Device Tree Blob (or binary) is a file containing information about the board and its hardware.

Why is it needed?

Most embedded platforms do not provide a way of discovering the hardware they have. You either have to resort to guesswork (which is not viable), or provide the Linux kernel with information about the board and the peripherals.

Before the dtb was introduced, each board needed a kernel specifically compiled for them, which was hardcoded to use the peripherals. With the dtb, a single kernel can run on multiple devices, if it is given the right dtb at boot time.

How is it created?

The dtb is created from device tree source (dts) files. Those contain the hardware description in a readable format. The dtb format merely exists to make loading them simpler for the kernel. As such, dts can be converted to and from dtb with a device tree compiler, dtc, which is available on most linux distributions.

How is it used?

The dtb is loaded in memory by the bootloader (often uboot) before the kernel is started.

Some older versions of uboot do not support loading a separate dtb file, which means that the dtb has to be embedded in the kernel zImage.

QCDT

Some Qualcomm devices also use the QCDT format, where the dtb is appended to the end of the filesystem (boot.img) instead of the zImage.

Where can I find a dts for my device?

Extract the dts from a boot.img

When a dts is not present in the kernel source code at all, or when it is not immediately apparent which file is the correct one for your device, a dts can be extracted from a boot.img for your device.

This is done with extract-dtb and unpackbootimg (both packaged in postmarketOS). The resulting dtb can be converted back to a source file with the dtc compiler (though the comments will be lost, as well as the includes).

If dtc gives this error:

FATAL ERROR: Blob has incorrect magic number

Then you are likely working with a dtb that has an offset (Samsung does this). The offset can be identified with binwalk. For Samsung dtb, it is 0x40. The following command will remove the 0x40 offset and use dtc to create a file called dts from an input file called dtb.img:

dd if=dtb.img skip=$((0x40)) iflag=skip_bytes | dtc -I dtb -o dts

If all else fails, you can always use strings on the dtb file. The output will be messy and not directly useful, but may give you keywords (such as a model number) to look for within the kernel source code to help you locate and identify the correct .dts file.

Locate the dts in the kernel source

The dts files are generally present in the kernel fork your device uses. Look in the boards/ directory, or in arch/your_device_arch/boot/dts.

When a board is mainlined, the corresponding dts file is mainlined as well (though those may be put in a separate repository in the future).

If you cannot immediately find or identify the correct .dts in your downstream kernel source, analyse the boot.img as described above. You can use the information contained in the extracted dts, such as the model name, to find a matching file in the kernel source. Note that the .dts in the kernel source will almost definitely not look like the extracted dts. It will be much shorter, as most of the code comes from the includes.

Writing a device tree

When mainlining a board, it is often needed to write one's own device tree (see also Mainlining_Guide#Device_Tree_Source). Indeed, while the physical description part won't change, the name of the drivers will probably. Thus, you need to find kernel drivers that are compatible with your own device, and put them in the device tree (assuming there is one). You should at least read carefully the description on elinux.org. Another good tutorial to writing your device trees is present on xillybus.com.

See also

Links