OMAP Ubuntu Core

= Introduction = Canonical is now sharing a minimal filesystem for ARM based called Ubuntu Core. See here: https://wiki.ubuntu.com/Core This image contains the APT software so you can install and customize your filesystem from a minimal installation. This is mainly for developers who want to run a custom filesystem on an embedded device.

Except specified otherwise, most instructions and information provided in this wiki is applicable to any ARM platform.

= Configuring a boot partition e.g. Pandaboard = Here are a few steps I followed in order to get to a shell prompt on the serial console on my Pandaboard ES2.1: fatload mmc 0:1 0x80000000 uImage setenv bootargs rw vram=32M fixrtc mem=1G@0x80000000 root=/dev/mmcblk0p2 console=ttyO2,115200n8 rootwait bootm 0x80000000 wget http://ports.ubuntu.com/ubuntu-ports/dists/precise/main/installer-armel/current/images/omap4/netboot/MLO wget http://ports.ubuntu.com/ubuntu-ports/dists/precise/main/installer-armel/current/images/omap4/netboot/u-boot.bin wget http://ports.ubuntu.com/ubuntu-ports/dists/precise/main/installer-armel/current/images/omap4/netboot/uImage wget http://cdimage.ubuntu.com/ubuntu-core/daily/current/precise-core-armhf.tar.gz
 * If you don't already have one, prepare an SD Card with 2 partitions: one for the boot and one for the rootfs. See here for detailed instructions: http://omappedia.org/wiki/SD_Configuration
 * Open a terminal and follow the instructions below.
 * Create a temporary folder:
 * Get into this directory:
 * Create the boot script file boot.script with the following content:
 * Generate the boot.scr file:
 * Download the Oneiric Ocelot release from Canonical:
 * Download the MLO, u-boot.bin and kernel:
 * Copy files over to the boot partition:
 * Untar the filesystem onto the SDCard:
 * Clean files:
 * Alternatively, you can create your environment with Ubuntu 12.04, by downloading the following files instead of the one mentioned above:

= Tuning the Filesystem =

By default, the Ubuntu Core has no login prompt or serial console. You can get it to work with the following steps:

Getting a Terminal on the same serial port as for the console

 * If you have a "console" bootarg in your u-boot you can simply add 2 files to read the "console=" from /proc/cmdline file and do similarly to the linaro-overlay-minimal Linaro package:
 * On the SD Card rootfs partition, go to the init folder:
 * Create a new file with the extention of ".conf". It could be "serial-auto-detect-console.conf" for instance with the following content:
 * 1) serial-auto-detect-console - starts getty on serial console
 * 2) This service starts a getty on the serial port given in the 'console' kernel argument.
 * 1) This service starts a getty on the serial port given in the 'console' kernel argument.

start on runlevel [23] stop on runlevel [!23]

respawn

exec /bin/sh /bin/serial-console This file shall be called the same name as in its invokation in the 'exec' line of the "serial-auto-detect-console.conf" file. Therefore, you need to create in our case a file named "/bin/serial-console" with 'r+x' (read and execute) rights:
 * Secondly, create a shell script that will parse the kernel command line, read the "console" argument and launch the TTY:

Login in "root" without the need of a password
root::15259:...
 * On the SD Card rootfs partition, edit the file /etc/shadow and remove the '*' character in between the semi-colons. You should get something like:

Getting network up and running
In most cases, you'll just need to look at your Linux Desktop PC settings and mimic those for your board. The following steps will describe the configuration when using a DHCP server.

Network configuration files for 'DHCP' client
A few files on your target filesystem need to be taken care of. You can edit them from a Linux PC, this is the easiest way as not even "vi" is installed on the Ubuntu Core Filesystem. Steps are as follow: auto lo iface lo inet loopback auto eth0 iface eth0 inet dhcp Remove the "<>" symbols and replace by your own corporate DHCP and DNS servers adresses. domain  search  nameserver  nameserver  In your /etc/environment file, add something similar to this using your own corporate proxy server address and port number: http_proxy="http://myproxy.ext.mycompany.com:80" https_proxy="http://myproxy.ext.mycompany.com:80" ftp_proxy="http://myproxy.ext.mycompany.com:80" no_proxy="localhost,.mycompany.com" In your /etc/apt/apt.conf.d/proxy, add similar to this using your own corporate proxy server address and port number: Acquire {  http { Proxy : ; Proxy:: "DIRECT"; } }
 * Edit your /etc/network/interfaces file and add the bottom 2 lines:
 * If you are behind a firewall inside a 'Corporate Network', the following 2 files may need to be edited to according to your Coporate settings:
 * Edit your /etc/resolv.conf file and have something similar to this:
 * Add the proxy settings:

Just copy your similar file in your system and that should work.

Boot your Panda with network
In order to avoid this step, it's simpler to just add 'ip=dhcp' in the bootargs. The system will just request an IP address at boot time. In this case, your bootargs would look like it: bootargs quiet rw vram=32M fixrtc mem=1G@0x80000000 root=/dev/mmcblk0p2 console=ttyO2,115200n8 rootwait ip=dhcp should run fine.
 * Re-insert your SD Card into the Pandaboard
 * Boot the board with the network cable attached.
 * You should have an IP address after you run the following command line:
 * Finally verify you can use APT command:

