tegrarcm(1)

📦
version 1.9 · 2 versions
, in epel 10, fedora 43, fedora 44

💖 tegrarcm — Tegra firmware download utility 💖

okay bestie, gather round, because tegrarcm (that's the manual page tegrarcm(1) if we're being formal, which we are not) is about to become your new hyperfixation. this tool talks to Tegra devices in recovery mode and yeets code at them. let's get into it 🦋

✨ SYNOPSIS ✨

tegrarcm [ options ]

that's it. that's the whole vibe. options only, no positional drama. 💅

🌸 DESCRIPTION 🌸

so basically? this program sends code to a Tegra device that's sitting in recovery mode. it works with unlocked devices, and it also works with devices that are locked with a PKC (private key) — yes queen, it handles both.

⚠️ real talk: it is not capable of flashing firmware to a device. it can, however, download firmware that is then capable of flashing. that's the whole bit. for example, in ChromeOS tegrarcm is used to download a special build of U-Boot to the target Tegra device, with a payload that it then flashes to the boot memory device. slay. 🔥

devices with PKC enabled can be handled in two different ways, and you gotta pick your fighter:

  1. Data may be signed on-the-fly, during communication with the Tegra device, by providing the --pkc options. this method is the simplest, but it requires access to the device's PKC during the download process. it's giving "convenient but you gotta have the key on you" energy.
  2. The signing and download steps may be separated. signed data may first be prepared offline, without requiring access to a Tegra device, using the --gen-signed-msgs option. the signed data may later be sent to a Tegra device using the --download-signed-msgs option.

