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:
- will only copy blocks with data and skips empty blocks (around 50% less data to write)
- verifies checksums of downloaded data to prevent corrupt images
- safety checks to make sure that image is not written to mounted disks
- able to directly download from http server without local temporary files
- automatic decompression on-the-fly
- verifies PGP signatures
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:
- you are using LS1028A
- you have a very old U-Boot version on i.MX 8MQ or 8M+
- you have i.MX 8MQ with the DIP switch set to ON
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
.
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:
- obtain the platform-specific machine config from
reform-tools
- obtain the URL from which to download the U-Boot binary and download it (or build it yourself)
- from the machine config, obtain the correct flashing offsets
- 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.