Linux/Xtensa - User contributions [en]

Instructions for building and booting Linux

2014-07-29T18:19:13Z

Chris:

<big>''Note that this page is mostly outdated and only kept for reference. Support for Xtensa is now integrated in the main Buildroot repository and instructions for building Buildroot can be found under [[Buildroot]]''</big>

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 x86 machines running RedHat Enterprise Linux 4 (RHEL4) and Fedora Core 3 (FC3). It is expected to work on newer 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.
** '''NOTE:''' this assumes the default selection of packages in buildroot. Selecting extra packages may require a more recent host OS or more recent version of certain tools. For example, the default version of <tt>find</tt> on RHEL4 is too old to allow building all X11 packages in buildroot, so it is necessary to upgrade the host version of <tt>findutils</tt> on RHEL4 to build these packages.

* 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 Linux kernel sources ==

The following section describes how to download stable versions
of buildroot, and of the Linux kernel, for Xtensa cores.

First, create an empty directory <tt><workdir></tt> on a disk with
at least 4 GB available space. After the download operations below,
you'll end up with the following file structure,
which is assumed by the rest of this document:

<workdir>/
/buildroot
/linux

First download the buildroot sources.
The current stable source repository and branch have strange names,
bear with me, they're the correct ones to use.
'''Note:''' If you happen to have write access to the repository, use <tt>'''git+ssh:'''</tt> instead of '''<tt>git:</tt>''' in the clone command below,
so that you can later easily push changes back to the repository.
For more details, see the [http://wiki.linux-xtensa.org/index.php/Repository_Access repository access] page.

Download buildroot as follows:

'''$ cd <workdir>'''
'''$ git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot.git buildroot'''
'''$ cd buildroot'''
'''$ git checkout -b snapshot_2+SMP origin/snapshot_2+SMP'''

then the Linux kernel sources:

'''$ cd <workdir>'''
'''$ git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp.git linux'''

Note how in the first case (buildroot), we use a non default branch,
so the last two commands setup tracking for that remote branch and
does a check-out of that branch in the working tree.
In the second case (linux), we use the default branch (<i>master</i> branch)
which gets checked out by default.

Major development updates to buildroot for Xtensa are expected to happen
in the following repository, mostly in the master branch.
However, although it has some more recent packages, this repository is often
in a state of development and not quite as stable as the above.
So, '''DON'T DO THIS STEP''' unless you know what you are doing, and want to
experiment with this version of buildroot instead of the above.

'''$ cd <workdir>'''
'''$ git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa.git buildroot'''

== 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., '''dc233c'''). 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, AXAV110, or XTAV200 Boards ==

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), XTAV110 (LX110), 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"| XTAV110 (LX110)
| 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.

Recently the MMU was modified to come up uninitialized and it's
necessary for the Linux kernel to map the MMU prior to running.
This means you can't place breakpoints in the kernel until the
mapping has been completed. It's likely worth while looking
at the example .xt-gdbinit file in the Kernel Xtensa Documentation:

xtensa-2.6.29-smp-xcc-O3/Documentation/xtensa/gdbmacros/xt-gdbinit

When running on Avnet boards it's necessary to use a HardWare Breakpoint
at the kernel symbol '''set_breakpoints''' which is near ''' _startup'''
and set your early kernel breakpoints once you get to this hardware breakpoint.

With ISS simulation normal breakpoints must be used.

Below is an example snippet from the sample '''xt-gdbinit''' script:

if $debug_hw_breakpoints_supported
hbreak set_breakpoints
else
break set_breakpoints
end

set var $_startup = $bpnum
commands $_startup
set_breakpoints
delete $_startup
info breakpoints
set var $doing_commands = 0
end

=== Mounting the Root Filesystem Over NFS ===

If you build more than the minimal set of packages using
buildroot, the root filesystem can easily grow too large to
fit comfortably (or at all) inside the kernel. In this case,
rather than follow the instructions exactly as above,
you'll want to mount the root filesystem over NFS.

You may also want to mount the root filesystem over NFS to
make changes to the filesystem persistent across runs and
accessible from your development host.

First you need to install the root filesystem generated
using buildroot, to a machine that can serve it over NFS.
Assuming this machine runs Linux, one way to install it is
as follows:

$ '''mkdir ''<exportpath>'' '''
$ '''cd ''<exportpath>'' '''
$ '''sudo cpio -i -d -m -F ''<workdir>''/buildroot/binaries/uclibc/rootfs.xtensa_''<cname>''.cpio --no-absolute-filenames '''

You then need to enable the NFS server on your system
(if not already active), and export this filesystem.
How you do this depends on your host Linux distribution.
For example, on some Fedora releases, one might:

* add the export path to <tt>/etc/exports</tt> using a line such as

''<exportpath>'' *(rw,sync,no_root_squash,no_all_squash,no_wdelay)

* turn on the NFS server if needed:

$ '''sudo /sbin/chkconfig nfs on'''

* tell the NFS server about the new exported filesystem

$ '''sudo /usr/sbin/exportfs -a'''
$ '''sudo /usr/sbin/exportfs -r'''

Second, follow the instructions in the previous sections,
then configure the kernel again as follows.

Under '''General setup''', make sure the
'''Initial RAM filesystem and RAM disk (initramfs/initrd) support'''
entry is disabled (rather than enabled as done in previous sections).

Under '''Platform options''', under the line '''Default bootloader kernel arguments''',
select the boot parameters line and set it to something like this:

'''console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=''<server_ip>'':''<exportpath>'' '''

where ''<server_ip>'' is the IP address of your NFS server, and ''<exportpath>''
is the exported filesystem path.

Another approach is to just specify the ip addresses directly in the CMDLINE
'''CONFIG_CMDLINE="console=ttyS0,38400 ip=192.168.11.95:192.168.11.220:192.168.11.1:255.255.255.0:HiFi-2 root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.DC_C_233L debug coredump_filter=0xff" '''

Where the IP addresses are in the form:

'''${ipaddr}:${nfsroot_server}:${gatewayip}:${netmask}:${hostname}'''

Save this configuration, rebuild the kernel, and follow the
instructions in previous sections to download and run the kernel.
If everything goes well and is setup correctly, your kernel should
now boot with a root filesystem mounted over NFS.

== 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 an
Avnet board, except that when initially configuring the kernel,
start from a ISS platform template instead. For example for the
DC233C Variant:

'''$ mkdir build-iss'''
'''$ cd linux'''
'''$ make O=../build-iss ARCH=xtensa KBUILD_DEFCONFIG=iss_dc233c_defconfig defconfig'''

The above make example configures the kernel using the default configuration found in
'''arch/xtensa/configs/iss_dc233_defconfig'''. Most important to note is that the
root file system mounted when Linux boots comes via the targets device '''/dev/simdisk0'''
which is defined in the kernel '''.config''' file. For example:

'''CONFIG_SIMDISK0_FILENAME="/export2/DC_C_233L/LINUX_ROOT.ext2"'''

The SIMDISK file name and VARIANT name are typically configured when running '''make menuconfig'''; Ex:

'''$ make O=../build-iss ARCH=xtensa menuconfig'''

and selecting

'''Xtensa Platform options''' ---> '''Host filename for a simulated device'''

and entering the pathname to the .ext2 file there. Ex: '''/export2/DC_C_233L/LINUX_ROOT.ext2'''

You often want to change the VARIANT to the one you desire, Ex: FSF. You do this via
the top level menu:

'''Xtensa Processor type and features ---> Xtensa Processor Custom Core Variant Name'''

With the new SIMDISK approach you copy the EXT2 Filesystem file generated by Buildroot
to a location to be accessed by Xtensa Linux. Ex:

'''$ cp /export2/DC_C_233L/src/buildroot-xtensa-HiFi2-Snapshot/binaries/dc233c/rootfs.xtensa_dc233c.ext2 /export2/DC_C_233L/LINUX_ROOT.ext2'''

