Skip to content

Program Software on Kontron AM62L OSM-S/BL/DK#

The snagboot tool suite from Bootlin is an open-source, generic solution for the recovery and flashing of embedded platforms. It accesses the hardware through the USB protocols provided by the ROM code of the SoC and by the running bootloader. snagboot consists of three command line tools:

  • snagrecover uses the ROM code of the SoC to set up the external RAM and to start a bootloader provided by the host PC. No non-volatile memory (eMMC, SPI NOR) is modified in this step.
  • snagflash communicates with the running bootloader (U-Boot) to write images to the non-volatile memories, using either DFU, UMS or Fastboot.
  • snagfactory provides a GUI which orchestrates both of the above tools. It recovers and flashes a group of boards in parallel, driven by a single configuration file and without any interaction with the U-Boot console.

For programming our boards, we use snagfactory, because the whole procedure — from recovering the SoC up to resetting the flashed board — is described in one YAML file, which can be kept under version control and reused for every board.

The manual workflow with snagrecover and snagflash is described in the second part of this guide.

Both the ROM code of the SoC and the DFU gadget of U-Boot are standard USB DFU devices, so the board can also be started and programmed with plain dfu-util, without snagboot — see Flashing U-Boot without Snagflash over DFU.

Up-to-Date Bootloader and snagboot Required

Support for the AM62Lx family was added in snagboot v2.2, so at least this version is required (this guide was written against v3.0.1).

Installing snagboot on Linux#

snagboot is a Python package available on PyPI. It is best installed with pipx, which keeps the tools in their own virtual environment:

$ pipx install snagboot

The package provides the command line tools snagrecover, snagflash and snagfactory.

snagfactory needs the optional GUI dependencies, so install the package with the gui extra instead if you want to use it:

$ pipx install 'snagboot[gui]'

In addition, udev rules have to be installed so that the tools get read and write access to the USB devices exposed by the SoC without root privileges:

$ snagrecover --udev > 50-snagboot.rules
$ sudo cp 50-snagboot.rules /etc/udev/rules.d/
$ sudo udevadm control --reload-rules
$ sudo udevadm trigger

Do Not Run snagboot as root

Running snagboot as root is not recommended and will typically fail, since the package is installed for the current user only. The udev rules above are what makes access to the USB devices possible without root privileges.

To list the supported SoC models and check the name to use with the -s option and in the snagfactory configuration file, run:

$ snagrecover --list-socs

Installing snagboot on Windows#

snagboot also runs on Windows 10 and 11, either via an executable installer or via pip. In both cases the "libusb-win32" driver has to be bound to the USB device of the board. See the snagboot installation guide for details.

Putting the Board into Recovery Mode#

The workflows start with a board that exposes the USB DFU device of its ROM code. Prerequisites:

  • Switch S1 on the board set to 1 (ON), which puts it into recovery mode
  • Board connected to the PC via the USB OTG port
  • SoC booting from DFU

DFU Boot Mode

In recovery mode (S1 = 1) the ROM code of the AM62L skips the eMMC and exposes a USB DFU device. If no valid boot code is provided over DFU, it falls back to the SD card. The eMMC is ignored for as long as S1 is set to 1.

Programming with snagfactory#

snagfactory needs a configuration file that describes the recovery images and the flashing tasks for the board. Once this file is loaded, the tool detects every board in DFU mode, starts a bootloader on it and then runs the flashing tasks over Fastboot.

Writing the Configuration File#

The configuration file has two top-level sections:

  • boards maps the USB IDs (vid:pid) of a board in recovery mode to the SoC model used for it.
  • soc-models contains a <soc-model>-firmware section with the recovery images and a <soc-model>-tasks section with the flashing pipeline for every SoC model referenced under boards.

The following configuration starts the bootloader images tiboot3.bin, tispl.bin and u-boot.img in the RAM of the board, writes the bootloader flash-emmc.bin to the boot partition of the eMMC, writes the WIC image to the user area, and finally configures the eMMC to boot from its boot partition:

am62l-factory.yaml
boards:
  "0451:6165": "am62l3"

