Bootable SD card

Introduction
This page describes how to create a bootable SD card. Depending on how the SD card is connected, the location to write data to can be different. Throughout this document ${card} refers to the SD card and ${p} to the partition if any. If the SD card is connected via a USB adapter, linux will know it for example as /dev/sdb (with /dev/sda being a boot drive). Please notice that this device can be different based on numerous factors, so when not sure, check the last few lines of dmesg after plugging in the device. If connected via a SD slot on a device, linux will know it as /dev/mmcblk0 (or mmcblk1, mmcblk2 depending on which mmc slot is used).

Data is either stored raw on the SD card or in a partition. If ${p} is used then the appropiate partition should be used. Also this differs for USB adapters or mmc controllers. When using an USB adapter, ${p} will be 1, 2, 3 etc so the resulting device is /dev/sdb1. Using an mmc controller, this would be p1, p2, p3 etc so the resulting device is /dev/mmcblk0p1.

To summarize: ${card} and ${card}${p}1 mean /dev/sdb and /dev/sdb1 on a USB connected SD card, and /dev/mmcblk0, /dev/mmcblk0p1 on an mmc controller connected device.

SD Card Layout
A default U-Boot build for an Allwinner based board uses the following layout on (micro-)SD cards or eMMC storage (from v2018.05 or newer): Typically partitions start at 1MB (which is the default setting of most partitioning tools), but there is no hard requirement for this, so U-Boot can grow bigger than 984KB, if needed.

The 8KB offset is dictated by the BROM, it will check for a valid eGON/TOC0 header at this location. The 40KB offset for U-Boot proper is the default U-Boot setting and can be changed at build time using the  configuration variable.

Newer SoCs (tested on H2+, A64, H5, H6) can also load the SPL from sector 256 (128KB) of an SD card or eMMC, if no valid eGON/TOC0 signature is found at 8KB. The U-Boot proper offset needs to be adjusted accordingly in this case.

Mainline U-Boot used to have a more complex, fixed layout for the SD card/eMMC sectors in the first Megabyte:

As the feature set of U-Boot proper grew over time, this proved to be too restricting, as we completely filled the area before the environment and started to corrupt it. To avoid future issues, it was decided to move the default location for the environment to a FAT partition, which is more flexible and has no real size limits.

Identify the card
First identify the device of the card and export it as ${card}. The commands

or

can help with finding available/correct partition names.

 export card=/dev/sdX export p=""
 * If the SD card is connected via USB and is sdX (replace X for a correct letter)

 export card=/dev/mmcblk0 export p=p
 * If the SD card is connected via mmc and is mmcblk0

Cleaning
To be on safe side erase the first part of your SD Card (also clears the partition table). dd if=/dev/zero of=${card} bs=1M count=1

If you wish to keep the partition table, run: dd if=/dev/zero of=${card} bs=1k count=1023 seek=1

Bootloader
You will need to write the u-boot-sunxi-with-spl.bin to the sd-card. If you don't have this file yet, refer to the "compilation" section of mainline or legacy U-Boot.

 dd if=u-boot-sunxi-with-spl.bin of=${card} bs=1024 seek=8

To update the bootloader from the u-boot prompt itself:

 mw.b 0x48000000 0x00 0x100000                # Zero buffer tftp 0x48000000 u-boot-sunxi-with-spl.bin    # Or use load to read from MMC or SCSI etc mmc erase 0x10 0x400                         # Erase the MMC region containing u-boot, do not reset at this point! mmc write 0x48000000 0x10 0x400              # Write updated u-boot

If using u-boot v2013.07 or earlier then the offsets, and therefore procedure, are slightly different:

Note: if bootloader was generated by Buildroot (tested on 2015.02), this is the case.

 dd if=spl/sunxi-spl.bin of=${card} bs=1024 seek=8 dd if=u-boot.bin of=${card} bs=1024 seek=32

Partitioning
With recent U-Boot it's fine to use ext2/ext3 as boot partition, and other filesystems in the root partition too.