'''NOTE:''' There is an old '''iss_defconfig''' that tries to use a '''tuntap''' Ethernet
interface that currently isn't supported.
Previously with this old iss_defconfig using the '''tuntap''' Ethernet interface
it was suggested to set up the initramfs filesystem, and do the following.
Under '''Bus Options''', deselect '''PCI support'''.
Under '''Platform Options''', deselect '''Default bootloader kernel arguments'''.
Hopefully we will someday be able to support the use of a network interface with
ISS simulation and then be able to mount NFS root partitions again. So I'm leaving
this note for future exploration of this mechanism; Hope you don't mind the clutter.

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 --memlimit=128'''
'''(xt-gdb) symbol-file <workdir>/build-iss/vmlinux'''
'''(xt-gdb) run'''

Wait patiently while Linux boots ... (maybe a minute). The setting of the '''memlimit'''
needs to match the PLATFORM_DEFAULT_MEM_SIZE defined in /arch/xtensa/platforms/iss/include/platform/hardware.h.
Currently this limit us 128 MegaBytes:

#define PLATFORM_DEFAULT_MEM_SIZE 0x08000000 /* 13,4217,728 128M */

and we will be extending this for the DC233L to take advantage of it's V3 MMU.

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.

Toolchain Overlay File

2014-01-28T18:56:58Z

Chris: /* Creating the overlay */

== Introduction ==

The ''Overlay'' is a tar file that includes modified versions of processor configuration dependent files that are required by various toolchain tools, such as binutils, gcc, and gdb. The overlay described here has a specific layout and is intended for toolchain generators, such as buildroot or crosstool-NG.

== Creating the overlay ==

The overlay file shipped by Tensilica uses a flat directory structure, which is not suitable for buildroot or crosstool-NG at the moment. The file is part of the generated processor package, and can be found in the XtDevTools directory:

XtDevTools/install/build/$VERSION/$XTENSA_CORE/src/xtensa-config-overlay.tar.gz

The following script converts this file and writes the modified version to xtensa-overlay.tar. Simply provide the path and name of the overlay provided by Tensilica when running the script:

./script xtensa-config-overlay.tar.gz

The file xtensa-overlay.tar created by the script can now be used to build buildroot or crosstool-NG. For more information how to configure those generators, please see [[Buildroot]] or [[crosstool-NG]].

(Note that there is also a similar overlay file in the generated processor package provided by Tensilica, but it has a different directory layout and is not suitable for the script provided below. It can be found under .../$XTENSA_CORE/xtensa-elf/src/linux/misc/linux-overlay.tar.gz)

== Conversion Script ==

#!/bin/sh
if [ $# -ne 1 ]; then
echo "Error: No overlay file specified"
exit 1
fi
if [ $1 == "xtensa-overlay.tar" ]; then
echo "Error: Input file must be named other than 'xtensa-overlay.tar'"
exit 1
fi
if [ ! -f $1 ]; then
echo "Error: Overlay file $1 not found"
exit 1
fi
TMPDIR=`mktemp -d`
tar xzf $1 -C $TMPDIR
mkdir -p $TMPDIR/overlay/binutils/bfd $TMPDIR/overlay/binutils/ld \
$TMPDIR/overlay/binutils/include $TMPDIR/overlay/gcc/include \
$TMPDIR/overlay/gdb/bfd $TMPDIR/overlay/gdb/gdb/regformats \
$TMPDIR/overlay/gdb/gdb/gdbserver $TMPDIR/overlay/gdb/include
mv $TMPDIR/binutils/xtensa-config.h $TMPDIR/overlay/binutils/include
mv $TMPDIR/binutils/xtensa-modules.c $TMPDIR/overlay/binutils/bfd
mv $TMPDIR/gcc/xtensa-config.h $TMPDIR/overlay/gcc/include
mv $TMPDIR/gdb/xtensa-config.c $TMPDIR/overlay/gdb/gdb
mv $TMPDIR/gdb/xtensa-config.h $TMPDIR/overlay/gdb/include
mv $TMPDIR/gdb/xtensa-modules.c $TMPDIR/overlay/gdb/bfd
mv $TMPDIR/gdb/xtensa-xtregs.c $TMPDIR/overlay/gdb/gdb/gdbserver
mv $TMPDIR/gdb/reg-xtensa.dat $TMPDIR/overlay/gdb/gdb/regformats
tar cf xtensa-overlay.tar -C $TMPDIR/overlay/ binutils gcc gdb
rm -fr $TMPDIR

== Example Files ==

The following files are the original and generated overlay file for the DC_D_233L processor.

* http://www.linux-xtensa.org/pub/xtensa-config-overlay.tar.gz - Original overlay file provided by Tensilica
* http://www.linux-xtensa.org/pub/xtensa-overlay.tgz - : Generated overlay file, applicable to buildroot and crosstool-NG

Toolchain Overlay File

2014-01-28T18:49:54Z

Chris: /* Conversion Script */

== Introduction ==

The ''Overlay'' is a tar file that includes modified versions of processor configuration dependent files that are required by various toolchain tools, such as binutils, gcc, and gdb. The overlay described here has a specific layout and is intended for toolchain generators, such as buildroot or crosstool-NG.

== Creating the overlay ==

The overlay file shipped by Tensilica uses a flat directory structure, which is not suitable for buildroot or crosstool-NG at the moment. It is part of the generated processor package, and can be found in the XtDevTools directory:

XtDevTools/install/build/$VERSION/$XTENSA_CORE/src/xtensa-config-overlay.tar.gz

The following script converts the directory structure of that file by creating a new overlay file, called xtensa-overlay.tgz, and extracting the necessary files from the Tensilica overlay. Simply provide the path and name of the overlay provided by Tensilica when running the script:

./script xtensa-config-overlay.tar.gz

This will create the file xtensa-overlay.tgz required by buildroot or crosstool-NG. For more information how to configure those generators, please see [[Buildroot]] or [[crosstool-NG]].

(Note that there is also a similar file under .../$XTENSA_CORE/xtensa-elf/src/linux/misc/linux-overlay.tar.gz. This file has a different layout structure and doesn't work with the script below)

== Conversion Script ==

#!/bin/sh
if [ $# -ne 1 ]; then
echo "Error: No overlay file specified"
exit 1
fi
if [ $1 == "xtensa-overlay.tar" ]; then
echo "Error: Input file must be named other than 'xtensa-overlay.tar'"
exit 1
fi
if [ ! -f $1 ]; then
echo "Error: Overlay file $1 not found"
exit 1
fi
TMPDIR=`mktemp -d`
tar xzf $1 -C $TMPDIR
mkdir -p $TMPDIR/overlay/binutils/bfd $TMPDIR/overlay/binutils/ld \
$TMPDIR/overlay/binutils/include $TMPDIR/overlay/gcc/include \
$TMPDIR/overlay/gdb/bfd $TMPDIR/overlay/gdb/gdb/regformats \
$TMPDIR/overlay/gdb/gdb/gdbserver $TMPDIR/overlay/gdb/include
mv $TMPDIR/binutils/xtensa-config.h $TMPDIR/overlay/binutils/include
mv $TMPDIR/binutils/xtensa-modules.c $TMPDIR/overlay/binutils/bfd
mv $TMPDIR/gcc/xtensa-config.h $TMPDIR/overlay/gcc/include
mv $TMPDIR/gdb/xtensa-config.c $TMPDIR/overlay/gdb/gdb
mv $TMPDIR/gdb/xtensa-config.h $TMPDIR/overlay/gdb/include
mv $TMPDIR/gdb/xtensa-modules.c $TMPDIR/overlay/gdb/bfd
mv $TMPDIR/gdb/xtensa-xtregs.c $TMPDIR/overlay/gdb/gdb/gdbserver
mv $TMPDIR/gdb/reg-xtensa.dat $TMPDIR/overlay/gdb/gdb/regformats
tar cf xtensa-overlay.tar -C $TMPDIR/overlay/ binutils gcc gdb
rm -fr $TMPDIR

== Example Files ==

The following files are the original and generated overlay file for the DC_D_233L processor.

* http://www.linux-xtensa.org/pub/xtensa-config-overlay.tar.gz - Original overlay file provided by Tensilica
* http://www.linux-xtensa.org/pub/xtensa-overlay.tgz - : Generated overlay file, applicable to buildroot and crosstool-NG

Boot Loader

2013-12-03T22:30:08Z

Chris:

== Boot Loaders ==

The [http://en.wikipedia.org/wiki/Bootloader bootstrap loader or boot loader] is a small program running on a computer or device after power-on to load the operating system. Most boot loaders today provide additional features that allow to upgrade the firmware and access the system for troubleshooting.

== U-Boot <small>([[U-Boot|build instructions for Xtensa]])</small> ==

U-Boot is one of the most popular boot loaders for Linux. It has a very complete [http://www.denx.de/wiki/U-Boot Project Page] as well as an nice introduction available [http://www.linuxfordevices.com/c/a/Linux-For-Devices-Articles/Introduction-to-Das-UBoot-the-universal-open-source-bootloader/ here]. A very complete U-Boot manual is also available [http://www.denx.de/wiki/DULG/Manual here].

A development tree for supporting Xtensa in the latest version of U-Boot has been set up [https://github.com/foss-xtensa/u-boot here]

== RedBoot ==

Tensilica has also ported [http://sourceware.org/redboot/ RedBoot] for the Xtensa architecture. A RedBoot binary targeting the XTAV60 (LX60) or XTAV200 (LX200) emulation board is usually provided after generating an FPGA bitstream for one of these boards. See the relevant board documentation from Tensilica for more details such as usage and supported features. For more information and to request sources, please contact [http://www.tensilica.com/ Tensilica] directly. For an example of how to boot the Linux kernel using RedBoot on the LX60 or LX200 boards, see [[RedBoot Example]].

A source tarball for RedBoot with support for the Xtensa architecture is available [http://linux-xtensa.org/pub/redboot/redboot1.3.1-RB2007.2.tgz here]. For more details, see the tarball's [http://linux-xtensa.org/pub/redboot/redboot1.3.1-RB2007.2/README.txt README.txt] file.

== Host-Side Loading via OCD ==

An alternative to boot loaders is an external (e.g. ''"host-side"'') loading mechanism.

One common way to load a Linux kernel is to use debugging interfaces such as On-Chip Debug (OCD). For example, Tensilica Tools GDB (xt-gdb) can connect to a target Xtensa processor using OCD via the Xtensa OCD Daemon. It can then load and execute a Linux RAM image (Image.elf or vmlinux) onto the target using standard GDB commands. See [[Buildroot_Build_Instructions#Download_and_run_the_kernel|Download and Run the Kernel]] for an example.

== Linux Kernel Self-Boot Image ==

It is possible to adapt the kernel build scripts for the Xtensa architecture to create a self-booting image. That is, a Linux kernel image that includes a Reset handler and can be either burned in ROM or Flash or downloaded to the target using another mechanism such as OCD. '''''Note: This has not yet been implemented.'''''

Main Page

2013-11-20T17:49:39Z

Chris:

{{DISPLAYTITLE:<span style="display:none"></span>}}
 
= <big>Welcome to the Linux/Xtensa Wiki</big> =

This Wiki project provides information for running and porting [http://en.wikipedia.org/wiki/Linux Linux] and other Open Source Software to the [http://www.tensilica.com Xtensa processor architecture].

The Xtensa processor architecture is a configurable, extensible, and synthesizable 32-bit RISC processor core. All Xtensa processors share a common base instruction set architecture, thereby ensuring compatibility of third party application software and development tools. Many architecture specific projects, such as the Linux kernel, GNU toolchain, and other development tools and applications already support the Xtensa architecture. Modifications to support a specific processor configuration are limited to a small set of configuration files, and the process is mostly automated. The pages listed under ''Developing on the Xtensa Platform'' provide information to support a specific configuration.

{|
|-
|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]]
* [[Instructions for building and booting Linux]]
<div style="margin-top:1em; border-bottom:1px solid #c0c0c0; ; width:350px; ">
<big>Support</big>
</div>
* [[Mailing Lists]]
* [[Status of the Xtensa Port]]
* [[Supported Processor Configurations]]
|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>Developing on the Xtensa Platform</big>
</div>
* [[Toolchain and Embedded Distributions]]
* [[Linux Kernel]]
* [[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]]
* [[Xtensa on QEMU]]
* [[Testing and Verification]]

| colspan=3 |
 
|-

|}

<i><small>
'''NOTE:''' Due to spam, creation of new wiki accounts has been disabled until further notice.
If you want to get an account, and be able to edit or contribute anything,
please 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>

Supported Processors

2013-11-11T20:50:25Z

Chris:

== Xtensa Processor Architecture ==

[[image:chip.jpg|right]]
The Xtensa processor architecture is a configurable and extensible synthesizable 32-bit RISC processor core. SoC and processor designers can select from a variety of options, such as instruction-set extensions (for example, narrow instructions, floating point instructions, etc.), memory, cache, and interrupt configurations. Moreover, Xtensa processors also support custom-defined instructions and registers. Nevertheless, all Xtensa processors share a common base instruction set architecture, thereby ensuring compatibility of third party application software and development tools.

Tensilica’s Diamond Standard Series processor family consists of a number of ready-to-use synthesizable cores and is based on the Xtensa processor architecture. The Diamond Standard 233L processor, for example, contains an MMU and fully supports running Linux.

== Automatic Support for Custom Xtensa Cores ==

Despite the endless possibilities provided by the configurability and extensibility of the Xtensa architecture, generating an open source toolchain and kernel that fully support a specific configured Xtensa processor is straightforward. It only requires to update a small set of files inside the toolchain and kernel sources before the actual build process. All necessary files are typically provided by the processor vendor or directly from Tensilica in the form of a single ''overlay'' file. This mostly automated process (scripted) avoids having to ''manually'' port the kernel to a new processor variant, which would be typical for a fixed processor architecture.

Note that a ''processor configuration'' is also often referred to as a ''core variant'' in Linux. The following list shows processor configurations already included in the kernel:

* Diamond 232L
* Diamond 233L
* Stretch S6000 (without MMU)
* 'FSF' default configuration (only for tool verification)

Crosstool-NG

2013-11-11T19:36:06Z

Chris:

== Overview ==

Crosstool-NG provides a system to build a complete toolchain. It supports various C-libraries (newlib, uClibc, glibc, and eglibc), but can also be used to build a toolchain without a C-library. The following paragraphs describe the steps to build a toolchain tailored for an Xtensa configuration.

== Configure and build Crosstool-NG ==

The mainline repository for crosstool-NG does not yet include support for Xtensa, so you need to clone the repository from linux-xtensa.org:

git clone https://github.com/foss-xtensa/crosstool-NG.git

=== Build ct-ng ===

ct-ng is similar to the command 'make' for other projects, and is used to configure and build the toolchain. Since we cloned it from the repository, it is not yet preconfigured with 'autoconf', so run autoconf first:

autoconf

The next step is to configure ct-ng for your system. The default installation path is /usr/local/ but can be overwritten with the --prefix option. In this example, we install it in the current directory. Note that the prefix option requires an absolute path, so we use $PWD in this example:

./configure --prefix=$PWD/usr

Finally, run 'make install' to build ct-ng and install it:

make install

== Building a 'bare' toolchain without a C-library ==

=== Configure the toolchain ===

The first step is to configure the toolchain:

./ct-ng menuconfig

Make the following changes (---> means to enter the sub-menu). We are assuming that the overlay tar image (OVERLAY_TARFILE) has been copied to ABSOLUTE_PATH_TO_OVERLAY. More information about the overlay file can be found [[Create Overlay|here]]. Note that the processor configuration name is currently not used.

Target options --->
Target Architecture (xtensa)
Target Architecture Variant (Custom Xtensa processor configuration)
(PROCESSOR_NAME) Custom Xtensa process configuration name
(OVERLAY_TARFILE) Custom Xtensa overlay file name
(ABSOLUTE_PATH_TO_OVERLAY) Full path to custom Xtensa processor configurations

C-library --->
C library (none)

The default directory for the created toolchain is $HOME/x-tools, but can be configured under 'Paths and misc options':

Paths and misc options --->
(${HOME}/x-tools/${CT_TARGET}) Prefix directory

=== Build and install the toolchain ===

Finally, build and install the toolchain.

./ct-ng build

=== Test it ===

export PATH=$PATH:$HOME/x-tools/xtensa-unknown-linux-gnu/bin
xtensa-unknown-linux-gnu-gcc t.c

== Building a 'glibc' based toolchain ''(experimental)'' ==

NOTE THAT THE REPOSITORY IS CURRENTLY NOT AVAILABLE.

The glibc port is experimental at the moment and also not part of the main repository yet. A version for Xtensa can be found on linux-xtensa.org, so you can clone it from there:

git clone git://.../git/glibc

=== Configure the toolchain ===

Similar to the 'bare' version above, the first step is to configure crosstool-NG. Simply run

./ct-ng menuconfig

and make the following changes (---> means to enter the sub-menu). We are assuming that the overlay file ([[Create Overlay]]) has been copied to ABSOLUTE_PATH_TO_OVERLAY/CPUNAME.tar.gz.

Paths and misc options --->
[*] Try features marked as EXPERIMENTAL

Target options --->
Target Architecture (xtensa)
Target Architecture Variant (Custom Xtensa processor configuration)
(PROCESSOR_NAME) Custom Xtensa process configuration name
(OVERLAY_TARFILE) Custom Xtensa overlay file name
(ABSOLUTE_PATH_TO_OVERLAY) Full path to custom Xtensa processor configurations

C-library --->
C library (glibc)
glibc version (Custom glibc)
(ABSOLUTE_PATH_TO_glibc-2.17) Full path to custom glibc source
(ports) Extra addons

=== Build and install the toolchain ===

Finally, build and install the toolchain.

./ct-ng build

Supported Processor Configurations

2013-11-11T19:07:53Z

Chris:

= Software Recommendations =

== 128 MB RAM Limit ==

Kernel highmem support has not yet been implemented in the main kernel tree, thus restricting generally usable RAM to the first 128 MB (starting from physical address zero). Implementing kernel highmem support should release this limitation, but it isn't yet clear whether an implementation is practical in the presence of cache aliasing (caches larger than 4 x N kB, for an N-way set-associative cache) on RB-200x release or earlier Tensilica processors.

= Hardware Recommendations =

This section contains recommendations, notes, limitations and requirements for the development of hardware systems using Linux-Xtensa. They are oriented more towards hardware designer when they create a new Xtensa processor configuration or design an SOC with Xtensa processors.

== MMU ==

Processor configurations that run Linux should always include the MMU feature. Although Linux also supports MMU-less processors, it is not very well tested and has a lot of pitfalls. If the overhead of an MMU is too big, an alternative open or closed source operating system should be considered.

== Atomic Memory Access Support ==

For future compatibility with Linux kernel releases for the Xtensa architecture, please include support for the atomic load-conditional-store S32C1I instruction when designing your memory system. The memory system must provide for the atomic update of a memory location by holding off the load until all other transactions are complete, and holding off any other transactions once the atomic operation has started until it has finished.

Tensilica's PIF Bridges all support this, but if you are using other bridges, this implementation should be verified.

== Large RAM with Large Caches ==

Tensilica asks to please contact Tensilica support if you are planning to use or build a linux based system that may require more than 128 MB of main RAM for an Xtensa processor configured with large caches (cache size > 4*N kB, for an N-way set associative cache). There are some system limitations that should be evaluated before proceeding.

Main Page

2013-11-11T19:07:00Z

Chris:

{{DISPLAYTITLE:<span style="display:none"></span>}}
 
= <big>Welcome to the Linux/Xtensa Wiki</big> =

This Wiki project provides information for running and porting [http://en.wikipedia.org/wiki/Linux Linux] and other Open Source Software to the [http://www.tensilica.com Xtensa processor architecture].

The Xtensa processor architecture is a configurable, extensible, and synthesizable 32-bit RISC processor core. All Xtensa processors share a common base instruction set architecture, thereby ensuring compatibility of third party application software and development tools. Many architecture specific projects, such as the Linux kernel, GNU toolchain, and other development tools and applications already support the Xtensa architecture. Modifications to support a specific processor configuration are limited to a small set of configuration files, and the process is mostly automated. The pages listed under ''Supporting a processor configuration'' provide information to support a specific configuration.

{|
|-
|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]]
* [[Instructions for building and booting Linux]]
<div style="margin-top:1em; border-bottom:1px solid #c0c0c0; ; width:350px; ">
<big>Support</big>
</div>
* [[Mailing Lists]]
* [[Status of the Xtensa Port]]
* [[Supported Processor Configurations]]
|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>Developing for the Xtensa Platform</big>
</div>
* [[Toolchain and Embedded Distributions]]
* [[Linux Kernel]]
* [[Boot Loader|Boot Loader]]

<div style="margin-top:1em; border-bottom:1px solid #c0c0c0; ; width:350px; ">
<big>Supporting a new Platform</big>
</div>
* [[Platform Porting|Porting the Kernel to a new Platform (Board)]]
* [[ABI Interface]]
* [[Xtensa on QEMU]]
* [[Testing and Verification]]

| colspan=3 |
 
|-

|}

<i><small>
'''NOTE:''' Due to spam, creation of new wiki accounts has been disabled until further notice.
If you want to get an account, and be able to edit or contribute anything,
please 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>

KnownIssues

2013-11-11T18:59:28Z

Chris: Blanked the page

Linux Kernel

2013-11-11T18:59:12Z

Chris:

= Building a Kernel =

The current mechanism to support a specific Xtensa processor configuration is not yet fully automated, but is a very simple and straight forward process. Note that the Xtensa port of Linux uses the terminology ''variant'' to describe a processor configuration. For this example, we will use ''MyCore'' as the new processor name, but any name can be used. The steps involved adding a processor configuration are:

# Create a new directory for the processor ''variant'' (MyCore) and copy a set of configuration files that describes the processor to that directory
# Add the name of the processor configuration to a Linux configuration file.
# Add the path of the ''variant'' directory to a Makefile

== Create a directory for the variant and copy configuration files ==

All processor configuration specific sources and header files are located in arch/xtensa/variants/''variant-name'' for source files, and arch/xtensa/variants/''variant-name''/include/variant for header files. The include directory typically contains at least the following three files that describe the processor configuration:

* tie.h - describing custom defined TIE registers
* tie-asm.h - macros to access additional TIE registers
* core.h - describing various processor configurations, such as cache sizes, register options, etc.

All processor configurations provide a set of these files as part of the ''overlay'' provided by Tensilica.

If we want to add another processor, we have to create the following directory and copy the three configurations file to that directory:

mkdir -p arch/xtensa/variants/MyCore/include/variant
cp tie.h tie-asm.h core.h arch/xtensa/variants/MyCore/include/variant

== Add the processor name to a Linux configuration file ==

The file arch/xtensa/Kconfig contains a list of processor configurations. Simply add a new entry under the menu "Processor type and features" in the "Xtensa Processor Configuration" list. In most cases, the configuration will have an MMU, so add also the line ''select MMU''.

choice
prompt "Xtensa Processor Configuration"
...
config XTENSA_VARAINT_DC233C
bool "dc233c - Diamond 233L Standard Core Rev.C (LE)"
select MMU
help
...
'''config XTENSA_VARIANT_MYCORE'''
'''bool "MyCore - My extreeem core"'''
'''select MMU'''
'''help'''
'''MyCore with various optimizations.'''

== Add the processor to the makefile ==

Simply add a line for your core at the top of the file. The part of the configuration name CONFIG_XTENSA_VARIANT_MYCORE after CONFIG_ must match the name that was added to Kconfig, and the right hand side must match the name of the directory created in step 1.

variant-$(CONFIG_XTENSA_VARIANT_S6000) := s6000
'''variant-$(CONFIG_XTENSA_VARIANT_MYCORE) := MyCore'''

= Kernel loadable modules using FLIX with L32R =

The kernel module loader (for the Xtensa architecture) supports only the limited set of relocations needed for module loading. This includes, for example, relocation of literals referenced by L32R instructions. This loader is not given specific information about any custom TIE configured in the processor, and thus is currently not able to relocate L32R instructions encoded in a FLIX bundle.

To ensure kernel modules load properly, they need to avoid L32R instructions within FLIX instruction bundles.

Existing kernel code does not generate such instructions, so it is not susceptible.
However, it is possible to generate FLIX instructions using assembly code, or using the Tensilica XCC compiler. In the case of assembly code, simply avoid using L32R or MOVI instructions within a FLIX instruction bundle, unless a MOVI is known to fit without expanding ("relaxing") into an L32R instruction. In the case of XCC, pass the -mno-flix to the compiler (xt-xcc) to avoid generating FLIX bundles.

'''Note''': The use of Tensilica software tools (including XCC) for Linux development is described in the ''Tensilica OSKit Guide'', available from Tensilica.

== Debugging Kernel Loadable Modules ==

Debugging loadable modules isn't easy, a few pointers mentioned here might save you some time. There is a mechanism that Amit Kalie mentioned on his KGDB webpage on loading the module symbols into gdb while loading a module [http://kgdb.linsyssoft.com/initmodule.htm Debuging init_module].

The [http://linux.about.com/od/commands/l/blcmdl8_insmod.htm <tt>insmod</tt> command] has a <tt>''--map''</tt>
option that dumps the module component offsets needed by Amit's approach.
Unfortunately the initial Xtensa buildroot snapshots have a version of <tt>insmod</tt> that doesn't provide this option. Also, while debugging the kernel it's not convenient to run <tt>insmod</tt> on the console of the target.

A workaround to this problem is to hack the kernel <tt>module.c</tt> file and enable debugging.

#if 1
#define DEBUGP printk
#else
#define DEBUGP(fmt , a...)
#endif

This will enable <tt>module.c</tt> to print the module section addresses. You then just list them in the gdb <tt>add-symbol-file</tt> command using that command's section (<tt>''-s''</tt>) options.
Note that the <tt>.text</tt> section is specified without using the <tt>''-s''</tt> option: its address is given alone before any <tt>''-s''</tt> option.

final section addresses: [Kernel Console Log/Output]
0xc02a9098 .note.gnu.build-id
0xc02b1000 .init.literal
0xc02a7000 .text
0xc02b11d8 .init.text
0xc02a90bc .rodata
0xc02a92c4 .rodata.str1.4
0xc02ac27c .data
0xc02ac640 __param
0xc02ac668 .gnu.linkonce.this_module
0xc02ac76c .bss
0xc02aaf0c .symtab
0xc02ab8fc .strtab

add-symbol-file /export/src/Transwitch/a2000_src/a2000_src/Linux_atlanta/ctlm-cpe/drivers/ctlmeth/ctlmeth.ko \
0xc02a7000 \
-s .data 0xc02ac27c \
-s .init.text 0xc02b11d8 \
-s .bss 0xc02ac76c \
-s .init.literal 0xc02b1000 \
-s .rodata 0xc02a90bc

You likely want to compile your modules unoptimized and unstripped to facilitate debugging and provide the path to the module source to gdb with the <tt>dir</tt> command.
For example:
dir /home/pdelaney/src/Transwitch/a2000_src/a2000_src/Linux_atlanta/ctlm-cpe/drivers/ctlmeth/

Supported Processors

2013-11-11T18:49:16Z

Chris: /* Automatic Support for Custom Xtensa Cores */

== Xtensa Processor Architecture ==

[[image:chip.jpg|right]]
The Xtensa processor architecture is a configurable, extensible, and synthesizable 32-bit RISC processor core. SoC and processor designers can select from a variety of options, such as instruction-set extensions, memory, cache, and interrupt configurations. Moreover, Xtensa processors can be extended with custom-defined instructions and registers, as well as custom port and queue interfaces. All Xtensa processors share a common base instruction set architecture, thereby ensuring compatibility of third party application software and development tools.

Tensilica’s Diamond Standard Series processor family consists of a number of ready-to-use synthesizable cores and is based on the Xtensa processor architecture. The Diamond Standard 233L processor, for example, contains an MMU and fully supports running Linux.

== Automatic Support for Custom Xtensa Cores ==

Despite the endless possibilities provided by the configurability and extensibility of the Xtensa architecture, obtaining an open source toolchain and kernel that fully support a specific configured Xtensa core is a straightforward matter. The process is mostly automated (scripted), avoiding any need to manually port the kernel to a new processor variant as is typical for a fixed processor architecture. Modifications to toolchain and kernel sources are limited to a small set of configuration files, typically provided by Tensilica in the form of an ''overlay'' to be copied into the sources. The development tools and kernel are subsequently configured and built as usual. (Of course, you still have to port Linux to your particular board or platform.)

== Kernel and Processor Configuration ==

Because the kernel is much closer to the hardware and provides an abstraction for many architectural options, it needs to be configured and compiled for a particular platform and processor configuration. It also requires development tools configured for the particular processor. Note that a ''processor configuration'' is also often referred to as a ''core variant'' in Linux. The following list shows processor configurations already included in the kernel, but adding a new configuration is a very simple and straight forward process.

* Diamond 232L
* Diamond 233L
* Stretch S6000 (without MMU)
* 'FSF' default configuration (only for tool verification)

Crosstool-NG

2013-11-11T06:33:42Z

Chris: /* Building a 'glibc' based toolchain (experimental) */

== Overview ==

Crosstool-NG provides a system to build a complete toolchain. It supports various C-libraries (newlib, uClibc, glibc, and eglibc), but can also be used to build a toolchain without a C-library. The following paragraphs describe the steps to build a toolchain tailored for an Xtensa configuration.

== Configure and build Crosstool-NG ==

The mainline repository for crosstool-NG does not yet include support for Xtensa, so you need to clone the repository from linux-xtensa.org:

git clone git@github.com:foss-xtensa/crosstool-NG.git

=== Build ct-ng ===

ct-ng is similar to the command 'make' for other projects, and is used to configure and build the toolchain. Since we cloned it from the repository, it is not yet preconfigured with 'autoconf', so run autoconf first:

autoconf

The next step is to configure ct-ng for your system. The default installation path is /usr/local/ but can be overwritten with the --prefix option. In this example, we install it in the current directory. Note that the prefix option requires an absolute path, so we use $PWD in this example:

./configure --prefix=$PWD/usr

Finally, run 'make install' to build ct-ng and install it:

make install

== Building a 'bare' toolchain without a C-library ==

=== Configure the toolchain ===

The first step is to configure the toolchain:

./ct-ng menuconfig

Make the following changes (---> means to enter the sub-menu). We are assuming that the overlay tar image (OVERLAY_TARFILE) has been copied to ABSOLUTE_PATH_TO_OVERLAY. More information about the overlay file can be found [[Create Overlay|here]]. Note that the processor configuration name is currently not used.

Target options --->
Target Architecture (xtensa)
Target Architecture Variant (Custom Xtensa processor configuration)
(PROCESSOR_NAME) Custom Xtensa process configuration name
(OVERLAY_TARFILE) Custom Xtensa overlay file name
(ABSOLUTE_PATH_TO_OVERLAY) Full path to custom Xtensa processor configurations

C-library --->
C library (none)

The default directory for the created toolchain is $HOME/x-tools, but can be configured under 'Paths and misc options':

Paths and misc options --->
(${HOME}/x-tools/${CT_TARGET}) Prefix directory

=== Build and install the toolchain ===

Finally, build and install the toolchain.

./ct-ng build

=== Test it ===

export PATH=$PATH:$HOME/x-tools/xtensa-unknown-linux-gnu/bin
xtensa-unknown-linux-gnu-gcc t.c

== Building a 'glibc' based toolchain ''(experimental)'' ==

NOTE THAT THE REPOSITORY IS CURRENTLY NOT AVAILABLE.

The glibc port is experimental at the moment and also not part of the main repository yet. A version for Xtensa can be found on linux-xtensa.org, so you can clone it from there:

git clone git://.../git/glibc

=== Configure the toolchain ===

Similar to the 'bare' version above, the first step is to configure crosstool-NG. Simply run

./ct-ng menuconfig

and make the following changes (---> means to enter the sub-menu). We are assuming that the overlay file ([[Create Overlay]]) has been copied to ABSOLUTE_PATH_TO_OVERLAY/CPUNAME.tar.gz.

Paths and misc options --->
[*] Try features marked as EXPERIMENTAL

Target options --->
Target Architecture (xtensa)
Target Architecture Variant (Custom Xtensa processor configuration)
(PROCESSOR_NAME) Custom Xtensa process configuration name
(OVERLAY_TARFILE) Custom Xtensa overlay file name
(ABSOLUTE_PATH_TO_OVERLAY) Full path to custom Xtensa processor configurations

C-library --->
C library (glibc)
glibc version (Custom glibc)
(ABSOLUTE_PATH_TO_glibc-2.17) Full path to custom glibc source
(ports) Extra addons

=== Build and install the toolchain ===

Finally, build and install the toolchain.

./ct-ng build

Crosstool-NG

2013-11-11T06:24:26Z

Chris: /* Configure and build Crosstool-NG */

== Overview ==

Crosstool-NG provides a system to build a complete toolchain. It supports various C-libraries (newlib, uClibc, glibc, and eglibc), but can also be used to build a toolchain without a C-library. The following paragraphs describe the steps to build a toolchain tailored for an Xtensa configuration.

== Configure and build Crosstool-NG ==

The mainline repository for crosstool-NG does not yet include support for Xtensa, so you need to clone the repository from linux-xtensa.org:

git clone git@github.com:foss-xtensa/crosstool-NG.git

=== Build ct-ng ===

ct-ng is similar to the command 'make' for other projects, and is used to configure and build the toolchain. Since we cloned it from the repository, it is not yet preconfigured with 'autoconf', so run autoconf first:

autoconf

The next step is to configure ct-ng for your system. The default installation path is /usr/local/ but can be overwritten with the --prefix option. In this example, we install it in the current directory. Note that the prefix option requires an absolute path, so we use $PWD in this example:

./configure --prefix=$PWD/usr

Finally, run 'make install' to build ct-ng and install it:

make install

== Building a 'bare' toolchain without a C-library ==

=== Configure the toolchain ===

The first step is to configure the toolchain:

./ct-ng menuconfig

Make the following changes (---> means to enter the sub-menu). We are assuming that the overlay tar image (OVERLAY_TARFILE) has been copied to ABSOLUTE_PATH_TO_OVERLAY. More information about the overlay file can be found [[Create Overlay|here]]. Note that the processor configuration name is currently not used.

Target options --->
Target Architecture (xtensa)
Target Architecture Variant (Custom Xtensa processor configuration)
(PROCESSOR_NAME) Custom Xtensa process configuration name
(OVERLAY_TARFILE) Custom Xtensa overlay file name
(ABSOLUTE_PATH_TO_OVERLAY) Full path to custom Xtensa processor configurations

C-library --->
C library (none)

The default directory for the created toolchain is $HOME/x-tools, but can be configured under 'Paths and misc options':

Paths and misc options --->
(${HOME}/x-tools/${CT_TARGET}) Prefix directory

=== Build and install the toolchain ===

Finally, build and install the toolchain.

./ct-ng build

=== Test it ===

export PATH=$PATH:$HOME/x-tools/xtensa-unknown-linux-gnu/bin
xtensa-unknown-linux-gnu-gcc t.c

== Building a 'glibc' based toolchain ''(experimental)'' ==

The glibc port is experimental at the moment and also not part of the main repository yet. A version for Xtensa can be found on linux-xtensa.org, so you can clone it from there:

git clone git://linux-xtensa.org/git/glibc

=== Configure the toolchain ===

Similar to the 'bare' version above, the first step is to configure crosstool-NG. Simply run

./ct-ng menuconfig

and make the following changes (---> means to enter the sub-menu). We are assuming that the overlay file ([[Create Overlay]]) has been copied to ABSOLUTE_PATH_TO_OVERLAY/CPUNAME.tar.gz.

Paths and misc options --->
[*] Try features marked as EXPERIMENTAL

Target options --->
Target Architecture (xtensa)
Target Architecture Variant (Custom Xtensa processor configuration)
(PROCESSOR_NAME) Custom Xtensa process configuration name
(OVERLAY_TARFILE) Custom Xtensa overlay file name
(ABSOLUTE_PATH_TO_OVERLAY) Full path to custom Xtensa processor configurations

C-library --->
C library (glibc)
glibc version (Custom glibc)
(ABSOLUTE_PATH_TO_glibc-2.17) Full path to custom glibc source
(ports) Extra addons

=== Build and install the toolchain ===

Finally, build and install the toolchain.

./ct-ng build

Toolchain Overlay File

2013-11-11T05:58:38Z

Chris:

== Introduction ==

The ''Overlay'' is a tar file that includes modified versions of processor configuration dependent files that are required by various toolchain tools, such as binutils, gcc, and gdb. The overlay described here has a specific layout and is intended for toolchain generators, such as buildroot or crosstool-NG.

== Creating the overlay ==

The overlay file shipped by Tensilica uses a flat directory structure, which is not suitable for buildroot or crosstool-NG at the moment. It is part of the generated processor package, and can be found in the XtDevTools directory:

XtDevTools/install/build/$VERSION/$XTENSA_CORE/src/xtensa-config-overlay.tar.gz

The following script converts the directory structure of that file by creating a new overlay file, called xtensa-overlay.tgz, and extracting the necessary files from the Tensilica overlay. Simply provide the path and name of the overlay provided by Tensilica when running the script:

./script xtensa-config-overlay.tar.gz

This will create the file xtensa-overlay.tgz required by buildroot or crosstool-NG. For more information how to configure those generators, please see [[Buildroot]] or [[crosstool-NG]].

(Note that there is also a similar file under .../$XTENSA_CORE/xtensa-elf/src/linux/misc/linux-overlay.tar.gz. This file has a different layout structure and doesn't work with the script below)

== Conversion Script ==

#!/bin/sh
TMPDIR=`mktemp -d`
tar xzf $1 -C $TMPDIR
mkdir -p $TMPDIR/overlay/binutils/bfd $TMPDIR/overlay/binutils/ld \
$TMPDIR/overlay/binutils/include $TMPDIR/overlay/gcc/include \
$TMPDIR/overlay/gdb/bfd $TMPDIR/overlay/gdb/gdb/regformats \
$TMPDIR/overlay/gdb/gdb/gdbserver $TMPDIR/overlay/gdb/include
mv $TMPDIR/binutils/xtensa-config.h $TMPDIR/overlay/binutils/include
mv $TMPDIR/binutils/xtensa-modules.c $TMPDIR/overlay/binutils/bfd
mv $TMPDIR/gcc/xtensa-config.h $TMPDIR/overlay/gcc/include
mv $TMPDIR/gdb/xtensa-config.c $TMPDIR/overlay/gdb/gdb
mv $TMPDIR/gdb/xtensa-config.h $TMPDIR/overlay/gdb/include
mv $TMPDIR/gdb/xtensa-modules.c $TMPDIR/overlay/gdb/bfd
mv $TMPDIR/gdb/xtensa-xtregs.c $TMPDIR/overlay/gdb/gdb/gdbserver
mv $TMPDIR/gdb/reg-xtensa.dat $TMPDIR/overlay/gdb/gdb/regformats
tar czf xtensa-overlay.tgz -C $TMPDIR/overlay/ binutils gcc gdb
rm -fr $TMPDIR

== Example Files ==

The following files are the original and generated overlay file for the DC_D_233L processor.

* http://www.linux-xtensa.org/pub/xtensa-config-overlay.tar.gz - Original overlay file provided by Tensilica
* http://www.linux-xtensa.org/pub/xtensa-overlay.tgz - : Generated overlay file, applicable to buildroot and crosstool-NG

Mailing Lists

2013-10-10T20:26:56Z

Chris:

=== Mailing Lists http://lists.linux-xtensa.org ===

The Linux/Xtensa project currently uses a single mailing for all related topics: ''[http://lists.linux-xtensa.org/mailman/listinfo/linux-xtensa linux-xtensa@linux-xtensa.org]'' [http://lists.linux-xtensa.org/pipermail/linux-xtensa/ (''Archive'')]

===Subscribing and Unsubscribing===

Subscriptions are handled through the email interface or web interface of the mailing list software. In case of the email interface, send an email with the command ''subscribe'' if you want to join a mailing list, or ''unsubscribe'' to leave a mailing list to ''listname''-request@linux-xtensa.org. The command can be in either the subject line or the body of the mail.

* subscribe [''password''] [digest] [address=''address'']
*: Subscribe to the mailing list. A ''password'' is required to unsubscribe from the mailing list. If you omit the ''password'', one will be generated for you. Specifying a ''address'' allows to use a different email address than the sender.
* unsubscribe [''password''] [address=''address'']
*: Unsubscribe from the mailing list. A password is required to unsubscribe from the mailing list. If ommitted, you will receive a confirmation email.
* help
*: Receive a copy of the help message including a list of all commands.

The web interface can be reached under http://lists.linux-xtensa.org. Select the mailing list you want to subscribe or unsubscribe, and follow the instructions.

=== Posting ===

You need to subscribe before you can post on the mailing list. To send an an email to all subscribers of a mailing list, send it to ''listname''@linux-xtensa.org.

Note that the mailing lists are public. By posting messages to any of these three lists, you implicitly agree that the posted messages are in the public domain, and as such may be freely copied,
archived, duplicated, and sent to other persons. For guidelines about posting, please, read also http://www.ietf.org/rfc/rfc1855.txt.

=== Archive ===

The web interface (http://lists.linux-xtensa.org) provides an archive of the mailing lists.

=== Help ===

In case of any problems, you can send an email to the list owner: ''listname''-owner@linux-xtensa.org.
[[Image:Example.jpg]]

Mailing Lists

2013-10-10T20:23:41Z

Chris:

=== Lists ===

The Linux/Xtensa project currently uses a single mailing for all related topics: ''linux-xtensa@linux-xtensa.org '' [http://lists.linux-xtensa.org/pipermail/linux-xtensa/ (''Archive'')]

===Subscribing and Unsubscribing===

Subscriptions are handled through the email interface or web interface of the mailing list software. In case of the email interface, send an email with the command ''subscribe'' if you want to join a mailing list, or ''unsubscribe'' to leave a mailing list to ''listname''-request@linux-xtensa.org. The command can be in either the subject line or the body of the mail.

* subscribe [''password''] [digest] [address=''address'']
*: Subscribe to the mailing list. A ''password'' is required to unsubscribe from the mailing list. If you omit the ''password'', one will be generated for you. Specifying a ''address'' allows to use a different email address than the sender.
* unsubscribe [''password''] [address=''address'']
*: Unsubscribe from the mailing list. A password is required to unsubscribe from the mailing list. If ommitted, you will receive a confirmation email.
* help
*: Receive a copy of the help message including a list of all commands.

The web interface can be reached under http://lists.linux-xtensa.org. Select the mailing list you want to subscribe or unsubscribe, and follow the instructions.

=== Posting ===

You need to subscribe before you can post on the mailing list. To send an an email to all subscribers of a mailing list, send it to ''listname''@linux-xtensa.org.

Note that the mailing lists are public. By posting messages to any of these three lists, you implicitly agree that the posted messages are in the public domain, and as such may be freely copied,
archived, duplicated, and sent to other persons. For guidelines about posting, please, read also http://www.ietf.org/rfc/rfc1855.txt.

=== Archive ===

The web interface (http://lists.linux-xtensa.org) provides an archive of the mailing lists.

=== Help ===

In case of any problems, you can send an email to the list owner: ''listname''-owner@linux-xtensa.org.
[[Image:Example.jpg]]

MediaWiki:Sidebar

2013-10-08T18:46:22Z

Chris:

* navigation
** mainpage|mainpage-description
** portal-url|portal
** currentevents-url|currentevents
** [http://lists.linux-xtensa.org Mailing Lists]
** helppage|help
* SEARCH
* TOOLBOX
* LANGUAGES

MediaWiki:Sidebar

2013-10-08T18:46:00Z

Chris:

* navigation
** mainpage|mainpage-description
** portal-url|portal
** currentevents-url|currentevents
** [[http://lists.linux-xtensa.org Mailing Lists]]
** helppage|help
* SEARCH
* TOOLBOX
* LANGUAGES

MediaWiki:Sidebar

2013-10-08T18:44:13Z

Main Page

2013-10-01T17:03:50Z

Chris:

{{DISPLAYTITLE:<span style="display:none"></span>}}
 
= <big>Welcome to the Linux/Xtensa Wiki</big> =

This Wiki project provides information for running and porting [http://en.wikipedia.org/wiki/Linux Linux] and other Open Source Software to the [http://www.tensilica.com Xtensa processor architecture].

The Xtensa processor architecture is a configurable, extensible, and synthesizable 32-bit RISC processor core. All Xtensa processors share a common base instruction set architecture, thereby ensuring compatibility of third party application software and development tools. Many architecture specific projects, such as the Linux kernel, GNU toolchain, and other development tools and applications already support the Xtensa architecture. Modifications to support a specific processor configuration are limited to a small set of configuration files, and the process is mostly automated. The pages listed under ''Supporting a processor configuration'' provide information to support a specific configuration.

{|
|-
|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]]
* [[Instructions for building and booting Linux]]
<div style="margin-top:1em; border-bottom:1px solid #c0c0c0; ; width:350px; ">
<big>Support</big>
</div>
* [[Mailing Lists]]
* [[Status of the Xtensa Port]]
* [[KnownIssues|Known Kernel Issues and Limitations]]
* [[Supported Processor Configurations]]
|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>Supporting a processor configuration</big>
</div>
* [[Toolchain and Embedded Distributions]]
* [[Linux Kernel]]
* [[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]]
* [[Xtensa on QEMU]]
* [[Testing and Verification]]

| colspan=3 |
 
|-

|}

<i><small>
'''NOTE:''' Due to spam, creation of new wiki accounts has been disabled until further notice.
If you want to get an account, and be able to edit or contribute anything,
please 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>

Main Page

2013-07-10T23:26:45Z

Chris:

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

This Wiki project provides information for running and porting [http://en.wikipedia.org/wiki/Linux Linux] and other Open Source Software to the [http://www.tensilica.com Xtensa processor architecture].

The Xtensa processor architecture is a configurable, extensible, and synthesizable 32-bit RISC processor core. All Xtensa processors share a common base instruction set architecture, thereby ensuring compatibility of third party application software and development tools. Many architecture specific projects, such as the Linux kernel, GNU toolchain, and other development tools and applications already support the Xtensa architecture. Modifications to support a specific processor configuration are limited to a small set of configuration files, and the process is mostly automated. The pages listed under ''Supporting a processor configuration'' provide information to support a specific configuration.

{|
|-
|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]]
* [[Instructions for building and booting Linux]]
<div style="margin-top:1em; border-bottom:1px solid #c0c0c0; ; width:350px; ">
<big>Support</big>
</div>
* [[Mailing Lists]]
* [[Status of the Xtensa Port]]
* [[KnownIssues|Known Kernel Issues and Limitations]]
* [[Supported Processor Configurations]]
|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>Supporting a processor configuration</big>
</div>
* [[Toolchain and Embedded Distributions]]
* [[Linux Kernel]]
* [[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]]
* [[Xtensa on QEMU]]
* [[Testing and Verification]]

| colspan=3 |
 
|-

|}

<i><small>
'''NOTE:''' Due to spam, creation of new wiki accounts has been disabled until further notice.
If you want to get an account, and be able to edit or contribute anything,
please 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>

Linux/Xtensa:About

2013-06-27T23:56:46Z

Chris:

This Wiki is the primary resource for the community of developers and users of the Linux operating system on Xtensa processors. The Xtensa processor architecture is a configurable, extensible, and synthesizable 32-bit RISC processor core. Processor and SOC vendors can select from various processor options and even create customized instructions in addition to a base ISA to tailor the processor for a particular application.

'''Disclaimer'''

The information or software, including but not limited to the scripts, tools, and utilities contained on this project pages are presented without warranty of any kind, expressed or implied. Users must take full responsibility for the use of information or software contained herein. <br>
'''Linux®''' is the registered trademark of Linus Torvalds in the U.S. and other countries. <br>
'''Xtensa®''' is the registered trademark of Tensilica, Inc.

Linux/Xtensa:About

2013-06-27T23:56:38Z

Chris:

U-Boot

2013-06-14T21:14:40Z

Chris: New page: Under Construction - This page will describe the steps required to support a Xtensa processor configuration in U-Boot.

Under Construction - This page will describe the steps required to support a Xtensa processor configuration in U-Boot.

Boot Loader

2013-06-14T21:13:27Z

Chris:

== Boot Loaders ==

The [http://en.wikipedia.org/wiki/Bootloader bootstrap loader or boot loader] is a small program running on a computer or device after power-on to load the operating system. Most boot loaders today provide additional features that allow to upgrade the firmware and access the system for troubleshooting.

== U-Boot <small>([[U-Boot|build instructions for Xtensa]])</small> ==

U-Boot is one of the most popular boot loaders for Linux. It has a very complete [http://www.denx.de/wiki/U-Boot Project Page] as well as an nice introduction available [http://www.linuxfordevices.com/c/a/Linux-For-Devices-Articles/Introduction-to-Das-UBoot-the-universal-open-source-bootloader/ here]. A very complete U-Boot manual is also available [http://www.denx.de/wiki/DULG/Manual here].

A development tree for supporting Xtensa in the latest version of U-Boot has been set up [http://git.linux-xtensa.org/cgi-bin/git.cgi?p=dev/u-boot.git;a=summary here]

An older port to the Xtensa architecture is also available for the LX60 and LX200 FPGA development boards in the git repository [http://git.linux-xtensa.org/cgi-bin/git.cgi?p=discont/u-boot-xtensa.git;a=summary here] with instructions for [[Setting up U-Boot]] for the LX60 or LX200 FPGA development boards.

== RedBoot ==

Tensilica has also ported [http://sourceware.org/redboot/ RedBoot] for the Xtensa architecture. A RedBoot binary targeting the XTAV60 (LX60) or XTAV200 (LX200) emulation board is usually provided after generating an FPGA bitstream for one of these boards. See the relevant board documentation from Tensilica for more details such as usage and supported features. For more information and to request sources, please contact [http://www.tensilica.com/ Tensilica] directly. For an example of how to boot the Linux kernel using RedBoot on the LX60 or LX200 boards, see [[RedBoot Example]].

A source tarball for RedBoot with support for the Xtensa architecture is available [http://linux-xtensa.org/pub/redboot/redboot1.3.1-RB2007.2.tgz here]. For more details, see the tarball's [http://linux-xtensa.org/pub/redboot/redboot1.3.1-RB2007.2/README.txt README.txt] file.

== Host-Side Loading via OCD ==

An alternative to boot loaders is an external (e.g. ''"host-side"'') loading mechanism.

One common way to load a Linux kernel is to use debugging interfaces such as On-Chip Debug (OCD). For example, Tensilica Tools GDB (xt-gdb) can connect to a target Xtensa processor using OCD via the Xtensa OCD Daemon. It can then load and execute a Linux RAM image (Image.elf or vmlinux) onto the target using standard GDB commands. See [[Buildroot_Build_Instructions#Download_and_run_the_kernel|Download and Run the Kernel]] for an example.

== Linux Kernel Self-Boot Image ==

It is possible to adapt the kernel build scripts for the Xtensa architecture to create a self-booting image. That is, a Linux kernel image that includes a Reset handler and can be either burned in ROM or Flash or downloaded to the target using another mechanism such as OCD. '''''Note: This has not yet been implemented.'''''

Main Page

2013-04-18T21:14:20Z

Chris:

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

This Wiki project provides information about support for the [http://www.tensilica.com Xtensa processor architecture] in [http://en.wikipedia.org/wiki/Linux Linux] and other Open Source Software.

The Xtensa processor architecture is a configurable, extensible, and synthesizable 32-bit RISC processor core. All Xtensa processors share a common base instruction set architecture, thereby ensuring compatibility of third party application software and development tools. Many architecture specific projects, such as the Linux kernel, GNU toolchain, and other development tools and applications already support the Xtensa architecture. Modifications to support a specific processor configuration are limited to a small set of configuration files, and the process is mostly automated. The pages listed under ''Supporting a processor configuration'' provide information to support a specific configuration.

{|
|-
|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]]
* [[Instructions for building and booting Linux]]
<div style="margin-top:1em; border-bottom:1px solid #c0c0c0; ; width:350px; ">
<big>Support</big>
</div>
* [[Mailing Lists]]
* [[Status of the Xtensa Port]]
* [[KnownIssues|Known Kernel Issues and Limitations]]
* [[Supported Processor Configurations]]
|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>Supporting a processor configuration</big>
</div>
* [[Toolchain and Embedded Distributions]]
* [[Linux Kernel]]
* [[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]]
* [[Xtensa on QEMU]]
* [[Testing and Verification]]

| colspan=3 |
 
|-

|}

<i><small>
'''NOTE:''' Due to spam, creation of new wiki accounts has been disabled until further notice.
If you want to get an account, and be able to edit or contribute anything,
please 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>

Software Running on Xtensa

2013-04-18T21:13:53Z

Chris: Software Running on Xtensa moved to Status of the Xtensa Port

#REDIRECT [[Status of the Xtensa Port]]

Status of the Xtensa Port

2013-04-18T21:13:53Z

Chris: Software Running on Xtensa moved to Status of the Xtensa Port

This page provides additional information for software support for the Xtensa architecture. While most applications are written architecture independent, development tools and operating systems must be ported to a new processor architecture. Support for the Xtensa architecture has already been integrated in most Open Source software projects. Development trees that feed to the respective mainline repository and for new development can be found in local [http://git.linux-xtensa.org GIT] repositories.

=== Toolchain: Compiler (GCC) and various binary utilities (binutils) ===

All GNU toolchain tools are maintained in OpenSource and can be downloaded from the respective locations.
* Binutils: http://www.gnu.org/software/binutils/
* GCC: http://gcc.gnu.org/

Additional information to patch these sources for a specific Xtensa processor configuration can be found under [[Toolchain and Embedded Distributions]].

=== C-Libraries: GlibC and uClibc ===

Xtensa has long been part of uClibc, however, there are a lot of bug fixes pending for the next release (0.9.33.3). Support for the Native Posix Thread Library (NTPL) is under development and is expected to be part of the following release. Development for Glibc with NPTL (older thread libraries are not supported by Glibc anymore) is also current under way. A development tree can be found in the local [http://git.linux-xtensa.org GIT] repositories.
* uClibc: http://www.uclibc.org/
* GlibC: http://www.gnu.org/software/libc/

=== Debugging ===

GDB is maintained in OpenSource and support for Xtensa in other debugging tools was maintained as patches in local buildroot repositories, and are currently updated and pushed to the respective main repositories.
* GDB: http://www.gnu.org/software/gdb/
* strace: http://sourceforge.net/projects/strace/

=== Linux kernel ===

Xtensa has been part of the official Linux kernel tree since 2.6.13, however, a lot of patches were maintained in a local stable tree for a long time, and are currently ported to the latest kernel tree. Features, such as large memory support and cache aliasing should be expected to hit the kernel in the 3.10/3.11 time frame. The latest version can be found at https://www.kernel.org/.

=== Toolchain creation tools and embedded distributions (crosstool-NG, buildroot, etc) ===

Xtensa is supported by buildroot, which can be downloaded from http://www.buildroot.net. Support for crosstool-NG has not been pushed into the official tree yet. A version can be downloaded from local [http://git.linux-xtensa.org GIT] repositories. Additional information to configure these tools for a specific Xtensa processor configuration can be found under [[Toolchain and Embedded Distributions]].
* Buildroot: http://www.buildroot.net
* Crosstool-NG: http://crosstool-ng.org/

=== Other Projects ===

The following list are additional projects that are architecture specific, or that have architecture specific components with additional information how to compile them for Xtensa.

* [[LibFFI]] - LibFFI is a library that provides an interface to execute low-level functions. It is mostly used by scripting or higher-level languages, such as Python, Dalvik, etc.

U-Boot Porting

2013-04-05T23:06:22Z

Chris:

WORK IN PROGRESS

== Adding a new Platform (Board) ==

# add a line for the name of board and cpu to $UBOOT/boards.cfg
# create a configuration file for the board

=== Edit boards.cfg ===

Add a line to the bottom of the boards.cfg file describing the new board and processor.
* BOARD-NAME: Name of the board. This name is usually also used for the target name.
* CPU-NAME: Name of the processor (Xtensa configuration); must match the directory name cpu-CPU-NAME.
* VENDOR-NAME:

BOARD-NAME CPU-NAME xtensa BOARD-NAME VENDOR-NAME
#Target ARCH CPU Board name Vendor SoC Options

=== Create a configuration file for the board ===

<code> include/configs/ <code> directory, which is typically named after the board: <code> ''<board>''.h </code>. This file contains various board-specific macro definitions, such as FLASH location, device registers, etc.

You should include ''addrspace.h'' from the Xtensa include directory. This file provides macros to

#include <asm/addrspace.h>

== OLD INFORMATION ==

The easiest way to add new platform to U-Boot is usually to start from a similar board and modify the files as needed. The first step is to add the board to the main <code>Makefile</code> in the root directory.

Unlike other architectures, the processor configurations (''variants'') are defined inside the Xtensa include directory.

The following version allows for arbitrary Xtensa processor configuration. Instead of <code> make ''<board>''_config </code>, it requires an additional name to specify the ''<variant>''. This is the name of the processor configuration. The configuration <code> make ''variant''_''board''_config </code>, for example, the following command will configure U-Boot for the xtav60 board with a dc232l processor configuration: <code>make dc232l_xtav60_config</code>

%''<board>''_config: unconfig
@$(MKCONFIG) xtensa xtensa xtav60 avnet NULL $(*:_=)
@echo "VARIANT = $(*:_=)" >> $(obj)include/config.mk

''<board>''_config: unconfig
@$(MKCONFIG) xtensa xtensa ''<board>'' ''<vendor>'' NULL ''variant''

All board specific files are concentrated in one directory (the ''<vendor>'' sub-directory is optional):

board/[''<vendor>]''/''<board>''

This directory typically contains a README file describing the board and features, files for the build system (<code> Makefile </code> and <code> config.mk </code>), and one or more source files to initialize the board.

There is one additional configuration file in the <code> include/configs/ <code> directory, which is typically named after the board: <code> ''<board>''.h </code>. This file contains various board-specific macro definitions, such as FLASH location, device registers, etc.

You should include ''addrspace.h'' from the Xtensa include directory. This file provides macros to

#include <asm/addrspace.h>

== Adding a new Processor Configuration ==

Status of the Xtensa Port

2013-03-27T16:26:13Z

Chris:

Main Page

2013-03-24T20:39:59Z

Chris:

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

This Wiki project provides information about support for the [http://www.tensilica.com Xtensa processor architecture] in [http://en.wikipedia.org/wiki/Linux Linux] and other Open Source Software.

The Xtensa processor architecture is a configurable, extensible, and synthesizable 32-bit RISC processor core. All Xtensa processors share a common base instruction set architecture, thereby ensuring compatibility of third party application software and development tools. Many architecture specific projects, such as the Linux kernel, GNU toolchain, and other development tools and applications already support the Xtensa architecture. Modifications to support a specific processor configuration are limited to a small set of configuration files, and the process is mostly automated. The pages listed under ''Supporting a processor configuration'' provide information to support a specific configuration.

{|
|-
|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]]
* [[Instructions for building and booting Linux]]
<div style="margin-top:1em; border-bottom:1px solid #c0c0c0; ; width:350px; ">
<big>Support</big>
</div>
* [[Mailing Lists]]
* [[Software Running on Xtensa]]
* [[KnownIssues|Known Kernel Issues and Limitations]]
* [[Supported Processor Configurations]]
|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>Supporting a processor configuration</big>
</div>
* [[Toolchain and Embedded Distributions]]
* [[Linux Kernel]]
* [[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]]
* [[Xtensa on QEMU]]
* [[Testing and Verification]]

| colspan=3 |
 
|-

|}

<i><small>
'''NOTE:''' Due to spam, creation of new wiki accounts has been disabled until further notice.
If you want to get an account, and be able to edit or contribute anything,
please 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>

Software Support for Xtensa

2013-03-24T20:38:55Z

Chris: Software Support for Xtensa moved to Software Running on Xtensa

#REDIRECT [[Software Running on Xtensa]]

Status of the Xtensa Port

2013-03-24T20:38:55Z

Chris: Software Support for Xtensa moved to Software Running on Xtensa

This page provides additional information for software support for the Xtensa architecture. While most applications are written architecture independent, development tools and operating systems must be ported to a new processor architecture. Support for the Xtensa architecture has already been integrated in most Open Source software projects. Development trees that feed to the respective mainline repository and for new development can be found in local [http://git.linux-xtensa.org GIT] repositories.

=== Toolchain: Compiler (GCC) and various binary utilities (binutils) ===

All GNU toolchain tools are maintained in OpenSource and can be downloaded from the respective locations.
* Binutils: http://www.gnu.org/software/binutils/
* GCC: http://gcc.gnu.org/

Additional information to patch these sources for a specific Xtensa processor configuration can be found under [[Toolchain and Embedded Distributions]].

=== C-Libraries: GlibC and uClibc ===

Xtensa has long been part of uClibc, however, there are a lot of bug fixes pending for the next release (0.9.33.3). Support for the Native Posix Thread Library (NTPL) is under development and is expected to be part of the following release. Development for Glibc with NPTL (older thread libraries are not supported by Glibc anymore) is also current under way. A development tree can be found in the local [http://git.linux-xtensa.org GIT] repositories.
* uClibc: http://www.uclibc.org/
* GlibC: http://www.gnu.org/software/libc/

=== Debugging ===

GDB is also maintained in OpenSource and can be downloaded from http://www.gnu.org/software/gdb/. Support for other debugging tools (strace, ltrace, oprofile, etc.) has not been pushed to their respective main repositories, yet. Patches have been maintained in local buildroot repositories. More information can be found at http://www.gnu.org/software/gdb/

=== Linux kernel ===

Xtensa has been part of the official Linux kernel tree since 2.6.13, however, a lot of patches were maintained in a local stable tree for a long time, and are currently ported to the latest kernel tree. Features, such as large memory support and cache aliasing should be expected to hit the kernel in the 3.10/3.11 time frame. The latest version can be found at https://www.kernel.org/.

=== Toolchain and embedded distributions (crosstool-NG, buildroot, etc) ===

Xtensa is supported by buildroot, which can be downloaded from http://www.buildroot.net. Support for crosstool-NG has not been pushed into the official tree yet. A version can be downloaded from local [http://git.linux-xtensa.org GIT] repositories. Additional information to configure these tools for a specific Xtensa processor configuration can be found under [[Toolchain and Embedded Distributions]].
* Buildroot: http://www.buildroot.net
* Crosstool-NG: http://crosstool-ng.org/

=== Other Projects ===

The following list are additional projects that are architecture specific, or that have architecture specific components with additional information how to compile them for Xtensa.

* [[LibFFI]] - LibFFI is a library that provides an interface to execute low-level functions. It is mostly used by scripting or higher-level languages, such as Python, Dalvik, etc.

Testing and Verification

2013-03-19T22:26:40Z

Chris:

<big>Under Development</big>

This page describes mechanisms to test the various architecture dependent software, such as toolchain and Linux kernel.

== Dejagnu ==

Dejagnu (http://www.gnu.org/software/dejagnu/) is used by many GNU and other tools as a test environment, and must be installed on the host before running some of the tests below. Additional information for setting it up for a board with an Xtensa processor or for a simulator (ISS or QEMU) can be found under [[DejaGnu]].

== Binutils ==

== GCC ==

== GlibC ==

=== Using Crosstool-NG ===

${CROSSTOOL}/.build/xtensa-unknown-linux-gnu/buildtools/bin

== GDB ==

== Kernel (LTP) ==

While the kernel itself doesn't come with any extensive test suite, the Linux Test Project - LTP (http://ltp.sourceforge.net/) provides an

DejaGnu

2013-03-19T17:45:22Z

Chris:

DejaGnu

2013-03-19T17:41:21Z

Chris:

http://www.gnu.org/software/dejagnu/ is a framework for testing various other tools and programs.

The following instructions are intended to run the test suite in a simulator or on a board running Linux.

== Remote board using ssh ==

== Remote board using telnet/FTP ==

Although the preferred method to use dejagnu is over ssh, it might be necessary to use telnet and ftp, instead, if ssh is not supported or to slow on the particular target. Unfortunately, Dejagnu doesn't fully support telnet/ftp as a remote target out of the box, so it is necessary to patch the telnet.exp file.
The distribution running on that board needs to be configured to include support for an ftp and telnet daemon, and these services should be running.

The telnet.exp file can usually be found under /usr/share/dejagnu/telnet.exp. http://linux-xtensa.org/pub/patches/dejagnu/dejagnu-telnet.patch.gz

cd /usr/share/dejagnu
cp telnet.exp telnet.exp.orig
gunzip -c <path-to>/dejagnu-telnet.patch.gz | patch -p0

The next step is to create a board interface file for the target. In this example, we use the name 'lx60', but it can be any name.

lx60.exp
load_generic_config "unix";
set_board_info hostname "lx60"
set_board_info compiler "<path-to-compiler>/xtensa-linux-gcc"
set_board_info connect "telnet"
set_board_info file_transfer "ftp"
set_board_info shell_prompt "\\$ "
set_board_info protocol "telnet"
set_board_info telnet_username "test"
set_board_info telnet_password "test"
set_board_info ftp_username "test"
set_board_info ftp_password "test"

Before we can run teh testsuite, we need to tell it what board to use. Create the file site.exp under <path-to-libffi>/testsuite/site.exp with the following content:
lappend boards_dir "<directory-that-includes-lx60.exp>"

Finally, you can run the testsuite:
export RUNTESTFLAGS="--target_board=lx60"
make check

== Tensilica ISS Simulator ==

# Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003 Free Software
# Foundation, Inc.
#
# This file is part of DejaGnu.
#
# DejaGnu is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# DejaGnu is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with DejaGnu; if not, write to the Free Software Foundation,
# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

# Load the generic configuration for this board. This will define a basic
# set of routines used to communicate with the board.
load_generic_config "sim"
# basic-sim.exp is a basic description for the standard Cygnus simulator.
load_base_board_description "basic-sim"
# Command to invoke the simulator
set_board_info sim xt-run
setup_sim xtensa
# No multilib flags needed by default.
process_multilib_options ""
# The compiler used to build for this board. This has *nothing* to do
# with what compiler is tested if we're testing gcc.
set_board_info compiler "[find_gcc]"
set_board_info cflags "[libgloss_include_flags] [newlib_include_flags]"
set_board_info ldflags "[libgloss_link_flags] [newlib_link_flags]"
# This board doesn't use a linker script.
set_board_info ldscript ""
# The simulator doesn't return exit statuses and we need to indicate this.
set_board_info needs_status_wrapper 1
# No support for signals on this target.
set_board_info gdb,nosignals 1

Supported Processors

2013-03-18T23:51:28Z

Chris:

== Xtensa Processor Architecture ==

[[image:chip.jpg|right]]
The Xtensa processor architecture is a configurable, extensible, and synthesizable 32-bit RISC processor core. SoC and processor designers can select from a variety of options, such as instruction-set extensions, memory, cache, and interrupt configurations. Moreover, Xtensa processors can be extended with custom-defined instructions and registers, as well as custom port and queue interfaces. All Xtensa processors share a common base instruction set architecture, thereby ensuring compatibility of third party application software and development tools.

Tensilica’s Diamond Standard Series processor family consists of a number of ready-to-use synthesizable cores and is based on the Xtensa processor architecture. The Diamond Standard 233L processor, for example, contains an MMU and fully supports running Linux.

== Automatic Support for Custom Xtensa Cores ==

Despite the endless possibilities provided by the configurability and extensibility of the Xtensa architecture, obtaining an open source toolchain and kernel that fully support a specific configured Xtensa core is a straightforward matter. The process is mostly automated (scripted), avoiding any need to manually port the kernel to a new processor variant as is typical for a fixed processor architecture. Modifications to toolchain and kernel sources are limited to a small set of configuration files, typically provided by Tensilica in the form of an ''overlay'' to be copied into the sources. The development tools and kernel are subsequently configured and built as usual. (Of course, you still have to port Linux to your particular board or platform.)

In the Linux kernel for example, all configuration files are located inside the Xtensa include directory in the kernel sources (<code>arch/xtensa/variant/''config''/include/variant/</code>). Adding support to the kernel for a custom configured Xtensa processor generally involves copying the appropriate configuration files into the appropriate variant directory.

== Kernel and Processor Configuration ==

Because the kernel is much closer to the hardware and provides an abstraction for many architectural options, it needs to be configured and compiled for a particular platform and processor configuration. It also requires development tools configured for the particular processor. Note that a ''processor configuration'' is also often referred to as a ''core variant'' in Linux. The following list shows processor configurations already included in the kernel, but adding a new configuration is a very simple and straight forward process.

* Diamond 232L
* Diamond 233L
* Stretch S6000 (without MMU)
* 'FSF' default configuration (only for tool verification)

Supported Processors

2013-03-18T23:50:27Z

Chris:

== Xtensa Processor Architecture ==

[[image:chip.jpg|right]]
The Xtensa processor architecture is a configurable, extensible, and synthesizable 32-bit RISC processor core. SoC and processor designers can select from a variety of options, such as instruction-set extensions, memory, cache, and interrupt configurations. Moreover, Xtensa processors can be extended with custom-defined instructions and registers, as well as custom port and queue interfaces. All Xtensa processors share a common base instruction set architecture, thereby ensuring compatibility of third party application software and development tools.

Tensilica’s Diamond Standard Series processor family consists of a number of ready-to-use synthesizable cores and is based on the Xtensa processor architecture. The Diamond Standard 233L processor, for example, contains an MMU and fully supports running Linux.

== Automatic Support for Custom Xtensa Cores ==

Despite the endless possibilities provided by the configurability and extensibility of the Xtensa architecture, obtaining an open source toolchain and kernel that fully support a specific configured Xtensa core is a straightforward matter. The process is mostly automated (scripted), avoiding any need to manually port the kernel to a new processor variant as is typical for a fixed processor architecture. Modifications to toolchain and kernel sources are limited to a small set of configuration files, typically provided by Tensilica in the form of an ''overlay'' to be copied into the sources. The development tools and kernel are subsequently configured and built as usual. (Of course, you still have to port Linux to your particular board or platform.)

In the Linux kernel for example, all configuration files are located inside the Xtensa include directory in the kernel sources (<code>arch/xtensa/variant/''config''/include/variant/</code>). Adding support to the kernel for a custom configured Xtensa processor generally involves copying the appropriate configuration files into the appropriate variant directory.

== Kernel and Processor Configuration ==

Because the kernel is much closer to the hardware and provides an abstraction for many architectural options, it needs to be configured and compiled for a particular platform and processor configuration. It also requires development tools configured for the particular processor. Note that a ''processor configuration'' is also often referred to as a ''core variant'' in Linux. The following list shows processor configurations included in the kernel.
* Diamond 232L
* Diamond 233L
* Stretch S6000 (without MMU)
* 'FSF' default configuration (only for tool verification)

Supported Processors

2013-03-18T23:48:56Z

Chris:

== Xtensa Processor Architecture ==

[[image:chip.jpg|right]]
The Xtensa processor architecture is a configurable, extensible, and synthesizable 32-bit RISC processor core. SoC and processor designers can select from a variety of options, such as instruction-set extensions, memory, cache, and interrupt configurations. Moreover, Xtensa processors can be extended with custom-defined instructions and registers, as well as custom port and queue interfaces. All Xtensa processors share a common base instruction set architecture, thereby ensuring compatibility of third party application software and development tools.

Tensilica’s Diamond Standard Series processor family consists of a number of ready-to-use synthesizable cores and is based on the Xtensa processor architecture. The Diamond Standard 233L processor, for example, contains an MMU and fully supports running Linux.

[[Supported Processor Configurations]] provides additional information when defining a new '''custom''' Xtensa processor.

== Automatic Support for Custom Xtensa Cores ==

Despite the endless possibilities provided by the configurability and extensibility of the Xtensa architecture, obtaining an open source toolchain and kernel that fully support a specific configured Xtensa core is a straightforward matter. The process is mostly automated (scripted), avoiding any need to manually port the kernel to a new processor variant as is typical for a fixed processor architecture. Modifications to toolchain and kernel sources are limited to a small set of configuration files, typically provided by Tensilica in the form of an ''overlay'' to be copied into the sources. The development tools and kernel are subsequently configured and built as usual. (Of course, you still have to port Linux to your particular board or platform.)

In the Linux kernel for example, all configuration files are located inside the Xtensa include directory in the kernel sources (<code>arch/xtensa/variant/''config''/include/variant/</code>). Adding support to the kernel for a custom configured Xtensa processor generally involves copying the appropriate configuration files into the appropriate variant directory.

== Kernel and Processor Configuration ==

Because the kernel is much closer to the hardware and provides an abstraction for many architectural options, it needs to be configured and compiled for a particular platform and processor configuration. It also requires development tools configured for the particular processor. Note that a ''processor configuration'' is also often referred to as a ''core variant'' in Linux. The following list shows processor configurations included in the kernel.
* Diamond 232L
* Diamond 233L
* Stretch S6000 (without MMU)
* 'FSF' default configuration (only for tool verification)

Linux Kernel

2013-03-18T23:47:15Z

Chris:

The current mechanism to support a specific Xtensa processor configuration is not yet fully automated, but is a very simple and straight forward process. Note that the Xtensa port of Linux uses the terminology ''variant'' to describe a processor configuration. For this example, we will use ''MyCore'' as the new processor name, but any name can be used. The steps involved adding a processor configuration are:

# Create a new directory for the processor ''variant'' (MyCore) and copy a set of configuration files that describes the processor to that directory
# Add the name of the processor configuration to a Linux configuration file.
# Add the path of the ''variant'' directory to a Makefile

== Create a directory for the variant and copy configuration files ==

All processor configuration specific sources and header files are located in arch/xtensa/variants/''variant-name'' for source files, and arch/xtensa/variants/''variant-name''/include/variant for header files. The include directory typically contains at least the following three files that describe the processor configuration:

* tie.h - describing custom defined TIE registers
* tie-asm.h - macros to access additional TIE registers
* core.h - describing various processor configurations, such as cache sizes, register options, etc.

All processor configurations provide a set of these files as part of the ''overlay'' provided by Tensilica.

If we want to add another processor, we have to create the following directory and copy the three configurations file to that directory:

mkdir -p arch/xtensa/variants/MyCore/include/variant
cp tie.h tie-asm.h core.h arch/xtensa/variants/MyCore/include/variant

== Add the processor name to a Linux configuration file ==

The file arch/xtensa/Kconfig contains a list of processor configurations. Simply add a new entry under the menu "Processor type and features" in the "Xtensa Processor Configuration" list. In most cases, the configuration will have an MMU, so add also the line ''select MMU''.

choice
prompt "Xtensa Processor Configuration"
...
config XTENSA_VARAINT_DC233C
bool "dc233c - Diamond 233L Standard Core Rev.C (LE)"
select MMU
help
...
'''config XTENSA_VARIANT_MYCORE'''
'''bool "MyCore - My extreeem core"'''
'''select MMU'''
'''help'''
'''MyCore with various optimizations.'''

== Add the processor to the makefile ==

Simply add a line for your core at the top of the file. The part of the configuration name CONFIG_XTENSA_VARIANT_MYCORE after CONFIG_ must match the name that was added to Kconfig, and the right hand side must match the name of the directory created in step 1.

variant-$(CONFIG_XTENSA_VARIANT_S6000) := s6000
'''variant-$(CONFIG_XTENSA_VARIANT_MYCORE) := MyCore'''

Linux Kernel

2013-03-18T23:46:27Z

Chris: New page: The current mechanism to support a specific Xtensa processor configuration is not yet fully automated, but is a very simple and straight forward process. Note that the Xtensa port of Linux...

The current mechanism to support a specific Xtensa processor configuration is not yet fully automated, but is a very simple and straight forward process. Note that the Xtensa port of Linux uses the terminology ''variant'' to describe a processor configuration. For this example, we will use ''MyCore'' as the new processor name in this example, but any name can be used. The steps involved adding a processor configuration are:

# Create a new directory for the processor ''variant'' and copy a set of configuration files that describes the processor to that directory
# Add the name of the processor configuration to a Linux configuration file.
# Add the path of the ''variant'' directory to a Makefile

== Create a directory for the variant and copy configuration files ==

All processor configuration specific sources and header files are located in arch/xtensa/variants/''variant-name'' for source files, and arch/xtensa/variants/''variant-name''/include/variant for header files. The include directory typically contains at least the following three files that describe the processor configuration:

* tie.h - describing custom defined TIE registers
* tie-asm.h - macros to access additional TIE registers
* core.h - describing various processor configurations, such as cache sizes, register options, etc.

All processor configurations provide a set of these files as part of the ''overlay'' provided by Tensilica.

If we want to add another processor, we have to create the following directory and copy the three configurations file to that directory:

mkdir -p arch/xtensa/variants/MyCore/include/variant
cp tie.h tie-asm.h core.h arch/xtensa/variants/MyCore/include/variant

== Add the processor name to a Linux configuration file ==

The file arch/xtensa/Kconfig contains a list of processor configurations. Simply add a new entry under the menu "Processor type and features" in the "Xtensa Processor Configuration" list. In most cases, the configuration will have an MMU, so add also the line ''select MMU''.

choice
prompt "Xtensa Processor Configuration"
...
config XTENSA_VARAINT_DC233C
bool "dc233c - Diamond 233L Standard Core Rev.C (LE)"
select MMU
help
...
'''config XTENSA_VARIANT_MYCORE'''
'''bool "MyCore - My extreeem core"'''
'''select MMU'''
'''help'''
'''MyCore with various optimizations.'''

== Add the processor to the makefile ==

Simply add a line for your core at the top of the file. The part of the configuration name CONFIG_XTENSA_VARIANT_MYCORE after CONFIG_ must match the name that was added to Kconfig, and the right hand side must match the name of the directory created in step 1.

variant-$(CONFIG_XTENSA_VARIANT_S6000) := s6000
'''variant-$(CONFIG_XTENSA_VARIANT_MYCORE) := MyCore'''

DejaGnu

2013-03-18T23:12:51Z

Chris: New page: http://www.gnu.org/software/dejagnu/ is a framework for testing various other tools and programs. The following instructions are intended to run the test suite on a board running Linux. T...

http://www.gnu.org/software/dejagnu/ is a framework for testing various other tools and programs.

The following instructions are intended to run the test suite on a board running Linux. The distribution running on that board needs to be configured to include support for an ftp and telnet daemon, and these services should be running.

Although the preferred method to use dejagnu is over ssh, it might be necessary to use telnet and ftp, instead, if ssh is not supported or to slow on the particular target. Unfortunately, Dejagnu doesn't fully support telnet/ftp as a remote target out of the box, so it is necessary to patch the telnet.exp file.

The telnet.exp file can usually be found under /usr/share/dejagnu/telnet.exp. [http://linux-xtensa.org/pub/patches/dejagnu/dejagnu-telnet.patch.gz http://linux-xtensa.org/pub/patches/dejagnu/dejagnu-telnet.patch.gz]

cd /usr/share/dejagnu
cp telnet.exp telnet.exp.orig
gunzip -c <path-to>/dejagnu-telnet.patch.gz | patch -p0

The next step is to create a board interface file for the target. In this example, we use the name 'lx60', but it can be any name.

lx60.exp
load_generic_config "unix";
set_board_info hostname "lx60"
set_board_info compiler "<path-to-compiler>/xtensa-linux-gcc"
set_board_info connect "telnet"
set_board_info file_transfer "ftp"
set_board_info shell_prompt "\\$ "
set_board_info protocol "telnet"
set_board_info telnet_username "test"
set_board_info telnet_password "test"
set_board_info ftp_username "test"
set_board_info ftp_password "test"

Before we can run teh testsuite, we need to tell it what board to use. Create the file site.exp under <path-to-libffi>/testsuite/site.exp with the following content:
lappend boards_dir "<directory-that-includes-lx60.exp>"

Finally, you can run the testsuite:
export RUNTESTFLAGS="--target_board=lx60"
make check

Testing and Verification

2013-03-18T23:10:07Z

Chris:

<big>Under Development</big>

This page describes mechanisms to test the various architecture dependent software, such as toolchain and Linux kernel.

== Dejagnu ==

Dejagnu (http://www.gnu.org/software/dejagnu/) is used by many GNU and other tools as a test environment, and must be installed on the host before running any of the tests.

=== Xtensa ISS (simulator) ===

=== QEMU ===

=== Board ===

== Binutils ==

== GCC ==

== GlibC ==

=== Using Crosstool-NG ===

${CROSSTOOL}/.build/xtensa-unknown-linux-gnu/buildtools/bin

== GDB ==

== Kernel (LTP) ==

While the kernel itself doesn't come with any extensive test suite, the Linux Test Project - LTP (http://ltp.sourceforge.net/) provides an

Platform Porting

2013-03-18T22:03:27Z

Chris: /* Adding a new Platform to the Kernel */

== Adding a new Platform to the Kernel ==

The easiest way to add support for a new platform for Xtensa is usually to look at the directories of one of the platforms already supported for Xtensa and to copy and modify those files. Drivers to support on-chip devices should go to the generic driver directory instead of the architecture directory. Adding a new platform should not require other changes to generic sources outside the platform specific directories. Modifications to the kernel are, therefore, mostly limited to the following places:

# Modify <code>arch/xtensa/Kconfig</code> and <code>arch/xtensa/Makefile</code> to add support for the new platform.
# Create a directory with the name of the platform in the architecture part of the kernel under <code>arch/xtensa/platforms/</code>. This directory should contain the source files to support hardware components other than generic devices, such as PCI host-bridges, etc.
# Create a directory for the header files: <code>arch/xtensa/platforms/''name''/include</code>. It must at least contain the <code>hardware.h</code> file to describe some fundamental hardware settings.
# ''(optional)'' add a default configuration file for the platform with the name <code>''name''_defconfig</code> to <code>arch/xtensa/configs</code>.

=== Modify <code>Kconfig</code> and <code>Makefile</code> ===

Adding support for a new platform to the build system of Linux only requires to modify <code>Kconfig</code> and <code>Makefile</code>. The new entry in <code>Kconfig</code> allows the configuration scripts to pick up the new platform and the change in <code>Makefile</code> instructs the build process to enter the platform directory, if selected.

<b><code>Kconfig</code></b>

config XTENSA_PLATFORM_''NAME''
bool ''NAME''
help
''descriptive text''

<b><code>Makefile</code></b>
platform-$(CONFIG_XTENSA_PLATFORM_''NAME'') := ''directory-name''

=== Directory for the Headers ===

Any platform specific header files should go to the <code>platform-''name''</code> directory under <code>include/asm-xtensa/</code>. It should contain at least the <code>hardware.h</code> file that describes the physical memory configuration.

/*
* Memory configuration.
*/

#define PLATFORM_DEFAULT_MEM_START 0x00000000
#define PLATFORM_DEFAULT_MEM_SIZE 0x08000000

=== Directory for the new Platform ===

All source files for the new platform should be in <code>arch/xtensa/platforms/''name''</code>. The Xtensa port provides a few hooks that can be used by the platform for initialization and other purposes. These functions are defined as <code>weak</code> symbols with a default 'dummy' implementation in the generic Xtensa sources. Platforms can, therefore, overwrite the default implementation simply by defining the function in one of its sources.

<code>extern void platform_init(bp_tag_t* bootparams);</code><br>
The kernel calls this function early in the boot process prior to initializing the MMU. This allows the platform to perform early initializations of components. The argument <code>bootparams</code> is a list of configuration tags passed from the boot-loader (see also [[Boot Loader]]

<code>extern void platform_setup (char **);</code><br>
This function is called from <code>setup_arch</code> with a pointer to the command-line string.

<code>extern void platform_init_irq (void);</code><br>
This function, called from <code>init_IRQ</code>, allows platforms to initialize external interrupt controllers.

<code>extern void platform_restart (void);</code><br>
<code>extern void platform_halt (void);</code><br>
<code>extern void platform_power_off (void);</code><br>
The kernel calls one of these functions to either restart, halt, or reboot the system.

<code>extern void platform_idle (void);</code><br>
This is the ''idle'' function called whenever there is no thread or process ready.

<code>extern void platform_heartbeat (void);</code><br>
The kernel calls this function every HZ interval.

<code>extern void platform_pcibios_init (void);</code><br>
The kernel calls this function in case PCI is enabled to allow the platform to setup the PCI bus.

<code>extern int platform_pcibios_fixup (void);</code><br>
The kernel calls this function in case PCI is enabled to allow the platform to modify PCI configuration after scanning the PCI bus has completed.

<code>extern void platform_calibrate_ccount (void);</code><br>
Platforms that can identify the processor speed should implement this function. It allows the platform to set the cpu clock frequency (if CONFIG_XTENSA_CALIBRATE is enabled). This function should determine the processor speed and set the following variables accordingly:
* <code>ccount_per_jiffy</code> - This is the number of CCOUNT ticks per <code>jiffy</code>. 'A jiffy' is the time between two ticks, where HZ describes the number of ticks per seconds.
* <code>ccount_nsec</code> - This is the time (in nano-seconds) between two subsequent CCOUNT ticks.

Platform Porting

2013-03-18T22:02:15Z

Chris: /* Adding a new Platform to the Kernel */

== Adding a new Platform to the Kernel ==

The easiest way to add support for a new platform for Xtensa is usually to look at the directories of one of the platforms already supported for Xtensa and to copy and modify those files. Drivers to support on-chip devices should go to the generic driver directory instead of the architecture directory. Adding a new platform should not require other changes to generic sources outside the platform specific directories. Modifications to the kernel are, therefore, mostly limited to the following places:

# Modify <code>arch/xtensa/Kconfig</code> and <code>arch/xtensa/Makefile</code> to add support for the new platform.
# Create a directory for the header files: <code>arch/xtensa/platforms/''name''/include</code>. It must at least contain the <code>hardware.h</code> file to describe some fundamental hardware settings.
# Create a directory with the name of the platform in the architecture part of the kernel under <code>arch/xtensa/platform/</code>. This directory should contain the source files to support hardware components other than generic devices, such as PCI host-bridges, etc.
# ''(optional)'' add a default configuration file for the platform with the name <code>''name''_defconfig</code> to <code>arch/xtensa/configs</code>.

=== Modify <code>Kconfig</code> and <code>Makefile</code> ===

Adding support for a new platform to the build system of Linux only requires to modify <code>Kconfig</code> and <code>Makefile</code>. The new entry in <code>Kconfig</code> allows the configuration scripts to pick up the new platform and the change in <code>Makefile</code> instructs the build process to enter the platform directory, if selected.

<b><code>Kconfig</code></b>

config XTENSA_PLATFORM_''NAME''
bool ''NAME''
help
''descriptive text''

<b><code>Makefile</code></b>
platform-$(CONFIG_XTENSA_PLATFORM_''NAME'') := ''directory-name''

=== Directory for the Headers ===

Any platform specific header files should go to the <code>platform-''name''</code> directory under <code>include/asm-xtensa/</code>. It should contain at least the <code>hardware.h</code> file that describes the physical memory configuration.

/*
* Memory configuration.
*/

#define PLATFORM_DEFAULT_MEM_START 0x00000000
#define PLATFORM_DEFAULT_MEM_SIZE 0x08000000

=== Directory for the new Platform ===

All source files for the new platform should be in <code>arch/xtensa/platforms/''name''</code>. The Xtensa port provides a few hooks that can be used by the platform for initialization and other purposes. These functions are defined as <code>weak</code> symbols with a default 'dummy' implementation in the generic Xtensa sources. Platforms can, therefore, overwrite the default implementation simply by defining the function in one of its sources.

<code>extern void platform_init(bp_tag_t* bootparams);</code><br>
The kernel calls this function early in the boot process prior to initializing the MMU. This allows the platform to perform early initializations of components. The argument <code>bootparams</code> is a list of configuration tags passed from the boot-loader (see also [[Boot Loader]]

<code>extern void platform_setup (char **);</code><br>
This function is called from <code>setup_arch</code> with a pointer to the command-line string.

<code>extern void platform_init_irq (void);</code><br>
This function, called from <code>init_IRQ</code>, allows platforms to initialize external interrupt controllers.

<code>extern void platform_restart (void);</code><br>
<code>extern void platform_halt (void);</code><br>
<code>extern void platform_power_off (void);</code><br>
The kernel calls one of these functions to either restart, halt, or reboot the system.

<code>extern void platform_idle (void);</code><br>
This is the ''idle'' function called whenever there is no thread or process ready.

<code>extern void platform_heartbeat (void);</code><br>
The kernel calls this function every HZ interval.

<code>extern void platform_pcibios_init (void);</code><br>
The kernel calls this function in case PCI is enabled to allow the platform to setup the PCI bus.

<code>extern int platform_pcibios_fixup (void);</code><br>
The kernel calls this function in case PCI is enabled to allow the platform to modify PCI configuration after scanning the PCI bus has completed.

<code>extern void platform_calibrate_ccount (void);</code><br>
Platforms that can identify the processor speed should implement this function. It allows the platform to set the cpu clock frequency (if CONFIG_XTENSA_CALIBRATE is enabled). This function should determine the processor speed and set the following variables accordingly:
* <code>ccount_per_jiffy</code> - This is the number of CCOUNT ticks per <code>jiffy</code>. 'A jiffy' is the time between two ticks, where HZ describes the number of ticks per seconds.
* <code>ccount_nsec</code> - This is the time (in nano-seconds) between two subsequent CCOUNT ticks.

Status of the Xtensa Port

2013-03-18T21:51:55Z

Chris:

This page provides additional information for software support for the Xtensa architecture. While most applications are written architecture independent, development tools and operating systems must be ported to a new processor architecture. Support for the Xtensa architecture has already been integrated in most Open Source software projects. Development trees that feed to the respective mainline repository and for new development can be found in local [http://git.linux-xtensa.org GIT] repositories.

=== Toolchain: Compiler (GCC) and various binary utilities (binutils) ===

All GNU toolchain tools are maintained in OpenSource and can be downloaded from the respective locations.
* Binutils: http://www.gnu.org/software/binutils/
* GCC: http://gcc.gnu.org/

Additional information to patch these sources for a specific Xtensa processor configuration can be found under [[Toolchain and Embedded Distributions]].

=== C-Libraries: GlibC and uClibc ===

Xtensa has long been part of uClibc, however, there are a lot of bug fixes pending for the next release (0.9.33.3). Support for the Native Posix Thread Library (NTPL) is under development and is expected to be part of the following release. Development for Glibc with NPTL (older thread libraries are not supported by Glibc anymore) is also current under way. A development tree can be found in the local [http://git.linux-xtensa.org GIT] repositories.
* uClibc: http://www.uclibc.org/
* GlibC: http://www.gnu.org/software/libc/

=== Debugging ===

GDB is also maintained in OpenSource and can be downloaded from http://www.gnu.org/software/gdb/. Support for other debugging tools (strace, ltrace, oprofile, etc.) has not been pushed to their respective main repositories, yet. Patches have been maintained in local buildroot repositories. More information can be found at http://www.gnu.org/software/gdb/

=== Linux kernel ===

Xtensa has been part of the official Linux kernel tree since 2.6.13, however, a lot of patches were maintained in a local stable tree for a long time, and are currently ported to the latest kernel tree. Features, such as large memory support and cache aliasing should be expected to hit the kernel in the 3.10/3.11 time frame. The latest version can be found at https://www.kernel.org/.

=== Toolchain and embedded distributions (crosstool-NG, buildroot, etc) ===

Xtensa is supported by buildroot, which can be downloaded from http://www.buildroot.net. Support for crosstool-NG has not been pushed into the official tree yet. A version can be downloaded from local [http://git.linux-xtensa.org GIT] repositories. Additional information to configure these tools for a specific Xtensa processor configuration can be found under [[Toolchain and Embedded Distributions]].
* Buildroot: http://www.buildroot.net
* Crosstool-NG: http://crosstool-ng.org/

=== Other Projects ===

The following list are additional projects that are architecture specific, or that have architecture specific components with additional information how to compile them for Xtensa.

* [[LibFFI]] - LibFFI is a library that provides an interface to execute low-level functions. It is mostly used by scripting or higher-level languages, such as Python, Dalvik, etc.

Status of the Xtensa Port

2013-03-18T21:49:12Z

Chris: /* C-Libraries: GlibC and uClibc */

This page provides additional information for software support for the Xtensa architecture. While most applications are written architecture independent, development tools and operating systems must be ported to a new processor architecture. Support for the Xtensa architecture has already been integrated in most Open Source software projects. Development trees that feed to the respective mainline repository and for new development can be found in local [http://git.linux-xtensa.org GIT] repositories.

=== Toolchain: Compiler (GCC) and various binary utilities (binutils) ===

All GNU toolchain tools are maintained in OpenSource and can be downloaded from the respective locations.
* Binutils: http://www.gnu.org/software/binutils/
* GCC: http://gcc.gnu.org/

Additional information to patch these sources for a specific Xtensa processor configuration can be found under [[Toolchain and Embedded Distributions]].

=== C-Libraries: GlibC and uClibc ===

Xtensa has long been part of uClibc, however, there are a lot of bug fixes pending for the next release (0.9.33.3). Support for the Native Posix Thread Library (NTPL) is under development and is expected to be part of the following release. Development for Glibc with NPTL (older thread libraries are not supported by Glibc anymore) is also current under way. A development tree can be found in the local [http://git.linux-xtensa.org GIT] repositories.
* http://www.uclibc.org/
* http://www.gnu.org/software/libc/

=== Debugging ===

GDB is also maintained in OpenSource and can be downloaded from http://www.gnu.org/software/gdb/. Support for other debugging tools (strace, ltrace, oprofile, etc.) has not been pushed to their respective main repositories, yet. Patches have been maintained in local buildroot repositories.

=== Linux kernel ===

Xtensa has been part of the official Linux kernel tree since 2.6.13, however, a lot of patches were maintained in a local stable tree for a long time, and are currently ported to the latest kernel tree. Features, such as large memory support and cache aliasing should be expected to hit the kernel in the 3.10/3.11 time frame. The latest version can be found at https://www.kernel.org/.

=== Toolchain and embedded distributions (crosstool-NG, buildroot, etc) ===

Xtensa is supported by buildroot, which can be downloaded from http://www.buildroot.net. Support for crosstool-NG has not been pushed into the official tree yet. A version can be downloaded from local [http://git.linux-xtensa.org GIT] repositories. Additional information to configure these tools for a specific Xtensa processor configuration can be found under [[Toolchain and Embedded Distributions]].

=== Other Projects ===

* [[LibFFI]] - LibFFI is a library that provides an interface to execute low-level functions. It is mostly used by scripting or higher-level languages, such as Python, Dalvik, etc.

Buildroot

2013-03-18T21:48:24Z

Chris:

This page describes the steps to build a toolchain and root file system for a specific processor configuration based on the latest release of Buildroot.

== Getting Buildroot and other prerequisites ==

* Buildroot
*: Download the latest release from http://buildroot.net/download.html or clone the development tree <code>git clone git://git.buildroot.net/buildroot</code>
* Xtensa overlay file
*: The overlay file includes patches for toolchain tools, such as compiler, assembler, and debugger, that are required to support a specific Xtensa processor configuration. Tensilica provides such an overlay as part of the processor download, however, it needs to be reformatted to match the specific format required by buildroot. For a script to convert the overlay file, and additional information, please go to [[Toolchain Overlay File]]. The current version of buildroot requires that the overlay file name has the format xtensa_<CORE_NAME>.tar, where CORE_NAME can be any user selected name.

== Configuring and building Buildroot ==

The first step is to configure Buildroot <code>make menuconfig</code>. Select Xtensa, and for a custom configuration, provide a core name and absolute path to the directory containing the overlay file. The overlay file name must be xtensa_<CORE_NAME>.tar, where core name can be any user selected name.

Target Architecture (Xtensa)
Target Architecture Variant (Custom Xtensa processor configuration)
(PROCESSOR_NAME) Custom Xtensa processor configuration name
(ABSOLUTE_OVERLAY_PATH) Overlay directory for custom configuration

Finally, run <code>make</code> to build the toolchain and root file system. For more information about Buildroot, please also read the documents provided by Buildroot under http://buildroot.net/docs.html.

== Build Buildroot with Crosstool-NG ==

Using the Crosstool-NG toolchain allows to build a version of a Buildroot image based on GlibC instead of uClibc. In the current version, Buildroot cannot build Crosstool-NG for Xtensa directly, but can be configured to use it as an ''external'' toolchain. The first step is to build and install Crosstool-NG, so Buildroot can use it to compile the root file system. More information to build Crosstool-NG for Xtensa can be found under [[Crosstool-NG]]. Assuming Crosstool-NG is installed in 'ABSOLUTE_PATH_TO_XTOOLS', which is typically <code>$HOME/x-tools</code>, you can make the following additional configurations changes in Buildroot:

Toolchain --->
Toolchain type (External toolchain)
Toolchain (Custom toolchain)
Toolchain origin (Pre-installed toolchain)
(ABSOLUTE_PATH_TO_XTOOLS) Toolchain path
($(ARCH)-unknown-linux-gnu) Toolchain prefix
External toolchain C library (glibc/eglibc)

Toolchain and Embedded Distributions

2013-03-17T21:01:43Z

Chris: /* [http://crosstool-ng.org/ crosstool-NG] <small>(build instructions for Xtensa)</small> */

== [[Toolchain Overlay File]] ==

Because Xtensa is a configurable and extensible processor architecture that allows to define additional registers and instructions, the toolchain is the main software component that usually needs to be adapted for a specific Xtensa processor configuration. Tensilica provides a small set of configuration files in form of an ''overlay'' that replace the versions in the toolchain sources. The [[Toolchain Overlay File]] is a version of that ''overlay'' provided by Tensilica with a specific format required for crosstool-NG and buildroot. A script to convert the ''overlay'' provided by Tensilica can be found under [[Toolchain Overlay File]]

== Start from scratch with FSF/OSS sources ==

Creating a toolchain and bootable root file system starting from sources is certainly the most challenging approach. It usually requires additional patches and sometimes matching versions of sources. While support for Xtensa is integrated in most toolchain tools, they must be patches for a specific Xtensa processor configuration. The ''overlay'' metioned above includes a necessary set of configuration files together with information explaining the process to patch the toolchain sources.

== [http://crosstool-ng.org/ crosstool-NG] <small>([[crosstool-NG|build instructions for Xtensa]])</small> ==

crosstool-NG (http://crosstool-ng.org/) provides a system to build a complete toolchain. It supports various C-libraries (Multilib, uClibc, glibc, and eglibc), but can also be used to build a 'bare' toolchain. The current version does not yet support Xtensa as a target, but a development version can be retrieved from the local [http://git.linux-xtensa.org/ GIT] repositories. The process of patching the toolchain and other architecture specific software is fully automated using the [[Toolchain Overlay File]]. More information for building a toolchain for Xtensa using crosstool-NG can be found [[crosstool-NG|here]].

== [http://www.buildroot.uclibc.org BuildRoot] <small>([[Buildroot|build instructions for Xtensa]])</small> ==

Buildroot is a set of Makefiles and patches that makes it easy to generate a cross-compilation toolchain and root file system for your target Linux system. The Xtensa architecture is fully supported in the official tree, including support for specific processor configuration using the [[Toolchain Overlay File]]. For build instructions, see [[Buildroot]].