soc-models:
  am62l3-firmware:
    tiboot3:
      path: "tiboot3.bin"
    tispl:
      path: "tispl.bin"
    u-boot:
      path: "u-boot.img"

  am62l3-tasks:
    - target-device: mmc0
      fb-buffer-addr: 0x82000000

    - task: flash
      args:
        - part: "hwpart 1"            # Boot partition 0 - eMMC
          image: "flash-emmc.bin"
        - part: "hwpart 1"
          image: "u-boot.env"
          image-offset: 0x1E0000      # primary environment
        - part: "hwpart 1"
          image: "u-boot.env"
          image-offset: 0x1F0000      # redundant environment
        - part: "hwpart 0"            # User Data Area - eMMC
          image: "image.wic.gz"

    - task: run
      args:
        - "oem_run:mmc partconf 0 1 1 1"
        - "oem_run:mmc bootbus 0 2 0 0"

Hardware Partition Numbering

  • hwpart 0 is the eMMC user data area
  • hwpart 1 is boot partition 0 (BOOT0)
  • hwpart 2 is boot partition 1 (BOOT1)

Use hwpart 2 instead of hwpart 1 if you need to write to boot partition 1.

Note

flash-emmc.bin is a combined bootloader image that holds tiboot3.bin, tispl.bin and u-boot.img for the eMMC.

The paths of the images are resolved relative to the location of the configuration file, so it is convenient to keep it next to the images, e.g. in the Yocto deploy folder.

Running snagfactory#

Start the GUI without any arguments:

On Linux:

$ snagfactory

You will see a window with a few parameters, as shown below:

Snagfactory GUI with the Config and Start buttons, the list of scanned boards and the detailed logs

snagfactory-gui-boot-process snagfactory-flash-progress

Then program the board as follows:

  1. Load the configuration file with the Config button (1). The parsed values can be checked in the Config view on the right.
  2. Power up the board in recovery mode and connect it to the host PC. As soon as the board is in DFU mode, it is recognized automatically and appears under Scanned boards (4).
  3. Click the Start button (2). Every board now runs through the recovery phase (snagrecover loads and starts the bootloader) and the flashing phase (the task pipeline is executed over Fastboot), independently of the other boards.
  4. Watch the progress under Scanned boards and open the Detailed logs (3) of a single board if a task fails.
  5. Finally, set switch S1 back to 0 (OFF) to boot from the eMMC, then power-cycle the board. It now boots the software that was just written to the eMMC.

When all boards are done, the UI switches to log view mode, where the result and the detailed session log of every processed board can be inspected. The logs are stored in the snagboot app data directory of the host, together with the configuration used for the session.

Manual Workflow with snagrecover and snagflash#

If flashing over snagfactory is not possible for whatever reason, the same procedure can be run step by step with the two underlying command line tools: snagrecover starts a bootloader on the board, and snagflash then writes the images to the non-volatile memories of the device. The transfer protocol is selected with the -P option, and the matching gadget has to be started from the U-Boot console first.

Loading and Starting a Bootloader with snagrecover#

Prerequisites:

  • Bootloader images tiboot3.bin, tispl.bin and u-boot.img
  • Board in recovery mode as described above

Create a firmware configuration file for snagrecover, e.g. am62l.yaml, which lists the images to be loaded via snagrecover:

am62l.yaml
tiboot3:
  path: tiboot3.bin
tispl:
  path: tispl.bin
u-boot:
  path: u-boot.img

Run the recovery, am62l3 is the SoC model of the AM62L:

$ snagrecover -s am62l3 -f am62l.yaml

The bootloader is now transferred to the board (RAM) and started. Watch the serial debug console — the U-Boot prompt should appear there after a few seconds. From this point on, the board can be used as usual, e.g. to flash the eMMC with snagflash.

Flashing with snagflash over Fastboot#

Prerequisites:

  • U-Boot running on the device, either started via snagrecover or from eMMC/SD card
  • The image(s) to flash located in the working directory

Start the Fastboot gadget in U-Boot:

Target:

=> fastboot usb 0

snagflash writes raw images at an arbitrary offset through its Extended Fastboot mode, which is driven by a small command file (-I) or interactively (-i). Chaining plain Fastboot sub-commands with -f only works with named partitions that U-Boot already knows about, so it cannot address raw eMMC offsets or hardware partitions — use the command-file approach below instead.

Flashing the Bootloader over Fastboot#

flash.cmd
# flash.cmd
set target mmc0
set fb-addr 0x82000000
flash flash-emmc.bin 0 hwpart 1

Host:

$ snagflash -P fastboot-uboot -p 0451:6165 -I flash.cmd

Flashing a WIC Image over Fastboot#

