Installing Linux on your AC100

:!: Before doing anything else, please, help yourself, help people who would like to help you: Make Backups !
How to backup and restore your AC100

Prerequisites

It is highly recommended to backup all data on your AC100 before continuing. With access to the original partitions, it is practically impossible to make irreversible changes to (that is, to “brick”) your AC100; it's simply not going to happen.

For the rest of this guide, you'll need:

  • Your AC100
  • A secondary computer (“helper”) for nvflash / putusb operations
  • A mini-USB (male) to USB (male) cable

Choice of distribution

The AC100 is an ARMv7 system, so you'll want to run a distribution with ARMv7 repositories (or a source distribution, like Gentoo). We'll discuss some alternatives presently, but if you're in doubt, just choose Ubuntu.

Ubuntu

You can run Ubuntu on the AC100! [more]

You may follow the dedicated “quick” Ubuntu installation guide, or keep reading, for detailed instructions.

Arch Linux ARM

ALARM works very well on the AC100!

Choose this distribution for a KISS system. You'll assume responsibility for the dirty details of system administration. As a novice user, prepare to wade through a lot of knowledge about modern Linux distributions, with the Arch wiki holding your hand firmly.

Users of (regular/x86) Arch Linux will feel very much at home with ALARM; there isn't really any difference from user point of view. The vast majority of packages from x86 Arch repositories are available in ALARM's armv7h counterparts, and ABS and the AUR are fully at your service.

You may follow the dedicated “quick” Arch installation guide, or keep reading, for detailed instructions.

Gentoo

Gentoo is Gentoo. [more]

Fedora

?

Slackware

It should be very possible to run Slackware on AC100.

RSEL

RedSleeve Enterprise Linux, Gordan Bobic's RHEL ARM port. [more]

Choice of kernel

Once you've settled for a distribution, you need to choose a Linux kernel adapted to the hardware platform of the AC100 . This is provided mainly by the marvin24s-kernel project on gitorious.org. Except for the case of Ubuntu (?), you will not find compiled kernel packages for the AC100 in the official distribution repositories.

For a complete comparison of kernels for the AC100, along with their status and requirements, check kernels. Here's a condensed list of marvin24s-kernel branches:

Bootloader and partition table

The stock bootloader (Fastboot) works only with the proprietary partition scheme (tegrapart) present on a stock AC100. TODO Correct this

If your plan is to install Linux to the internal eMMC, please keep in mind that kernel support for tegrapart varies (see kernels). Generally, kernel versions > 3.1 do not have tegrapart support. At this point you need to decide whether to keep using tegrapart or to switch over (“upgrade”) to a standard GPT partition scheme, which works with all kernels.

Keeping tegrapart

If you are fine with keeping tegrapart / Fastboot (you don't plan to run kernels > 3.1.x and/or you'll run Linux from external media), you can skip ahead to section Section:next

Switching to GPT

If you decide to use GPT, there's a tiny bit more work to be done.

While it may be theoretically possible to keep both partition schemes in parallel, you should assume that GPT replaces tegrapart on your eMMC. This means that you will need to change the bootloader as well. Instead of Fastboot, we will use Das U-boot (uboot) / the universal bootloader.

Conversion to GPT/uboot is done in one easy step, by running a script preinstalled on the sosboot ramdisk.

Step 1

Connect your AC100 to your secondary computer with the USB cable.

Step 2

Start your AC100 into recovery mode by holding CTRL+ESC and pressing the Power button. The screen should stay black at this point.

Step 3

Transfer the sosboot ramdisk as a bootloader with nvflash:

helper # nvflash --bl /path/to/sosboot.img --sync

Step 4

You are now in an sosboot environment running from RAM on your ac100. To convert your partition table to GPT and install uboot, execute the script (./switch-to-uboot):

sosboot # ./switch-to-uboot

and follow the on-screen instructions.

Step 5

Switch off your AC100.

Installing the new system

Installation consists of deploying these parts:

  • A base rootfs - Transfer to the target root partition
  • A Kernel image + initramfs - Transfer to the target boot partition
  • Modules corresponding to the kernel (if not already included in the rootfs!)
  • Firmware (if not already included in the rootfs!)

Modules and firmware should reside in /usr/lib/modules and /usr/lib/firmware respectively on the rootfs.

Base rootfs

For the specific rootfs to use, please refer to the documentation of your distribution of choice. (E.g for Arch Linux ARM the recommended base is the Trimslice archive, and for Ubuntu you should use the lubuntu 12.10 armv7h rootfs image.)

Step 1

Download your rootfs (image or archive) to an ext2/vFAT formatted USB drive or SD card.

Step 2

Start sosboot (see steps 1 to 3 of section Switch to GPT).

Step 3

Insert the USB drive / SD card and mount the medium:

sosboot # mkdir /medium
sosboot # export MEDIUM="/dev/mmcblk1p1"

for SD card, OR

sosboot # export MEDIUM="/dev/sda1"

for USB drive. Then mount the medium:

sosboot # mount $MEDIUM /medium

Step 4

Create a new filesystem on the target root partition. If unsure, use ext4 on /dev/mmcblk0p7:

sosboot # export TARGET="/dev/mmcblk0p7" 
sosboot # mkfs.ext4 $TARGET 

Step 5

For a rootfs package in the form of an archive (e.g. ALARM Trimslice), mount $TARGET and extract the files to its filesystem:

sosboot # mkdir /target
sosboot # mount $TARGET /target
sosboot # tar xvf /medium/rootfs.tar.gz -C /target
sosboot # umount /target

For a rootfs package in the form of an image, instead just flash this image to $TARGET:

sosboot # dd if=/mnt/rootfs.img of=$TARGET bs=1M

Step 6

Unmount the medium:

