Pandaboard

The Pandaboard is an ARMv7 architecture single board computer based on a Texas Instruments OMAP4430 SOC (System On Chip) @ 1GHz. A later model, the Pandaboard ES include an OMAP4460 clocked @ 1.2GHz.

Installation
Installing Gentoo a Pandaboard is quite simple for anyone with some experience installing Gentoo. An SD card is required with at least 2 GB size. If the goal is to have a self hosting Gentoo installation, a minimum of 8 GB is recommended. A Gentoo install on a Pandaboard with a base system and compiled kernel (as of 2015) can be around 4 GB. This can balloon very quickly so if a desktop enviroment installation is planned, a card with more capacity is highly recommended as the Pandaboard can accommodate SD cards up to 32 GB. Anyone familiar with the Gentoo Linux installation process would find that it is not much different from a regular installation, however, if building on an amd64 or other PC there are extra steps required thereby having to cross compile the kernel and bootloader for the ARMv7 architecture. Also there is the issue of not being able to natively run some of the binaries necessary in a normal installation because of the differing architecture. There are some workarounds to this as described through the article.

Requirements
To be able to install Gentoo, the following are required:


 * A machine with Gentoo and an SD card reader on it
 * A Pandaboard or Pandaboard ES
 * One SD card at least 2 GB, preferably 8 GB or larger
 * A network connection

Preparation
The installation on this device is a bit different, and therefore maybe not so easy as a regular installation, as it is not possible to install Gentoo on it by booting an installation environment. For installing Gentoo (and any other distro, really) a host system is required to prepare a minimal installation on the SD card.

The basic steps to set up the installation are:


 * 1) Prepare the SD card
 * 2) Extract stage3 to the 2nd partition of the SD card
 * 3) Extract portage snapshot (required to emerge things and ntp(see below))
 * 4) Cross compile and install the bootloader (U-boot) and kernel
 * 5) Setup fstab
 * 6) Setup root password
 * 7) Configure hostname and networking (optional, but recommended)
 * 8) Enable SSH access (optional, but recommended)
 * 9) Enable serial console access (optional, but recommended)

Hardware
The Pandaboard has the following specifications:


 * OMAP4430 @ 1GHz
 * PowerVR SGX540 graphics
 * 1 GB LPDDR2 RAM
 * WiLink 6.0 Wireless (wl12xx Linux module)

SD Card Setup
OMAP-based systems need a special setup of the SD card to boot from it. For more information please check this link. (TODO: Find the broken link..)

The following script will format an SD card accordingly, creating two partitions. The first partition size is based on the size of the SD card itself, and it's formatted in vfat. The second partition is the free space left on the card after the first partition, and it's formatted in ext4.

(Replace mmcblk0 with the name of the device of the SD card)

Now mount the partitions on the card in preparation to install Gentoo to the Pandaboard.

Unpack stage3 and portage
The unpacking of the stage3 and portage is much the same as a regular Gentoo installation.

Here's some information about the stages.

Architecture: arm Subarchitecture: armv7a CHOST: armv7a-hardfloat-linux-gnueabi Profile: default/linux/arm/13.0

The new EABI is used, also called gnueabi along with hardfloat. That is armhf on Debian.

Therefore, an stage3 is needed for best performance, available under the  directory in a preferred Gentoo mirror. The armv7a_hardfp stage3 is the required download.

Optionally, also grab a portage snapshot

Extract the stage3 and snapshot, this may take a while. (Adjust the tarball name accordingly)

Bootloader and kernel
A kernel and a bootloader for the Pandaboard need to be fetched and built to boot the Pandaboard.

The Pandaboard doesn't have a NAND/flash device, so the bootloader (U-Boot) needs to be located on the SD card, along with the kernel.

For building the required software needed to boot the Pandaboard, the following tools are emerged on the host system.


 * - For creating a crosscompiler to compile the kernel and U-Boot
 * - This includes mkimage which creates boot.scr and kernel/ramdisk images that U-Boot can understand
 * - The Pandaboard requires the first SD card partition to have a FAT based filesystem

Using the Ubuntu kernel
Originally the vanilla kernel.org wasn't as tested as the one used on Ubuntu. TI decided to provide support to Ubuntu, so it makes sense to have all the fixes Ubuntu have by using their kernel.

If the following link returns a 404 not found error, download the latest file from the precise distribution in the following link, the latest stable kernel version will be labeled "security, updates (main)". https://launchpad.net/ubuntu/+source/linux-ti-omap4

Fetch the Linux Kernel for the Pandaboard from Ubuntu precise distribution:

Extract the kernel sources and change to the directory, the given example is for the Ubuntu kernel, modify for the version being used:

The default kernel config for this kernel version is really minimal, and doesn't have support for wifi or accelerated graphics drivers. Gentoo developer provided a basic kernel config along with the original Gentoo on Pandaboard documentation for reference.

