Instructions for building and booting Linux
These instructions explain how to build a toolchain, root filesystem and kernel for Linux running on an Xtensa processor. These instructions apply specifically to the XTAV60 (LX60) board. They are based on a snapshot of work in progress.
Some general notes on these instructions:
- The following was tested on an x86 machine running RedHat Enterprise Linux 4 (RHEL4) and Fedora Core 3 (FC3). It is expected to work on other Fedora releases (e.g. was tested on FC6) but to maintain host compatibility with Tensilica Tools, it is best to avoid Fedora releases beyond FC5. Other host distributions likely work but have not been tested.
- Lines prefixed with "sudo" need to be executed as root. The rest is best executed as a non-root user. (It is possible to install subversion and git as a non-root user if root access is an issue. How to do this isn't shown here.)
- Lines that set environment variables assume a Bourne compatible shell (e.g. /bin/sh or bash), but are easily adapted to other shells.
- Instructions are assumed executed all in order (e.g. commands assume current directory and environment variables set earlier).
Ensure you have all needed packages installed on your system
Install the 'Subversion' source control tools
Download and install the Subversion source control tools if you don't have them already installed (FC6 has it, FC3 doesn't):
$ sudo yum install subversion
This may install dependent packages (e.g. 'apr', etc).
Documentation for Subversion is available online at http://svnbook.red-bean.com/
or by typing svn help at a shell prompt.
Download and install the git source control tools
First determine whether you already have git installed. Try:
$ git
which should output a help page. If instead git is not found, download and install the git source control tools.
On FC6, you can just do the following
(which installs documentation accessible with man git
or git help):
$ sudo yum install git
On FC3, yum doesn't know about git, so you have to do something like:
$ cd /tmp $ lwp-download http://kernel.org/pub/software/scm/git/git-1.5.3.1.tar.bz2 $ tar xfj git-1.5.3.1.tar.bz2 $ cd git-1.5.3.1 $ make prefix=/usr/local all $ sudo make prefix=/usr/local install
and make sure /usr/local/bin is in your PATH.
This doesn't install git documentation. For that, you have
to build doc and info make targets, which require first
installing other packages such as asciidoc and others.
However, for this example, documentation is not necessary.
You can find online docs such as a
tutorial
and manual pages.
Download buildroot and the Linux kernel
Download buildroot sources
Buildroot is used to build the toolchain and root filesystem. First setup a work area:
$ cd <workdir>
where <workdir> is the path to an empty directory on a disk with at least 4 GB available space. The following creates and populates the <workdir>/trunk directory:
$ svn co svn://linux-xtensa.org/var/svn/repos/buildroot/trunk/
Download Linux kernel sources
First you need to decide which kernel tree to work with. The xtensa-devel tree contains the most recent changes but is not very stable -- it gets updated semi-regularly with the very latest Linux kernel tree from kernel.org. The xtensa-2.6.23 tree is a more stable tree based on the 2.6.23.n kernel from kernel.org. You can also get both kernel source trees of course.
To get the stable tree into directory <dir> (which must not already exist):
$ cd <workdir> $ git clone git://git.linux-xtensa.org/kernel/xtensa-2.6.23 <dir>
This creates and populates the <workdir>/<dir> directory. If <dir> is omitted, it defaults to xtensa-2.6.23 (the last non-extension part of the cloned path).
Similarly, to get the development tree:
$ cd <workdir> $ git clone git://git.linux-xtensa.org/kernel/xtensa-devel <dir>
Install any required processor specific overlay
This step is required if you are targeting a custom Xtensa processor. If you use a Diamond 232L Standard Core, you can skip this step.
To configure buildroot and the kernel to use a custom Xtensa processor configuration, you need to overlay a set of files customized for your processor configuration onto toolchain sources (gcc, binutils, gdb, etc) and the Linux kernel. This process has been automated using a script located in the buildroot source tree. For usage information, you can invoke it without arguments:
$ cd <workdir> $ ./trunk/target/xtensa/xt-buildroot-overlay-install
which displays a help message similar to the following:
xt-buildroot-overlay-install version 1.1
Usage: xt-buildroot-overlay-install <parameters> [<options>]
Where <parameters> are:
-t file.tgz Specify path to the Xtensa Linux overlay tarball, typically
<xtensa_root>/xtensa-elf/src/linux/misc/linux-overlay.tar.gz
-b dir Path to the base of the buildroot source tree, in which
package specific overlay tarballs get installed.
-k dir Path to the base of the Linux kernel source tree, in which
the Linux kernel specific overlay gets installed.
-c config_name Name for the Xtensa processor configuration as it will be
known to the open source community. Must be a lowercase
identifier, starting with a letter, consisting of letters
and numbers and underscores, not ending with underscore
and not containing consecutive underscores. For examples:
dc232b , dc232b_be , mmubasele , fsf , s5000 .
-l long_name Long name for the Xtensa processor configuration, human-
readable with spaces etc allowed (must be quoted).
For example: 'Diamond 232L Standard Core Rev.B (LE)'
Try to keep it within approximately 40 characters.
And <options> are:
-f If package specific overlay tarballs already exist in
the destination source tree, overwrite them without asking.
--help Show this usage message.
Note that the Xtensa Linux overlay tarball MUST be obtained from an Xtensa core package built using release RB-2008.3 or later. Until this release becomes available (sometime in early 2008), the overlay tarball can be obtained by providing Tensilica customer support with your processor configuration and TIE (such as, .xcf and .tdb files); they should be able to generate it for active customers.
Here is an example invocation of the overlay installation script:
$ ./trunk/target/xtensa/xt-buildroot-overlay-install -t blinkcore-linux-overlay.tar.gz \
-b ./trunk -k ./xtensa-devel -c superzip -l "ChipCorp SuperZIP Blink Accelerator Core"
The script extracts some relevant information from the overlay tarball, presents it along with relevant parameters to the user, and prompts for confirmation before proceeding.
The chosen processor name (-c option) must be unique among known Xtensa processors. It is also probably wise to avoid names confusingly similar to other (non-Xtensa) processors. If you expect at some point to contribute support for your custom processor to the open-source community, this name will likely be long-lived. (One way to contribute support for a custom processor might be to submit the overlay tarball or files to the linux-xtensa.org maintainers.)
In the steps below, buildroot and the Linux kernel must be configured
(in their respective make menuconfig steps) to select
the custom Xtensa processor option.
This presents an extra configuration menu entry where you must provide
the name of the Xtensa processor. Set it to the same name
as was specified in the -c option above.
Build a toolchain and root filesystem using buildroot
Note: for more details on generic buildroot topics not covered in this simple how-to, see buildroot.uclibc.org.
Change some default behavior
Edit trunk/target/generic/target_skeleton/etc/inittab
Comment out the default getty's:
# Set up a couple of getty's
#tty1::respawn:/sbin/getty 38400 tty1
#tty2::respawn:/sbin/getty 38400 tty2
We'll use the serial port getty. Modify the baud rate from 115200 to 38400, and un-comment the line:
# Put a getty on the serial port
ttyS0::respawn:/sbin/getty -L ttyS0 38400 vt100
Configure buildroot
Note: You need the TERM environment variable properly set for curses based tools to work.
$ cd <workdir>/trunk $ make menuconfig
You should get a curses interface for configuring buildroot. Make the following changes:
- Change Target Architecture from i386 to xtensa
- Change Target Architecture Variant to desired Xtensa or Diamond core (e.g. dc232b)
- Under Toolchain Options, make sure uClibc C library Version is set to (uClibc 0.9.29)
- Under Toolchain Options, change Binutils Version from '2.17' to '2.17.50.0.17'
- Under Target Options, enable cpio the root filesystem; this creates a Compression method submenu; under this submenu, select gzip
- Again under Target Options, enable initramfs for initial ramdisk of linux kernel
- Exit and save the configuration
Configure uClibc
$ make uclibc-config
Build buildroot
$ make
THIS WILL TAKE A LONG TIME (perhaps an hour or many, depending on your system).
Wait patiently for build to complete. This builds an entire toolchain as well as some basic packages, and constructs a root filesystem. It might build many more packages if you selected them earlier with menuconfig.
If Something Goes Wrong
Perhaps you missed some step above and the build fails. Or you're just switching to a different processor configuration, or making some change with unknown dependencies. Either way, you'll probably need to fix the error and/or make the change, and redo the whole build. The above 'make' command does not check many dependencies, so it will usually NOT rebuild things that depend on whatever you have fixed. Here's one possible sequence to retry the make without having to wipe out the 'trunk' directory tree completely and start again from the svn checkout. (Caveat emptor: this sequence has not yet been tested.)
$ rm -rf *build_xtensa* binaries $ make uclibc-config $ make
It should not be necessary to empty the 'dl' subdirectory, which contains tarballs downloaded from the Internet, or the .config file, which contains the buildroot configuration. It does seem safer to delete the uClibc configuration.
Build a Linux kernel
Configure the kernel
The build is a two-step process: configure the kernel, and build it. First, before we can do anything with the kernel, set your PATH to point to the toolchain built using buildroot.
$ export PATH="<workdir>/trunk/build_xtensa/staging_dir/usr/bin:$PATH"
Now setup a destination for kernel builds. We usually like to have the build directory separate from the source directory, so we use 'O=</destination/path>' in kernel make commands.
$ mkdir build-kernel
Let's start with the default configuration for the XTAV60 (LX60) board as follows:
$ cd xtensa-devel $ make O=../build-kernel ARCH=xtensa KBUILD_DEFCONFIG=lx60_defconfig defconfig
This configures the kernel using the default configuration found in arch/xtensa/configs/lx60_defconfig.
Let's customize this a little bit to select the correct processor configuration, and to bundle the root filesystem into the kernel:
$ make O=../build-kernel ARCH=xtensa menuconfig
Under General setup, make sure the Initial RAM filesystem and RAM disk (initramfs/initrd) support entry is enabled. Underneath that, edit Initramfs source file(s), and enter the path to the cpio formatted root filesystem generated by buildroot:
<workdir>/trunk/binaries/uclibc/rootfs.xtensa.cpio.gz
(Don't forget to replace <workdir> with the appropriate full path.)
Under Processor type and features, make sure the Xtensa Processor Configuration is correct and matches the processor configuration name you used to build the toolchain with buildroot (for example, dc232b for Diamond 232L Rev.B). The kernel build selects a toolchain and processor variant specific headers based on this selection.
Exit menuconfig, saving your configuration changes.
Backup your configuration outside the build directory. For example:
$ cp ../build-kernel/.config config.saved
If you do a clean rebuild of the kernel (e.g. "rm -rf ../build-kernel") you can now configure it with simply:
mkdir ../build-kernel ; cp config.saved ../build-kernel/.config
Of course if you update the kernel, you'll probably again have to do:
make O=../build-kernel ARCH=xtensa menuconfig
and save a new copy of your configuration.
Build the kernel
$ make O=../build-kernel ARCH=xtensa
The build will issue a few warnings which are normal. Once complete, the bootable image is in:
<workdir>/build-kernel/arch/xtensa/boot/Image.elf
and the uncompressed ELF file containing kernel symbols is in:
<workdir>/build-kernel/vmlinux
There is also a RedBoot bootable image (if you use RedBoot) in:
<workdir>/build-kernel/arch/xtensa/boot/zImage.redboot
Run the resulting kernel
Install Xtensa Tools with the 232L core
This can be done a a different machine than the one used so far, as long as it has access to the <workdir> directory tree.
Install and setup the Xtensa OCD Daemon
Setup and connect your JTAG probe, etc.
Connect a terminal server
At 38400 bps 8N1 no flow control to the LX60 serial port.
Optionally, setup networking
This step is optional.
Setup the board's MAC address using dipswitches (see LX60 docs) and connect the LX60 to a network that has a DHCP server that will respond to that MAC address. If you don't do this step, you'll simply not have network access, and the boot process will take a minute or so longer while the kernel times out waiting for a BOOTP response. You can edit the kernel configuration and rebuild the kernel to avoid using bootp (in particular, remove "ip=bootp" from the kernel cmdline).
Download and run the kernel
Reset the LX60 board (see board documentation).
Using Tensilica Tools, invoke:
$ xt-gdb <workdir>/build-kernel/arch/xtensa/boot/Image.elf
(xt-gdb) target remote <ocdhost>:20000 0 (xt-gdb) reset (xt-gdb) load (xt-gdb) set $pc = &_ResetVector (xt-gdb) symbol-file <workdir>/build-kernel/vmlinux (xt-gdb) c
where <ocdhost> is the IP address or DNS name of the machine running the Xtensa OCD daemon. The Linux kernel should start booting as soon as 'c' (continue) is executed.
You should eventually get a login prompt. Just login as root (no password).
Try various Linux commands. Look at /bin, /sbin, /usr/bin, etc to see what's available. Not all guaranteed to work, but basic things like 'ls' and 'ping' seem to work fine.
Note: no need to setup an NFS or TFTP server. The filesystem is contained within the kernel image. You may be able to mount other filesystems over NFS though, if you wish, after booting.
Building and Running a Kernel in Simulation (ISS)
You can build and run a Linux kernel in the Xtensa Instruction Set Simulator (ISS). The following instructions have only been tried with an ISS from release RB-2007.2 of Tensilica Tools. Bear in mind that the LX60 port is likely much more stable than the ISS port of Linux at this point in time.
Note: Depending on your host OS version, you may need to install Tensilica Tools on a separate machine.
Building a Kernel for ISS
Repeat all the same instructions as above for building the kernel for the XTAV60 (LX60) board, except that when initially configuring the kernel, start from the ISS platform template instead:
$ cd xtensa-devel
$ make O=../build-kernel ARCH=xtensa CROSS_COMPILE=xtensa_dc232b-linux-uclibc- \
KBUILD_DEFCONFIG=iss_defconfig defconfig
This configures the kernel using the default configuration found in arch/xtensa/configs/iss_defconfig.
Also, when running menuconfig:
$ make O=../build-kernel ARCH=xtensa CROSS_COMPILE=xtensa_dc232b-linux-uclibc- \
menuconfig
in addition to setting up the initramfs filesystem, do the following. Under Bus Options, deselect PCI support. Under Platform Options, deselect Default booloader kernel arguments. Under Processor type and features, under Xtensa Processor Configuration, select dc232l.
Continue configuring and building the kernel as usual. Note that if you
had built kernel images for another platform such as the XTAV60 (LX60)
board, this will overwrite them.
Running a Kernel on ISS
Using Tensilica Tools, invoke:
$ xt-gdb <workdir>/build-kernel/arch/xtensa/boot/Image.elf
(xt-gdb) target sim --turbo (xt-gdb) symbol-file <workdir>/build-kernel/vmlinux (xt-gdb) run
Wait patiently while Linux boots ... (maybe a minute)
Login as root (no password).
Note: Input via ISS is cooked, so everything typed gets echoed. Also, time as reported by the kernel does not progress according to true wall-clock time: it currently depends on a simulated processor clock, which advances at various speeds according to load.