sosboot # umount /medium

Kernel image, modules and firmware

For the minimum amount of work, it is recommended to start by using precompiled kernel images (see kernels), modules and firmware.

Once you're in your new system, you may compile a different kernel - natively - on your AC100 and deploy this in place of the precompiled one.

You may also compile or cross-compile a kernel from sources (see kernels#compile|kernels:compilation) and use that one instead.

Fastboot

If you opted to keep the Fastboot bootloader; the kernel, initramfs and kernel parameters need to take the form of a unified Android boot image, which is flashed to either partition 1 (“SOS”) or partition 2 (“LNX”) of the internal eMMC. TODO: This may not be true at all

Step 1

Download a boot image to your USB drive or SD card. (E.g. lubuntu-12.10-preinstalled-desktop-armhf+ac100.bootimg for Ubuntu 12.10.)

(If you have a kernel zImage and initramfs, you may create your own Fastboot compatible Android boot image with the 'abootimg' utility.)

Step 2

In sosboot, mount the medium again:

sosboot # mount $MEDIUM /medium
Step 3

Flash the kernel image to the kernel partition:

sosboot # dd if=/medium/kernel.boot.image of=/dev/mmcblk0p2

if you want the kernel on the “LNX” partition, or

sosboot # dd if=/medium/kernel.boot.image of=/dev/mmcblk0p1

if you want the kernel on the “SOS” partition.

Now unmount the medium:

sosboot # umount /medium

, remove the drive and switch off your AC100.

Installation complete.

Uboot

If you installed Uboot, the kernel and initramfs images are loaded directly from an ext2/ext3/ext4 partition anywhere on the internal eMMC, an SD card or a USB device, or via a network connection. TODO fact?

Step 1

Find a kernel! You should be looking for

# A kernel image (zImage)
# An initramfs (initramfs.img)
# Kernel modules

If you have an Android boot image, you can extract a zImage and initramfs.img from that with abootimg -x <bootimage>.

Step 2

Create a filesystem on the first partition of the internal eMMC, your USB drive or your SD card. If unsure, use an ext2 filesystem on “SOS” partition, i.e. replace <boot> with /dev/mmcblk0p1.

sosboot # mkfs.ext2 <boot>

Mount the ext2 partition and create a /boot directory there:

sos # mount <boot> /mnt
sos # mkdir /mnt/boot
Step 3

Transfer the kernel (you may use the same filesystem):

sosboot # cp /path/to/zImage /mnt/boot/zImage
sosboot # cp /path/to/initramfs /mnt/boot/initramfs
Step 4

Create a bootscript source file /mnt/boot/boot.cmd of the following form:

echo === <Insert some message here> ===
<device type> dev <device no>
setenv bootargs '<your kernel command line>'
ext2load <device type> <device no>:<partition no> <address 1> </path/to/zImage>
ext2load <device type> <device no>:<partition no> <address 2> </path/to/initramfs>
bootz <address 1> <address 2>

Example for ext4 rootfs on eMMC partition 7, and kernel files on partition 1:

echo === boot.scr: Loading your kernel from eMMC partition 1 ===
mmc dev 0
setenv bootargs 'quiet root=/dev/mmcblk0p7 rootfstype=ext4 mem=512M@0M vmalloc=320M'
ext2load mmc 0:1 0x1000000 /boot/zImage
ext2load mmc 0:1 0x2200000 /boot/initramfs
bootz 0x1000000 0x2200000
Step 5

Compile the boot script:

sosboot # cd /mnt/boot
sosboot # mkimage -A arm -O linux -T script -C none -a 0 -e 0 -n "ubootscript" -d boot.cmd boot.scr
Step 6

Finally, check that the following files exist and are accessible to uboot:

# zImage [on an ext filesystem on eMMC, SD or USB drive]
# initramfs [on an ext filesystem on eMMC, SD or USB drive]]
# boot.scr [In /boot of an ext filesystem on the 1:st partition of eMMC/SD/USB

Then do

cd / 
umount /mnt 

remove the drive and switch off your AC100.

Installation complete.

Booting your new Linux system / troubleshooting

Press the power button.

The boot process will look a bit different depending on your bootloader:

Fastboot

With Fastboot you have the choice to boot from “LNX” partition or “SOS” partition.

If you installed the boot image to “LNX”, just wait for the kernel to load.

If you installed the boot image to “SOS”, hold <HOME> button after power on. Then wait for the kernel to load.

Uboot

(Note: boot.scr may not be needed anymore. TODO: Please correct.)

'uboot' will look for a boot script (/boot/boot.scr) on the 1:st partition of each device known to it, until it finds one or runs out of devices to search.

If the boot script fails to execute, you should be presented with a uboot shell. You may use this to manually set the kernel parameters, load the kernel and boot. This procedure is illustrated with an example: Load a kernel located on an ext4 filesystem on the “SOS” partition and boot into a rootfs on eMMC partition 7.

PAZ00 # setenv bootargs 'quiet root=/dev/mmcblk0p7 rootfstype=ext4 mem=512M@0M vmalloc=320M'
PAZ00 # ext2load mmc 0:1 0x1000000 /boot/zImage
PAZ00 # ext2load mmc 0:1 0x2000000 /boot/initramfs
PAZ00 # bootz 0x1000000 0x2000000

Now what?

If everything went well, you will now be in the middle of a (more or less) basic Linux system running on your AC100.

Well done.

You may continue to ”configure the system” to really get things going.

Common problems

Problems that can't be helped / corrected in the guide. E.g.

  • “I gave away my AC100” A: This has nothing to do with this guide! :D
  • “I forgot to create backups” A: Don't. Don't!
  • “My AC100 doesn't hover with this kernel” A: That's a known bug.

etc.

/END OF GUIDE

Login