Differences between revisions 1 and 39 (spanning 38 versions)
Revision 1 as of 2014-06-02 19:47:23
Size: 7830
Editor: ?IanCampbell
Comment:
Revision 39 as of 2014-12-31 10:39:32
Size: 23487
Editor: ?IanCampbell
Comment: Avoid strikethrough of supported boards names when the corresponding installation report is closed, otherwise it looks like the board isn't really supported.
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
= Install Using Debian Installer = = Introduction =

Support for boards using the Allwinner "sunxi" (sun4i, sun5i, sun7i etc) family of processors, e.g. A10, A13, A20, etc.

= Install Using Debian-Installer =
Line 7: Line 11:
The following should work out of the box:

 * Cubietruck

Other platforms are still usable but may require more manual intervention to install.

== Installing to SATA ==

Support for installing to a SATA devices from the network is currently available in the Debian Installer [[http://d-i.debian.org/daily-images/armhf/daily/|daily builds]].
Debian-installer should work out of the box on all the following sunxi-based systems, but as the developers do not have access to all of them, the installer has only been tested on particular systems. If you have used the installer on one of the untested systems, please submit an installation-report to the Debian project (cf. the [[http://d-i.debian.org/manual/en.armhf/ch05s04.html#submit-bug|Submitting Installation Reports]] chapter in the Debian installation-guide).

=== Systems tested and confirmed working ===

||'''System'''||'''Device Tree Blob'''||'''Notes'''||
||Cubietech Cubieboard||`sun4i-a10-cubieboard.dtb`||[[https://bugs.debian.org/770904|Installation Report]]||
||Cubietech Cubieboard2||`sun7i-a20-cubieboard2.dtb`||
||Cubietech Cubietruck (Cubieboard3)||`sun7i-a20-cubietruck.dtb`||
||!LeMaker Banana Pi || `sun7i-a20-bananapi.dtb`|| needs mainline u-boot v2014.10 or newer||
||Olimex A10-OLinuXino-LIME||`sun4i-a10-olinuxino-lime.dtb`|| needs mainline u-boot v2014.10rc3 or newer; (outdated) manual installation information: [[InstallingDebianOn/Allwinner/A10-OLinuXino-LIME]] ||
||Olimex A20-Olinuxino Micro||`sun7i-a20-olinuxino-micro.dtb`||[[https://bugs.debian.org/774176|Installation Report]]||

=== Systems for which the installer has support code, but on which installation has not been tested yet ===

||'''System'''||'''Device Tree Blob'''||
||INet-97F Rev 02||`sun4i-a10-inet97fv2.dtb`||
||!LinkSprite pcDuino||`sun4i-a10-pcduino.dtb`||
||Mele A1000||`sun4i-a10-a1000.dtb`||
||Miniand Hackberry||`sun4i-a10-hackberry.dtb`||
||Olimex A10s-Olinuxino Micro||`sun5i-a10s-olinuxino-micro.dtb`||
||Olimex A13-Olinuxino||`sun5i-a13-olinuxino.dtb`||
||Olimex A13-Olinuxino Micro||`sun5i-a13-olinuxino-micro.dtb`||
||!PineRiver Mini X-Plus||`sun4i-a10-mini-xplus.dtb`||

The installer can also be used on other sunxi-based systems as long as device-tree support for them is available, but on those systems manual intervention during the installation is required (see
[[#Systems not supported Out-of-the-box|below]]).

== Storage options ==

From Jessie Beta 2 onwards, Debian-Installer allows installing to either a SATA disk or to an MMC/SD card. Installation to the on-board NAND flash available on some sunxi-based systems is '''not''' supported.

Booting the installed system directly from a SATA disk requires a u-boot with AHCI support (see the corresponding [[#u-boot-ahci-support|uboot information]] below).

== Pre-installation preparations ==

On sunxi-based systems, [[#U-boot versions for sunxi-based systems|u-boot]] is the system firmware that initializes the hardware and then allows to boot an operating system. It is the sunxi-equivalent of the BIOS on a PC. In contrast to PCs, where the BIOS is stored in an on-board flash memory chip, on sunxi-based devices u-boot is usually stored on an SD card. Some sunxi-based devices have on-board flash memory and even contain a stripped-down u-boot version in it, but this version is usually unsuitable for Debian. Therefore you usually have to setup an SD card with the appropriate u-boot version for your particular device (see [[#Creating a bootable SD-Card with u-boot|below]]) as a prerequisite for installing Debian.


== Installing over the network by TFTP ==
Line 18: Line 52:

=== U-boot Bootloader ===

''TBD'': This needs a u-boot with AHCI support (WIP, upstream).
Line 46: Line 76:
setenv bootargs "console=ttyS0,115200 -- ${diargs}" setenv bootargs "console=ttyS0,115200 --- ${diargs}"
Line 71: Line 101:
== Installing from a USB stick ==

Starting at 2014-10-04, the daily installer builds offer the option to install the system from a USB stick, provided you are running mainline u-boot and have a device for which u-boot provides [[#u-boot-ehci-support|EHCI]] support.

Unpack the [[http://d-i.debian.org/daily-images/armhf/daily/hd-media/hd-media.tar.gz|hd-media tarball]] onto a USB stick with a filesystem that is supported by u-boot (FAT16 / FAT32 / ext2 / ext3 / ext4) and copy the ISO image of either the weekly [[http://cdimage.debian.org/cdimage/weekly-builds/armhf/iso-cd/debian-testing-armhf-CD-1.iso|Debian/testing CD #1]] or the weekly [[http://cdimage.debian.org/cdimage/weekly-builds/armhf/iso-dvd/debian-testing-armhf-DVD-1.iso|Debian/testing DVD #1]] onto the stick.

Insert the USB stick into the target system and issue the command

{{{
uboot> run usb_boot
}}}

at the u-boot command prompt to start the installer.

Notice: The combination of the daily-built hd-media tarball and the weekly-built CD/DVD image might not work correctly in periods of kernel transitions in Debian. The installer assumes that the kernel in the hd-media tarball and the kernel modules in the ISO image have the same version, which of course might not be the case directly after a kernel version bump.

Line 72: Line 119:
=== Booting the Installed System ===

At the u-boot prompt run the following:
== Booting the installed system ==
=== Booting the Installed System from MMC/SD Card ===

If you are running a current mainline u-boot or a recent u-boot-sunxi
(cf. the [[#U-boot versions for sunxi-based systems|u-boot overview]] below),
have installed the system to an MMC/SD card and have used the guided partitioning option in the installer, autobooting the installed system works without requiring any user interaction.

Some background information:

By default, u-boot-sunxi expects the first partition on the MMC/SD card to be the boot partition and to contain either a FAT or an ext2 filesystem. The guided partitioning option in the installer takes care of this and sets up an ext2-formatted /boot partition as the first partition. If you have chosen a different layout, you have to manually set the u-boot environment variable ${partition} to the number of the partition containing /boot.

Mainline u-boot does not impose restrictions on the filesystem type of the boot partition, as long as u-boot generally supports the particular filesystem (which by default includes ext2/ext3/ext4). Mainline u-boot also does not use the ${device}/${partition} scheme used by u-boot-sunxi, but instead automatically checks all available devices for a boot script.

=== Booting the Installed System from a SATA Disk on Mainline U-Boot ===

If booting from MMC fails and a SATA disk is available, mainline u-boot automatically tries to boot from it. If you want to manually boot from a SATA disk at the u-boot prompt, just enter the command "run scsi_boot".

Notice: the mechanism to automatically boot from SATA disk had a bug in mainline u-boot v2014.10rc2, but this issue has been [[http://git.denx.de/?p=u-boot.git;a=commit;h=a03bdaa1408be4e8b6adfc8577a0ceac3ebc51e5|fixed]] in the release version of u-boot v2014.10.

=== Booting the Installed System from a SATA Disk on U-Boot-Sunxi ===

Note: u-boot-sunxi does by default not support booting from SATA. This paragraph applies only if you use a u-boot-sunxi version on which additional AHCI patches have been applied.

U-boot-sunxi does not have an autoboot mechanism for SATA disks.
To manually boot from a SATA disk on u-boot-sunxi, run the following at the u-boot prompt:
Line 95: Line 164:
=== Systems not supported Out-of-the-box ===

This is a bit more fiddly.

First find a suitable device tree blob (DTB) for your board. You might find one in the [[http://d-i.debian.org/daily-images/armhf/daily/device-tree|daily builds]], or upstream. Otherwise you might need to write one yourself (or find someone who is willing to do it for you).

Once you have a suitable DTB you can populate the TFTP server with the vmlinuz, initrd.gz and the DTB and create a suitable installer boot script by modifying the one above.

Boot the installer and preceed as usual. Towards the end you will encounter:
== Installing on systems that are not supported out of the box ==

First find a suitable device tree blob (DTB) for your board. You might find one in the [[http://d-i.debian.org/daily-images/armhf/daily/device-tree|daily builds]], or in the [[https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git|device-tree git repo]]. The latter is a repository containing all of the device tree files shipped with the upstream Linux kernel but in a separate git tree (which is much quicker to clone and build than the full kernel) which tracks mainline Linux development. You can build all of the ARM (and therefore Allwinner/sunxi) device tree blobs in that tree in only a few seconds devices with:

{{{
$ sudo apt-get install device-tree-compiler git make cpp
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git
$ cd devicetree-rebasing
$ make -j all_arm
}}}

The device tree blobs will be found in {{{src/arm/*.dtb}}}. You can build a single device tree by passing it to make instead of {{{all_arm}}}. e.g.

{{{
$ make src/arm/sun7i-a20-cubietruck.dtb
}}}

Otherwise you might need to write a device tree file yourself (or find someone who is willing to do it for you). If you only have the device tree source (DTS) you can convert it to DTB using these commands:

{{{
$ sudo apt-get install device-tree-compiler
$ dtc -I dts -O dtb infile.dts > outfile.dtb
}}}

Once you have a suitable DTB you can populate the TFTP server with the vmlinuz, initrd.gz and the DTB and create a suitable installer boot script by modifying the one [[#Installing over the network by TFTP|above]].

Boot the installer and proceed as usual. Towards the end you will encounter:
Line 118: Line 205:
This is expected. Make a note of the partitions and continue. Once the installer has completed the you need to boot the resulting system but using the DTB from TFTP in order to fix things up: This is expected. Make a note of the partitions and continue. Once the installer has completed the installation you need to boot the resulting system, but using the DTB from TFTP in order to fix things up. This can be done like in the following example (which assumes an installation to a SATA disk):
Line 154: Line 241:
== Installing to MMC ==

Support for the sunxi MMC controller will be in upstream Linux v3.16, however it has been backported to the v3.15 Debian kernel. However at the time of writing Debian Installer is using v3.14 and hence cannot install to MMC on this platform.

''TBD'': Describe installation to MMC once D-I switches to v3.15.

= Install Using SD Card Images =

See Linux sunxi projects [[http://linux-sunxi.org/Bootable_OS_images#Debian|Bootable OS Images]] page.

''NOTE'': Obviously YMMV with these images.

= Mainline kernel and linux-sunxi.org 3.4 kernel =

There are two different Linux kernel series for sunxi-based systems:
 * mainline kernel
 * linux-sunxi.org kernel
Development for sunxi-based systems had originally begun based on an Allwinner android kernel. The [[https://linux-sunxi.org/Linux_Kernel|linux-sunxi.org 3.4 kernel series]] is based on this android kernel and is maintained by a group of volunteers at linux-sunxi.org.

The mainline kernel is the "official" Linux kernel series released by Linus Torvalds. Beginning with kernel 3.8, several developers have been working on integrating sunxi support into the mainline kernel. An overview of the progress can be found in the [[https://linux-sunxi.org/Linux_mainlining_effort|linux-sunxi.org]] wiki.

Debian uses the same kernel on all supported architectures and therefore supports only the mainline kernel. The disadvantage of the mainline kernel compared to the linux-sunxi.org kernel is that not all sunxi-specific drivers have yet been ported. The mainline kernel contains support for serial console, USB, SATA, Ethernet and MMC/SD, but it has no display and audio drivers for sunxi hardware, i.e. while running a headless server usually works without problems with the mainline kernel, it currently cannot be used for media center applications and the like and as there is no local display support, its use on tablets and other mobile devices is very limited.

While the installer always uses the mainline kernel, it is possible to manually install a linux-sunxi.org kernel on a Debian system later on, but in that case you are on your own with regard to kernel updates and bootloader setup. Several of the automatic mechanisms in Debian to smoothly handle kernel updates and bootloader configuration will not work properly with the linux-sunxi.org 3.4 series.

= U-boot versions for sunxi-based systems =

== Overview ==
There are several u-boot versions for sunxi-based systems:

 * the original Allwinner u-boot
 * u-boot-sunxi
 * mainline u-boot

You can mostly ignore the original Allwinner u-boot for Debian
purposes. Compared to u-boot-sunxi it is rather old and relies on
proprietary bootloader components ("boot0"/"boot1") to perform
basic hardware initialization. About the only use case for it is
booting from the NAND flash available on some sunxi-based boards
in conjunction with using an android or android-derived kernel
version that contains the original Allwinner NAND flash driver for
Android.

[[https://github.com/linux-sunxi/u-boot-sunxi|U-boot-sunxi]] is derived
from the original Allwinner u-boot and is maintained by a group of
volunteers at linux-sunxi.org. It contains an SPL component that
takes care of the basic hardware initialization and therefore does
not need the proprietary boot0/boot1 loaders from Allwinner. It can
boot locally from MMC/SD card and over the network by TFTP, but it
cannot access the NAND flash. The current version (as of 08/2014)
has been updated to the featureset of mainline u-boot v2014.04; it
does not have [[#u-boot-psci-support|PSCI]]-,
[[#u-boot-ahci-support|AHCI]]- and [[#u-boot-ehci-support|EHCI]]-support.

[[http://www.denx.de/wiki/U-Boot/WebHome|Mainline u-boot]] is the
official upstream u-boot version. Work is currently in progress
to integrate the sunxi-specific parts of u-boot-sunxi into
mainline u-boot. When this process is completed, u-boot-sunxi
can be replaced by mainline u-boot. Mainline u-boot as of release v2014.10 already supports several sunxi-based systems, although not yet all systems that are supported by u-boot-sunxi. An overview of the current status is available in
the [[https://linux-sunxi.org/Mainline_U-boot|linux-sunxi.org wiki]].
Mainline u-boot has - besides the master git tree at http://git.denx.de/u-boot.git/ - so-called "custodian trees" for each
supported platform, in which platform-specific changes get integrated
first before being merged into the central u-boot git
repository for the next release. The sunxi custodian tree is available
at http://git.denx.de/u-boot-sunxi.git/ and contains the most
current sunxi platform support patches for mainline u-boot, including
[[#u-boot-psci-support|PSCI]]-,
[[#u-boot-ahci-support|AHCI]]- and
[[#u-boot-ehci-support|EHCI]]-support for various systems.

During the v2014.10 development cycle for mainline u-boot, some rather invasive changes have been introduced. This includes restructuring the build system and introducing a new default environment and a new generic bootcmd handling.
The new default environment is not fully compatible with some older bootscripts written for u-boot-sunxi, but flash-kernel >= 3.24 creates bootscripts that work with both the old and the new default environment. If you are using a flash-kernel version older than 3.24 and intend to change from u-boot-sunxi to mainline u-boot, you should update flash-kernel first.

== Creating a bootable SD-Card with u-boot ==

Debian provides mainline u-boot images for a variety of supported systems in the [[https://packages.debian.org/jessie/armhf/u-boot-sunxi/filelist|u-boot-sunxi:armhf]] package. To create a bootable SD card with u-boot on it, copy the appropriate u-boot image to offset 8kb on the SD card, e.g. with

{{{
$ dd if=/usr/lib/u-boot/Cubietruck/u-boot-sunxi-with-spl.bin of=/dev/SDCARD bs=1k seek=8
}}}

for the Cubietruck. Please note that the u-boot-sunxi package contains both normal as well as FEL images for various systems. FEL mode is a special boot mode that allows sunxi-based systems to be booted via a USB cable from another system instead of from a mass storage device. FEL mode requires specifically adapted u-boot builds which are unsuitable for booting from SD card, so use the normal non-FEL images for building bootable SD cards.

<<Anchor(u-boot-psci-support)>>
== SMP/PSCI support ==

For SMP support on Allwinner SOCs, i.e. for using more than one CPU
core, the mainline Linux kernel requires support for PSCI (Power
State Coordination Interface) in u-boot, which is only available in mainline u-boot.

<<Anchor(u-boot-ahci-support)>>
== AHCI support ==

AHCI support allows u-boot to boot the kernel, initrd and dtb from a
SATA harddisk. U-boot itself has still to be installed on an SD
card, but the rest of the system can be put onto a (much faster)
harddisk. This feature is (as of 11/2014) available in mainline
u-boot for
[[http://git.denx.de/?p=u-boot/u-boot-sunxi.git;a=commit;h=a6e50a88d8d3724fc75f1c6959b80a6c7c69cbad|Cubietech Cubieboard 1+2 and Cubietruck]], Olimex A10-OLinuXino-Lime, Olimex A20-OLinuXino-Lime 1+2, Olimex A20-OLinuXino-Micro, Lemaker Banana Pi, Mele A1000 and Mele A1000G.

For the Cubieboard2 and the Cubietruck you can alternatively also use the "sunxi-mainlining-with-smp-and-ahci-wip" branch of Ian Campbell's git repository at git://gitorious.org/ijc/u-boot.git. It is based on an older u-boot-sunxi snapshot and combines PSCI and AHCI support for these two systems. This branch is not updated anymore, so if possible, you should use mainline u-boot.

<<Anchor(u-boot-ehci-support)>>
== EHCI support ==

EHCI support allows u-boot to boot the kernel, initrd and dtb from a
USB mass storage device such as a USB memory stick or a USB harddisk.
U-boot itself has still to be installed on an SD card, but the rest
of the system can be put onto a USB device. This feature is
available in mainline u-boot for certain devices, among them:
[[http://git.denx.de/?p=u-boot/u-boot-sunxi.git;a=commit;h=fc36a588283838bbaf502ab32b6dcb92aee51ec2|Cubietech Cubietruck]],
[[http://git.denx.de/?p=u-boot/u-boot-sunxi.git;a=commit;h=0061e46462da670ba0f6811d407df438692f137d|Cubietech Cubieboard 1+2 and Olimex A13-OLinuXino Micro]], Olimex A10-OLinuXino-Lime, Olimex A10s-OLinuXino-Micro, Olimex A13-OLinuXino, Olimex A20-OLinuXino-Lime 1+2, !LeMaker Banana Pi, Mele A1000 and Mele A1000G.

= Board Specific Information =

== Cubietech Cubietruck ==

Wifi requires non-free firmware DebianPkg:firmware-brcm80211 at least version 0.42 plus an additional firmware file which is not yet packaged but can be installed with:

{{{
wget -O /lib/firmware/brcm/brcmfmac43362-sdio.txt http://dl.cubieboard.org/public/Cubieboard/benn/firmware/ap6210/nvram_ap6210.txt
}}}

Message such as {{{brcmfmac: brcmf_fil_cmd_data: Failed err=-23}}} are expected and do not represent a actual problem.

.

Introduction

Support for boards using the Allwinner "sunxi" (sun4i, sun5i, sun7i etc) family of processors, e.g. A10, A13, A20, etc.

Install Using Debian-Installer

Supported Platforms

Debian-installer should work out of the box on all the following sunxi-based systems, but as the developers do not have access to all of them, the installer has only been tested on particular systems. If you have used the installer on one of the untested systems, please submit an installation-report to the Debian project (cf. the Submitting Installation Reports chapter in the Debian installation-guide).

Systems tested and confirmed working

System

Device Tree Blob

Notes

Cubietech Cubieboard

sun4i-a10-cubieboard.dtb

Installation Report

Cubietech Cubieboard2

sun7i-a20-cubieboard2.dtb

Cubietech Cubietruck (Cubieboard3)

sun7i-a20-cubietruck.dtb

LeMaker Banana Pi

sun7i-a20-bananapi.dtb

needs mainline u-boot v2014.10 or newer

Olimex A10-OLinuXino-LIME

sun4i-a10-olinuxino-lime.dtb

needs mainline u-boot v2014.10rc3 or newer; (outdated) manual installation information: ?InstallingDebianOn/Allwinner/A10-OLinuXino-LIME

Olimex A20-Olinuxino Micro

sun7i-a20-olinuxino-micro.dtb

Installation Report

Systems for which the installer has support code, but on which installation has not been tested yet

System

Device Tree Blob

INet-97F Rev 02

sun4i-a10-inet97fv2.dtb

LinkSprite pcDuino

sun4i-a10-pcduino.dtb

Mele A1000

sun4i-a10-a1000.dtb

Miniand Hackberry

sun4i-a10-hackberry.dtb

Olimex A10s-Olinuxino Micro

sun5i-a10s-olinuxino-micro.dtb

Olimex A13-Olinuxino

sun5i-a13-olinuxino.dtb

Olimex A13-Olinuxino Micro

sun5i-a13-olinuxino-micro.dtb

PineRiver Mini X-Plus

sun4i-a10-mini-xplus.dtb

The installer can also be used on other sunxi-based systems as long as device-tree support for them is available, but on those systems manual intervention during the installation is required (see below).

Storage options

From Jessie Beta 2 onwards, Debian-Installer allows installing to either a SATA disk or to an MMC/SD card. Installation to the on-board NAND flash available on some sunxi-based systems is not supported.

Booting the installed system directly from a SATA disk requires a u-boot with AHCI support (see the corresponding uboot information below).

Pre-installation preparations

On sunxi-based systems, u-boot is the system firmware that initializes the hardware and then allows to boot an operating system. It is the sunxi-equivalent of the BIOS on a PC. In contrast to PCs, where the BIOS is stored in an on-board flash memory chip, on sunxi-based devices u-boot is usually stored on an SD card. Some sunxi-based devices have on-board flash memory and even contain a stripped-down u-boot version in it, but this version is usually unsuitable for Debian. Therefore you usually have to setup an SD card with the appropriate u-boot version for your particular device (see below) as a prerequisite for installing Debian.

Installing over the network by TFTP

NOTE: These instructions assume the use of a TFTP server, which should already be installed. However the installer images can also be loaded via other means, e.g. from MMC.

Prepare the TFTP Server

Download the kernel vmlinuz, installer initrd.gz and the appropriate Flattended Device Tree (FDT) Blob (or DTB) for the board and copy them to a path on your TFTP server. e.g.

# mkdir -p /srv/tftp/didaily/armhf/daily/{netboot,device-tree}
# cd /srv/tftp/didaily/armhf/daily/
# wget -P netboot http://d-i.debian.org/daily-images/armhf/daily/netboot/vmlinuz http://d-i.debian.org/daily-images/armhf/daily/netboot/initrd.gz
# wget -P device-tree http://d-i.debian.org/daily-images/armhf/daily/device-tree/sun7i-a20-cubietruck.dtb 

Create a script to boot the installer. e.g. /srv/tftp/didaily/cubietruck:

#setenv diargs <EXTRA ARGUMENTS>

setenv fdt_addr       0x43000000
setenv ramdisk_addr_r 0x48000000
setenv kernel_addr_r  0x47000000

setenv dibase /didaily/armhf/daily

tftp ${kernel_addr_r} ${dibase}/netboot/vmlinuz
setenv bootargs "console=ttyS0,115200 --- ${diargs}"

tftp ${fdt_addr} ${dibase}/device-tree/sun7i-a20-cubietruck.dtb
fdt addr ${fdt_addr} 0x40000

tftp ${ramdisk_addr_r} ${dibase}/netboot/initrd.gz
bootz ${kernel_addr_r} ${ramdisk_addr_r}:${filesize} ${fdt_addr}

then to make a script which u-boot can run:

# mkimage -T script -A arm -d /srv/tftp/didaily/cubietruck /srv/tftp/didaily/cubietruck.scr

Running the Installer

At the u-boot prompt, boot the images which were just downloaded via the script:

uboot> setenv autoload no
uboot> dhcp
uboot> tftp ${scriptaddr} /didaily/cubietruck.scr
uboot> source ${scriptaddr}

Install in the usual way. Use setenv diargs foo=bar to pass arguments to the installer (e.g. for preseeding)

Installing from a USB stick

Starting at 2014-10-04, the daily installer builds offer the option to install the system from a USB stick, provided you are running mainline u-boot and have a device for which u-boot provides EHCI support.

Unpack the hd-media tarball onto a USB stick with a filesystem that is supported by u-boot (FAT16 / FAT32 / ext2 / ext3 / ext4) and copy the ISO image of either the weekly Debian/testing CD #1 or the weekly Debian/testing DVD #1 onto the stick.

Insert the USB stick into the target system and issue the command

uboot> run usb_boot

at the u-boot command prompt to start the installer.

Notice: The combination of the daily-built hd-media tarball and the weekly-built CD/DVD image might not work correctly in periods of kernel transitions in Debian. The installer assumes that the kernel in the hd-media tarball and the kernel modules in the ISO image have the same version, which of course might not be the case directly after a kernel version bump.

Booting the installed system

Booting the Installed System from MMC/SD Card

If you are running a current mainline u-boot or a recent u-boot-sunxi (cf. the u-boot overview below), have installed the system to an MMC/SD card and have used the guided partitioning option in the installer, autobooting the installed system works without requiring any user interaction.

Some background information:

By default, u-boot-sunxi expects the first partition on the MMC/SD card to be the boot partition and to contain either a FAT or an ext2 filesystem. The guided partitioning option in the installer takes care of this and sets up an ext2-formatted /boot partition as the first partition. If you have chosen a different layout, you have to manually set the u-boot environment variable ${partition} to the number of the partition containing /boot.

Mainline u-boot does not impose restrictions on the filesystem type of the boot partition, as long as u-boot generally supports the particular filesystem (which by default includes ext2/ext3/ext4). Mainline u-boot also does not use the ${device}/${partition} scheme used by u-boot-sunxi, but instead automatically checks all available devices for a boot script.

Booting the Installed System from a SATA Disk on Mainline U-Boot

If booting from MMC fails and a SATA disk is available, mainline u-boot automatically tries to boot from it. If you want to manually boot from a SATA disk at the u-boot prompt, just enter the command "run scsi_boot".

Notice: the mechanism to automatically boot from SATA disk had a bug in mainline u-boot v2014.10rc2, but this issue has been fixed in the release version of u-boot v2014.10.

Booting the Installed System from a SATA Disk on U-Boot-Sunxi

Note: u-boot-sunxi does by default not support booting from SATA. This paragraph applies only if you use a u-boot-sunxi version on which additional AHCI patches have been applied.

U-boot-sunxi does not have an autoboot mechanism for SATA disks. To manually boot from a SATA disk on u-boot-sunxi, run the following at the u-boot prompt:

uboot> scsi scan
uboot> setenv device scsi
uboot> setenv partition 0
uboot> load ${device} ${partition} ${scriptaddr} boot.scr
uboot> setenv bootargs console=ttyS0,115200n8 root=/dev/sda2 rootwait
uboot> source ${scriptaddr}

This can be made the default with:

uboot> setenv device scsi
uboot> setenv partition 0
uboot> setenv bootargs console=ttyS0,115200n8 root=/dev/sda2 rootwait
uboot> setenv boot_debian scsi scan\;load \${device} \${partition} \${scriptaddr} boot.scr\;source \${scriptaddr}
uboot> setenv bootcmd run boot_debian
uboot> saveenv
uboot> boot

Installing on systems that are not supported out of the box

First find a suitable device tree blob (DTB) for your board. You might find one in the daily builds, or in the device-tree git repo. The latter is a repository containing all of the device tree files shipped with the upstream Linux kernel but in a separate git tree (which is much quicker to clone and build than the full kernel) which tracks mainline Linux development. You can build all of the ARM (and therefore Allwinner/sunxi) device tree blobs in that tree in only a few seconds devices with:

$ sudo apt-get install device-tree-compiler git make cpp
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git
$ cd devicetree-rebasing
$ make -j all_arm

The device tree blobs will be found in src/arm/*.dtb. You can build a single device tree by passing it to make instead of all_arm. e.g.

$ make src/arm/sun7i-a20-cubietruck.dtb

Otherwise you might need to write a device tree file yourself (or find someone who is willing to do it for you). If you only have the device tree source (DTS) you can convert it to DTB using these commands:

$ sudo apt-get install device-tree-compiler
$ dtc -I dts -O dtb infile.dts > outfile.dtb

Once you have a suitable DTB you can populate the TFTP server with the vmlinuz, initrd.gz and the DTB and create a suitable installer boot script by modifying the one above.

Boot the installer and proceed as usual. Towards the end you will encounter:

   ┌─────────────────┤ [!] Continue without boot loader ├──────────────────┐
   │                                                                       │
   │                       No boot loader installed                        │
   │ No boot loader has been installed, either because you chose not to or │
   │ because your specific architecture doesn't support a boot loader yet. │
   │                                                                       │
   │ You will need to boot manually with the /vmlinuz kernel on partition  │
   │ /dev/sda1 and root=/dev/sda2 passed as a kernel argument.             │
   │                                                                       │
   │                              <Continue>                               │
   │                                                                       │
   └───────────────────────────────────────────────────────────────────────┘

This is expected. Make a note of the partitions and continue. Once the installer has completed the installation you need to boot the resulting system, but using the DTB from TFTP in order to fix things up. This can be done like in the following example (which assumes an installation to a SATA disk):

uboot> setenv fdt_addr       0x43000000
uboot> setenv ramdisk_addr_r 0x48000000
uboot> setenv kernel_addr_r  0x47000000
uboot> setenv dibase /didaily/armhf/daily
uboot> setenv autoload no;dhcp
uboot> tftp ${fdt_addr} ${dibase}/device-tree/sun7i-a20-cubieboard2.dtb
uboot> fdt addr ${fdt_addr} 0x40000
uboot> scsi scan
uboot> load scsi 0 ${kernel_addr_r} /vmlinuz
uboot> load scsi 0 ${ramdisk_addr_r} /initrd.img
uboot> setenv bootargs console=ttyS0,115200n8 root=/dev/sda2 rootwait
uboot> bootz ${kernel_addr_r} ${ramdisk_addr_r}:${filesize} ${fdt_addr}

This should now boot you to a login prompt.

Login and install flash-kernel and the u-boot-tools:

# apt-get install flash-kernel u-boot-tools

Now you need to create a flash-kernel database entry. Start by copying the entries for Cubietech Cubietruck from /usr/share/flash-kernel/db/all.db to /etc/flash-kernel/db. Now you need to modify the Machine and DTB-Id fields.

For the Machine use the output of:

# cat /proc/device-tree/model ; echo

For DTB-Id if you used a DTB from the daily builds then use that name for DTB-Id. If you got the DTB from somewhere else then install it as /boot/dtb-$(uname -r) and omit the DTB-Id field. In this case you will need to take care around kernel upgrades.

Now run flash-kernel and reboot. At this point you should be able to boot using the process from Booting the Installed System above. If this fails the boot again using the manual method described above and try again e.g. fix your /etc/flash-kernel/db.

Once you have it working run reportbug flash-kernel and report a wishlist bug to support your platform. Be sure to include the contents of /etc/flash-kernel/db and say where the DTB came from.

Mainline kernel and linux-sunxi.org 3.4 kernel

There are two different Linux kernel series for sunxi-based systems:

  • mainline kernel
  • linux-sunxi.org kernel

Development for sunxi-based systems had originally begun based on an Allwinner android kernel. The linux-sunxi.org 3.4 kernel series is based on this android kernel and is maintained by a group of volunteers at linux-sunxi.org.

The mainline kernel is the "official" Linux kernel series released by Linus Torvalds. Beginning with kernel 3.8, several developers have been working on integrating sunxi support into the mainline kernel. An overview of the progress can be found in the linux-sunxi.org wiki.

Debian uses the same kernel on all supported architectures and therefore supports only the mainline kernel. The disadvantage of the mainline kernel compared to the linux-sunxi.org kernel is that not all sunxi-specific drivers have yet been ported. The mainline kernel contains support for serial console, USB, SATA, Ethernet and MMC/SD, but it has no display and audio drivers for sunxi hardware, i.e. while running a headless server usually works without problems with the mainline kernel, it currently cannot be used for media center applications and the like and as there is no local display support, its use on tablets and other mobile devices is very limited.

While the installer always uses the mainline kernel, it is possible to manually install a linux-sunxi.org kernel on a Debian system later on, but in that case you are on your own with regard to kernel updates and bootloader setup. Several of the automatic mechanisms in Debian to smoothly handle kernel updates and bootloader configuration will not work properly with the linux-sunxi.org 3.4 series.

U-boot versions for sunxi-based systems

Overview

There are several u-boot versions for sunxi-based systems:

  • the original Allwinner u-boot
  • u-boot-sunxi
  • mainline u-boot

You can mostly ignore the original Allwinner u-boot for Debian purposes. Compared to u-boot-sunxi it is rather old and relies on proprietary bootloader components ("boot0"/"boot1") to perform basic hardware initialization. About the only use case for it is booting from the NAND flash available on some sunxi-based boards in conjunction with using an android or android-derived kernel version that contains the original Allwinner NAND flash driver for Android.

U-boot-sunxi is derived from the original Allwinner u-boot and is maintained by a group of volunteers at linux-sunxi.org. It contains an SPL component that takes care of the basic hardware initialization and therefore does not need the proprietary boot0/boot1 loaders from Allwinner. It can boot locally from MMC/SD card and over the network by TFTP, but it cannot access the NAND flash. The current version (as of 08/2014) has been updated to the featureset of mainline u-boot v2014.04; it does not have PSCI-, AHCI- and EHCI-support.

Mainline u-boot is the official upstream u-boot version. Work is currently in progress to integrate the sunxi-specific parts of u-boot-sunxi into mainline u-boot. When this process is completed, u-boot-sunxi can be replaced by mainline u-boot. Mainline u-boot as of release v2014.10 already supports several sunxi-based systems, although not yet all systems that are supported by u-boot-sunxi. An overview of the current status is available in the linux-sunxi.org wiki. Mainline u-boot has - besides the master git tree at http://git.denx.de/u-boot.git/ - so-called "custodian trees" for each supported platform, in which platform-specific changes get integrated first before being merged into the central u-boot git repository for the next release. The sunxi custodian tree is available at http://git.denx.de/u-boot-sunxi.git/ and contains the most current sunxi platform support patches for mainline u-boot, including PSCI-, AHCI- and EHCI-support for various systems.

During the v2014.10 development cycle for mainline u-boot, some rather invasive changes have been introduced. This includes restructuring the build system and introducing a new default environment and a new generic bootcmd handling. The new default environment is not fully compatible with some older bootscripts written for u-boot-sunxi, but flash-kernel >= 3.24 creates bootscripts that work with both the old and the new default environment. If you are using a flash-kernel version older than 3.24 and intend to change from u-boot-sunxi to mainline u-boot, you should update flash-kernel first.

Creating a bootable SD-Card with u-boot

Debian provides mainline u-boot images for a variety of supported systems in the u-boot-sunxi:armhf package. To create a bootable SD card with u-boot on it, copy the appropriate u-boot image to offset 8kb on the SD card, e.g. with

$ dd if=/usr/lib/u-boot/Cubietruck/u-boot-sunxi-with-spl.bin of=/dev/SDCARD bs=1k seek=8

for the Cubietruck. Please note that the u-boot-sunxi package contains both normal as well as FEL images for various systems. FEL mode is a special boot mode that allows sunxi-based systems to be booted via a USB cable from another system instead of from a mass storage device. FEL mode requires specifically adapted u-boot builds which are unsuitable for booting from SD card, so use the normal non-FEL images for building bootable SD cards.

SMP/PSCI support

For SMP support on Allwinner SOCs, i.e. for using more than one CPU core, the mainline Linux kernel requires support for PSCI (Power State Coordination Interface) in u-boot, which is only available in mainline u-boot.

AHCI support

AHCI support allows u-boot to boot the kernel, initrd and dtb from a SATA harddisk. U-boot itself has still to be installed on an SD card, but the rest of the system can be put onto a (much faster) harddisk. This feature is (as of 11/2014) available in mainline u-boot for Cubietech Cubieboard 1+2 and Cubietruck, Olimex A10-OLinuXino-Lime, Olimex A20-OLinuXino-Lime 1+2, Olimex A20-OLinuXino-Micro, Lemaker Banana Pi, Mele A1000 and Mele A1000G.

For the Cubieboard2 and the Cubietruck you can alternatively also use the "sunxi-mainlining-with-smp-and-ahci-wip" branch of Ian Campbell's git repository at git://gitorious.org/ijc/u-boot.git. It is based on an older u-boot-sunxi snapshot and combines PSCI and AHCI support for these two systems. This branch is not updated anymore, so if possible, you should use mainline u-boot.

EHCI support

EHCI support allows u-boot to boot the kernel, initrd and dtb from a USB mass storage device such as a USB memory stick or a USB harddisk. U-boot itself has still to be installed on an SD card, but the rest of the system can be put onto a USB device. This feature is available in mainline u-boot for certain devices, among them: Cubietech Cubietruck, Cubietech Cubieboard 1+2 and Olimex A13-OLinuXino Micro, Olimex A10-OLinuXino-Lime, Olimex A10s-OLinuXino-Micro, Olimex A13-OLinuXino, Olimex A20-OLinuXino-Lime 1+2, LeMaker Banana Pi, Mele A1000 and Mele A1000G.

Board Specific Information

Cubietech Cubietruck

Wifi requires non-free firmware firmware-brcm80211 at least version 0.42 plus an additional firmware file which is not yet packaged but can be installed with:

wget -O /lib/firmware/brcm/brcmfmac43362-sdio.txt http://dl.cubieboard.org/public/Cubieboard/benn/firmware/ap6210/nvram_ap6210.txt

Message such as brcmfmac: brcmf_fil_cmd_data: Failed err=-23 are expected and do not represent a actual problem.

Resources

http://linux-sunxi.org/