Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

The meta-tegra layer includes MACHINE definitions for NVIDIA’s Jetson development kits. If you are developing a custom device using one of the Jetson modules with, for example, a custom carrier board, or you just want to modify the default boot-time configuration (pinmux, etc.) for an existing development kit as a separate MACHINE in your own metadata layer, you may need to supply a MACHINE-specific file for your builds.

IMPORTANT: For any custom carrier board/hardware design, make sure you consult the appropriate Platform Adaptation and Bring-Up Guide document available at the Jetson Software Documentation Site to get all the details on how to customize the pinmux configuration and other low-level hardware configuration settings. Failing to provide the correct settings could damage your device.

Boot-time hardware configuration and boot flash programming is particularly complicated for Jetson modules, and varies substantially between models. Consult a recent version of the L4T Driver Package Documentation, particularly the “BSP Customization” and “Bootloader” chapters, for background information. As mentioned above, the Platform Adaptation documentation is also a good reference.

NOTE: Due to restrictions in the implementation of bootloader update payloads, the length of your custom MACHINE name should be 31 characters or less.

Jetson Orin

This guide is based on Jetson Linux R35.4.1 so change bbappend names accordingly if you use a different release. Occurences of ${machine} should be replaced by your machine name.

Create a new machine config

Create a new Machine configuration at conf/machine/${machine}.conf in your layer. For guidance on what it should contain look at any of the machine configurations in meta-tegra.

Create a new flash config

As of PR https://github.com/OE4T/meta-tegra/pull/1386 (first introduced in the scarthgap release branch), flashvars files are now generated by the tegra-flashvars recipe from machine configuration variables instead of being manually checked in.

Define the flash configuration in your ${machine}.conf machine configuration file using TEGRA_FLASHVAR_* variables. For example:

TEGRA_FLASHVAR_PINMUX_CONFIG ?= "tegra234-${machine}-pinmux.dtsi"
TEGRA_FLASHVAR_PMC_CONFIG ?= "tegra234-${machine}-padvoltage-default.dtsi"

Review the content of the TEGRA_FLASHVAR variables used with the MACHINE you are basing your custom machine on, and/or review the flashvars file generated by a build of the MACHINE you are basing your custom MACHINE on in order to decide which variables need customization.

The tegra-flashvars recipe will automatically generate the flashvars file from these variable settings. If you need to provide custom files referenced by these variables, use the method described in Add pinmux dtsi files.

Add pinmux dtsi files

Generate the pinmux dtsi files with the Nvidia pinmux Excel sheet (or this one for Orin AGX). Rename the resulting files to start with tegra234- (Otherwise meta-tegra has issues handling them.) and convert line endings to Unix using dos2unix. Copy the files to recipes-bsp/tegra-binaries/tegra-flashvars.

NOTE: If you manually rename your generated DTSI files, you may need to modify the #include statement on line 35 of your -pinmux.dtsi file, as it has the original filename for the -gpio-default.dtsi file hardcoded.

Install the files with following tegra-bootfiles_35.4.1.bbappend:

# Hack: The fetch task is disabled on this recipe, so the following is just for the task signature.
FILESEXTRAPATHS:prepend := "${THISDIR}/${BPN}:"
SRC_URI:append:${machine} = "\
    file://tegra234-${machine}-gpio-default.dtsi \
    file://tegra234-${machine}-padvoltage-default.dtsi \
    file://tegra234-${machine}-pinmux.dtsi \
"

# Hack: As the fetch task is disabled for this recipe, we have to directly access the files."
CUSTOM_DTSI_DIR := "${THISDIR}/${BPN}"
do_install:append:${machine}() {
    install -m 0644 ${CUSTOM_DTSI_DIR}/tegra234-${machine}-gpio-default.dtsi ${D}${datadir}/tegraflash/
    install -m 0644 ${CUSTOM_DTSI_DIR}/tegra234-${machine}-padvoltage-default.dtsi ${D}${datadir}/tegraflash/
    install -m 0644 ${CUSTOM_DTSI_DIR}/tegra234-${machine}-pinmux.dtsi ${D}${datadir}/tegraflash/
}

