Device Tree Structure

A device tree is a tree-structured data format that represents information about the devices on a board.
Using device trees provides:
Fewer “machine code” and “board” files
A single unmodified kernel used for many platforms
For developing a product with the platform, the device tree data is automatically included in the flashed image.
The device tree data must be included in the flashed image when upgrading a product from an earlier release. Future kernel versions are expected to support device trees and to deprecate board files.

Device Tree Format

A device tree is a tree structure containing kernel-level information about hardware, including:
Device characteristics
Connections between devices (buses)
Device configuration information
A device tree represents the hardware. The information in a device tree comes from sources such as hardware specifications and board schematics.
Device tree data is represented in the following formats:
Device Tree source files (*.dts and *.dtsi files)
Flattened device tree (FDT) structures
The resolved DTS and DTSI files for a device are represented as an FDT structure.
For information on the flattened device tree (FDT) format, see:
Binary files known as device tree blobs or DTBs (*.dtb files)
The device tree compiler (DTC) compiles the FDT structure into a DTB file.

Device Tree Files in the BSP Framework

The BSP framework from NVIDIA includes device tree source files that describe the supported platforms. It provides source files that support hardware differences among the variants of each platform.
A hierarchy of DTSI files describes each platform. From highest (most general) to lowest (most specific), the hierarchy levels are:
A hierarchy of DTSI files describes each platform:
|-- Base Platform DTS
|-- Platform Intermediate DTSI
|-- Platform Common DTSI
|-- SoC DTSI
The SDK supplies the DTS files in the following directories:
<top>/hardware/nvidia/soc/t186/
<top>/hardware/nvidia/platform/t194
tegra186-vcm31_<e3550a01-t186a | e3550a01-t186b | e3550a03-t186a | e3550a03-t186b>-base-*.dtsi
Files named with this syntax contain chip-specific nodes common for boards that have the Tegra version in question.
tegra186194-vcm31t186194-common.dtsi
Files named with this syntax contain a Device Tree for the vcm31 platform with the specified Tegra version.
DTS and DTSI files refer to each other using include statements. This allows the reuse of pre-existing device tree nodes. A board-00 DTS file includes the relevant board DTSI file, which includes the relevant chip-specific DTSI file, which in turn includes the relevant SoC DTSI file.

Example: Platform Common DTSI

The tegra186-soc/tegra186-common.dtsi file is included in the platform intermediate DTSI file for each platform. It is included in the platform intermediate DTSI.
#include "address_map_new.h"
#include "clk-t186.h"
#include "reset-t186.h"
#include "tegra186-irq.h"
#include "tegra186-vcm31-thermal.dtsi"
#include "tegra186-camera.dtsi"
#include "tegra186-safety-sce.dtsi"
#include "t18x/tegra186-gpcdma-sid.h"
#include "t18x/tegra-t18x-agic.h"
#include "tegra186-soc-prod.dtsi"
 
