Advanced Setup and Customization
To use with NVIDIA® Tegra® Linux Driver Package (L4T), you can manually configure and setup the software drivers before use or allow JetPack to perform the standard setup.
Consult your board documentation for guidance on manually setting up and configuring your reference board.
Note: | NVIDIA JetPack performs the following: • Install the Linux for Tegra package
• Configure or flash your Tegra device
• Run samples If you installed using JetPack, skip these topics. For more information, see the JetPack documentation. |
Reference Board Preparation
When developing systems and application software with L4T, you run and test your code on an actual reference platform, such as the NVIDIA® Jetson™ TX2 developer kit. Your code targets this hardware directly, rather than a software simulator or emulator.
Accordingly, you must acquire and set up your reference board before using L4T. Consult your board documentation for guidance on setting up and configuring your board.
Although the reference board supports a variety of peripheral devices, you can start developing on L4T with a board that has the following:
•A USB cable to plug into the board recovery port
Boot Options
Boot L4T on the Jetson TX2 reference board from a root file system (rootfs) on integrated, attached, or network-accessible storage. The boot loader must be loaded from the internal eMMC. Root filesystem options include:
•USB stick (formatted to EXT4)
•USB hard disk (formatted to EXT4)
•SD card (formatted to EXT4)
•Internal eMMC
•Network File System (NFS)
Linux Host System Prerequisites
To use L4T on a Linux host system, the following hardware and software prerequisites must be met:
•A kernel image (Image). L4T contains a kernel image for your use. Alternatively, you can download and rebuild the kernel image from source.
•Boot loader. Flashing on a Tegra X2 series (Jetson TX2) developer board requires a boot loader, which is a combination of NVIDIA T-Boot (nvtboot) and U-Boot.
•NFS if you intend to boot L4T on the reference board from your Linux host system or a network-accessible server.
•A USB cable to plug into the recovery port.
Extracting Tegra Linux Driver Package
Use the following procedures to extract your L4T package. Commands in the examples assume you extracted the release package in ~/.
To extract Tegra Linux Driver Package
•Extract the package manually by executing the following command:
Tip: | In the above expression, float your cursor over a place-holder to reveal the currently-defined value. |
Setting Up Your File System
L4T requires a root file system. You must create a Linux host system and copy it to your reference board.
Sample Root File System
L4T comes with a pre-built sample root file system created for the Jetson TX2 developer kit. If you wish to create an Ubuntu sample root file system, see:
Setting Up the Root File System
Before booting the target board, configure the root file system (rootfs) to:
•Set up the rootfs
•Copy it to the rootfs on the device
Step 1: Set Up the Root File System
This procedure uses the sample file system provided by NVIDIA as the base. If you wish to use your own file system, set the LDK_ROOTFS_DIR environment variable to point to the location of your rootfs and skip the steps for setting the root file system.
To set up the rootfs
1. Download the following file to your home directory:
This file contains the NVIDIA-provided sample root file system.
2. Extract the compressed file as follows:
•Navigate to the rootfs directory of the extracted NVIDIA driver package.
$ cd <your_L4T_root>/Linux_for_Tegra/rootfs
Where <your_L4T_root> is your L4T root directory, which is assumed to be your home directory (~).
•Extract the sample file system to the rootfs directory.
$ sudo tar -jxpf ../../Tegra-Linux-Sample-Root-Filesystem_<
release_type>.tbz2
3. Run the apply_binaries.sh script to copy the NVIDIA user space libraries into the target file system.
$ cd ..
$ sudo ./apply_binaries.sh
4. If you are using a different rootfs, or if you have already configured your rootfs, apply the NVIDIA user space libraries by setting the LDK_ROOTFS_DIR environment variable to point to your rootfs. Then run the script, as shown above, to copy the binaries into your target file system.
If the apply_binaries.sh script installs the binaries correctly, the last message output from the script is “Success!”.
You have now completed setting up the root filesystem. Proceed to flash the rootfs onto the target Tegra device.
Step 2: Copy the rootfs to the Device
Use these procedures to copy the file system to the Tegra device.
1. Pick a device to place your rootfs.
2. If you prefer to use an external storage device for the root filesystem, use the following procedure.
To copy the file system to an external storage device
1. Plug your rootfs device into the host system.
2. If your device is not formatted as Ext4, enter the following command to format it with an Ext4 file system:
$ sudo mkfs.ext4 /dev/sd<port><device_number>
Where:
•<port> is the port to which your device is mounted.
•<device_number> is the device number of the device attached to the port. You can use the dmesg command to determine the port.
3. If needed, mount your device with the following command:
$ sudo mount /dev/sdX1 <mntpoint>
Where <mntpoint> is the mount point on the host system for your rootfs device.
4. Copy the file system. If LDK_ROOTFS_DIR is set, execute these commands:
$ cd ${LDK_ROOTFS_DIR}
$ sudo cp -a * <mntpoint> && sync
5. If it is not set, copy the rootfs directory that is included in the release by executing the following commands:
$ cd <your_L4T_root>/Linux_for_Tegra/rootfs
$ sudo cp -a * <mntpoint> && sync
6. After copying the content to the external disk or device, unmount the disk and connect it to the target Tegra device.
Flashing the Boot Loader and Kernel
This section describes the steps to flash and boot the target Tegra device. It also provides usage information for the flash.sh helper script.
Flash Procedure
First, flash the board with the boot loader and kernel, and optionally, flash the rootfs to internal eMMC.
Prerequisites
The following directories must be present:
•bootloader—boot loader plus flashing tools (NvFlash, CFG,
BCT, etc.)
•kernel—a kernel zImage /vmlinux.uimg, DTB files, and kernel modules
•rootfs—the root file system that you download (This directory starts empty and you populate it with the sample file system.)
•nv_tegra—NVIDIA® Tegra® user space binaries and sample applications
Additionally, before running the following commands, you must have the USB cable connected to the recovery port.
To flash the boot loader and kernel
1. Put the target into reset/recovery mode.
•Power on the carrier board and hold the RECOVERY button.
•Then press the RESET button.
2. Run the flash.sh script that is in the top level directory of this release. The script must be supplied with the target board (jetson-tx2) for the root file system:
Where <rootdev> depends on where the root file system will be:
•If the root file system will be on the Jetson TX2 internal eMMC, execute the script as follows:
sudo ./flash.sh jetson-tx2 mmcblk0p1
•If the root file system will be on a USB disk, execute the script as follows:
sudo ./flash.sh jetson-tx2 sda1
•If a SATA device is connected, that device enumerates as sda1.
•If the root file system will be on an SD card, execute the script as follows:
sudo ./flash.sh jetson-tx2 mmcblk1p1
The above examples are for U-Boot. For Fastboot, add the following argument:
-L <PATH_TO_FASTBOOT_BIN_FILE>
For example:
This loads the boot loader and kernel.
Flash Script Usage
Locate the most up-to-date usage information by running flash.sh -h (using the flash.sh script included in the release). The basic usage is as follows.
Specify the required parameters and one or more of the options in the following table.
Parameters | Description |
<platform> | Is the < platform> for your release. |
<rootdev> | Is one of following: |
| mmcblk0p1 | Specifies internal eMMC. |
mmcblk1p1 | Specifies external SDCARD. |
sda1 | Specifies external USB device (such as, USB memory stick or HDD). |
eth0 | Specifies nfsroot via external USB Ethernet interface. |
Options | Description |
-h | Specifies to print this usage information. |
-b <bct_file> | Specifies the NvFlash Boot Configuration Table (BCT) file. |
-c <cfg_file> | Specifies the NvFlash configuration file. |
-d <dtb_file> | Optionally specifies a device tree file to use instead of the default. |
-e <emmc_file> | Specifies the eMMC size of the target device. |
-f <flashapp> | Specifies the path to flash application: nvflash or tegra-rcm. |
-i | Specifies to pass the user kernel command line to the kernel as-is. |
-k <partition id> | Specifies the kernel partition ID to be updated (minimum = 5). |
-n <nfs args> | Specifies the static NFS network assignments: <Client IP>:<Server IP>:<Gateway IP>:<Netmask> |
-o <odmdata> | Specifies the ODM data value. |
-p | Total eMMC HW boot partition size. |
-r | Specifies to skip building and reuse existing system.img. |
-s <ubootscript> | Specifies the boot script file for U-Boot. |
-C <cmdline> | Specifies the kernel command line. Warning: Each option in this kernel command-line gets higher precedence over the same option from fastboot. In case of NFS booting, this script adds NFS booting related arguments if the -i option is omitted. |
-F <flasher> | Specifies the flash server, such as fastboot.bin. |
-I <initrd> | Specifies initrd file. Null initrd is the default. |
-K <kernel> | Specifies the kernel image, such as zImage. |
-L <bootloader> | Specifies the full path to the boot loader, such as fastboot.bin or u-boot.bin. |
-P <end_of_PPT_plus_1> | Specifies the sum of the primary GPT start address, the size of PPT, plus 1. |
-R <rootfs_dir> | Specifies the sample rootfs directory. |
-N <nfsroot> | Specifies the nfsroot, for example: <my IP addr>:/my/exported/nfs/rootfs |
-S <size> | Specifies the rootfs size in bytes. This is valid only for internal rootdev. KiB, MiB, GiB style shorthand is allowed. For example, 1GiB signifies 1024 * 1024 * 1024 bytes. |
-T <ITS_file> | ITS file name. Valid only for u-boot. |
Increasing the Internal Memory Partition for the Root File System
The suggested rootfs partition size for the Jetson TX2 platform is 15 gigabytes (GB).It is specified by default in the <target_board>.conf file used by the flash.sh script.
Use the -S <size-in-bytes> argument to flash.sh to change the partition size.
To flash for a larger partition
•Execute the following command:
$ sudo ./flash.sh -S <size> <
platform> <rootdev>
Where:
•<size> is the desired size for the partition, such as 8589934592 (or 8 GiB) for 8 GB, if you want to decrease the size of the partition.
•<rootdev> is the rootfs partition internal memory, for example mmcblk0p1.
Determining the Success of a Driver Update
After updating drivers on a target board, verify that the update completed successfully. You can determine the success or failure of a driver update by using the following commands.
To determine the success of a driver update
•Execute the following command on a booted target device:
$ sha1sum -c /etc/nv_tegra_release
If the driver update succeeded, the output displays the word OK after the file name. A typical success message looks like this:
/usr/lib/xorg/modules/drivers/nvidia_drv.so: OK
The driver update fails if the file is missing. A typical error message looks like this:
sha1sum: /usr/lib/xorg/modules/drivers/nvidia_drv.so: No such file or directory
/usr/lib/xorg/modules/drivers/nvidia_drv.so: FAILED open or read
The driver update also fails if the new file is not the same as the existing file, producing an error such as:
/usr/lib/xorg/modules/drivers/nvidia_drv.so: FAILED
Installing Additional Packages
L4T comes with additional NVIDIA packages, including packages for Ubuntu and Google Chrome.
Installing Additional NVIDIA Packages
Additional NVIDIA packages may be posted alongside the release. To make full use of the features in the release, install these additional packages.
Directly after the
apply_binaries step in
Setting Up the Root File System, you can install the package into the configured rootfs.
Installing Additional Ubuntu Packages
Install additional packages from Ubuntu, using the provided sample file system.
L4T is tested with the provided sample file system Ubuntu packages. Periodic Ubuntu package updates from Canonical are not validated.
To receive notifications
1. Locate and edit the following file:
/etc/apt/sources.list
2. Add the following line:
For example, for a rootfs based on the Xenial Xerus distribution of Ubuntu, add the line:
Prerequisite
You have attached an Ethernet cable to the device through either the Ethernet port (if available) or through the USB Ethernet adapter.
To install more packages
1. Boot the target device.
2. Verify your Ethernet connection.
3. Update the package list by executing:
$ sudo apt-get update
Ensure that you run sudo apt-get update and not apt-get upgrade, which upgrades already installed packages. Do not confuse the two commands.
4. Install packages using apt-get. For example, to install wget execute this command:
$ sudo apt-get install wget
Configuring NFS Root on the Linux Host
To boot the target device from NFS, you must provide an NFS root mount point on your Linux host machine. The general steps for configuring an NFS root on the Linux host are as follows.
Prerequisites
•An Ethernet connection to install packages on the host.
•An Ethernet connection on the target.
To configure NFS root on the Linux host
1. Install the nfs components on your host machine:
$ sudo apt-get install nfs-common nfs-kernel-server
2. The NFS server must know which directories you want to 'export' for clients. This information is specified in the /etc/exports file.
•Modify /etc/exports to look somewhat like this:
$ /nfsroot *(rw,nohide,insecure,no_subtree_check,async,no_root_squash)
•After adding the entry, restart using the following command:
$ sudo /etc/init.d/nfs-kernel-server restart
3. Create an /nfsroot directory on your Linux host machine:
$ sudo mkdir /nfsroot
4. Copy the file system to the nfsroot directory:
$ cd ./rootfs
$ sudo cp -a * /nfsroot
5. Export the root point:
$ sudo exportfs -a
Alternatively, you can export or un-export all directories by using the -a and -u flags. The following command un-exports all directories:
$ sudo exportfs -au
6. (Optional) If the Ubuntu firewall blocks NFS root access, it must be disabled depending on your configuration. You can do so with the following command:
$ sudo ufw disable
7. If there are issues performing the NFS boot, to separately verify everything on the ‘host’ machine is configured properly, you can perform the following step on a booted target board through USB/SD/internal eMMC. It should be possible to mount the host NFS root point on the target device:
$ mkdir rootfs
$ sudo mount -v -o nfsvers=3 <IP-ADDR>:/nfsroot rootfs
Where <IP-ADDR> is the IP address of the Linux Host machine as taken from the ifconfig command. This proves that the host configuration is correct.
Note: Prior to executing the mount command on the target machine, you must install the nfs-common package using the following command:
$ sudo apt-get install nfs-common
To boot the target with the NFS root point, see
Flashing the Boot Loader and Kernel. Be sure to include the
-N option for the nfs root point.
Getting the Kernel Sources
You can manually rebuild the kernel used for this package. Internet access is required.
Sync with git
Prerequisites
•You have installed Git. Install Git with the following command:
$ sudo apt-get install git-core
•Your system has the default Git port 9418 open for outbound connections.
To sync the kernel sources
•Get the kernel source by running the source_sync.sh script:
$ sudo ./source_sync.sh
When prompted enter a ‘tag’ name, as provided in the release notes.
You can sync to any Linux tag you like. However, the tag provided in the release notes syncs the sources to the same source revision the release binary was built from. To see a list of the available release tags, use:
$ git tag -l tegra-l4t*
Manually Download and Expand
As an alternative, you can download the kernel source files and then manually expand them. If possible, it is recommended to instead sync with git.
To manually download and expand
1. In a browser, navigate to:
2. Locate and download the L4T Sources for your release.
3. Expand the TBZ2 file.
$ sudo tar -vxjf sources.tbz2
4. Manually expand the TBZ2 files in the resulting source directory.
Building the NVIDIA Kernel
Follow the steps in this procedure to build the NVIDIA kernel.
Prerequisites
•You have downloaded the kernel source code
To build the Tegra Kernel
1. Export the following environment variables:
$ export CROSS_COMPILE=<crossbin>
$ export TEGRA_KERNEL_OUT=<outdir>
$ export ARCH=arm64
Where:
•<crossbin> is the prefix applied to form the path to the toolchain for cross compilation targeting arm64, e.g., gcc.
The reference arm64 toolchain is:
<aarch64_toolchain_install>/bin/aarch64-unknown-linux-gnu-
•<outdir> is the desired destination for the compiled kernel.
2. Execute the following commands to create the .config:
$ cd <myworkspace>/<kernel_source>
$ mkdir $TEGRA_KERNEL_OUT
Where <kernel_source> directory contains the kernel sources.
$ make O=$TEGRA_KERNEL_OUT tegra18_defconfig
Where <myworkspace> is the parent of the Git root.
3. Execute the following commands to build the kernel:
$ make O=$TEGRA_KERNEL_OUT zImage
4. Execute the following command to create the kernel device tree components:
$ make O=$TEGRA_KERNEL_OUT dtbs
5. Execute the following commands to build the kernel modules (and optionally install them)
$ make O=$TEGRA_KERNEL_OUT modules
$ make O=$TEGRA_KERNEL_OUT modules_install INSTALL_MOD_PATH=<your_destination>
6. Copy both the uncompressed (Image) and compressed (zImage) kernel images over the ones present in the following directory:
Linux_for_Tegra/kernel
7. Replace the contents of Linux_for_Tegra/kernel/dtb/ with the contents of:
$TEGRA__KERNEL_OUT/arch/arm64/boot/dts/
8. Archive the kernel modules created using the following command:
cd <modules_install_path>
tar --owner root --group root -cjf kernel_supplements.tbz2 lib/modules
Use the archive to replace the one in the kernel directory of the release:
Linux_for_Tegra/kernel/kernel_supplements.tbz2
Building External Kernel Modules
The procedures in this section describe how to build an out-of-tree kernel module against kernel headers included in the BSP.
The kernel headers are installed at: /usr/src/linux-headers-<kernel version>
To compile natively on the target system
1. Determine user space architecture with the following command:
getconf LONG_BIT
The command returns 64 for AARCH64.
2. In AARCH64 user space, prepare the kernel headers with the following commands:
$ cd /usr/src/linux-headers-`uname -r`
$ sudo make modules_prepare
3. Build the kernel module.
To cross-compile on another system
1. Uncompress the following kernel headers to a local directory:
<top>/Linux_for_Tegra/kernel/kernel_headers.tbz2
with the following commands:
cd <local src dir>
tar xpf <top>/Linux_for_Tegra/kernel/kernel_headers.tbz2
2. Set up the cross-compile toolchain with the following commands:
export CROSS_COMPILE=<crossbin>
export ARCH=arm64
Where <crossbin> completes path to the tool chain for cross compilation targeting arm64, e.g., gcc.
For this reference toolchain:
<aarch64_toolchain_install>/bin/aarch64-unknown-linux-gnu-
For a Linaro toolchain, the path is similar to the following:
<linaro_install>/aarch64-unknown-linux-gnu/bin/aarch64-unknown-linux-gnu-
3. Prepare the kernel headers with the following commands:
cd <local src dir>/linux-headers-<kernel version>
export ARCH=arm64
sudo make modules_prepare
4. Specify <local_source_directory>/linux-headers-<kernel version> as the kernel source path, with the following line in the make file:
make -C <local src dir>/linux-headers-<kernel version> M=$(PWD) modules
5. Build the kernel module.
OpenGL/EGL Gears Test Application
To run a sample OpenGL/EGL test application, you can run the open-source Gears application.
To install and run Gears test application
1. Boot the target system with an Ethernet connection.
2. Enable package download from the “universe” repository by editing /etc/apt/sources.list as root:
$ sudo vi /etc/apt/sources.list
3. Uncomment the following line in the file by removing the leading # character:
# deb http://ports.ubuntu.com/ubuntu-ports/ xenial universe
4. Update the repository:
$ sudo apt-get update
5. Install the mesa-utils and mesa-utils-extra packages:
$ sudo apt-get install -y mesa-utils
$ sudo apt-get install -y mesa-utils-extra
6. At this point you should be able to run the application with the following steps:
$ export DISPLAY=:0
$ X&
$ /usr/bin/es2gears
GStreamer-based Multimedia Playback (NvGstPlayer)
Use the GStreamer open source multimedia framework and the NvGstPlayer utility for testing multimedia local playback and HTTP/RTSP streaming playback use cases. The NvGstPlayer can be used as a reference implementation.
For more information about the NvGstPlayer application, refer to the ReadMe file included with the release.
Installing GStreamer
Install GStreamer from the Internet directly on the target. The wrapper library, gst-openmax, is an interface between GStreamer and OpenMAX. It enables accelerated NVIDIA plug-ins in the GStreamer framework.
For more information about GStreamer, see the following website:
NvGstPlayer is a multimedia player test application.
Complete prerequisite steps in the file nvgstcapture_README.txt before running the NvGstPlayer and NvGstCapture applications.
Instructions for installing GStreamer are also included in that text file.
Using NvGstPlayer
NvGstPlayer is a command line media file player. It plays audio/video files encapsulated in MP4, 3GP, AVI, ASF, WMA, MKV, M2TS, WEBM, and MOV. NvGstPlayer supports local file playback and playback over RSTP, HTTP, and UDP.
For information about NvGstPlayer runtime commands, default settings, and important notes see the nvgstplayer_README.txt file included in the release.
Gstreamer-based Camera Capture (NvGstCapture)
The NvGstCapture application supports GStreamer version 0.10.36 by default. NvGstCapture captures audio and video data using a microphone and camera and encapsulate encoded A/V data in the container file.
For NvGstCapture installation and usage information, see the nvgstcapture-<VERSION>_README.txt file included with the release at ~Linux_for_Tegra/nv_tegra/nv_sample_apps.
Determining Version and Platform Information
Use the procedures in this section to determine the flashed BSP version, the kernel version, and other platform information.
To determine the BSP version and other platform information
•Determine the BSP version and other platform information with the following command:
head -1 /etc/nv_tegra_release
Output from that command is similar to the following:
#R27 (release), REVISION: 1.0, GCID: 7164062, BOARD: t186ref, EABI: aarch64, DATE: Tue Mar 03 23:37:30 UTC 2017
To determine the kernel version
•Determine the kernel version, with the following command in the kernel directory:
head -4 Makefile
Output is similar to the following:
VERSION = 4
PATCHLEVEL = 4
SUBLEVEL = 15
Or, if the system is running, determine the kernel version with the following command:
uname -a
Output is similar to the following:
Linux tegra-ubuntu 4.4.15-tegra #1 SMP PREEMPT Tue Mar 03 16:29:05 PDT 2017 aarch64 aarch64 aarch64 GNU/Linux
To determine boot configuraition
Determine the boot configuration from the following information.
•Boot option: l4t/config/t186ref/p2771-0000/extlinux.conf.emmc
•‘FDT /boot/tegra186-quill-p3310-1000-a00-00-base.dtb’ indicates the board device tree blob file. The source is located at:
arch/arm64/boot/dts/tegra186-quill-p3310-1000-a00.dts.
•Default u-boot build configuration:
•3rdparty/u-boot/configs/p2771-0000-000_defconfig
and/or
•3rdparty/u-boot/configs/p2771-0000-500_defconfig
•Default kernel build configuration: arch/arm64/configs/tegra18_defconfig
NVIDIA Bug Reporting Script
For debugging purposes, attach the log file to communicate issues found with the release. Use the nvidia-bug-report-tegra.sh script to generate log files.
To generate a log file for bug reporting
•Log into the target board and enter the following command:
$ sudo /usr/bin/nvidia-bug-report-tegra.sh
To generate a log file for bug reporting with extended logging mode
•Log into the target board and enter the following command:
$ sudo /usr/bin/nvidia-bug-report-tegra.sh -e
By default, the logfile generated by both these procedures is located at:
$HOME/nvidia-bug-report-tegra.log
Attach a log file when reporting any issues to NVIDIA, whether through email or the forums.
