Linux/Xtensa - User contributions [en]

Main Page

2008-07-14T22:51:46Z

Bwilson: /* <big>Welcome to the Linux/Xtensa Wiki</big> */

= <big>Welcome to the Linux/Xtensa Wiki</big> =

This Wiki project provides information about the [http://en.wikipedia.org/wiki/Linux Linux] port to the [http://www.tensilica.com Xtensa processor architecture].

{|
|-
|style="width:45%;height=100%; background:#ffffff;" valign=top|
<div style="border-bottom:1px solid #c0c0c0; ; width:350px; ">
<big>Getting Started</big>
</div>
* [[Supported Processors]]
* [[Evaluation Platforms|Evaluation Platforms]]
* [[Instruction Set Simulators|Running Linux in a Simulator]]
* [[Buildroot_Build_Instructions|Instructions for building and booting Linux (buildroot)]]
<div style="margin-top:1em; border-bottom:1px solid #c0c0c0; ; width:350px; ">
<big>Support</big>
</div>
* [[Internet Resources]]
* [[OpenSource Software|OpenSource Tools and Applications]]
|style="width:10%;height:100%;background:#ffffff;" |
 
|style="width:45%;height:100%; background:#ffffff;" valign=top|
<div style="border-bottom:1px solid #c0c0c0; ; width:350px; ">
<big>Linux from Scratch</big>
</div>
* [[Toolchain and Embedded Distributions]]
* [[Kernel Build Instructions|Kernel Build Instructions]]
* [[Boot Loader|Boot Loader]]

<div style="margin-top:1em; border-bottom:1px solid #c0c0c0; ; width:350px; ">
<big>Developers' Resources</big>
</div>
* [[Platform Porting|Porting the Kernel to a new Platform (Board)]]
* [[ABI Interface]]

<div style="margin-top:1em; border-bottom:1px solid #c0c0c0; ; width:350px; ">
<big>System Developer Information</big>
</div>
* [[System Software|For Software Developers]]
* [[System Hardware|For Hardware Developers]]

| colspan=3 |
 
|-
| colspan=3 |
<div style="margin-top:1em; border-bottom:1px solid #c0c0c0; ">
<big>News</big>
</div>
2008-07-14 Buildroot snapshot 20080711 posted, see download page.<br>
2008-04-25 Linux Xtensa 2.6.24 tree updated to 2.6.24.4.<br>
2008-01-23 Initial buildroot snapshot posted, see download page.<br>
2007-09-05 Moved to a new server.<br>

|-
|}

<i><small>
'''Note:''' At this time, new users by default cannot edit any Wiki pages.
This may change in the future.
Meanwhile, if you want to edit or contribute anything, try sending an email to the
[http://lists.linux-xtensa.org/mailman/listinfo/linux-xtensa linux-xtensa mailing list]
identifying yourself and what you want to contribute.
</small></i>

Instructions for building and booting Linux

2008-06-24T16:49:27Z

Bwilson: Use "Xtensa Tools" instead of "Tensilica Tools".

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.

Some general notes on these instructions:

* They are a work in progress. If you are using the latest development sources, the build process may change, so you should be sure to get the latest version of this document at [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions]. If you are using one of the development snapshot releases, you should use the version of the build instructions included with that snapshot.

* 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 Xtensa 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 <tt>git</tt> 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).

== Setup your host system ==

If you are using one of the snapshot releases, you can skip this step.

If you want to work with the latest development sources, you will need
[[Installing GIT|<tt>git</tt> installed on your system]].

== Download buildroot and the Linux kernel ==

The following section describes how to download the latest
versions of buildroot and of the Linux kernel.
Skip this step if you are using one of the
[http://wiki.linux-xtensa.org/index.php/Buildroot_Snapshots snapshot releases].

=== Download buildroot sources ===

Buildroot is used to build the toolchain and root filesystem.
First setup a work area:

$ cd <workdir>

where <tt><workdir></tt> is the path to an empty directory on a disk with
at least 4 GB available space.
The following creates and populates the <tt><workdir>/buildroot</tt> directory:

$ git clone git://git.linux-xtensa.org/buildroot/buildroot-xtensa buildroot

=== Download Linux kernel sources ===

First you need to decide which kernel tree to work with.
(You can also download multiple kernel source trees of course.)

For now this is simple, there is just one active tree.
At the time of writing, the <tt>xtensa-2.6.24</tt> tree is the active tree.

The <tt>xtensa-2.6.24</tt> tree is based on the released 2.6.24 kernel
from <tt>kernel.org</tt>.

To get the <tt>xtensa-2.6.24</tt> tree into directory ''<dir>'' (which must not already exist),
do this:

$ cd <workdir>
$ git clone git://git.linux-xtensa.org/kernel/xtensa-2.6.24 <dir>

This creates and populates the ''<workdir>/<dir>'' directory. If ''<dir>'' is omitted, it defaults to <tt>xtensa-2.6.24</tt> (the last non-extension part of the cloned path). For the purposes of this document, we assume ''<dir>'' is named <tt>linux</tt>, like this:

$ git clone git://git.linux-xtensa.org/kernel/xtensa-2.6.24 linux

== 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>
$ ./buildroot/target/xtensa/xt-buildroot-overlay-install

which displays a help message similar to the following:

xt-buildroot-overlay-install version 1.3
Usage: xt-buildroot-overlay-install <parameters> [<options>]
Where <parameters> are:
-t file.tgz Specify path to the Xtensa Linux overlay tarball, typically
<xtensa_root>/src/xtensa-config-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.

Here is an example invocation of the overlay installation script:

$ ./buildroot/target/xtensa/xt-buildroot-overlay-install -t blinkcore-config-overlay.tar.gz \
-b ./buildroot -k ./linux -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 <code>''make menuconfig''</code> steps) to select
the <code>''custom''</code> 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 <code>-c</code> 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 [http://buildroot.uclibc.org/ buildroot.uclibc.org].

=== Configure buildroot ===

The first time you configure buildroot, start with defaults for your Xtensa processor:

$ cd <workdir>/buildroot
$ ./target/xtensa/setup-config <i><corename></i>

where ''<corename>'' is the overlay name of your selected Xtensa or Diamond core
(e.g., '''dc232b'''). If you omit ''<corename>'', a help message and a list
of currently installed Tensilica core overlays is displayed.

Optionally, you can then customize your buildroot configuration, such as
selecting additional packages, setting various parameters, and so on.
The following make targets provide a ''curses'' (text-based graphical) interface
for configuring buildroot, the uClibc C library, and busybox, respectively.
('''Note:''' You need the <tt>TERM</tt> environment variable properly set for
these curses based tools to work.)

$ make menuconfig
$ make uclibc-menuconfig
$ make busybox-menuconfig

=== Build buildroot ===

Just type:

$ make

THIS WILL TAKE A LONG TIME (from about 30 minutes with defaults on a 3 GHz Pentium 4,
to perhaps an hour or many depending on your system and on whether
you enabled extra packages in your buildroot configuration).

Wait patiently for the 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 <tt>make</tt> command usually works fine if you
just added a package using menuconfig, but otherwise does not check many dependencies, so it will usually NOT rebuild things that depend on whatever you have fixed or changed. Here's one way to retry the make from scratch without having to wipe out the <tt>buildroot</tt> directory tree completely and start again from the git cloning.

$ rm -rf *build_xtensa* binaries
$ make

It is not necessary to empty the 'dl' subdirectory, which contains tarballs downloaded from the Internet, nor the .config file, which contains the buildroot configuration. Customizations to the uClibc and <tt>busybox</tt> configurations should have ended up getting saved in target/xtensa/uClibc.config and target/xtensa/busybox-config, respectively, so hopefully are preserved by the above sequence.

== Build and Run a Linux Kernel on the XTAV60 or XTAV200 Board ==

References to the ''XTAV60 board'' refer to the combination of
the Avnet [http://www.em.avnet.com/tensilica1 LX60 (Xilinx) Development Board]
and a Tensilica-provided FPGA bitstream containing a configured Tensilica
processor and basic peripheral IP. For more details, please refer to the
''Tensilica Avnet LX60 (XT-AV60) Board User's Guide''.

Similarly, references to the ''XTAV200 board'' refers the combination of
the Avnet [http://www.em.avnet.com/tensilica2 LX200 (Xilinx) Development Board]
and a Tensilica-provided FPGA bitstream containing a configured Tensilica
processor and basic peripheral IP. For more details, please refer to the
''Tensilica Avnet LX200 (XT-AV200) Board User's Guide''.

=== Configure the kernel ===

The kernel 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>''/buildroot/build_xtensa_''<cname>''/staging_dir/usr/bin:$PATH"

where ''<cname>'' is the name of the Xtensa processor configuration you selected
when building the toolchain (e.g., <code>dc232b</code>).

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. If you'll be routinely building multiple
configurations of the Linux kernel, it's good to have some
naming conventions for the build directory. For example,
to experiment with multiple target platforms but only one
processor configuration, we include just the platform name here:

$ mkdir build-xtav60

Let's start with the default kernel configuration for the Avnet board
(which works on both XTAV60 (LX60) and XTAV200 (LX200) boards)
as follows:

$ cd linux
$ make O=../build-xtav60 ARCH=xtensa KBUILD_DEFCONFIG=lx60_defconfig defconfig

This configures the kernel using the default configuration found in
arch/xtensa/configs/lx60_defconfig.

NOTE: This kernel configuration has nothing to do with Xtensa
processor configuration. That comes next.

Let's now customize this a little bit to select the correct Xtensa processor
configuration, and to bundle the root filesystem into the kernel:

$ make O=../build-xtav60 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>''/buildroot/binaries/uclibc/rootfs.xtensa_''<cname>''.cpio.gz

(Don't forget to replace ''<workdir>'' with the appropriate full path
and ''<cname>'' with your Xtensa processor configuration name.)

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.
If the desired processor configuration does not appear explicitly in the list,
simply select '''Custom Xtensa processor configuration''' and enter the
processor configuration name (all lowercase) into the next menu parameter,
'''Xtensa Processor Custom Variant Name'''.

Back in the main menu, under '''Platform options''', make sure the
'''CPU clock rate''' entry is set correctly according to the following table:

{| border="1" style="text-align:center; margin: 1em auto 1em auto"
|-
! Board !! Frequency selected in XPG <br/>(MHz) !! ''CPU clock rate'' setting <br/>(kHz)
|-
|rowspan="3"| XTAV60 (LX60)
| 30 || 33333
|-
| 40 || 40000
|-
| 50 || 50000
|-
|rowspan="3"| XTAV200 (LX200)
| 30 || 31250
|-
| 40 || 41667
|-
| 50 || 50000
|-
|}

Exit menuconfig, saving your configuration changes.

Backup your configuration outside the build directory. For example:

$ cp ../build-xtav60/.config config.xtav60.saved

If you do a clean rebuild of the kernel (e.g., "rm -rf ../build-xtav60")
you can now configure it with simply:
$ mkdir ../build-xtav60 ; cp config.xtav60.saved ../build-xtav60/.config
Of course if you update the kernel, you'll probably again have to do:
$ make O=../build-xtav60 ARCH=xtensa menuconfig
and save a new copy of your configuration.

=== Build the kernel ===

$ make O=../build-xtav60 ARCH=xtensa

The build will issue a few warnings which are normal.
Once complete, the bootable image is in:
<workdir>/build-xtav60/arch/xtensa/boot/Image.elf
and the uncompressed ELF file containing kernel symbols is in:
<workdir>/build-xtav60/vmlinux
There is also a RedBoot bootable image (if you use RedBoot) in:
<workdir>/build-xtav60/arch/xtensa/boot/zImage.redboot

=== Install Xtensa Tools for the selected core ===

If you opt to download the kernel over OCD, you need <tt>xt-gdb</tt>
which is part of Tensilica's Xtensa Tools package. This must be obtained
from Tensilica, and is not the same toolchain as built by buildroot.
You also need to install the corresponding Tensilica core package,
so that the Xtensa Tools know about your particular configured
Tensilica core.

The toolchain built using buildroot can be configured to
include GDB, but that version of GDB does not support
communicating with Tensilica's Xtensa OCD Daemon, and
thus cannot be used to download the kernel over OCD.

In this example, it is assumed that the machine hosting the
Xtensa Tools 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 XTAV60 serial port.

=== Optionally, setup networking ===

This step is optional.

Setup the board's MAC address using dipswitches
(see XTAV60 or XTAV200 board docs as appropriate)
and connect the board 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 board (see board documentation).

Using Xtensa Tools, invoke:

$ xt-gdb <workdir>/build-xtav60/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-xtav60/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 <tt>/bin</tt>,
<tt>/sbin</tt>, <tt>/usr/bin</tt>, etc to see what's available.

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.

== Build and Run a Linux Kernel on the Instruction Set Simulator (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 the RB-2008.3 release of Xtensa Tools. Bear in
mind that the XTAV60 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
Xtensa Tools on a separate machine.

=== Configure and Build the Kernel for ISS ===

Repeat all the same instructions as above for building the kernel for the
XTAV60 board, except that when initially configuring the kernel,
start from the ISS platform template instead:

$ mkdir build-iss
$ cd linux
$ make O=../build-iss ARCH=xtensa 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-iss ARCH=xtensa menuconfig

in addition to setting up the initramfs filesystem, do the following.
Under '''Bus Options''', deselect '''PCI support'''.
Under '''Platform Options''', deselect '''Default bootloader kernel arguments'''.

Continue configuring and building the kernel as usual.

=== Run the Kernel on ISS ===

Using Xtensa Tools, invoke:

$ xt-gdb <workdir>/build-iss/arch/xtensa/boot/Image.elf

(xt-gdb) target sim --turbo
(xt-gdb) symbol-file <workdir>/build-iss/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.

Instructions for building and booting Linux

2008-06-24T16:45:13Z

Bwilson: Use "Xtensa Tools" instead of "Tensilica Tools" and update current RB release name

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.

Some general notes on these instructions:

* They are a work in progress. If you are using the latest development sources, the build process may change, so you should be sure to get the latest version of this document at [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions]. If you are using one of the development snapshot releases, you should use the version of the build instructions included with that snapshot.

* 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 <tt>git</tt> 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).

== Setup your host system ==

If you are using one of the snapshot releases, you can skip this step.

If you want to work with the latest development sources, you will need
[[Installing GIT|<tt>git</tt> installed on your system]].

== Download buildroot and the Linux kernel ==

The following section describes how to download the latest
versions of buildroot and of the Linux kernel.
Skip this step if you are using one of the
[http://wiki.linux-xtensa.org/index.php/Buildroot_Snapshots snapshot releases].

=== Download buildroot sources ===

Buildroot is used to build the toolchain and root filesystem.
First setup a work area:

$ cd <workdir>

where <tt><workdir></tt> is the path to an empty directory on a disk with
at least 4 GB available space.
The following creates and populates the <tt><workdir>/buildroot</tt> directory:

$ git clone git://git.linux-xtensa.org/buildroot/buildroot-xtensa buildroot

=== Download Linux kernel sources ===

First you need to decide which kernel tree to work with.
(You can also download multiple kernel source trees of course.)

For now this is simple, there is just one active tree.
At the time of writing, the <tt>xtensa-2.6.24</tt> tree is the active tree.

The <tt>xtensa-2.6.24</tt> tree is based on the released 2.6.24 kernel
from <tt>kernel.org</tt>.

To get the <tt>xtensa-2.6.24</tt> tree into directory ''<dir>'' (which must not already exist),
do this:

$ cd <workdir>
$ git clone git://git.linux-xtensa.org/kernel/xtensa-2.6.24 <dir>

This creates and populates the ''<workdir>/<dir>'' directory. If ''<dir>'' is omitted, it defaults to <tt>xtensa-2.6.24</tt> (the last non-extension part of the cloned path). For the purposes of this document, we assume ''<dir>'' is named <tt>linux</tt>, like this:

$ git clone git://git.linux-xtensa.org/kernel/xtensa-2.6.24 linux

== 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>
$ ./buildroot/target/xtensa/xt-buildroot-overlay-install

which displays a help message similar to the following:

xt-buildroot-overlay-install version 1.3
Usage: xt-buildroot-overlay-install <parameters> [<options>]
Where <parameters> are:
-t file.tgz Specify path to the Xtensa Linux overlay tarball, typically
<xtensa_root>/src/xtensa-config-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.

Here is an example invocation of the overlay installation script:

$ ./buildroot/target/xtensa/xt-buildroot-overlay-install -t blinkcore-config-overlay.tar.gz \
-b ./buildroot -k ./linux -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 <code>''make menuconfig''</code> steps) to select
the <code>''custom''</code> 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 <code>-c</code> 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 [http://buildroot.uclibc.org/ buildroot.uclibc.org].

=== Configure buildroot ===

The first time you configure buildroot, start with defaults for your Xtensa processor:

$ cd <workdir>/buildroot
$ ./target/xtensa/setup-config <i><corename></i>

where ''<corename>'' is the overlay name of your selected Xtensa or Diamond core
(e.g., '''dc232b'''). If you omit ''<corename>'', a help message and a list
of currently installed Tensilica core overlays is displayed.

Optionally, you can then customize your buildroot configuration, such as
selecting additional packages, setting various parameters, and so on.
The following make targets provide a ''curses'' (text-based graphical) interface
for configuring buildroot, the uClibc C library, and busybox, respectively.
('''Note:''' You need the <tt>TERM</tt> environment variable properly set for
these curses based tools to work.)

$ make menuconfig
$ make uclibc-menuconfig
$ make busybox-menuconfig

=== Build buildroot ===

Just type:

$ make

THIS WILL TAKE A LONG TIME (from about 30 minutes with defaults on a 3 GHz Pentium 4,
to perhaps an hour or many depending on your system and on whether
you enabled extra packages in your buildroot configuration).

Wait patiently for the 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 <tt>make</tt> command usually works fine if you
just added a package using menuconfig, but otherwise does not check many dependencies, so it will usually NOT rebuild things that depend on whatever you have fixed or changed. Here's one way to retry the make from scratch without having to wipe out the <tt>buildroot</tt> directory tree completely and start again from the git cloning.

$ rm -rf *build_xtensa* binaries
$ make

It is not necessary to empty the 'dl' subdirectory, which contains tarballs downloaded from the Internet, nor the .config file, which contains the buildroot configuration. Customizations to the uClibc and <tt>busybox</tt> configurations should have ended up getting saved in target/xtensa/uClibc.config and target/xtensa/busybox-config, respectively, so hopefully are preserved by the above sequence.

== Build and Run a Linux Kernel on the XTAV60 or XTAV200 Board ==

References to the ''XTAV60 board'' refer to the combination of
the Avnet [http://www.em.avnet.com/tensilica1 LX60 (Xilinx) Development Board]
and a Tensilica provided FPGA bitstream containing a configured Tensilica
processor and basic peripheral IP. For more details, please refer to the
''Tensilica Avnet LX60 (XT-AV60) Board User's Guide''.

Similarly, references to the ''XTAV200 board'' refers the combination of
the Avnet [http://www.em.avnet.com/tensilica2 LX200 (Xilinx) Development Board]
and a Tensilica provided FPGA bitstream containing a configured Tensilica
processor and basic peripheral IP. For more details, please refer to the
''Tensilica Avnet LX200 (XT-AV200) Board User's Guide''.

=== Configure the kernel ===

The kernel 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>''/buildroot/build_xtensa_''<cname>''/staging_dir/usr/bin:$PATH"

where ''<cname>'' is the name of the Xtensa processor configuration you selected
when building the toolchain (e.g., <code>dc232b</code>).

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. If you'll be routinely building multiple
configurations of the Linux kernel, it's good to have some
naming conventions for the build directory. For example,
to experiment with multiple target platforms but only one
processor configuration, we include just the platform name here:

$ mkdir build-xtav60

Let's start with the default kernel configuration for the Avnet board
(which works on both XTAV60 (LX60) and XTAV200 (LX200) boards)
as follows:

$ cd linux
$ make O=../build-xtav60 ARCH=xtensa KBUILD_DEFCONFIG=lx60_defconfig defconfig

This configures the kernel using the default configuration found in
arch/xtensa/configs/lx60_defconfig.

NOTE: This kernel configuration has nothing to do with Xtensa
processor configuration. That comes next.

Let's now customize this a little bit to select the correct Xtensa processor
configuration, and to bundle the root filesystem into the kernel:

$ make O=../build-xtav60 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>''/buildroot/binaries/uclibc/rootfs.xtensa_''<cname>''.cpio.gz

(Don't forget to replace ''<workdir>'' with the appropriate full path
and ''<cname>'' with your Xtensa processor configuration name.)

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.
If the desired processor configuration does not appear explicitly in the list,
simply select '''Custom Xtensa processor configuration''' and enter the
processor configuration name (all lowercase) into the next menu parameter,
'''Xtensa Processor Custom Variant Name'''.

Back in the main menu, under '''Platform options''', make sure the
'''CPU clock rate''' entry is set correctly according to the following table:

{| border="1" style="text-align:center; margin: 1em auto 1em auto"
|-
! Board !! Frequency selected in XPG <br/>(MHz) !! ''CPU clock rate'' setting <br/>(kHz)
|-
|rowspan="3"| XTAV60 (LX60)
| 30 || 33333
|-
| 40 || 40000
|-
| 50 || 50000
|-
|rowspan="3"| XTAV200 (LX200)
| 30 || 31250
|-
| 40 || 41667
|-
| 50 || 50000
|-
|}

Exit menuconfig, saving your configuration changes.

Backup your configuration outside the build directory. For example:

$ cp ../build-xtav60/.config config.xtav60.saved

If you do a clean rebuild of the kernel (e.g., "rm -rf ../build-xtav60")
you can now configure it with simply:
$ mkdir ../build-xtav60 ; cp config.xtav60.saved ../build-xtav60/.config
Of course if you update the kernel, you'll probably again have to do:
$ make O=../build-xtav60 ARCH=xtensa menuconfig
and save a new copy of your configuration.

=== Build the kernel ===

$ make O=../build-xtav60 ARCH=xtensa

The build will issue a few warnings which are normal.
Once complete, the bootable image is in:
<workdir>/build-xtav60/arch/xtensa/boot/Image.elf
and the uncompressed ELF file containing kernel symbols is in:
<workdir>/build-xtav60/vmlinux
There is also a RedBoot bootable image (if you use RedBoot) in:
<workdir>/build-xtav60/arch/xtensa/boot/zImage.redboot

=== Install Tensilica Tools for the selected core ===

If you opt to downloading the kernel over OCD, you need <tt>xt-gdb</tt>
which is part of Tensilica Software Tools. This must be obtained
from Tensilica, and is not the same toolchain as built by buildroot.
You also need to install the corresponding Tensilica core package,
so that Tensilica Software Tools know about your particular configured
Tensilica core.

The toolchain built using buildroot can be configured to
include GDB, but that version of GDB does not support
communicating with Tensilica's Xtensa OCD Daemon, and
thus cannot be used to download the kernel over OCD.

In this example, it is assumed that the machine hosting the
Tensilica Tools 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 XTAV60 serial port.

=== Optionally, setup networking ===

This step is optional.

Setup the board's MAC address using dipswitches
(see XTAV60 or XTAV200 board docs as appropriate)
and connect the board 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 board (see board documentation).

Using Tensilica Tools, invoke:

$ xt-gdb <workdir>/build-xtav60/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-xtav60/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 <tt>/bin</tt>,
<tt>/sbin</tt>, <tt>/usr/bin</tt>, etc to see what's available.

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.

== Build and Run a Linux Kernel on the Instruction Set Simulator (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 the RB-2008.3 release of Xtensa Tools. Bear in
mind that the XTAV60 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
Xtensa Tools on a separate machine.

=== Configure and Build the Kernel for ISS ===

Repeat all the same instructions as above for building the kernel for the
XTAV60 board, except that when initially configuring the kernel,
start from the ISS platform template instead:

$ mkdir build-iss
$ cd linux
$ make O=../build-iss ARCH=xtensa 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-iss ARCH=xtensa menuconfig

in addition to setting up the initramfs filesystem, do the following.
Under '''Bus Options''', deselect '''PCI support'''.
Under '''Platform Options''', deselect '''Default bootloader kernel arguments'''.

Continue configuring and building the kernel as usual.

=== Run the Kernel on ISS ===

Using Xtensa Tools, invoke:

$ xt-gdb <workdir>/build-iss/arch/xtensa/boot/Image.elf

(xt-gdb) target sim --turbo
(xt-gdb) symbol-file <workdir>/build-iss/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.

Instructions for building and booting Linux

2008-06-24T16:40:17Z

Bwilson: RB-2008.3 has now been released.

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.

Some general notes on these instructions:

* They are a work in progress. If you are using the latest development sources, the build process may change, so you should be sure to get the latest version of this document at [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions]. If you are using one of the development snapshot releases, you should use the version of the build instructions included with that snapshot.

* 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 <tt>git</tt> 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).

== Setup your host system ==

If you are using one of the snapshot releases, you can skip this step.

If you want to work with the latest development sources, you will need
[[Installing GIT|<tt>git</tt> installed on your system]].

== Download buildroot and the Linux kernel ==

The following section describes how to download the latest
versions of buildroot and of the Linux kernel.
Skip this step if you are using one of the
[http://wiki.linux-xtensa.org/index.php/Buildroot_Snapshots snapshot releases].

=== Download buildroot sources ===

Buildroot is used to build the toolchain and root filesystem.
First setup a work area:

$ cd <workdir>

where <tt><workdir></tt> is the path to an empty directory on a disk with
at least 4 GB available space.
The following creates and populates the <tt><workdir>/buildroot</tt> directory:

$ git clone git://git.linux-xtensa.org/buildroot/buildroot-xtensa buildroot

=== Download Linux kernel sources ===

First you need to decide which kernel tree to work with.
(You can also download multiple kernel source trees of course.)

For now this is simple, there is just one active tree.
At the time of writing, the <tt>xtensa-2.6.24</tt> tree is the active tree.

The <tt>xtensa-2.6.24</tt> tree is based on the released 2.6.24 kernel
from <tt>kernel.org</tt>.

To get the <tt>xtensa-2.6.24</tt> tree into directory ''<dir>'' (which must not already exist),
do this:

$ cd <workdir>
$ git clone git://git.linux-xtensa.org/kernel/xtensa-2.6.24 <dir>

This creates and populates the ''<workdir>/<dir>'' directory. If ''<dir>'' is omitted, it defaults to <tt>xtensa-2.6.24</tt> (the last non-extension part of the cloned path). For the purposes of this document, we assume ''<dir>'' is named <tt>linux</tt>, like this:

$ git clone git://git.linux-xtensa.org/kernel/xtensa-2.6.24 linux

== 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>
$ ./buildroot/target/xtensa/xt-buildroot-overlay-install

which displays a help message similar to the following:

xt-buildroot-overlay-install version 1.3
Usage: xt-buildroot-overlay-install <parameters> [<options>]
Where <parameters> are:
-t file.tgz Specify path to the Xtensa Linux overlay tarball, typically
<xtensa_root>/src/xtensa-config-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.

Here is an example invocation of the overlay installation script:

$ ./buildroot/target/xtensa/xt-buildroot-overlay-install -t blinkcore-config-overlay.tar.gz \
-b ./buildroot -k ./linux -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 <code>''make menuconfig''</code> steps) to select
the <code>''custom''</code> 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 <code>-c</code> 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 [http://buildroot.uclibc.org/ buildroot.uclibc.org].

=== Configure buildroot ===

The first time you configure buildroot, start with defaults for your Xtensa processor:

$ cd <workdir>/buildroot
$ ./target/xtensa/setup-config <i><corename></i>

where ''<corename>'' is the overlay name of your selected Xtensa or Diamond core
(e.g., '''dc232b'''). If you omit ''<corename>'', a help message and a list
of currently installed Tensilica core overlays is displayed.

Optionally, you can then customize your buildroot configuration, such as
selecting additional packages, setting various parameters, and so on.
The following make targets provide a ''curses'' (text-based graphical) interface
for configuring buildroot, the uClibc C library, and busybox, respectively.
('''Note:''' You need the <tt>TERM</tt> environment variable properly set for
these curses based tools to work.)

$ make menuconfig
$ make uclibc-menuconfig
$ make busybox-menuconfig

=== Build buildroot ===

Just type:

$ make

THIS WILL TAKE A LONG TIME (from about 30 minutes with defaults on a 3 GHz Pentium 4,
to perhaps an hour or many depending on your system and on whether
you enabled extra packages in your buildroot configuration).

Wait patiently for the 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 <tt>make</tt> command usually works fine if you
just added a package using menuconfig, but otherwise does not check many dependencies, so it will usually NOT rebuild things that depend on whatever you have fixed or changed. Here's one way to retry the make from scratch without having to wipe out the <tt>buildroot</tt> directory tree completely and start again from the git cloning.

$ rm -rf *build_xtensa* binaries
$ make

It is not necessary to empty the 'dl' subdirectory, which contains tarballs downloaded from the Internet, nor the .config file, which contains the buildroot configuration. Customizations to the uClibc and <tt>busybox</tt> configurations should have ended up getting saved in target/xtensa/uClibc.config and target/xtensa/busybox-config, respectively, so hopefully are preserved by the above sequence.

== Build and Run a Linux Kernel on the XTAV60 or XTAV200 Board ==

References to the ''XTAV60 board'' refer to the combination of
the Avnet [http://www.em.avnet.com/tensilica1 LX60 (Xilinx) Development Board]
and a Tensilica provided FPGA bitstream containing a configured Tensilica
processor and basic peripheral IP. For more details, please refer to the
''Tensilica Avnet LX60 (XT-AV60) Board User's Guide''.

Similarly, references to the ''XTAV200 board'' refers the combination of
the Avnet [http://www.em.avnet.com/tensilica2 LX200 (Xilinx) Development Board]
and a Tensilica provided FPGA bitstream containing a configured Tensilica
processor and basic peripheral IP. For more details, please refer to the
''Tensilica Avnet LX200 (XT-AV200) Board User's Guide''.

=== Configure the kernel ===

The kernel 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>''/buildroot/build_xtensa_''<cname>''/staging_dir/usr/bin:$PATH"

where ''<cname>'' is the name of the Xtensa processor configuration you selected
when building the toolchain (e.g., <code>dc232b</code>).

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. If you'll be routinely building multiple
configurations of the Linux kernel, it's good to have some
naming conventions for the build directory. For example,
to experiment with multiple target platforms but only one
processor configuration, we include just the platform name here:

$ mkdir build-xtav60

Let's start with the default kernel configuration for the Avnet board
(which works on both XTAV60 (LX60) and XTAV200 (LX200) boards)
as follows:

$ cd linux
$ make O=../build-xtav60 ARCH=xtensa KBUILD_DEFCONFIG=lx60_defconfig defconfig

This configures the kernel using the default configuration found in
arch/xtensa/configs/lx60_defconfig.

NOTE: This kernel configuration has nothing to do with Xtensa
processor configuration. That comes next.

Let's now customize this a little bit to select the correct Xtensa processor
configuration, and to bundle the root filesystem into the kernel:

$ make O=../build-xtav60 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>''/buildroot/binaries/uclibc/rootfs.xtensa_''<cname>''.cpio.gz

(Don't forget to replace ''<workdir>'' with the appropriate full path
and ''<cname>'' with your Xtensa processor configuration name.)

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.
If the desired processor configuration does not appear explicitly in the list,
simply select '''Custom Xtensa processor configuration''' and enter the
processor configuration name (all lowercase) into the next menu parameter,
'''Xtensa Processor Custom Variant Name'''.

Back in the main menu, under '''Platform options''', make sure the
'''CPU clock rate''' entry is set correctly according to the following table:

{| border="1" style="text-align:center; margin: 1em auto 1em auto"
|-
! Board !! Frequency selected in XPG <br/>(MHz) !! ''CPU clock rate'' setting <br/>(kHz)
|-
|rowspan="3"| XTAV60 (LX60)
| 30 || 33333
|-
| 40 || 40000
|-
| 50 || 50000
|-
|rowspan="3"| XTAV200 (LX200)
| 30 || 31250
|-
| 40 || 41667
|-
| 50 || 50000
|-
|}

Exit menuconfig, saving your configuration changes.

Backup your configuration outside the build directory. For example:

$ cp ../build-xtav60/.config config.xtav60.saved

If you do a clean rebuild of the kernel (e.g., "rm -rf ../build-xtav60")
you can now configure it with simply:
$ mkdir ../build-xtav60 ; cp config.xtav60.saved ../build-xtav60/.config
Of course if you update the kernel, you'll probably again have to do:
$ make O=../build-xtav60 ARCH=xtensa menuconfig
and save a new copy of your configuration.

=== Build the kernel ===

$ make O=../build-xtav60 ARCH=xtensa

The build will issue a few warnings which are normal.
Once complete, the bootable image is in:
<workdir>/build-xtav60/arch/xtensa/boot/Image.elf
and the uncompressed ELF file containing kernel symbols is in:
<workdir>/build-xtav60/vmlinux
There is also a RedBoot bootable image (if you use RedBoot) in:
<workdir>/build-xtav60/arch/xtensa/boot/zImage.redboot

=== Install Tensilica Tools for the selected core ===

If you opt to downloading the kernel over OCD, you need <tt>xt-gdb</tt>
which is part of Tensilica Software Tools. This must be obtained
from Tensilica, and is not the same toolchain as built by buildroot.
You also need to install the corresponding Tensilica core package,
so that Tensilica Software Tools know about your particular configured
Tensilica core.

The toolchain built using buildroot can be configured to
include GDB, but that version of GDB does not support
communicating with Tensilica's Xtensa OCD Daemon, and
thus cannot be used to download the kernel over OCD.

In this example, it is assumed that the machine hosting the
Tensilica Tools 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 XTAV60 serial port.

=== Optionally, setup networking ===

This step is optional.

Setup the board's MAC address using dipswitches
(see XTAV60 or XTAV200 board docs as appropriate)
and connect the board 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 board (see board documentation).

Using Tensilica Tools, invoke:

$ xt-gdb <workdir>/build-xtav60/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-xtav60/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 <tt>/bin</tt>,
<tt>/sbin</tt>, <tt>/usr/bin</tt>, etc to see what's available.

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.

== Build and Run a Linux Kernel on the Instruction Set Simulator (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 XTAV60 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.

=== Configure and Build the Kernel for ISS ===

Repeat all the same instructions as above for building the kernel for the
XTAV60 board, except that when initially configuring the kernel,
start from the ISS platform template instead:

$ mkdir build-iss
$ cd linux
$ make O=../build-iss ARCH=xtensa 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-iss ARCH=xtensa menuconfig

in addition to setting up the initramfs filesystem, do the following.
Under '''Bus Options''', deselect '''PCI support'''.
Under '''Platform Options''', deselect '''Default bootloader kernel arguments'''.

Continue configuring and building the kernel as usual.

=== Run the Kernel on ISS ===

Using Tensilica Tools, invoke:

$ xt-gdb <workdir>/build-iss/arch/xtensa/boot/Image.elf

(xt-gdb) target sim --turbo
(xt-gdb) symbol-file <workdir>/build-iss/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.

Buildroot Snapshots

2008-01-24T23:48:23Z

Bwilson: replace subversion- and git-based instructions with a link to the download page

= Stable Snapshots of Buildroot and the Linux kernel =

As an alternative to using the latest source files from GIT and Subversion, you can use one of the snapshot bundles available on the [http://www.linux-xtensa.org/download.html download page]. These snapshots include versions of the Linux kernel and the Buildroot files that have been tested to work together, as well as associated build documentation that matches those snapshots.

(If you want the latest sources instead, please refer to the
latest [[Buildroot_Build_Instructions]].)

Instructions for building and booting Linux

2008-01-21T22:01:49Z

Bwilson: /* Install any required processor specific overlay */

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.

Some general notes on these instructions:

* They are a work in progress. If you are using the latest development sources, the build process may change, so you should be sure to get the latest version of this document at [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions]. If you are using one of the development snapshot releases, you should use the version of the build instructions included with that snapshot.

* 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 ==

If you are using one of the snapshot releases, you can skip this step.
If you want to work with the latest development sources, you will need
Subversion and <code>git</code>.

=== Install the ''Subversion'' source control tools ===

First verify whether you already have Subversion installed. Try:

$ svn help

which should output a help page. If not,
download and install the [http://subversion.tigris.org/ Subversion]
source control tools:

$ 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 <code>svn help</code> at a shell prompt.

=== Download and install the <code>git</code> 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 <code>man git</code>
or <code>git help</code>):

$ 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 <code>/usr/local/bin</code> 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
[http://www.kernel.org/pub/software/scm/git/docs/tutorial.html tutorial]
and [http://www.kernel.org/pub/software/scm/git/docs/ manual pages].

== Download buildroot and the Linux kernel ==

The following section describes how to download the latest
versions of buildroot and of the Linux kernel.
Skip this step if you are using one of the
[http://wiki.linux-xtensa.org/index.php/Buildroot_Snapshots snapshot releases].

=== Download buildroot sources ===

Buildroot is used to build the toolchain and root filesystem.
First setup a work area:

$ cd <workdir>

where <tt><workdir></tt> is the path to an empty directory on a disk with
at least 4 GB available space.
The following creates and populates the <tt><workdir>/buildroot</tt> directory:

$ svn co svn://linux-xtensa.org/var/svn/repos/buildroot/trunk buildroot

=== Download Linux kernel sources ===

First you need to decide which kernel tree to work with.
(You can also download multiple kernel source trees of course.)

At the time of writing, the <tt>xtensa-2.6.24</tt> tree is the most current.

The <tt>xtensa-2.6.24</tt> tree is based on the release candidate 2.6.24-rc''n'' kernel
from <tt>kernel.org</tt>.

The <tt>xtensa-devel</tt> tree contains the most recent changes but is not as stable.
It also gets updated semi-regularly with the very latest Linux kernel tree from <tt>kernel.org</tt>.
'''Note:''' The <tt>xtensa-devel</tt> tree is about to be recreated from scratch; if you
have previously cloned this tree, you will have to clone it again once this happens to
avoid confusing git when pulling (from what would be a mismatching tree).

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.24 <dir>

This creates and populates the <workdir>/<dir> directory. If <dir> is omitted, it defaults to <tt>xtensa-2.6.24</tt> (the last non-extension part of the cloned path). For the purposes of this document, we assume <dir> is named <tt>linux</tt>.

Similarly, to get the development tree:

$ cd <workdir>
$ git clone git://git.linux-xtensa.org/kernel/xtensa-devel <dir>

Note that the latter <tt>xtensa-devel</tt> tree currently contains two branches:
'''master''' (the default branch checked out by the clone command above),
and '''testing'''.
''Note: more branches will be added when the tree is recreated.''
Often, development
checkins are made to the '''testing''' branch before getting repackaged
and integrated over to the '''master''' branch some time later.
You can switch to another branch (within the cloned repository)
using the <tt>git-checkout</tt> command, for example:

$ git checkout testing

== 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>
$ ./buildroot/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:

$ ./buildroot/target/xtensa/xt-buildroot-overlay-install -t blinkcore-linux-overlay.tar.gz \
-b ./buildroot -k ./linux -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 <code>''make menuconfig''</code> steps) to select
the <code>''custom''</code> 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 <code>-c</code> 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 [http://buildroot.uclibc.org/ buildroot.uclibc.org].

=== Configure buildroot ===

Note: You need the TERM environment variable properly set for curses
based tools to work.

The first time you configure buildroot, start with defaults for Xtensa processors:

$ cd <workdir>/buildroot
$ cp target/xtensa/defconfig .config
$ make menuconfig

You should get a curses interface for configuring buildroot.
Make the following changes:

* Change '''Target Architecture Variant''' to desired Xtensa or Diamond core (e.g., '''dc232b''')
* Make any other desired changes (e.g., selecting additional packages)
* Exit and save the configuration

If later you want to change the buildroot configuration without losing
other changes made so far, just use ''make menuconfig'' by itself:

$ cd <workdir>/buildroot
$ make menuconfig

=== Configure uClibc ===

Apply the default uClibc configuration for Xtensa processors:

$ make uclibc-config

To further customize uClibc, you can then optionally configure it like this:

$ make uclibc-menuconfig

=== Build buildroot ===

$ make

THIS WILL TAKE A LONG TIME (from 20 minutes to perhaps an hour or many,
depending on your system and on whether you enabled extra packages in
your buildroot configuration).

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 <tt>make</tt> 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 <tt>buildroot</tt> directory tree completely and start again from the svn checkout.

$ 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. Customizations to the uClibc configuration should have ended up getting saved in target/xtensa/uClibc.config , so hopefully are preserved by the above sequence.

== Build and Run a Linux Kernel on the XTAV60 or XTAV200 Board ==

References to the ''XTAV60 board'' refer to the combination of
the Avnet [http://www.em.avnet.com/tensilica1 LX60 (Xilinx) Development Board]
and a Tensilica provided FPGA bitstream containing a configured Tensilica
processor and basic peripheral IP. For more details, please refer to the
''Tensilica Avnet LX60 (XT-AV60) Board User's Guide''.

Similarly, references to the ''XTAV200 board'' refers the combination of
the Avnet [http://www.em.avnet.com/tensilica2 LX200 (Xilinx) Development Board]
and a Tensilica provided FPGA bitstream containing a configured Tensilica
processor and basic peripheral IP. For more details, please refer to the
''Tensilica Avnet LX200 (XT-AV200) Board User's Guide''.

=== Configure the kernel ===

The kernel 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>''/buildroot/build_xtensa_''<cname>''/staging_dir/usr/bin:$PATH"

where ''<cname>'' is the name of the Xtensa processor configuration you selected
when building the toolchain (e.g., <code>dc232b</code>).

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. If you'll be routinely building multiple
configurations of the Linux kernel, it's good to have some
naming conventions for the build directory. For example,
to experiment with multiple target platforms but only one
processor configuration, we include just the platform name here:

$ mkdir build-xtav60

Let's start with the default kernel configuration for the Avnet board
(which works on both XTAV60 (LX60) and XTAV200 (LX200) boards)
as follows:

$ cd linux
$ make O=../build-xtav60 ARCH=xtensa KBUILD_DEFCONFIG=lx60_defconfig defconfig

This configures the kernel using the default configuration found in
arch/xtensa/configs/lx60_defconfig.

NOTE: This kernel configuration has nothing to do with Xtensa
processor configuration. That comes next.

Let's now customize this a little bit to select the correct Xtensa processor
configuration, and to bundle the root filesystem into the kernel:

$ make O=../build-xtav60 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>''/buildroot/binaries/uclibc/rootfs.xtensa_''<cname>''.cpio.gz

(Don't forget to replace ''<workdir>'' with the appropriate full path
and ''<cname>'' with your Xtensa processor configuration name.)

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.
If the desired processor configuration does not appear explicitly in the list,
simply select '''Custom Xtensa processor configuration''' and enter the
processor configuration name (all lowercase) into the next menu parameter,
'''Xtensa Processor Custom Variant Name'''.

Back in the main menu, under '''Platform options''', make sure the
'''CPU clock rate''' entry is set correctly according to the following table:

{| border="1" style="text-align:center; margin: 1em auto 1em auto"
|-
! Board !! Frequency selected in XPG <br/>(MHz) !! ''CPU clock rate'' setting <br/>(kHz)
|-
|rowspan="3"| XTAV60 (LX60)
| 30 || 33333
|-
| 40 || 40000
|-
| 50 || 50000
|-
|rowspan="3"| XTAV200 (LX200)
| 30 || 34091
|-
| 40 || 41667
|-
| 50 || 50000
|-
|}

Exit menuconfig, saving your configuration changes.

Backup your configuration outside the build directory. For example:

$ cp ../build-xtav60/.config config.xtav60.saved

If you do a clean rebuild of the kernel (e.g., "rm -rf ../build-xtav60")
you can now configure it with simply:
$ mkdir ../build-xtav60 ; cp config.xtav60.saved ../build-xtav60/.config
Of course if you update the kernel, you'll probably again have to do:
$ make O=../build-xtav60 ARCH=xtensa menuconfig
and save a new copy of your configuration.

=== Build the kernel ===

$ make O=../build-xtav60 ARCH=xtensa

The build will issue a few warnings which are normal.
Once complete, the bootable image is in:
<workdir>/build-xtav60/arch/xtensa/boot/Image.elf
and the uncompressed ELF file containing kernel symbols is in:
<workdir>/build-xtav60/vmlinux
There is also a RedBoot bootable image (if you use RedBoot) in:
<workdir>/build-xtav60/arch/xtensa/boot/zImage.redboot

=== Install Tensilica Tools for the selected core ===

If you opt to downloading the kernel over OCD, you need <tt>xt-gdb</tt>
which is part of Tensilica Software Tools. This must be obtained
from Tensilica, and is not the same toolchain as built by buildroot.
You also need to install the corresponding Tensilica core package,
so that Tensilica Software Tools know about your particular configured
Tensilica core.

The toolchain built using buildroot can be configured to
include GDB, but that version of GDB does not support
communicating with Tensilica's Xtensa OCD Daemon, and
thus cannot be used to download the kernel over OCD.

In this example, it is assumed that the machine hosting the
Tensilica Tools 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 XTAV60 serial port.

=== Optionally, setup networking ===

This step is optional.

Setup the board's MAC address using dipswitches
(see XTAV60 or XTAV200 board docs as appropriate)
and connect the board 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 board (see board documentation).

Using Tensilica Tools, invoke:

$ xt-gdb <workdir>/build-xtav60/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-xtav60/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 <tt>/bin</tt>,
<tt>/sbin</tt>, <tt>/usr/bin</tt>, etc to see what's available.

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.

== Build and Run a Linux Kernel on the Instruction Set Simulator (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 XTAV60 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.

=== Configure and Build the Kernel for ISS ===

Repeat all the same instructions as above for building the kernel for the
XTAV60 board, except that when initially configuring the kernel,
start from the ISS platform template instead:

$ mkdir build-iss
$ cd linux
$ make O=../build-iss ARCH=xtensa 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-iss ARCH=xtensa menuconfig

in addition to setting up the initramfs filesystem, do the following.
Under '''Bus Options''', deselect '''PCI support'''.
Under '''Platform Options''', deselect '''Default bootloader kernel arguments'''.

Continue configuring and building the kernel as usual.

=== Run the Kernel on ISS ===

Using Tensilica Tools, invoke:

$ xt-gdb <workdir>/build-iss/arch/xtensa/boot/Image.elf

(xt-gdb) target sim --turbo
(xt-gdb) symbol-file <workdir>/build-iss/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.

Instructions for building and booting Linux

2008-01-16T19:59:55Z

Bwilson:

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.

Some general notes on these instructions:

* They are a work in progress. If you are using the latest development sources, the build process may change, so you should be sure to get the latest version of this document at [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions]. If you are using one of the development snapshot releases, you should use the version of the build instructions included with that snapshot.

* 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 ==

If you are using one of the snapshot releases, you can skip this step.
If you want to work with the latest development sources, you will need
Subversion and <code>git</code>.

=== Install the ''Subversion'' source control tools ===

First verify whether you already have Subversion installed. Try:

$ svn help

which should output a help page. If not,
download and install the [http://subversion.tigris.org/ Subversion]
source control tools:

$ 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 <code>svn help</code> at a shell prompt.

=== Download and install the <code>git</code> 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 <code>man git</code>
or <code>git help</code>):

$ 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 <code>/usr/local/bin</code> 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
[http://www.kernel.org/pub/software/scm/git/docs/tutorial.html tutorial]
and [http://www.kernel.org/pub/software/scm/git/docs/ manual pages].

== Download buildroot and the Linux kernel ==

The following section describes how to download the latest
versions of buildroot and of the Linux kernel. Skip this step if
you are using one of the snapshot releases.

=== Download buildroot sources ===

Buildroot is used to build the toolchain and root filesystem.
First setup a work area:

$ cd <workdir>

where <tt><workdir></tt> is the path to an empty directory on a disk with
at least 4 GB available space.
The following creates and populates the <tt><workdir>/buildroot</tt> directory:

$ svn co svn://linux-xtensa.org/var/svn/repos/buildroot/trunk buildroot

=== Download Linux kernel sources ===

First you need to decide which kernel tree to work with.
(You can also download multiple kernel source trees of course.)

At the time of writing, the <tt>xtensa-2.6.24</tt> tree is the most current.

The <tt>xtensa-2.6.24</tt> tree is based on the release candidate 2.6.24-rc''n'' kernel
from <tt>kernel.org</tt>.

The <tt>xtensa-devel</tt> tree contains the most recent changes but is not as stable.
It also gets updated semi-regularly with the very latest Linux kernel tree from <tt>kernel.org</tt>.
'''Note:''' The <tt>xtensa-devel</tt> tree is about to be recreated from scratch; if you
have previously cloned this tree, you will have to clone it again once this happens to
avoid confusing git when pulling (from what would be a mismatching tree).

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.24 <dir>

This creates and populates the <workdir>/<dir> directory. If <dir> is omitted, it defaults to <tt>xtensa-2.6.24</tt> (the last non-extension part of the cloned path). For the purposes of this document, we assume <dir> is named <tt>linux</tt>.

Similarly, to get the development tree:

$ cd <workdir>
$ git clone git://git.linux-xtensa.org/kernel/xtensa-devel <dir>

Note that the latter <tt>xtensa-devel</tt> tree currently contains two branches:
'''master''' (the default branch checked out by the clone command above),
and '''testing'''.
''Note: more branches will be added when the tree is recreated.''
Often, development
checkins are made to the '''testing''' branch before getting repackaged
and integrated over to the '''master''' branch some time later.
You can switch to another branch (within the cloned repository)
using the <tt>git-checkout</tt> command, for example:

$ git checkout testing

== 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>
$ ./buildroot/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 , 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:

$ ./buildroot/target/xtensa/xt-buildroot-overlay-install -t blinkcore-linux-overlay.tar.gz \
-b ./buildroot -k ./linux -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 <code>''make menuconfig''</code> steps) to select
the <code>''custom''</code> 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 <code>-c</code> 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 [http://buildroot.uclibc.org/ buildroot.uclibc.org].

=== Configure buildroot ===

Note: You need the TERM environment variable properly set for curses
based tools to work.

The first time you configure buildroot, start with defaults for Xtensa processors:

$ cd <workdir>/buildroot
$ cp target/xtensa/defconfig .config
$ make menuconfig

You should get a curses interface for configuring buildroot.
Make the following changes:

* Change '''Target Architecture Variant''' to desired Xtensa or Diamond core (e.g., '''dc232b''')
* Make any other desired changes (e.g., selecting additional packages)
* Exit and save the configuration

If later you want to change the buildroot configuration without losing
other changes made so far, just use ''make menuconfig'' by itself:

$ cd <workdir>/buildroot
$ make menuconfig

=== Configure uClibc ===

Apply the default uClibc configuration for Xtensa processors:

$ make uclibc-config

To further customize uClibc, you can then optionally configure it like this:

$ make uclibc-menuconfig

=== Build buildroot ===

$ make

THIS WILL TAKE A LONG TIME (from 20 minutes to perhaps an hour or many,
depending on your system and on whether you enabled extra packages in
your buildroot configuration).

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 <tt>make</tt> 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 <tt>buildroot</tt> directory tree completely and start again from the svn checkout.

$ 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. Customizations to the uClibc configuration should have ended up getting saved in target/xtensa/uClibc.config , so hopefully are preserved by the above sequence.

== Build and Run a Linux Kernel on the XTAV60 or XTAV200 Board ==

References to the ''XTAV60 board'' refer to the combination of
the Avnet [http://www.em.avnet.com/tensilica1 LX60 (Xilinx) Development Board]
and a Tensilica provided FPGA bitstream containing a configured Tensilica
processor and basic peripheral IP. For more details, please refer to the
''Tensilica Avnet LX60 (XT-AV60) Board User's Guide''.

Similarly, references to the ''XTAV200 board'' refers the combination of
the Avnet [http://www.em.avnet.com/tensilica2 LX200 (Xilinx) Development Board]
and a Tensilica provided FPGA bitstream containing a configured Tensilica
processor and basic peripheral IP. For more details, please refer to the
''Tensilica Avnet LX200 (XT-AV200) Board User's Guide''.

=== Configure the kernel ===

The kernel 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>''/buildroot/build_xtensa_''<cname>''/staging_dir/usr/bin:$PATH"

where ''<cname>'' is the name of the Xtensa processor configuration you selected
when building the toolchain (e.g., <code>dc232b</code>).

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. If you'll be routinely building multiple
configurations of the Linux kernel, it's good to have some
naming conventions for the build directory. For example,
to experiment with multiple target platforms but only one
processor configuration, we include just the platform name here:

$ mkdir build-xtav60

Let's start with the default kernel configuration for the Avnet board
(which works on both XTAV60 (LX60) and XTAV200 (LX200) boards)
as follows:

$ cd linux
$ make O=../build-xtav60 ARCH=xtensa KBUILD_DEFCONFIG=lx60_defconfig defconfig

This configures the kernel using the default configuration found in
arch/xtensa/configs/lx60_defconfig.

NOTE: This kernel configuration has nothing to do with Xtensa
processor configuration. That comes next.

Let's now customize this a little bit to select the correct Xtensa processor
configuration, and to bundle the root filesystem into the kernel:

$ make O=../build-xtav60 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>''/buildroot/binaries/uclibc/rootfs.xtensa_''<cname>''.cpio.gz

(Don't forget to replace ''<workdir>'' with the appropriate full path
and ''<cname>'' with your Xtensa processor configuration name.)

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.
If the desired processor configuration does not appear explicitly in the list,
simply select '''Custom Xtensa processor configuration''' and enter the
processor configuration name (all lowercase) into the next menu parameter,
'''Xtensa Processor Custom Variant Name'''.

Exit menuconfig, saving your configuration changes.

Backup your configuration outside the build directory. For example:

$ cp ../build-xtav60/.config config.xtav60.saved

If you do a clean rebuild of the kernel (e.g., "rm -rf ../build-xtav60")
you can now configure it with simply:
$ mkdir ../build-xtav60 ; cp config.xtav60.saved ../build-xtav60/.config
Of course if you update the kernel, you'll probably again have to do:
$ make O=../build-xtav60 ARCH=xtensa menuconfig
and save a new copy of your configuration.

=== Build the kernel ===

$ make O=../build-xtav60 ARCH=xtensa

The build will issue a few warnings which are normal.
Once complete, the bootable image is in:
<workdir>/build-xtav60/arch/xtensa/boot/Image.elf
and the uncompressed ELF file containing kernel symbols is in:
<workdir>/build-xtav60/vmlinux
There is also a RedBoot bootable image (if you use RedBoot) in:
<workdir>/build-xtav60/arch/xtensa/boot/zImage.redboot

=== Install Xtensa Tools with the 232L (or selected) 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.

For this example, Xtensa Tools are only needed for downloading
the kernel over OCD using <code>xt-gdb</code>.

=== 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 XTAV60 serial port.

=== Optionally, setup networking ===

This step is optional.

Setup the board's MAC address using dipswitches
(see XTAV60 or XTAV200 board docs as appropriate)
and connect the board 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 board (see board documentation).

Using Tensilica Tools, invoke:

$ xt-gdb <workdir>/build-xtav60/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-xtav60/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 <tt>/bin</tt>,
<tt>/sbin</tt>, <tt>/usr/bin</tt>, etc to see what's available.

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.

== Build and Run a Linux Kernel on the Instruction Set Simulator (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 XTAV60 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.

=== Configure and Build the Kernel for ISS ===

Repeat all the same instructions as above for building the kernel for the
XTAV60 board, except that when initially configuring the kernel,
start from the ISS platform template instead:

$ mkdir build-iss
$ cd linux
$ make O=../build-iss ARCH=xtensa 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-iss ARCH=xtensa menuconfig

in addition to setting up the initramfs filesystem, do the following.
Under '''Bus Options''', deselect '''PCI support'''.
Under '''Platform Options''', deselect '''Default bootloader kernel arguments'''.

Continue configuring and building the kernel as usual.

=== Run the Kernel on ISS ===

Using Tensilica Tools, invoke:

$ xt-gdb <workdir>/build-iss/arch/xtensa/boot/Image.elf

(xt-gdb) target sim --turbo
(xt-gdb) symbol-file <workdir>/build-iss/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.