With separate boot partition
Partition the card with a 16MB boot partition starting at 1MB, and the rest as root partition

 sfdisk -R ${card} cat < blockdev --rereadpt ${card} cat < mkfs.vfat ${card}${p}1 mkfs.ext4 ${card}${p}2

 cardroot=${card}${p}2

Boot Partition
 mount ${card}${p}1 /mnt/ cp linux-sunxi/arch/arm/boot/uImage /mnt/ cp sunxi-boards/sys_config/a10/script.bin /mnt/ umount /mnt/

Single partition
(experimental)  sfdisk -R ${card} cat < mkfs.ext4 ${card}${p}1

<pre class="brush: bash"> cardroot=${card}${p}1

Boot Partition
<pre class="brush: shell"> mount ${card}${p}1 /mnt/ mkdir /mnt/boot cp linux-sunxi/arch/arm/boot/uImage /mnt/boot cp sunxi-boards/sys_config/a10/script.bin /mnt/boot umount /mnt/

GPT (experimental)
There is 8kb space for partition data. MBR uses only the first sector and allows for 4 partitions. If you are concerned about the 4 partition limitation you can try different partitioning scheme. While GPT standard mandates that GPT should have at least 128 entries gdisk can resize a GPT partition to 56 entries which fit into the 7kb that follow the protective MBR header and GPT header. Linux understands such GPT but some tools refuse it since it does not adhere to the standard. YMMV

The GPT partition table can also be moved out of the way of the SPL and U-Boot. This has the advantage that the full 128 or more partition table entries mandated by the GPT standard can be used. The start of the partition table is stored in the GPT header (LBA 1), and is usually set to 2. Version 1.0.3 and later of the gdisk program has the ability to change this value (command j in the "extra functionality" menu). The following table shows the card layout with the partition table start relocated to LBA 2048.

Boot Script
Mainline_U-Boot

Rootfs
This depends on what distribution you want to install. Which partition layout you use does not matter much, since the root device is passed to the kernel as argument. You might need tweaks to /etc/fstab or other files if your layout does not match what the rootfs expects. As of this writing most available images use two partitions with separate /boot.

Using rootfs tarball
<pre class="brush: shell"> mount ${card}${p}2 /mnt/ tar -C /mnt/ -xjpf my-chosen-rootfs.tar.bz2 umount /mnt

Linaro rootfs
Linaro offers a set of different root filesystems. A retention policy of 30 days applies to Linaro rootfs on snapshot servers. New snapshots can be generated on request. Latest snapshots can be made from sources such as Ubuntu Build Service

In any case, you can get the actual rootfs tarballs here. ALIP is a minimal LXDE based desktop environment which might me useful to most allwinner users.

Note that recent (2015, and maybe even earlier) versions of ALIP/Linaro/Ubuntu and any other rootfs that makes use of systemd (and possibly also upstart) can only be used with a kernel compiled with CONFIG_FHANDLE=y. In the default configuration of the Sunxi-3.4 kernel this option is not set (It says "# CONFIG_FHANDLE is not set" in .config ). So you must take care of this yourself during kernel configuration ("General Setup", "Open by fhandle syscalls").

Otherwise your kernel will boot, rootfs will mount and after that nothing will happen: no login prompt will appear on any console. If you must use a kernel without CONFIG_FHANDLE, try using a Debian rootfs with sysvinit.

Rootfs from LinuxContainers
LinuxContainers projects has various downloadable rootfs images.

Using debootstrap - Debian/Ubuntu based distributions
debootstrap</tt> is an alternative to rootfs tarball as described in the previous section

distro=precise mount ${card}${p}2 /mnt/ debootstrap --arch=armhf --foreign $distro /mnt/ cp /usr/bin/qemu-arm-static /mnt/usr/bin/ chroot /mnt /usr/bin/qemu-arm-static /bin/sh -i /debootstrap/debootstrap --second-stage
 * 1) feel free to change distro to raring/saucy/.. as appropriate for later Ubuntu version or wheezy for Debian
 * 1) you can add --variant=buildd to install a compiler in your chroot at debootstrap time but using apt is probably faster

