Revision History

Version Date Description

1

2012/12/09

Initial Release

2

2013/07/03

Mention tegra-uboot-flasher

3

2014/09/26

Updates for U-Boot’s recent USB device mode capabilities.

Introduction

This document provides a brief overview of tools such as nvflash and tegrarcm, which are used to program flash devices attached to Tegra, and related tasks.

Boot ROM And Miniloader

All tools described here initially communicate with the Tegra boot ROM using the RCM protocol. This protocol primarily allows arbitrary code to be downloaded into IRAM, and executed on the AVP. In practice, both nvflash and tegrarcm download a binary known as the miniloader.

The miniloader communicates over USB using another custom NVIDIA protocol known as nv3p. The miniloader and nv3p protocol implement a few more commands than the RCM protocol. In particular, one command allows a BCT to be downloaded, and the SDRAM controller to be configured and enabled using data from that BCT. A second command allows arbitrary code to be downloaded into SDRAM and executed on the AVP. This is useful because SDRAM is much larger than the AVP’s IRAM, and hence a much more complete application can fit into it.

The downloaded application may serve various purposes. For example:

  • During bootloader development, the bootloader may be sent directly to SDRAM via the miniloader. This avoids the need to write the bootloader into flash. This can speed up the development and test process significantly.

  • In order to write to flash devices, some form of flash-writing application may be downloaded.

tegrarcm

tegrarcm exists solely to perform the steps described above; to allow an arbitrary application to be downloaded into SDRAM and executed. Both use-cases described above are applicable.

In the flash-writing use-case, the downloaded application would typically be U-Boot, which in turn allows interactive or scripted execution of commands that write to flash devices. U-Boot might acquire the image to be flashed from an SD-card or other storage device, over the network, or directly from RAM downloaded along with U-Boot. The cbootimage tool exists to create the flash image itself.

Recent versions of U-Boot support USB device mode operation. A couple of protocols are currently supported; Mass Storage and DFU (Device Firmware Update). These allow the host machine to program flash interactively using standard protocols.

tegra-uboot-flasher

tegra-uboot-flasher is a set of scripts that build and use cbootimage, cbootimage-configs, tegrarcm, and U-Boot to flash Tegra devices in a simple way. Operation requires just the RCM protocol. For more details, please see the README at:

https://github.com/NVIDIA/tegra-uboot-flasher-scripts/blob/master/README-developer.txt

Nvflash

nvflash’s aim is to be a monolithic flashing tool for Tegra.

A few of nvflash’s commands communicate directly with the miniloader. For example, --getbct, which obtains a copy of the BCT currently programmed into flash.

Like tegrarcm, nvflash downloads an application into SDRAM via the miniloader. The filename of that application (known as the bootloader) must be specified using the --bl command-line option. This allows nvflash to download an arbitrary application into SDRAM. Hence, nvflash is capable of performing the bootloader development use-case mentioned in Downloaded Application above.

Generally though, nvflash expects to download NVIDIA’s "fastboot" bootloader, and then communicate with it using an extended nv3p protocol. nvflash can both write portions of the device’s flash, and/or read back parts of the device’s flash to the host machine.

When flashing a device from scratch, nvflash will read a configuration file describing the partition layout of the flash. The BCT, bootloader, and optionally other partition content will all be packed together online by nvflash, and then sent to fastboot to be written to flash. This process includes updating the BCT fields that specify the flashed bootloader location and hash, and re-signing the BCT if required. As such, cbootimage is not needed when using nvflash.

nvflash’s -r (resume) option expects that fastboot is already executing on the target, and hence communication can be initiated directly using nv3p, rather than having to download the miniloader and then fastboot first.

Tegra Partition Table

When flashing a device from scratch, nvflash reads a configuration file describing the layout of the target flash device. The flash layout is written as a list of partitions. Partions may have special types, such as:

  • boot_config_table (typically named BCT) to which the BCT will be written.

  • partition_table (typically named PT) to which a representation of the flash layout will be written. Note that this partition table format is custom to NVIDIA; it is not a standard format such as MBR or GPT.

  • bootloader (typically named EBT) to which the bootloader will be written, and the BCT updated to point at.

  • data (…) a general data partition, for example a kernel or root filesystem image.

  • GPT (typically named GPT) to which a representation of the flash layout will be written, in standard GPT (GUID Partition Table) format. This particular should be last in the list, since it is intended to act as the secondary/backup GPT at the end of the device.

eMMC Partition Concatenation

eMMC devices (but not SD cards) often have their own HW-level partitioning, exposing perhaps 2 "boot sectors" of ~1-4 MB, and a general region covering the rest of the flash device. Software typically treats those regions as separate devices or disks, and expects a standard partition table at the beginning of the general region. This is certainly the case with recent versions of U-Boot and the Linux kernel.

However, nvflash and NVIDIA’s fastboot bootloader view the eMMC as a single linear device, which includes both boot-sectors and the general region concatenated together. The BCT, PT, and EBT partitions are often larger than the eMMC device’s physical bootsectors. This prevents a standard MBR or GPT partition table from existing at the start of the general region.

Some possible workarounds exist in this scenario:

  • NVIDIA’s fastboot bootloader passes custom command-line arguments to the Linux kernel, derived from the PT partition table, indicating the partition layout of the device. Note that support for these custom command-line arguments only exists in NVIDIA’s downstream kernel; it does not exist in the upstream Linux kernel, and upstream U-Boot is not capable of creating these command-line arguments to pass to the kernel.

  • Some software will find and use the secondary/backup GPT if present. You should not attempt to manipulate the partition layout using a standard GPT editing tool.

  • If you intend to use or repurpose your device for use with upstream U-Boot and Linux kernel, you may ignore nvflash, create a flashable image using cbootimage, write that image to the eMMC’s boot sector(s), and then place a standard partition table at the beginning of the eMMC’s general region.