Configuring APT to fetch all packages
By default, many Ubuntu packages are not installable. In order to fetch all Ubuntu repositories (What's this ?), you need add the following lines to /etc/apt/sources.list: And then run: apt-get update

Adding a User Interface

 * On a Pandaboard, I recommend you install the OMAP4 packages first. Latest packages can be installed from the TI OMAP Release PPA on Launchpad: https://launchpad.net/~tiomap-dev/+archive/release . Details how to add this PPA are available on this Launchpad web page. Once set, run the commands:
 * If your kernel version updates, you may run into the LP#626749 issue (https://bugs.launchpad.net/ubuntu/+source/flash-kernel/+bug/626749). I solved it by creating the /etc/flash-kernel.conf file with the following content (my u-boot being on the 1st partition of my SD Card and my Filesystem being on the 1st partition of an external USB hard drive):
 * And then, re-run

>> date MMDDHHMMYY Note: if this command fails, see Configuring APT to fetch all packages
 * Set the date to reduce the messages from tar.
 * You'll need Xorg support too:
 * And now a window manager. A light WM is OpenBox and it can be installed with the following command line:
 * The PVR seems to have issues with the mouse cursor, hence just make sure to enbale the SWCursor option in your xorg.conf. This can be done in /etc/share/X11/xorg.conf.d/99-pvr.conf file:
 * Last but not least, start X:
 * You are now ready to right-click on your mouse and open an X-Terminal.

= Kernel and Bootloaders, do it yourself instead of using prebuilt binaries =

So now, the basic system is up to date, you have a working minimal Ubuntu environment. As you have certainly noticed, so far you have been using pre-built binaries downloaded from the Ubuntu archive. So now it is time to get into the real stuff, and rebuild your own kernel and bootloaders and start customizing it!

Bootloaders
First let's start with u-boot. Some decent efforts have been made by various people in the OMAP community to ensure that all the necessary patches are available in mainline boot. So in general, you just need to checkout a recent u-boot commit, build and put the binaries on SD boot partition... Nevertheless because u-boot is under active development, sometimes a random commit from the mainline tree might not work. As such it is recommended to use the most recent stable u-boot release (git tag) unless you really know what you are doing.

At the time of this writting, the most recent u-boot released version is v2011.12. So the following instructions will get you a working set of bootloaders for Panda and Panda ES (I tested on Rev A1 and Rev EB3):

git clone git://git.denx.de/u-boot.git git checkout -b v2011.12 v2011.12  make omap4_panda_config make

That will generate the following files: MLO u-boot.img u-boot.bin

u-boot.img is exactly the same as u-boot.bin, but a u-boot header has been appended (using mkimage). Nowadays, with current version of u-boot it is expected to use u-boot.img, as this filename is hardcoded in the initial bootloader (MLO).

So now you can copy the 2 files (MLO and u-boot.img) onto the SD boot partition to replace the pre-built bootloaders, and you should be able to boot again, and verify that you are using your own bootloaders (check the boot traces).

Linaro is also maintaining its own stable version of u-boot which is being used for Linaro and Canonical releases. The git tree is located here http://git.linaro.org/gitweb?p=boot/u-boot-linaro-stable.git. As usual you should start by using the most recent tag/branch. In general Linaro tree might get a few more patches which are in the process of being upstreamed, but the differences with mainline tend to decrease over time.

Kernel
Similarly to u-boot, there is some good support for Panda and Panda ES with the mainline kernel. As of this writting mainline kernel is at v3.3-rc1. If you checkout a recent mainline, you should be able to compile with the default OMAP defconfig, and it should boot:

git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git git checkout -b v3.3-rc1 v3.3-rc1   make omap2plus_defconfig make uImage

Alternatively, you might want to build the kernel modules as well: make modules

The default omap2plus_defconfig is the kernel configuration that works on any OMAP2+ boards. There are default settings, that you might want to change. For example, you can enable USB EHCI and that will bring support for the USB host on the Panda. Of course there are tons of other settings that you can change, it is now time to start customization!

= Chroot'ing into the Ubuntu Core Filesystem = One solution to customize your Ubuntu Core Filesystem is to do it from the Linux PC. Using a 'chroot' is sometimes quite convinient as you can run commands as you normally do on the ARM target. Here are some quick steps to get running:

Chroot configuration on the Linux PC
This can be done with the following command line (on your Linux PC): You are now in your 'chroot' which means you can run commands like if you were on your target ARM device.
 * Verify that on your Linux PC you have the 'qemu-user-static' Ubuntu package installed.
 * Have your SD Card mounted on your Linux PC and go to your rootfs Ubuntu Core folder, generally:
 * Copy the qemu for arm file:
 * If not done yet, have your network settings properly configured:
 * Then, mount sys, proc and dev:
 * Finally, chroot into your target filesystem:

Using the 'chroot'

 * The first step is to verify the network connection is fine. You can run:
 * You are now ready to install any new package in your Ubuntu Core Filesystem using APT tools.

Getting out of the 'chroot'
Make sure your at the / target FS and run the following commands:
 * Un-mount the target filesystem:
 * Go back to your original network settings:

= Helper scripts =
 * I created some helper scripts and was thinking it might be useful for everyone to share: https://github.com/DavidBercovitz/ubuntu-core
 * This script should help you create everything from scratch without having to type all the basic commands. I found it particularly useful for automation.

= Some useful links = Canonical Ubuntu Core wiki: http://www.canonical.com/engineering-services/ubuntu-core

Ubuntu Core Is Getting Ready For Oneiric: http://victorpalau.net/2011/08/26/ubuntu-core-is-getting-ready-for-oneiric/