Flashers Driver

The flasher drivers are used to flash images to DUTs via network, typically using TFTP and HTTP. It is designed to interact with the target bootloader and busybox shell to flash the DUT.

All flasher drivers inherit from the jumpstarter_driver_flashers.driver.BaseFlasher class, referencing their own bundle of binary artifacts necessary to flash the DUT, like kernel/initram/dtbs. See the bundle section for more details.

Installation

:substitutions:
$ pip3 install --extra-index-url {{index_url}} jumpstarter-driver-flashers

Configuration

Available drivers and bundles

Driver	Bundle
TIJ784S4Flasher	quay.io/jumpstarter-dev/jumpstarter-flasher-ti-j784s4:latest

Driver configuration

driver: jumpstarter_driver_flashers.driver.${DRIVER}

export:
  storage:
    type: "jumpstarter_driver_flashers.driver.TIJ784S4Flasher"
    children:
      serial:
        ref: "serial"
      power:
        ref: "power"
  serial:
    type: "jumpstarter_driver_pyserial.driver.PySerial"
    config:
      url: "/dev/serial/by-id/usb-FTDI_USB__-__Serial_Converter_112214101760A-if00-port0"
      baudrate: 115200
  power:
    type: jumpstarter_driver_yepkit.driver.Ykush
    config:
      serial: "YK112233"
      port: "1"

flasher drivers require four children drivers:

Child Driver	Description	Auto-created
serial	To communicate with the DUT via serial and drive the bootloader and busybox shell	No
power	To power on and off the DUT	No
tftp	To serve binaries via TFTP	Yes
http	To serve the images via HTTP	Yes

The power driver is used to control power cycling of the DUT, and the serial interface is used to communicate with the DUT bootloader via serial. TFTP and HTTP servers are used to serve images to the DUT bootloader and busybox shell.

Config parameters

Parameter	Description	Type	Required	Default
flasher_bundle	The OCI bundle to use for the flasher	str	yes
cache_dir	The directory to cache the images	str	no	/var/lib/jumpstarter/flasher
tftp_dir	The directory to serve the images via TFTP	str	no	/var/lib/tftpboot
http_dir	The directory to serve the images via HTTP	str	no	/var/www/html
variant	The variant of the DUT DTB to flash to	str	no	(the default defined in the manifest)
manifest	The manifest to use from the bundle. Every bundle can have multiple manifests, this is the name of the manifest to use	str	no	manifest.yaml
default_target	The default target to flash to if none specified	str	no

oci-bundles

The flasher drivers require some artifacts and basic information about the target device to operate. To make this easy to distribute and use, we use OCI bundles to package the artifacts and metadata.

The bundle is a container that uses oras to transport the artifacts and metadata. It is a container that contains the following:

