Instructions for building and booting Linux

This page describes what parts are necessary in order to run GNU/Linux OS on Xtensa, their interaction and setup.

GNU/Linux on Xtensa

GNU is a collection of free software that provides POSIX environment. Linux is an operating system kernel. In order to boot GNU/Linux OS on Xtensa the following parts are needed:

• a board with Xtensa core supported by Linux, or Xtensa simulator
• bootable Linux kernel image
• GNU software packaged in a form suitable for booting on Linux, the so called root file system
• a bootloader or on-chip debugger capable of loading Linux kernel image into the board RAM

To build Linux image and root file system a toolchain correctly configured for used Xtensa core is needed. Toolchain configuration is performed by application of Xtensa configuration overlay. Correct toolchain configuration is critical for building other pieces of software correctly.

Xtensa cores supported by Linux

Official requirements for Xtensa core to run Linux are listed in the Xtensa OSKit Guide document. The absolute minimum set of options required to run Linux is windowed registers, exception option and one level-1 or medium level timer interrupt.

• Full MMU option is required for full featured Linux kernel that includes process address space isolation, virtual memory and fork syscall.
• Full MMU option, thread pointer option and conditional store option are required for running userspace with NPTL or TLS.

Xtensa boards supported by Linux

The following boards collectively referred as XTFPGA family are readily supported by Linux: Avnet LX60, LX110, LX200; Xilinx ML605, KC705. For board details/setup guide please see corresponding Board Guide or Board Prototyping Guide provided with Xtensa software release.

Xtensa simulators

• Xtensa software provides Instruction Set Simulator (xt-run) capable of running Linux configured for ISS.
• QEMU is a free system emulator capable of emulating any XTFPGA board or ISS. It can be configured to emulate any Xtensa core, but it does not currently support TIE extensions to the core architecture. Please see this page for more details.

Linux kernel

Linux kernel needs to be configured for the specific Xtensa core. For that reason Linux is usually configured and built separately from the userspace software. Please see this page for more details.

Root file system

Currently we support building GNU software and packaging it into root file system with the Buildroot. There are several types of root file system that Linux can boot with:

CPIO archive

• CPIO archive may be built into the kernel (so called 'built-in initramfs'), the resulting single image will contain both Linux and GNU software. It's easy to boot, but in order to change anything the kernel needs to be rebuilt.
• CPIO archive may also be loaded separately from the kernel, but used in the same way as the built-in initramfs. It's harder to boot (two files instead of one), but easier to change.

Both cases of CPIO use RAM for the root file system, so they're very fast. The downsides are that they take some time at startup to unpack, reserve some RAM (which may be an issue on low-memory boards like LX60) and are not persistent.

EXT2/3/4 file system image

EXT2/3/4 file system image may be used directly with ISS or QEMU through the Simulated block device Linux feature. Please see this chapter for more details.

TAR image

Tar image may be unpacked into a directory shared through NFS. Linux on XTFPGA boards and on QEMU can be configured to use NFS root file system.

UBIFS image

UBIFS image may be written directly to the daughterboard FLASH on XTFPGA boards. Please see this chapter for more details.

Bootloader

U-Boot can be used as a bootloader on XTFPGA boards. Please see this page for more details about installing it into the daughterboard FLASH.

On-chip debugger

On-chip debugger is good for debugging lowest level software: bootloader and Linux kernel itself. It also allows loading executable images into new board with empty FLASH. It consists of JTAG probe connected to the XTFPGA daughterboard (ML605 and KC705 daughterboards also have built-in JTAG chip), OCD monitor (xt-ocd) running on developer machine where the other end of JTAG probe is connected, and xt-gdb, the modified version of GNU debugger from the Xtensa software release. Please see Tensilica Debug User's Guide for more information about OCD setup and configuration.

Building GNU/Linux OS

In order to follow these instruction a build machine with GNU/Linux and a set of development tools (native binutils and gcc, make, wget, tar, ...) is needed. In the following example all software will be downloaded and built in the current directory. Xtensa tools used in the examples are installed into $XT_ROOT, tools release is $XT_RELEASE and selected core is $XT_CORE.

Prepare the overlay

Please see this page for overlay repacking script and details of the overlay source location. Create conversion script by pasting this into the file overlay-script and making it executable:

 $ cat > overlay-script
 ....
 ^D
 $ chmod +x overlay-script

Run it and rename the resulting file:

 $ ./overlay-script ${XT_ROOT}/XtDevTools/install/builds/${XT_RELEASE}-linux/${XT_CORE}/src/xtensa-config-overlay.tar.gz
 $ mv xtensa-overlay.tar xtensa_${XT_CORE}.tar

Get, configure and build the toolchain and root file system

Get the buildroot git tree:

 $ git clone git://git.buildroot.net/buildroot

Check out some released version:

 $ git checkout 2014.11

Create build directory and configure it:

 $ mkdir buildroot-build
 $ make -C buildroot O=$(pwd)/buildroot-build menuconfig

Please see this chapter for more details about configuring the Buildroot.

Select 'Target Architecture' = Xtensa, 'Target Architecture Variant' = Custom Xtensa processor configuration, set 'Custom Xtensa processor configuration name' to the contents of ${XT_CORE}, set 'Overlay directory for custom configuration' = $(TOPDIR)/..

Select toolchain options, packages to be built and final root file system image type.

Build the toolchain and the root file system:

 $ make -C buildroot O=$(pwd)/buildroot-build

Get, configure and build the Linux kernel

Get stable Linux release tree:

 $ wget https://www.kernel.org/pub/linux/kernel/v3.x/linux-3.19.1.tar.xz
 $ tar -xf linux-3.19.1.tar.xz

Create variant directory for the specific core and copy core configuration files there:

 $ mkdir -p linux-3.19.1/arch/xtensa/variants/${XT_CORE}/include/variant
 $ cp ${XT_ROOT}/XtDevTools/install/builds/${XT_RELEASE}-linux/${XT_CORE}/config/*.h linux-3.19.1/arch/xtensa/variants/${XT_CORE}/include/variant

Create build directory and configure it:

 $ mkdir linux-build
 $ ARCH=xtensa CROSS_COMPILE=$(pwd)/buildroot-build/host/usr/bin/xtensa-buildroot-linux-uclibc- make -C linux-3.19.1 O=$(pwd)/linux-build menuconfig

Select 'Xtensa Processor Configuration' = Custom Xtensa processor configuration, set 'Xtensa Processor Custom Core Variant Name' to the contents of ${XT_CORE}. Select desired 'Xtensa System Type'.

Please see this chapter for more details about configuring Linux.

Build the kernel:

 $ ARCH=xtensa CROSS_COMPILE=$(pwd)/buildroot-build/host/usr/bin/xtensa-buildroot-linux-uclibc- make -C linux-3.19.1 O=$(pwd)/linux-build all

Booting GNU/Linux

TBD