After downloading the kconfig, update and customize it:

Using the mainline kernel
Another option is using the mainline kernel sources. Using the mainline kernel may have newer features but may also lack support for hardware 3D and/or DSP acceleration.

The mainline (vanilla-sources) kernel can be found at https://www.kernel.org/pub/linux/kernel/

Fetch the mainline kernel:

Extract the kernel source and change to the directory, modify versions to suit:

Create a default config and customize it:

uImage
This section describes cross-compiling a legacy u-boot uImage

Replace 9 with the number of cores there are on the host computer:

If the command fails due to no LOADADDR being specified add the required parameter to the command. This usually needs to be set when compiling a mainline kernel target.

Once the build is complete there will be a kernel image at

zImage
This section describes cross-compiling a zImage, u-boot can now boot this.

Once the build is complete there will be a kernel image at

Kernel modules
Compile and install the kernel modules, installing to the mounted root on the SD card.

Install the bootloader and kernel
Now copy the needed u-boot bootloader and Linux kernel files (the ones that were built before) to boot the Pandaboard.

fstab
The file needs to be set up to configure the root filesystem, and optionally a mount point  so it's possible to mount it and copy new boot files there in the future.

Edit the fstab similarly:

Setting a password
This is one of the most important parts of the installation. As without the root password it will not be possible to login!

For setting the password, the command has to be executed. However that's not possible since an x86/amd64 or other architecture PC can't run ARM binaries. Therefore, another way has to be chosen to modify the file that contains the passwords inside the chroot, so it is possible to set a default root password.

(Generate a password)

Replace the root user password similarly to the example given below. The secret is the second field which needs to be substituted with the output the command returned. In these two examples, the last line sets the password to "gentoo".

Boot script
TODO: explain preEnv.txt uEnv.txt

To boot the Pandaboard, a boot script is needed along with the command to create the file. This file is read by U-Boot in the boot process and can contain extra commands and environment configuration. It is possible to add any linux command line options here necessary for the boot process, such as a different location of the root filesystem.

Some examples of U-Boot boot.scr files (delete as appropriate in future) Example for uImage and fdt without initramfs. For booting without an initramfs there needs to be a minus "-" as second argument to bootm or bootz commands, in place where the ramdisk address would usually be.

Example for zImage and fdt with ramdisk

Create with  provided by u-boot-tools

Create a ramdisk with mkimage (optional?)

Network configuration
Please read the network configuration chapter of the ARM handbook to configure the network.

Clock and time
One of the problems the Pandaboard has, is that it doesn't have a battery to save the clock time. To mitigate this, on Gentoo there is an option in the init system called which sets the date of the system upon boot from a last modified date of a file.

has to be removed from the startup because it sets the date from the RTC, which is 2000-01-01 upon startup and overrides swclock's date.

uses the 's modification time to set the date, therefore update it to have the current date and time.

Although this doesn't fix the issue, at least helps to set a sane date and time. Consider using NTP, documented in the next chapter

SSH access
If SSH is required, add sshd to the startup of the system so it's possible to administrate the Pandaboard from over the network.

Serial terminal
By default the ttyS0 port is configured at 9600 bps. However, almost all of the ARM devices run the serial port at 115200 bps. Also, in the case of the Pandaboard, the port is ttyO2 instead of the normal ttyS0. So this should be added to the file:

Comment out or remove the lines containing ttyS* and add a new line replacing 9600 with 115200 and ttyS0 with ttyO2

Finishing up
Unmount the SD card, when the contents have finished writing it is safe to remove. This may take a while depending the speed of the SD card.

Post installation
This is pretty much all of the installation. It is highly recommended to read all the recommendations of the handbook.

Once the card is ready, put it into the Pandaboard and it should be able to boot.

One of the problems of the Pandaboard is that it doesn't save the date because it doesn't have a battery for the clock.

After logging into the new Gentoo on Pandaboard installation, is it recommended setting a date and emerging net-misc/ntp to keep the clock up-to-date. Also it's recommended to put both and  to boot on startup, so a proper date and time is set.

However, keep in mind that NTP requires a network connection and a NTP server being reachable, either on the local network or on the Internet.

Emerge ntp, start both ntp-client and ntpd and add them to the default runlevel on booting:

The Pandaboard has integrated hardware that needs either a driver, firmware or tools to work. Making work such hardware is documented on the following page:

TODO: (find links again..)

Special thanks

 * Raúl Porcel for writing the original Pandaboard GuideXML documentation
 * pandaboard.org for providing a Pandaboard to document and support Gentoo on it
 * Jordi Inglés, who gave an 8 GB SDHC for the project
 * Siarhei Siamashka (ssvb) for giving helpful hints
 * Michał Majchrowicz for checking the doc in the Pandaboard ES
 * Daniel Díaz
 * Steev for being a great help and converting the GuideXML to HTML
 * calculus for giving someone an urge to migrate the document to the wiki