both of these steps require use of the --signed-msgs-file option to indicate where to write/read the signed messages. this option provides a base filename, to which various extensions will be appended, to form the final filenames for the various signed data/messages. (yes, it's a prefix situation, not a full filename situation. noted. 📝)

this method is more complex, but it allows separation of the download and signing processes. for example, a highly secure signing machine could generate the signed messages and pass them to a factory system for download to the Tegra device. very "separation of church and state" of them, we love a security boundary. 👑

🧚 Platforms supported 🧚

  • Tegra20
  • Tegra30
  • Tegra114
  • Tegra124

🎀 How to use 🎀

  • Connect a USB cable from your development system to your Tegra device. you will either need a USB A to A cable or A to micro B depending on the target board. check your cables bestie, this is the number one cause of sadness. 😭
  • Find the appropriate BCT file for your board. for reference boards, BCT files can be found in the L4T distribution from NVIDIA.
  • Build some firmware for your device (such as U-Boot).
  • Run tegrarcm to download the firmware. that's the moment. the main character moment. ✨

👑 COMMANDS 👑

  • readbct — Read the BCT from the target device and write it to bctfile.

💅 OPTIONS 💅

  • --bct bctfile — Specify the BCT file to download to the Tegra device. this file contains memory configuration information for the board. BCT files can be obtained through the NVIDIA L4T distribution or generated with cbootimage and a proper configuration file.
  • --bootloader blfile — Specify the bootloader file to download to the Tegra device. this is the firmware file that will be downloaded and executed. the whole point, honestly. 🔥
  • --loadaddr loadaddr — Specify the address the bootloader will be loaded at. this should be specified in hex and is typically 0x108000 for a Tegra20 device or 0x80108000 for a Tegra30, Tegra114, or Tegra124 device. no pressure but get the number right. 💀
  • --entryaddr entryaddr — Specify the entry address that control will be passed to after the firmware is loaded. this should be specified in hex. if this option is omitted it is assumed to be the same as the load address. so like, it defaults to --loadaddr. cute of it. 🎀
  • --version — Print the version number and exit.
  • --help — Print help text and exit.
  • --miniloader mlfile — Read the miniloader from the specified file instead of using the built-in one. yes, there's a built-in one. no, you don't have to use it. 🦋
  • --miniloader_entry mlentry — Specify the entry address of the miniloader.
  • --usb-port-path path — Specify the physical USB port path of the Tegra device to control. (more on this in a sec, keep reading, it's a whole thing.)
  • --pkc key.der — Specify the key file for secured devices. the private key should be in DER format. ⚠️ keep this file safe, it's literally the private key.
  • --gen-signed-msgs — Generate signed messages for PKC secured devices.
  • --signed-msgs-file msg_file_prefix — Specify messages file name prefix. (prefix! not full filename! the extensions get appended!)
  • --download-signed-msgs — Download signed messages.
  • --soc tegra_soc_# — Specify Tegra SoC chip model number, ie, 124.
  • --usb-timeout timeout_ms — Specify usb transfer timeout value in ms, 0 for unlimited timeout. zero means "we wait forever, we're committed". 😤

🌈 USB PORT PATH 🌈

by default, tegrarcm operates on the first USB applicable device it finds. in a system that contains multiple Tegra devices, the user may wish to specify which device tegrarcm should operate upon. the --usb-port-path option allows this, and it does it in a manner that is most immune to the set of attached USB devices varying</b>. iconic behavior honestly.

note that the USB port path is associated with a physical USB port on a particular hub. this value will vary if you physically re-organize your USB connections. this feature is still useful even if your USB topology changes, providing you have some other mechanism to differentiate attached devices. for example, you could use a wrapper script around tegrarcm that identifies the appropriate device by other means, then automatically calculates the USB port path using the procedures below, and passes the value to tegrarcm. automation girlies rise up. 🤖

to determine the USB port path of a device, you must plug it in and find the current USB bus and USB device number of the device, then map that to the USB port path. simply run lsusb to find the current USB bus and device number. if you have multiple NVIDIA devices attached, you may need to unplug and replug the Tegra device to ensure you know which is which (all while not changing the state of any other USB devices so you don't confuse yourself). unplugging is the diagnostic tool of the people. 🙈

$ lsusb
[...]
Bus 003 Device 039: ID 0955:7721 NVidia Corp.
Bus 003 Device 045: ID 0955:7140 NVidia Corp.
[...]

then, to determine the USB port path, do one of these two things:

  1. Execute udevadm on the USB device, and look for the DEVPATH entry. the final component in the path is the USB port path:
$ udevadm info /dev/bus/usb/003/045
P: /devices/pci0000:00/0000:00:14.0/usb3/3-10/3-10.4
N: bus/usb/003/045
E: BUSNUM=003
E: DEVNUM=045
E: DEVPATH=/devices/pci0000:00/0000:00:14.0/usb3/3-10/3-10.4
  1. Look at all the sub-directories of /sys/bus/usb/devices/* that do not contain either ":" or "usb". each of these will contain a busnum and devnum file. find the directory which matches the lsusb output, and use its name:
$ cat /sys/bus/usb/devices/3-10.4/busnum
3
$ cat /sys/bus/usb/devices/3-10.4/devnum
45

alternatively, you may already have udev rules that create a device node symlink for the device (after some specific identification algorithm). in that case, you can search the udev output for MAJOR/MINOR values, or /sys/bus/usb/devices/* directories for "dev" files, that match the device node the symlink points to. iykyk. 💜

once the port path is known, this value will not vary unless your USB connections are physically changed, so you can use it over and over without repeating the steps above. set it and forget it, bestie. 🫶

🎀 EXAMPLES 🎀

okay bestie, this is the part where it gets real. these are the actual vibes-in-action moments, fr fr. copy these, run these, live these. ✨

1. the classic: download U-Boot to Seaboard, no PKC 💅

so like, no PKC enabled at all, just a straight-up download. the command:

$ sudo tegrarcm --bct seaboard.bct --bootloader u-boot.bin --loadaddr 0x108000

and the output? it's giving main character. here's exactly what you'll see:

bct file: seaboard.bct
bootloader file: u-boot.bin
load addr 0x108000
entry addr 0x108000
device id: 0x7820
uid:  0x33c20c0413fb217
RCM version: 2.1
downloading miniloader to target...
miniloader downloaded successfully
Chip UID:                0x33c20c0413fb217
Chip ID:                 0x20
Chip ID Major Version:   0x1
Chip ID Minor Version:   0x4
Chip SKU:                0x18 (t25)
Boot ROM Version:        0x1
Boot Device:             0x3 (SPI)
Operating Mode:          0x3 (developer mode)
Device Config Strap:     0x0
Device Config Fuse:      0x0
SDRAM Config Strap:      0x0
sending file: seaboard.bct
- 4080/4080 bytes sent
seaboard.bct sent successfully
sending file: u-boot.bin
- 268314/268314 bytes sent
u-boot.bin sent successfully

miniloader downloaded successfully?? ate. that line right there is the serotonin boost, no cap. 💖

2. read the BCT from a system 📖

when you just need to read the BCT off the thing and write it into a file, like a lil bookworm:

$ sudo tegrarcm --bct ventana.bct readbct

and it goes:

bct file: ventana.bct
device id: 0x7820
reading BCT from system, writing to ventana.bct...done!

short. sweet. done. periodt. ✨

3. Jetson TK1, PKC enabled, one single step 👑

here's the glow-up: PKC on, everything in one command, no extra steps. we love an efficient queen:

$ sudo tegrarcm --bct=jetson-tk1.bct --bootloader=u-boot.bin --loadaddr=0x83d88000 --pkc=rsa_priv.der

the output, in all its glory:

bct file: jetson-tk1-bct.bct
bootloader file: u-boot.bin
load addr 0x83d88000
entry addr 0x83d88000
device id: 0x7140
uid:  0x640010017410b1000000000016020540
RCM version: 64.1
downloading miniloader to target at address 0x4000e000 (136920 bytes)...
miniloader downloaded successfully
Chip UID:                0x000000017410b1000000000016020540
Chip ID:                 0x40
Chip ID Major Version:   0x1
Chip ID Minor Version:   0x1
Chip SKU:                0x81 (t124)
Boot ROM Version:        0x1
Boot Device:             0x2 (EMMC)
Operating Mode:          0x6 (odm secure mode with PKC)
Device Config Strap:     0x0
Device Config Fuse:      0x0
SDRAM Config Strap:      0x3
sending file: jetson-tk1-bct.bct
- 8192/8192 bytes sent
jetson-tk1-bct.bct sent successfully
sending file: u-boot.bin
| 440004/440004 bytes sent
u-boot.bin sent successfully
tiny lil detail, bestie: that progress bar for u-boot.bin uses | here instead of -. iconic, honestly. the tool contains multitudes. 💀

4. generate signed messages for later (PKC szn) 🔐

so instead of downloading right away, you're pre-making the signed messages so you can download later. very "planning ahead" of you, very responsible queen energy:

$ sudo tegrarcm --gen-signed-msgs --signed-msgs-file rel_1001.bin --bootloader=u-boot.bin --loadaddr 0x83d88000 --soc 124 --pkc rsa_priv.der

and out comes:

bootloader file: u-boot.bin
load addr 0x83d88000
entry addr 0x83d88000
Create file rel_1001.bin.qry...
Create file rel_1001.bin.ml...
Create file rel_1001.bin.bl...

three files, all signed up, all ready. look at you being all prepared. 🦋

5. download those previously-generated signed messages 🫶

and now you actually send the things you made in example 4. the full slay:

$ sudo tegrarcm --download-signed-msgs --signed-msgs-file rel_1001.bin --bct=jetson-tk1-bct.bct --bootloader=u-boot.bin --loadaddr 0x83d88000

and the whole thing unfolds like this:

bct file: jetson-tk1-bct.bct
bootloader file: u-boot.bin
load addr 0x83d88000
entry addr 0x83d88000
device id: 0x7140
uid:  0x640010017410b1000000000016020540
download signed query version rcm from file rel_1001.bin.qry
RCM version: 64.1
download signed miniloader rcm from file rel_1001.bin.ml
downloading miniloader to target at address 0x4000e000 (137572 bytes)...
miniloader downloaded successfully
Chip UID:                0x000000017410b1000000000016020540
Chip ID:                 0x40
Chip ID Major Version:   0x1
Chip ID Minor Version:   0x1
Chip SKU:                0x81 (t124)
Boot ROM Version:        0x1
Boot Device:             0x2 (EMMC)
Operating Mode:          0x6 (odm secure mode with PKC)
Device Config Strap:     0x0
Device Config Fuse:      0x0
SDRAM Config Strap:      0x3
sending file: jetson-tk1-bct.bct
- 8192/8192 bytes sent
jetson-tk1-bct.bct sent successfully
sending file: rel_1001.bin.bl
- 256/256 bytes sent
rel_1001.bin.bl sent successfully
sending file: u-boot.bin
| 440004/440004 bytes sent
u-boot.bin sent successfully

see how it pulls .qry, .ml and .bl back off the --signed-msgs-file prefix? that's the whole point of generating them ahead of time. chef's kiss. 😭💖

💀 RETURN VALUE 💀

if anything goes wrong — any error, any little oopsie — you get a non zero exit status back. that's it, that's the tea. zero means we're chilling, non-zero means something went sideways, bestie. check it in your scripts, i'm begging you. 🙈

👀 SEE ALSO 👀

go read that one too, it's the sibling. family matters. 💜

🌸 AUTHOR 🌸

Allen Martin, <amartin@nvidia.com>

thank you for your service, king. 🫶👑

<div align="center">

and that's the whole page, bestie!! 🎀✨

this masterpiece is tegrarcm-1.9, dated 29 November 2012 — a true vintage icon, serving looks since 2012 and still hitting different. 💅

now go flash something. you got this. mwah. 💖🦋🌸

</div>

📦 where this page comes from