(Don’t forget to replace ${machine} with your machine name.)

Then update the TEGRA_FLASHVAR_* settings in your ${machine}.conf to reference your custom files:

  • TEGRA_FLASHVAR_PINMUX_CONFIG should reference your tegra234-${machine}-pinmux.dtsi
  • TEGRA_FLASHVAR_PMC_CONFIG should reference your tegra234-${machine}-padvoltage-default.dtsi

(Optionally) disable board EEPROM usage

As explained in the Platform Adaptation and Bring-Up Guide by Nvidia, you might want to disable the usage of the board EEPROM. For that, create a custom version of the file referenced by TEGRA_FLASHVAR_MB2BCT_CFG in your machine configuration and modify it according to the Nvidia guide. Include this new file in Yocto using a tegra-bootfiles_35.4.1.bbappend as described in Add pinmux dtsi files, then update TEGRA_FLASHVAR_MB2BCT_CFG in your ${machine}.conf to reference the new file name.

Use a custom device tree

See Custom Device Tree and apply the described changes to your ${machine}.conf.

Jetson AGX Thor

Thor (Tegra264) custom machine definitions follow a similar pattern to Orin (Tegra234). Replace occurrences of ${machine} below with your machine name.

Create a new machine config

Create conf/machine/${machine}.conf in your layer. Use one of the existing Thor machine configurations in meta-tegra (e.g., jetson-agx-thor-t4000.conf) as a starting point. Your config should require the appropriate agx-thor-*.inc or tegra264.inc include.

Key Thor-specific variables to be aware of:

  • PARTITION_LAYOUT_RCMBOOT / PARTITION_LAYOUT_RCMBOOT_DEFAULT — partition layout XML used for the RCMBoot flashing stage. Thor uses a separate UEFI image for this stage. The default is flash_l4t_t264_rcmboot.xml.

  • TEGRA_RCM_EDK2_CONFIGURATION — controls which EDK2 firmware build is used for RCMBoot. Defaults to "minimal". If you set this to the same value as TEGRA_EDK2_CONFIGURATION, the main UEFI build is reused and no separate RCMBoot UEFI build is required.

  • EMC_BCTS — a comma-separated list of EMC BCT files for the flash process. This extends EMC_BCT to support multiple entries when needed for different memory configurations.

RCMBoot UEFI

Unlike Orin, Thor requires a UEFI firmware image specifically for the RCMBoot stage. The edk2-firmware-tegra-rcmboot recipe builds this from EDK2 sources. If you cannot or do not wish to build from source, the edk2-firmware-tegra-rcmboot-prebuilt recipe provides a prebuilt binary. To use the prebuilt binary, add the following to your machine configuration or local.conf:

PREFERRED_PROVIDER_edk2-firmware-tegra-rcmboot = "edk2-firmware-tegra-rcmboot-prebuilt"

See bootloader/uefi_bins/README_uefi.txt in the L4T BSP kit for information on the UEFI sources.

Add pinmux and BCT files

Unlike Orin, which uses .dtsi kernel device tree fragments for pinmux configuration, Thor uses MB1 BCT DTS files (.dts) for all boot-time hardware configuration. These are generated from the NVIDIA pinmux spreadsheet for Thor and have a tegra264-mb1-bct- naming convention in the reference BSP.

In your machine configuration, set the relevant TEGRA_FLASHVAR_* variables to the filenames of your custom BCT DTS files. The two most commonly customized are:

TEGRA_FLASHVAR_PINMUX_CONFIG ?= "tegra264-mb1-bct-pinmux-${MACHINE}.dts"
TEGRA_FLASHVAR_PMC_CONFIG    ?= "tegra264-mb1-bct-padvoltage-${MACHINE}.dts"