• manifest.yaml: The manifest file that describes the bundle
• data/*: The artifacts, including kernel, initram, dtbs, etc.

The format of the manifest is as follows:

:language: yaml

Table with the spec fields of the manifest:

Field	Description	Default
manufacturer	Name of the device manufacturer
link	URL to device documentation or manufacturer website
bootcmd	Command used to boot the device (e.g. booti, bootz)
default_target	Default target device to flash to if none specified
targets	Map of target names to device paths
login.type	Type of login shell	busybox
login.login_prompt	Expected login prompt string	login:
login.username	Username to log in with, leave empty if not needed
login.password	Password for login, leave empty if not needed
login.prompt	Shell prompt after successful login	#
preflash_commands	List of commands to run before flashing, useful to clear boot entries, etc
kernel.file	Path to kernel image within bundle
kernel.address	Memory address to load kernel to
initram.file	Path to initramfs within bundle (if any)
initram.address	Memory address to load initramfs to (if any)
dtb.default	Default DTB variant to use
dtb.address	Memory address to load DTB to
dtb.variants	Map of DTB variant names to files

Bundle Examples

An example bundle for the TI J784S4XEVM looks like this:

:language: yaml

You can find a script to build and push a bundle to a registry here: oci_bundles

Usage

CLI

The flasher driver provides a CLI to perform flashing, access to busybox shell and uboot.

$ jmp shell -l board=ti-03
INFO:jumpstarter.client.lease:Created lease request for labels {'board': 'ti-03'} for 0:30:00
jumpstarter ⚡remote ➤ j storage
Usage: j storage [OPTIONS] COMMAND [ARGS]...

  Software-defined flasher interface

Options:
  --help  Show this message and exit.

Commands:
  bootloader-shell  Start a uboot/bootloader interactive console
  busybox-shell     Start a busybox shell
  flash             Flash image to DUT from file

flash

Usage: j storage flash [OPTIONS] [FILE]

  Flash image(s) to DUT

  Usage examples:

  - Flash to default block device and target

      j storage flash image.img

  - Flash to specific block device (e.g., 'emmc')

      j storage flash image.img --target emmc

  - Flash to partition(s) on default block device

      j storage flash -t rootfs:rootfs.img

  - Flash to partition(s) on specific block device

      j storage flash --target emmc -t rootfs:rootfs.img -t boot:boot.img

Options:
  --target TEXT                  Block device to flash to (e.g., 'usd',
                                 'emmc'). If not provided, uses default
                                 target.
  -t TEXT                        Flash file to partition:
                                 'partition:filename'. Can be repeated for
                                 multiple partitions.
  --os-image-checksum TEXT       SHA256 checksum of OS image (direct value)
  --os-image-checksum-file FILE  File containing SHA256 checksum of OS image
  --force-exporter-http          Force use of exporter HTTP
  --force-flash-bundle TEXT      Force use of a specific flasher OCI bundle
  --cacert FILE                  CA certificate to use for HTTPS
  --insecure-tls / -k            Skip TLS certificate verification
  --header TEXT                  Custom HTTP header in 'Key: Value' format
  --bearer TEXT                  Bearer token for HTTP authentication
  --retries INTEGER              Number of retry attempts for flash operation
                                 (default: 3)
  --method [fls|shell]           Method to use for flash operation (default:
                                 fls)
  --fls-version TEXT             Download an specific fls version from the
                                 github releases
  --fls-binary-url TEXT          Custom URL to download FLS binary from
                                 (overrides --fls-version)
  --power-off / --no-power-off   Power off device after flashing (default)
  --console-debug                Enable console debug mode
  --help                         Show this message and exit.

Example:

jumpstarter ⚡remote ➤ j storage flash https://autosd.sig.centos.org/AutoSD-9/nightly/TI/auto-osbuild-am69sk-autosd9-qa-regular-aarch64-1716106242.66b4d866.raw.xz
BaseFlasherClient - INFO - Writing image to storage in the background: /AutoSD-9/nightly/TI/auto-osbuild-am69sk-autosd9-qa-regular-aarch64-1716106242.66b4d866.raw.xz
BaseFlasherClient - INFO - Setting up flasher bundle files in exporter
BaseFlasherClient - INFO - Writing image from storage, with metadata: md5=None,size=592736176 etag="23546fb0-63045567a5b80"
SNMPServerClient - INFO - Starting power cycle sequence
SNMPServerClient - INFO - Waiting 2 seconds...
SNMPServerClient - INFO - Power cycle sequence complete
BaseFlasherClient - INFO - Waiting for U-Boot prompt...
BaseFlasherClient - INFO - Running DHCP to obtain network configuration...
BaseFlasherClient - INFO - Running command: dhcp
BaseFlasherClient - INFO - Running command: printenv netmask
BaseFlasherClient - INFO - discovered dhcp details: DhcpInfo(ip_address='x.x.x.x', gateway='x.x.x.x', netmask='255.255.255.0')
BaseFlasherClient - INFO - Image written to storage: /AutoSD-9/nightly/TI/auto-osbuild-am69sk-autosd9-qa-regular-aarch64-1716106242.66b4d866.raw.xz
BaseFlasherClient - INFO - Running command: setenv serverip 'x.x.x.x'
BaseFlasherClient - INFO - Running command: tftpboot 0x82000000 J784S4XEVM.flasher.img
BaseFlasherClient - INFO - Running command: tftpboot 0x84000000 k3-j784s4-evm.dtb
BaseFlasherClient - INFO - Running boot command: booti 0x82000000 - 0x84000000
BaseFlasherClient - INFO - Using target block device: /dev/mmcblk1
BaseFlasherClient - INFO - Running preflash command: dd if=/dev/zero of=/dev/mmcblk0 bs=512 count=34
BaseFlasherClient - INFO - Running preflash command: dd if=/dev/zero of=/dev/mmcblk1 bs=512 count=34
BaseFlasherClient - INFO - Waiting until the http image preparation in storage is completed
BaseFlasherClient - INFO - Flash progress: 25.00 MB, Speed: 15.78 MB/s
...
...
BaseFlasherClient - INFO - Flash progress: 5086.12 MB, Speed: 13.77 MB/s
BaseFlasherClient - INFO - Flash progress: 5102.94 MB, Speed: 12.93 MB/s
BaseFlasherClient - INFO - Flushing buffers
BaseFlasherClient - INFO - Flashing completed in 7:26
BaseFlasherClient - INFO - Powering off target

Flash from a private OCI registry with credentials:

OCI_USERNAME=myuser OCI_PASSWORD=mypassword \
  j storage flash oci://registry.example.com/org/image:tag

Environment variables for OCI auth:

• OCI_USERNAME: registry username
• OCI_PASSWORD: registry password

bootloader-shell

Usage: j storage bootloader-shell [OPTIONS]

  Start a uboot/bootloader interactive console

Options:
  --console-debug  Enable console debug mode
  --help           Show this message and exit.

Example

jumpstarter ⚡remote ➤ j storage bootloader-shell
BaseFlasherClient - INFO - Setting up flasher bundle files in exporter
SNMPServerClient - INFO - Starting power cycle sequence
SNMPServerClient - INFO - Waiting 2 seconds...
SNMPServerClient - INFO - Power cycle sequence complete
BaseFlasherClient - INFO - Waiting for U-Boot prompt...
=> version
U-Boot 2024.01-rc3 (Jan 09 2024 - 00:00:00 +0000)

gcc (GCC) 11.4.1 20231218 (Red Hat 11.4.1-3)
GNU ld version 2.35.2-42.el9

busybox-shell

Usage: j storage busybox-shell [OPTIONS]

  Start a busybox interactive console

Options:
  --console-debug  Enable console debug mode
  --help           Show this message and exit.

Example

jumpstarter ⚡remote ➤ j storage busybox-shell
BaseFlasherClient - INFO - Setting up flasher bundle files in exporter
SNMPServerClient - INFO - Starting power cycle sequence
SNMPServerClient - INFO - Waiting 2 seconds...
SNMPServerClient - INFO - Power cycle sequence complete
BaseFlasherClient - INFO - Waiting for U-Boot prompt...
BaseFlasherClient - INFO - Running DHCP to obtain network configuration...
BaseFlasherClient - INFO - Running command: dhcp
BaseFlasherClient - INFO - Running command: printenv netmask
BaseFlasherClient - INFO - discovered dhcp details: DhcpInfo(ip_address='10.26.28.138', gateway='10.26.28.254', netmask='255.255.255.0')
BaseFlasherClient - INFO - Running command: setenv serverip '10.26.28.62'
BaseFlasherClient - INFO - Running command: tftpboot 0x82000000 J784S4XEVM.flasher.img
BaseFlasherClient - INFO - Running command: tftpboot 0x84000000 k3-j784s4-evm.dtb
BaseFlasherClient - INFO - Running boot command: booti 0x82000000 - 0x84000000
# uname -a
Linux buildroot 6.1.46-dirty #2 SMP PREEMPT Thu Mar 14 14:37:01 UTC 2024 aarch64 GNU/Linux
#

Python Examples

Flash the device with a specific image

flasherclient.flash("/path/to/image.raw.xz")

Flash the device with a specific image from a remote URL

flasherclient.flash("https://autosd.sig.centos.org/AutoSD-9/nightly/TI/auto-osbuild-j784s4evm-autosd9-qa-regular-aarch64-1716106242.66b4d866.raw.xz")

Flash into a specific partition

flasherclient.flash("/path/to/image.raw.xz", partition="emmc")

Utility Consoles

In addition to the flashing mechanisms, the flasher drivers also provide a way to access the DUT bootloader and busybox shell for convenience and debugging, when using the busybox_shell and bootloader_shell methods the embedded http and tftp servers will be online and serving the images from the flasher bundle.

Get the busybox shell on the device

with flasherclient.busybox_shell() as serial:
    serial.send("ls -la\n")
    serial.expect("#")
    print(serial.before)

Get the bootloader shell on the device

with flasherclient.bootloader_shell() as serial:
    serial.send("version\n")
    serial.expect("=>")
    print(serial.before)

API Reference

The BaseFlasher class provides a set of methods to flash the DUT,

.. autoclass:: jumpstarter_driver_flashers.client.BaseFlasherClient()
    :members: flash, busybox_shell, bootloader_shell, use_dtb, use_initram, use_kernel