/ {
#address-cells = <2>;
#size-cells = <2>;
 
chosen {
stdout-path = &uartb;
};
 

Example: SoC DTSI

The tegra186-soc/tegra186-common.dtsi file is the SoC-specific DTSI file. It is included in the platform common DTSI.
#include "address_map_new.h"
#include "clk-t186.h"
#include "reset-t186.h"
#include "tegra186-irq.h"
#include "tegra186-camera.dtsi"
#include "t18x/tegra186-gpcdma-sid.h"
#include "t18x/tegra-t18x-agic.h"
 
/ {
#address-cells = <2>;
#size-cells = <2>;
 
chosen {
};

Viewing Pinmux Settings in the DTS

Quickboot configures the pinmux; the kernel does not configure them.
The device tree entries for pinmux are visible in the following procfs location. It contains the different states defined for dynamic pinmux configuration.
/proc/device-tree/pinmux@70000868

Kernel DTS Compilation and Flashing

The framework build system compiles the kernel DTS and DTSI files for your platform into DTB data, which is included in the flash image. Along with the kernel, DTB files are built automatically.
The boot loader uses the libfdt library to manage DTB data. With this library, Quickboot performs the following tasks:
1. Reads the DTB from the kernel-dtb partition, if it exists.
2. Modifies the DTB to add device tree nodes that are specific to the platform.
3. Passes the modified DTB to the kernel, if Quickboot initially read the DTB from the kernel-dtb partition.
To flash a custom DTB file
Flash the file with the bootburn -u option and provide the path to your customized DTB file.
The default path is tegra186-<board>-010-a01-00-base.dtb.

Configuring Device Tree Support

By default, the board configuration files enable device tree support for a DTB partition device. The TARGET_KERNEL_DT_NAME configuration contains the prefix for the DTB/DTSI files for your platform.

Device Tree Data Format

The device tree data format represents information for the devices on a board. It has these characteristics:
A tree structure of nodes and properties
A single root node “/
Child nodes with properties
Key-value pairs represent properties
Keys used as property identifiers
Values are empty or byte streams
Data types of streams:
Strings "Value"
List of strings: "Value_1", "Value_1"
Binary data: [0x1 0x2 0x3]
Cell: <0x1 0x2 0x3>
The device tree data format is part of the Open Firmware industry standard (IEEE 1275).

SW-EDID

SW-EDID is a mechanism to provide EDID as a blob in a DTB. The driver reads the EDID data from the device tree instead of from the panel or monitor. SW-EDID is useful in the following cases:
The DDC channel of HDMI is not connected and another method is required to provide mode information to the driver. Instead of hard-coding the board file, the EDID blob is supplied in the DTB for the driver to read at runtime.
Debugging or experimental purposes where there is a need to override the EDID.
SW-EDID supports HDMI, DP, and LVDS drivers.

Configuring CPU Cores

In hypervisor configurations, the guest OS may not run on all CPU cores. The CPU cores that the OS is to use can be controlled by the DT. This section describes how to configure them.
This node contains the relevant information for the CPU:
cpus {
#address-cells = <2>;
#size-cells = <0>;
 
cpu@0 {
device_type = "cpu";
compatible = "arm,cortex-a57-64bit", "arm,armv8";
reg = <0x0 0x100>;
enable-method = "psci";
status = "disabled";
};
 
cpu@1 {
device_type = "cpu";
compatible = "arm,cortex-a57-64bit", "arm,armv8";
reg = <0x0 0x101>;
enable-method = "psci";
status = "disabled";
};
 
cpu@2 {
device_type = "cpu";
compatible = "arm,cortex-a57-64bit", "arm,armv8";
reg = <0x0 0x102>;
enable-method = "psci";
status = "disabled";
};
 
cpu@3 {
device_type = "cpu";
compatible = "arm,cortex-a57-64bit", "arm,armv8";
reg = <0x0 0x103>;
enable-method = "psci";
status = "disabled";
};
 
cpu@4 {
device_type = "cpu";
compatible = "nvidia,denver", "arm,armv8";
reg = <0x0 0x0>;
enable-method = "psci";
status = "disabled";
};
 
cpu@5 {
device_type = "cpu";
compatible = "nvidia,denver", "arm,armv8";
reg = <0x0 0x1>;
enable-method = "psci";
status = "disabled";
};
};
The status of a CPU core is controlled by the status property.
To enable core 4
Set the status property under the cpu@4 node to okay.
To disable core 4
Set the property to disabled.

Selecting dGPU Frequency Cap

The GPU provides the ability to select the dGPU frequency cap from the device tree. You can run dGPU in Max P, Max Q, or another mode. If the device tree property is not provided, dGPU defaults to Max P mode. Max P mode clock frequency comes from the VBIOS.

Device Tree Binding Document

The device tree binding document provides information on device tree properties supported by the kernel device tree binding documents that are available as part of the Linux kernel source.
Device tree binding documentation can be found in the Linux kernel source released with the package at:
kernel/Documentation/devicetree/bindings/
nvidia/Documentation/devicetree/bindings/