Search by Tags

Boot From an SD Card


Subscribe for this article updates

Warning: It is recommended to use SD booting only during development since normal SD cards aren't reliable for long-term usage. For a simple installation of bootable images please use our Toradex Easy Installer where available.


In order to boot from an SD card you need:

  • U-boot running on your module. If this is not the case, please use the Toradex Easy Installer to install a running image first. Alternatively, if not (yet) available for your particular module revert to using the Legacy Update Procedure as outlined in the following [table]( "Linux Image Downloads").
  • An SD card with two partitions. The first holding a FAT filesystem to host the kernel image and device trees, the second holding an ext4 (resp. ext3 on downstream T20/T30) filesystem to hold the rootfs


There are two ways to prepare the SD card:

  • Using the images provided by Toradex
  • Using the wic files as generated by an Angstrom Distribution/OpenEmbedded/Yocto Project build

The second option is faster, but it requires that you build the images first using the OpenEmbedded build system. Use it only if you are actually modifying or debugging the images.

Using Toradex Images

Use your preferred partitioning tool to create the mentioned partitions on your SD card. The size will depend on your module and images, but 100MB and 1-2GB should suffice in most cases. The order of the partitions is important since U-boot will look for the kernel in the first, and for the rootfs in the second one.

sudo parted -s /dev/sd? mklabel gpt mkpart primary fat32 1MiB 100MiB mkpart ext4 100MiB 2000MiB name 1 boot name 2 rootfs
sudo mkfs.fat -n boot /dev/sd?1 && sudo mkfs.ext4 -L rootfs /dev/sd?2
sudo lsblk /dev/sd? -o NAME,FSTYPE,LABEL,PARTLABEL (to verify)

Here, sd? is the device corresponding to the SD card (check yours by looking at dmesg after plugging the SD to your computer or using the lsblk command). We have named the partitions boot and rootfs, but you can name them at will. Do not forget to mount the partitions afterwards to be able to access them: sudo mount -L boot /mnt/boot; sudo mount -L rootfs /mnt/rootfs.

Now you need to copy the kernel image and the device trees into the first partition, and the rootfs into the second. To do this, first download an image for the Toradex Easy Installer corresponding to your module and look inside for the bootfs and the rootfs. These are named xxx-Image.bootfs.tar.xz and xxx-Image.rootfs.tar.xz. Simply untar each of them into the first and second partition respectively.

sudo tar xf Colibri-iMX6_LXDE-Image.bootfs.tar.xz --no-same-owner -C /mnt/boot
sudo tar xf Colibri-iMX6_LXDE-Image.rootfs.tar.xz -C /mnt/rootfs

Note: The Colibri iMX6 module has been used as an example. Alternatively, if you have a legacy image, you will find the boot files in the <module-name>_bin/ folder (you only need the zImage and the device tree for your module, remember downstream T20/T30 do not yet use a device tree), and the rootfs in the rootfs folder. Copy them to the partitions as follows:

sudo cp -L colibri-imx6_bin/{zImage,imx6dl-colibri-eval-v3.dtb} /mnt/boot
sudo cp -r rootfs/* /mnt/rootfs

Finally, unmount the partitions with sudo umount /mnt/{boot,rootfs}, insert the SD card into (one of) the carrier board slot(s) and boot your module entering U-boot (by hitting any key in the early boot screen). At the U-boot prompt you can check that your partitions are recognized with mmc dev 1; mmc part (where the number may be 0 for non-eMMC modules and 1 or 2 on Apalis depending on the particular slot used). You should see the names you gave them during the partitioning process. You can now boot with run sdboot.

Using wic Files

The OpenEmbedded build system supports the generation of wic images that can be directly burned to an SD card. By default, this feature is enabled in all our images since release 2.8b4 (on older releases only NXP i.MX modules support it). Thus, if you are building your own images from the Toradex repositories, you can find the corresponding wic image after a build in the deploy/images/name-of-the-board/ folder of your OpenEmbedded tree. The image is compressed and named xxx.wic.gz (e.g. Console-image-colibri-imx6.wic.gz). Decompress it first to get the original wic image and burn it directly to your SD card using e.g. the dd utility.

gzip -d xxx.wic.gz
sudo dd if=xxx.wic of=/dev/sd-card-device bs=4M

Or in one go:

zcat xxx.wic.gz | sudo dd of=/dev/sd-card-device bs=4M

where sd-card-device is the name of the Linux device exposing the SD card (you can find it using lsblk or looking at the output of dmesg after plugging the card). Move the SD card to your carrier board slot, turn on your module and quickly trigger the U-boot console (by pressing any key within the first 2 seconds). From there, you can boot from the SD card by executing run sdboot in the console.