cat <<EOT > etc/apt/sources.list deb http://ports.ubuntu.com/ $distro main universe deb-src http://ports.ubuntu.com/ $distro main universe deb http://ports.ubuntu.com/ $distro-security main universe deb-src http://ports.ubuntu.com/ $distro-security main universe deb http://ports.ubuntu.com/ $distro-updates main universe deb-src http://ports.ubuntu.com/ $distro-updates main universe EOT
 * 1) for Ubuntu

cat <<EOT > etc/apt/sources.list deb http://http.debian.net/debian $distro main contrib non-free deb-src http://http.debian.net/debian $distro main contrib non-free deb http://http.debian.net/debian $distro-updates main contrib non-free deb-src http://http.debian.net/debian $distro-updates main contrib non-free deb http://security.debian.org/debian-security $distro/updates main contrib non-free deb-src http://security.debian.org/debian-security $distro/updates main contrib non-free EOT
 * 1) for Debian

cat <<EOT >> etc/fstab none	/tmp	tmpfs	defaults,noatime,mode=1777 0 0 ${card}${p}1	/boot	vfat defaults 0 0 EOT exit cp /etc/resolv.conf /mnt/etc chroot /mnt export LANG=C apt-get update cat <<END > /etc/apt/apt.conf.d/71-no-recommends APT::Install-Recommends "0"; APT::Install-Suggests "0"; END apt-get install locales dpkg-reconfigure locales export LANG=en_US.UTF-8 apt-get install nvi ; apt-get remove nano passwd exit rm /mnt/usr/bin/qemu-arm-static /mnt/etc/resolv.conf echo something > /mnt/etc/hostname echo T0:2345:respawn:/sbin/getty -L ttyS0 115200 vt100 >> etc/inittab umount /mnt
 * 1) if you have a separate boot partition
 * 1) set up 'apt
 * 1) set up locales (Debian) - dpkg scripts tend to complain otherwise
 * 1) Choose en_US.UTF-8 for both prompts, or whatever you want.
 * 1) install your favourite packages here
 * 1) set root password - otherwise you won't be able to log in
 * 1) cleanup
 * 1) ensure hostname has not carried over from your build host
 * 1) enable serial console (Debian/sysvinit way)
 * 1) enable serial console (Ubuntu/upstart way - TBD)

Kernel modules
When you have copied rootfs to your card you might want to copy the kernel modules as well.

=Troubleshooting=


 * check partitioning - if you did the partitioning yourself read back the layout with sfdisk in sectors. sfdisk and gparted sometimes apply weird rounding when using megabytes.

sfdisk -uS -d /dev/sdd unit: sectors
 * 1) partition table of /dev/sdd

/dev/sdd1 : start=    2048, size= 16150528, Id=83 /dev/sdd2 : start=       0, size=        0, Id= 0 /dev/sdd3 : start=       0, size=        0, Id= 0 /dev/sdd4 : start=       0, size=        0, Id= 0


 * re-check that you have written the image correctly Check image checksum if provided. Re-read writing instructions carefully. Try another writing method if available - dd / phoenixsuit / win32-diskimage. Especially writing on Windows tends to cause trouble. If your board is new you can try an image for similar board with the same CPU. Use console cable if you have one to check the boot messages.


 * power off the board completely before booting If you are using a console cable the board may not power off completely. There is a possiblility that self-powered USB peripherials or USB hubs may cause sililar issue. The red power light would get dimmer when the board is off but does not turn off completely. In this case the mmc controller may not get reset properly and the board boots from nand. Power off the board, disconnect all peripherials, and disconnect the serial console cable. Try booting again. You can re-connect your peripherials before booting. This issue does not seem to happen when the kernel powers down the mmc controller properly but is common when the kernel crashes.


 * check for bad micro-SD card contact This is common issue on boards that use micro-SD socket. Try removing and re-inserting the card, cleaning the contacs on the card and dusting off the SD card socket. Some people report that inserting the card together with a piece of paper improves contact and allows booting cards which are too loose in the socket.

= See also =

U-Boot

 * U-Boot

External

 * Additional info on sunxi's flavor of U-Boot