Prerequisites:

  • Uncompressed or compressed (.gz, .xz, .bz2, .zst) WIC image located in the working directory
# flash.cmd
set target mmc0
set fb-addr 0x82000000
flash image.wic.gz 0

Host:

$ snagflash -P fastboot-uboot -p 0451:6165 -I flash.cmd

Faster Flashing with bmap

For faster flashing, place the matching .bmap file next to the image in the same directory (e.g. image.wic.bmap for image.wic.gz). flash finds the .bmap file automatically, verifies its checksums and writes only the used block ranges instead of the whole image. Note that fastboot-uboot is only the name of the Fastboot protocol variant used to talk to U-Boot's extended Fastboot mode — it has nothing to do with which image is being flashed.

Flashing U-Boot over DFU#

This writes the bootloader to the boot partition of the eMMC; no WIC image is involved.

Prerequisites:

  • Combined bootloader image (flash-emmc.bin) located in the working directory
  • U-Boot running on the device, either started via snagrecover or from eMMC/SD card

Set up the DFU alternate settings and start the DFU gadget in U-Boot:

Target:

=> setenv dfu_alt_info ${dfu_alt_info_emmc}
=> dfu 0 mmc 0

Host:

$ snagflash -P dfu -p 0451:6165 -D 0:flash-emmc.bin

Flashing U-Boot without Snagflash over DFU#

It is also possible to flash U-Boot to the boot partition using dfu-util directly, without snagboot.

dfu-util talks to the DFU devices of the board directly. It is the lowest level of the three workflows and useful for a quick update of the boot firmware, or on a host where snagboot is not installed. The tool is available in the package repositories of the common distributions:

$ sudo apt install dfu-util

The alternate settings which the connected DFU device offers can be listed at any time. This is the easiest way to check that the board is in DFU mode and which targets its current boot stage provides:

$ dfu-util -l

Starting the Bootloader#

Prerequisites:

  • Bootloader images tiboot3.bin, tispl.bin and u-boot.img located in the working directory
  • Board in recovery mode as described above

The boot stages are downloaded one after the other. The -R option resets the DFU device after the download, so that the next stage can expose its own DFU device:

$ sudo dfu-util -R -a bootloader -D tiboot3.bin
$ sudo dfu-util -R -a bootloader -D tispl.bin
$ sudo dfu-util -R -a u-boot.img -D u-boot.img

This is the manual equivalent of snagrecover. Watch the serial debug console — the U-Boot prompt should appear there after the last download. No non-volatile memory has been modified up to this point.

Flashing the Boot Firmware to the eMMC#

Prerequisites:

  • Boot firmware images located in the working directory
  • U-Boot running on the device, either started as described above or from eMMC/SD card

Start the DFU gadget in U-Boot with the alternate settings for the eMMC:

Target:

=> setenv dfu_alt_info ${dfu_alt_info_emmc}
=> dfu 0 mmc 0

The complete boot firmware can be written to the boot partition of the eMMC in one go:

Host:

$ sudo dfu-util -R -a rawemmc -D flash-emmc.bin

Alternatively, the boot images can be written individually. Here the alternate settings are addressed by name instead of by index, each writing its image to the offset listed in Flashing U-Boot over DFU:

$ sudo dfu-util -R -a tiboot3.bin.raw -D tiboot3.bin
$ sudo dfu-util -R -a tispl.bin.raw -D tispl.bin
$ sudo dfu-util -R -a u-boot.img.raw -D u-boot.img

Target:

=> mmc partconf 0 1 1 1
=> mmc bootbus 0 2 0 0

Flashing a WIC Image with UMS#

Prerequisites:

  • WIC image (uncompressed, or compressed with a matching .bmap file — see the note below)
  • U-Boot running on the device

U-Boot exports the eMMC, which is mmc 0 on this board, as a USB mass storage device:

=> ums 0 mmc 0

The eMMC now shows up as a block device on the host (check lsblk for the device name), and the image can be written to it either with snagflash:

$ snagflash -P ums -s image.wic.gz -b /dev/blockdevice

or directly with bmaptool, which snagflash also uses internally for this kind of transfer:

$ sudo bmaptool copy image.wic /dev/blockdevice

Faster Flashing with bmap

As with Fastboot, flashing a WIC image over UMS is much faster when the matching .bmap file (e.g. image.wic.bmap) is present next to the image — both snagflash -P ums and bmaptool copy then write only the blocks that are actually used instead of the complete image.

Further Information#