How to flash to an SD-card

Table of Contents

The disk images contain a partition table and optionally (in case of Debian installer) the bootloader U-Boot, so it has to be written to the SD-card or USB stick directly instead of being copied to a mounted filesystem or written onto an existing partition.

Writing the image to your SD-card or USB stick will destroy all the data that was on it before. Be very certain that the device you are writing the image to is indeed the SD-card or flash drive you inserted and not any other disk.

The following command will print the device node of any disk you attach to your machine while the command is running:

udevadm monitor --udev --property --subsystem-match=block/disk | sed -ne 's/^DEVNAME=//p'

Flash using bmaptool

If you have the package bmaptool installed, then instead of using dd you can flash the image to your SD-card like this:

sudo bmaptool copy https://reform.debian.net/images/reform-systemXXX.img.xz /dev/mmcblkXXX

The advantages of using bmaptool over using dd are:

Flash using dd

You can also write the images to an SD-card or USB stick using dd. Make sure to replace /path/to/reform-system.img by the path to the image you downloaded and /dev/mmcblkXXX by the block device belonging to your SD-card or USB flash drive.

xzcat /path/to/reform-system.img.xz | sudo dd of=/dev/mmcblkXXX status=progress

Flashing U-Boot

Due to space constraints, only “universal” images without U-Boot are being offered for download. The image provides device trees for all platforms in the /dtbs directory on the first partition where U-Boot will find them if ${fdtfile} is set to the correct, platform-specific value. This is the case for all U-Boot versions on MNT platforms unless for very old U-Boot versions on i.MX 8MQ and 8M+, so make sure you have recent U-Boot flashed to eMMC.

You only need to flash U-Boot to the beginning of your SD-card if any of the following conditions is true:

If your U-Boot on eMMC is old, you could also consider upgrading it to the latest version by running sudo reform-flash-uboot emmc.

If you are already using a MNT Reform and you want to flash u-boot to an SD-card for the same machine, you can also take the shortcut of using reform-flash-uboot. In that case, you can skip the remainder of these instructions and simply run:

sudo reform-flash-uboot sd

The above command will flash the fitting U-Boot for your current platform to your SD-card. If you are not on a MNT Reform machine or if you want to flash u-boot for a different SoM than the one you are currently using, keep reading this article.

Every platform requires its own U-Boot binary. If you want to flash the U-Boot binary specific to your platform to the beginning of your SD-card, you need to:

  1. obtain the platform-specific machine config from reform-tools
  2. obtain the URL from which to download the U-Boot binary and download it (or build it yourself)
  3. from the machine config, obtain the correct flashing offsets
  4. flash it with the appropriate offset to the beginning of the SD-card

Instead of downloading U-Boot (step 2) you can also build it yourself. How to do that is specific to each platform and out of scope for this documentation. If you opt for downloading a pre-built binary from MNT instead of building it yourself you need to obtain the correct URL to download that binary from. That information as well as the platform-specific offsets is stored in source-able config files provided for each platform by the reform-tools package.

1. Option A: with reform-tools installed locally

If you already are sitting in front of a MNT Reform, you can make use of the local copy of the platform-specific config files stored in /usr/share/reform-tools/machines/. The files are named according to the platform-specific output of cat /proc/device-tree/model. For example, with a classic Reform you can source the contained variables to your current shell by running:

source "/usr/share/reform-tools/machines/MNT Reform 2.conf"

1. Option B: without reform-tools installed

Without a local copy of reform-tools, you can obtain the latest version of the machine descriptions from the reform-tools git repository. You can have a look at the list of available machine configurations by running:

curl https://source.mnt.re/reform/reform-tools/-/archive/main/reform-tools-main.tar.gz | tar -tv | grep /machines/

Select the config specific to your platform (the files are named by the output of cat /proc/device-tree/model), download and source it. For example for “MNT Reform 2” you run:

curl https://source.mnt.re/reform/reform-tools/-/archive/main/reform-tools-main.tar.gz \
  | tar --to-stdout --wildcards -x "reform-tools-*/machines/MNT Reform 2.conf" \
  > machine.conf
source machine.conf

2. Obtain the download URL and download it

In the shell where you sourced the machine configuration, the variables $UBOOT_PROJECT, $UBOOT_TAG, $DTBPATH and $UBOOT_SHA1 contain the values specific to your platform:

echo "UBOOT_PROJECT: $UBOOT_PROJECT"
echo "UBOOT_TAG: $UBOOT_TAG"
echo "DTBPATH: $DTBPATH"
echo "UBOOT_SHA1: $UBOOT_SHA1"

For example for “MNT Reform 2”, this will print the following to your shell:

UBOOT_PROJECT: reform-boundary-uboot
UBOOT_TAG: 2024-07-19
DTBPATH: freescale/imx8mq-mnt-reform2.dtb
UBOOT_SHA1: 60ecf649038ebd92bfb6676bdf746daa30825dbf

Using these values, you can download the right U-Boot binary:

/usr/lib/apt/apt-helper download-file https://source.mnt.re/reform/${UBOOT_PROJECT}/-/jobs/artifacts/${UBOOT_TAG}/raw/$(basename "$DTBPATH" .dtb)-flash.bin?job=build flash.bin "SHA1:$UBOOT_SHA1"

If your system does not have apt installed, you can also use traditional curl or wget and verify the checksum afterwards:

wget https://source.mnt.re/reform/${UBOOT_PROJECT}/-/jobs/artifacts/${UBOOT_TAG}/raw/$(basename "$DTBPATH" .dtb)-flash.bin?job=build -O flash.bin
echo "$UBOOT_SHA1  flash.bin" | sha1sum --check

3. Obtain the flashing offsets

In the shell where you sourced the machine configuration, the variables $UBOOT_OFFSET and $FLASHBIN_OFFSET contain the values specific to your platform:

echo "UBOOT_OFFSET: $UBOOT_OFFSET"
echo "FLASHBIN_OFFSET: $FLASHBIN_OFFSET"

For example for “MNT Reform 2”, this will print the following to your shell:

UBOOT_OFFSET: 33792
FLASHBIN_OFFSET: 0

If you didn’t source the machine configurations, you can look up the values manually. They are required in the next step.

4. Flashing

Lastly, once you have flash.bin available, flash it to the SD-card with the correct offsets like this:

dd if=flash.bin of=/dev/mmcblkX bs=512 seek="$((UBOOT_OFFSET / 512))" skip="$((FLASHBIN_OFFSET / 512))"