Device Tree Customization
Device Tree Customization
Device tree customization is used when the base hardware description itself needs to change.
Unlike overlays, which append smaller runtime changes on top of the existing board definition, a custom DTB allows projects to maintain their own board-specific hardware description while still reusing the NVIDIA BSP foundation.
In this workspace, the NVIDIA Jetson BSP remains the hardware baseline, while project-specific board definitions are maintained inside a project-owned Yocto device tree recipe.
When to Use a Custom DTB
A custom device tree is typically preferred when the change belongs in the primary board description rather than in a small incremental overlay.
Typical examples include:
- Adding a project-specific compatible string
- Changing default board properties
- Selecting a different DTB for a given
MACHINE - Keeping project customization separate from NVIDIA BSP source files
- Supporting board-specific hardware configurations
- Maintaining long-term ownership of the platform configuration
- Supporting custom carrier board designs
- Integrating board-level GPIO, regulator, pinmux, or power-tree changes
If the change is optional or relatively small, overlays are usually simpler.
Overlays are commonly used for optional peripherals, sensors, expansion boards, or incremental runtime hardware enablement.
If the primary board definition itself changes, a custom DTB is generally the better approach.
Custom DTB Integration Flow
The integration model used in this workspace is:
The Yocto device tree recipe controls how DTS files are compiled and packaged into deploy artifacts.
The selected MACHINE determines which DTB is included in the generated flash bundle and ultimately used by the target platform during boot.
This approach keeps the board description under project control while still reusing the NVIDIA BSP, flashing workflow, and platform integration.
Workspace Structure
The workspace already includes a project-owned device tree recipe:
layers/meta-tegrademo/recipes-bsp/
└── tegrademo-devicetree/
└── tegrademo-devicetree_1.0.bb
The meta-tegrademo layer contains project-specific BSP customization separate from the NVIDIA vendor layers.
The recipe uses the Yocto devicetree class to compile custom DTS files and integrate them into the Yocto deployment workflow.
The device tree recipe builds against the NVIDIA device tree sources through:
DEPENDS += "nvidia-kernel-oot"
This dependency provides access to the NVIDIA kernel and BSP device tree sources required during DTB generation.
Example DTS files:
tegra234-p3737-0000+p3701-0000-oe4t.dts tegra234-p3768-0000+p3767-0000-oe4t.dts tegra234-p3768-0000+p3767-0005-oe4t.dts
These examples demonstrate the same integration pattern across AGX Orin, Orin NX, and Orin Nano platforms.
Example Customization
The example DTBs intentionally keep the customization minimal.
They inherit from the NVIDIA base device tree and introduce a project-specific compatible string at the root node.
#include "tegra234-p3737-0000+p3701-0000-nv.dts"
/ {
compatible = "oe4t,p3737-0000+p3701-0000+tegrademo",
"nvidia,p3737-0000+p3701-0000",
"nvidia,p3701-0000",
"nvidia,tegra234";
};
In real projects, custom DTBs commonly extend the NVIDIA base device tree with:
- GPIO configuration
- Pinmux updates
- Power regulators
- Peripheral enablement
- Carrier-board specific hardware integration
Although the example modification is intentionally small, it provides a simple way to validate that the project-owned DTB is active on the target system.
Machine Configuration
The custom DTB flow is controlled through Yocto configuration.
The project selects which recipe provides virtual/dtb and defines which DTB file should be used for each platform.
Within Yocto, virtual/dtb is part of the provider selection model used to determine which recipe supplies the active DTB artifacts during the build.
PREFERRED_PROVIDER_virtual/dtb = "tegrademo-devicetree" KERNEL_DEVICETREE:jetson-agx-orin-devkit = "tegra234-p3737-0000+p3701-0000-oe4t.dtb" KERNEL_DEVICETREE:jetson-orin-nano-devkit = "tegra234-p3768-0000+p3767-0005-oe4t.dtb" KERNEL_DEVICETREE:jetson-orin-nano-devkit-nvme = "tegra234-p3768-0000+p3767-0005-oe4t.dtb"
These settings are commonly maintained in project-specific machine or distribution configuration files.
This keeps the board definition explicitly tied to the selected MACHINE.
Build and Deployment
Build the device tree package:
bitbake tegrademo-devicetree
Rebuild the image:
bitbake demo-image-base
Verify that the generated DTB exists in the deploy directory:
ls tmp/deploy/images/$MACHINE/*.dtb
Flash the updated image:
./scripts-setup/flash-demo-image-base
This packages the custom DTB into the generated flash artifacts and deploys it onto the target system.
Validation on Target
After boot, validate the active device tree using the live DT information exposed by the kernel:
cat /sys/firmware/devicetree/base/compatible
Expected output:
oe4t,p3737-0000+p3701-0000+tegrademo
This confirms that the system booted using the project-specific DTB derived from the NVIDIA base board definition.
Additional validation commands:
dmesg | grep -i dtb
dtc -I fs /proc/device-tree
These checks help confirm that the correct DTB was loaded and applied during boot.
Relationship to Overlays
| Custom DTB | Overlay |
|---|---|
| Maintains the primary board description | Adds incremental runtime changes |
| Commonly used for larger board customization | Commonly used for optional hardware features |
| Typically tied to project-specific platforms | Typically used for modular hardware additions |
| Usually inherits from NVIDIA base DTS files | Extends the existing active DTB |
Both approaches are useful and can coexist within the same project.
Troubleshooting
If the target does not appear to use the expected DTB, verify:
- The image was rebuilt after changing
KERNEL_DEVICETREE - The board was reflashed using the updated deploy artifacts
PREFERRED_PROVIDER_virtual/dtbpoints to the correct recipe- The selected
MACHINEmatches the DTB configuration - The expected DTB exists under
tmp/deploy/images/$MACHINE/ - The generated flash bundle was regenerated after rebuilding the image
Useful checks:
bitbake -e demo-image-base | grep '^KERNEL_DEVICETREE='
bitbake -e demo-image-base | grep '^PREFERRED_PROVIDER_virtual/dtb='
ls tmp/deploy/images/$MACHINE/*.dtb
cat /sys/firmware/devicetree/base/compatible
dmesg | grep -i dtb
The most common issue is updating the device tree configuration without rebuilding and reflashing the image afterward.
In some cases, cleaning cached DTB artifacts before rebuilding may also help ensure the updated device tree is packaged correctly.