Then provide those files via a tegra-bootfiles_39.2.0.bbappend in your layer:

FILESEXTRAPATHS:prepend := "${THISDIR}/${BPN}:"
SRC_URI:append:${machine} = "\
    file://tegra264-mb1-bct-pinmux-${MACHINE}.dts \
    file://tegra264-mb1-bct-padvoltage-${MACHINE}.dts \
"

CUSTOM_BCT_DIR := "${THISDIR}/${BPN}"
do_install:append:${machine}() {
    install -m 0644 ${CUSTOM_BCT_DIR}/tegra264-mb1-bct-pinmux-${MACHINE}.dts ${D}${datadir}/tegraflash/
    install -m 0644 ${CUSTOM_BCT_DIR}/tegra264-mb1-bct-padvoltage-${MACHINE}.dts ${D}${datadir}/tegraflash/
}

Other TEGRA_FLASHVAR_* variables (e.g. GPIOINT_CONFIG, MB2BCT_CFG, PMIC_CONFIG) may also require custom files depending on your carrier board design. Consult the Platform Adaptation and Bring-Up Guide for Thor for the full list of configuration files and their purpose.

Use a custom device tree

See Custom Device Tree and apply the described changes to your ${machine}.conf.

Customizing the kernel

For custom hardware, you’ll probably need to modify the kernel in at least one of the following ways:

  • Custom kernel configuration
  • Custom device tree
  • Adding patches

Starting with the L4T R32.3.1-based branches, you can use the Yocto Linux tools to apply patches and configuration changes during the build, although it may be simpler to fork the linux-tegra-4.9 repository to apply patches, and supply your own defconfig file for the kernel configuration. Having your own fork of the kernel sources should also be easier for creating a custom device tree. (You should also set the KERNEL_DEVICETREE variable in your machine configuration file appropriately.)

Custom MACHINE definitions for existing hardware

If you need to define an alternate MACHINE configuration for an NVIDIA Jetson development kit without altering the boot-time configuration files for hardware initialization, you can have your MACHINE reuse the existing files in meta-tegra. For example, let’s say you want to create tegraflash packages for the Jetson-TX2 development kit for both the default cboot->U-boot->Linux boot sequence as well as for booting directly from cboot to Linux, without U-Boot. In your BSP or distro layer, you could add a machine configuration file called, for example, conf/machine/jetson-tx2-cboot.conf that looks like this:

MACHINEOVERRIDES = "jetson-tx2:${MACHINE}"
require conf/machine/jetson-tx2.conf
PACKAGE_EXTRA_ARCHS_append = " jetson-tx2"
PREFERRED_PROVIDER_virtual/bootloader = "cboot-prebuilt"

This would override the bootloader settings in the default jetson-tx2 configuration to use cboot instead of U-Boot, but otherwise reuse all of the MACHINE-specific packages, files, and settings for the jetson-tx2 MACHINE in meta-tegra.

For Jetson Xavier NX based machine types - jetson-xavier-nx-devkit and jetson-xavier-nx-devkit-emmc, the conf/machine/custom-machine.conf would look like this:

require conf/machine/jetson-xavier-nx-devkit-emmc.conf
MACHINEOVERRIDES = "cuda:tegra:tegra194:xavier-nx:jetson-xavier-nx-devkit-emmc:${MACHINE}"
PACKAGE_EXTRA_ARCHS_append = " jetson-xavier-nx-devkit-emmc"

Custom Device Tree

In many cases it is desirable to avoid forking or patching the kernel sources. The devicetree bbclass can be used to create a custom dtb. There’s an example in tegra-demo-distro documented at Using-device-tree-overlays which accomplishes this for recent branches.

Custom Partitioning

See Redundant-Rootfs-A-B-Partition-Support for suggestions regarding defining partition layout files for your MACHINE.