Linux/Xtensa - User contributions [en]

Toolchain and Embedded Distributions

2017-05-16T20:39:14Z

Marc: Typo fixes

== [[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 the 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 patched for a specific Xtensa processor configuration. The ''overlay'' mentioned above includes a necessary set of configuration files together with information explaining the process to patch the toolchain sources.

'''Warning:''' cross compilers running on 64bit hosts are known to produce broken code. For some more details see the [http://lists.linux-xtensa.org/pipermail/linux-xtensa/Week-of-Mon-20130715/001140.html explanation] of Chris Zankel.

== [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. Starting with release 1.22.0 the mainline crosstool-NG repository includes support for Xtensa. 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.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]].

== [http://www.openadk.org OpenADK] ==

OpenADK 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, including support for specific processor configuration using the [[Toolchain Overlay File]]. At the moment only Qemu emulation (dc232b,dc233c) targets are available. New configurations can be simply added.

Toolchain Overlay File

2013-07-08T23:07:37Z

Marc: /* Conversion Script */ Copy xtensa-xtregs.c instead of xtensa-regmap.c to gdbserver sources

== 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]].

== 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/src/binutils/xtensa-config.h $TMPDIR/overlay/binutils/include
mv $TMPDIR/src/binutils/xtensa-modules.c $TMPDIR/overlay/binutils/bfd
mv $TMPDIR/src/gcc/xtensa-config.h $TMPDIR/overlay/gcc/include
mv $TMPDIR/src/gdb/xtensa-config.c $TMPDIR/overlay/gdb/gdb
mv $TMPDIR/src/gdb/xtensa-config.h $TMPDIR/overlay/gdb/include
mv $TMPDIR/src/gdb/xtensa-modules.c $TMPDIR/overlay/gdb/bfd
mv $TMPDIR/src/gdb/xtensa-xtregs.c $TMPDIR/overlay/gdb/gdb/gdbserver
mv $TMPDIR/src/gdb/reg-xtensa.dat $TMPDIR/overlay/gdb/gdb/regformats
tar czf xtensa-overlay.tgz -C $TMPDIR/overlay/ binutils gcc gdb
rm -fr $TMPDIR

Main Page

2012-12-08T09:40:40Z

Marc: /* <big>Welcome to the Linux/Xtensa Wiki</big> */ Wiki account creation disabled

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

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

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

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

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

Instructions for building and booting Linux

2012-06-22T23:01:29Z

Marc: /* Download buildroot and Linux kernel sources */ Simplify checkout lines

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.

Instructions for building and booting Linux

2012-06-14T19:24:32Z

Marc: /* Download buildroot and the Linux kernel */ Clarify which trees to use

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 branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
'''$ git checkout 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.

Instructions for building and booting Linux

2011-11-11T05:12:21Z

Marc: /* Download buildroot and the Linux kernel */ Fix incorrect checkout instructions.

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 the Linux kernel ==

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

Adventurous users that want to use the '''bleeding edge''' code can execute the following:

'''$ cd <workdir>'''
'''$ git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa.git buildroot''' [NOT RECOMMENDED, NEWER PACKAGES BUT DEVELOPMENT ENVIRONMENT BROKEN]
'''$ git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp.git linux'''

where <tt><workdir></tt> is the path to an empty directory on a disk with
at least 4 GB available space. You end up with the following file structure,
which is assumed by the rest of this document:

<workdir>/
/buildroot
/linux

The MASTER branch of the buildroot repository is often is a state of development.
It's recommended to use the last snapshot for application developers. In the
case of the Avnet development boards a 'snapshot_2+SMP' branch is recommended
in the currently experimental SMP git repository:

'''$ git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot.git buildroot''' [RECOMEND YOU USE THIS GIT REPO]
'''$ cd buildroot'''
'''$ git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
'''$ git checkout snapshot_2+SMP'''

If you happen to have write access to either repository you should change '''git:''' to '''git+ssh:'''
For Example:

'''$ git clone git+ssh://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot.git buildroot'''
'''$ cd buildroot'''
'''$ git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
'''$ git checkout snapshot_2+SMP'''

For more details, see the [http://wiki.linux-xtensa.org/index.php/Repository_Access repository access] page.

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

Instructions for building and booting Linux

2011-11-10T01:03:37Z

Marc: /* Download buildroot and the Linux kernel */ Add missing 'cd'

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 the Linux kernel ==

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

Adventurous users that want to use the '''bleeding edge''' code can execute the following:

'''$ cd <workdir>'''
'''$ git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa.git buildroot''' [NOT RECOMMENDED, NEWER PACKAGES BUT DEVELOPMENT ENVIRONMENT BROKEN]
'''$ git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp.git linux'''

where <tt><workdir></tt> is the path to an empty directory on a disk with
at least 4 GB available space. You end up with the following file structure,
which is assumed by the rest of this document:

<workdir>/
/buildroot
/linux

The MASTER branch of the buildroot repository is often is a state of development.
It's recommended to use the last snapshot for application developers. In the
case of the Avnet development boards a 'snapshot_2+SMP' branch is recommended
in the currently experimental SMP git repository:

'''$ git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot.git buildroot''' [RECOMEND YOU USE THIS GIT REPO]
'''$ cd buildroot'''
'''$ git branch --track snapshot_2+SMP'''
'''$ git checkout snapshot_2+SMP'''

If you happen to have write access to either repository you should change '''git:''' to '''git+ssh:'''
For Example:

'''$ git clone git+ssh://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot.git buildroot'''
'''$ cd buildroot'''
'''$ git branch --track snapshot_2+SMP'''
'''$ git checkout snapshot_2+SMP'''

For more details, see the [http://wiki.linux-xtensa.org/index.php/Repository_Access repository access] page.

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

SMP-on-Xtensa

2010-05-06T20:43:32Z

Marc: Tidbit of info

Here's a [http://www.linux-xtensa.org/info/smp-interrupt-distrib.pdf diagram] of the interrupt distributor module, used by the initial Xtensa arch port of SMP Linux.

Evaluation Platforms

2010-05-06T20:25:27Z

Marc: /* SMP HiFi 2 Development Board */ Link to minimal SMP info

[[image:board.jpg|right]]
= Evaluation and Prototyping Platforms =

The following boards and simulators can be used for evaluation and prototyping purposes. Evaluation platforms generally fall into one of the following categories:
* instruction set simulators,
* emulation systems that use FPGAs to implement any Xtensa or Diamond core (within the capacity of the FPGAs), and
* boards that integrate a specific configured Xtensa or Diamond core(s) into an ASIC.
Field programmable gate arrays (FPGA) contain programmable logic that can be re-configured to emulate complex logic. Although slower than the dedicated circuitry of an ASIC (application specific integrated circuit), their re-configurability and practically zero NRE make them very useful for prototyping (for example, trying multiple Xtensa processor variants or configurations) or small volume applications.

== Instruction Set Simulator ==

Instruction Set Simulators (ISS) mimic the behavior of processors by simulating instructions, memory interface, and other I/O components. This allows developers to run and test their software long before real hardware becomes available. Functional simulators provide the best performance, whereas cycle-accurate simulators provide timing accuracy compatible to that of real hardware. The latter simulate the processor pipeline and external components synchronized to a virtual clock. Although this overhead reduces their performance, it can provide vital information to improve the implementation of algorithms.

=== Tensilica ISS ===

[http://www.tensilica.com/ Tensilica] offers a commercial functional simulator (TurboXim) and cycle-accurate simulator for the Xtensa processor architecture, as part of their standard software development tools. (You may be able to try a free limited time evaluation copy of this toolset.) Tensilica also offers XTMP and XTSC for modeling systems of one or multiple processors alongside custom functional or cycle-accurate software models for other components. Please visit [http://www.tensilica.com/ Tensilica's] website for further information.

The standalone simulator (xt-iss), for example, simply takes an ELF file as its argument and starts simulating instructions from the reset vector. The option <code>--turbo</code> invokes the (much faster) functional simulator TurboXim.

xt-iss ''[--turbo]'' Image.elf

== Emulation Platforms and Systems ==

=== Avnet Virtex-4 LX60 and LX200 ===

[http://www.em.avnet.com Avnet] offers the following development platforms for the Xilinx Virtex-4 LX FPGA that can emulate various
Xtensa processor configurations. The [http://www.em.avnet.com/tensilica1 LX60] is based on the Xilinx 4VLX60 and comes
with a 10/100 Ethernet PHY, DDR memory, flash memory, serial port, and 2 x 16 character LCD panel. The MAC controller, however, needs to be implemented inside the FPGA. MAC controllers are available from different vendors. [http://opencores.org OpenCores], for example, provides a free Ethernet controller supported by Linux and other operating systems. The [http://www.em.avnet.com/tensilica2 LX200] is based on the Xilinx XC4VLX200 and can emulate more complex processor configurations and extensions (for example the [http://www.tensilica.com/products/hifi_audio.htm HiFi 2 Audio Engine]) and provides the same components as the LX60 except for the LCD panel.

[http://www.tensilica.com Tensilica] provides a bitstream that describes the configuration data to emulate the Diamond Standard DC232L processor (Rev.B) on the LX60 FPGA. Tensilica refers to this board and bitstream combination as the XTAV60 board. It also includes support for the OpenCores Ethernet MAC. For further information, please, contact [http://www.tensilica.com/company/contact_us.htm Tensilica] directly.

=== SMP HiFi 2 Development Board ===
Some info is available here on an [[SMP HiFi 2 Development Board]] based on the LX200 board from Tensilica, running [[SMP-on-Xtensa|SMP]] Linux.
It has three custom Xtensa [http://www.tensilica.com/products/hifi_audio.htm HiFi 2] cores with coherent shared memory, shared and interprocessor interrupts, and the standard LX200 I/O.
Runs a V2009.8 release of [http://git.linux-xtensa.org/cgi-bin/git.cgi?p=u-boot/u-boot-xtensa.git;a=summary U-boot]. The board boots a [http://git.linux-xtensa.org/cgi-bin/git.cgi?p=kernel/xtensa-2.6.29-smp.git;a=summary 2.6.29 SMP Linux kernel] and runs a
snapshot of [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions buildroot] preconfigured with a C development environment, and the [http://www.tensilica.com/products/literature-docs/application-notes/audio-application-notes/using-tensilica-hifi2-codecs-on-xtensa-linux-with-mplayer.htm Mplayer] media player.

=== A2000 Prototype and Development Board ===
For development a small amount of pre-release, and currently PRIVATE, info is temporally available here on an [[Transwitch A2000 Development Board]] based on the A2000 board from [http://www.transwitch.com/ Transwitch],
currently running 2.6.29-SMP Linux.
The [http://www.transwitch.com/products/product/page.jsp?product=190 Atlanta 2000] chip has two super-scalar 400Mhz LX2 Xtensa cores, each with a MMU supporting large caches, PCI, DMA, and quite a few specialized DSP processors for doing Telecommunication.
The board runs Version 1.4 of [http://git.linux-xtensa.org/cgi-bin/git.cgi?p=u-boot/u-boot-xtensa.git;a=summary U-boot] which boots a [http://git.linux-xtensa.org/cgi-bin/git.cgi?p=kernel/xtensa-2.6.29-smp.git;a=summary 2.6.29 SMP Linux kernel] that runs a
snapshot of [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions buildroot] preconfigured with a C development environment or a production snapshot for running out of flash.

=== Eve ZeBu ===

[http://www.eve-team.com Eve] offers an emulation and verification system that can be used to emulate Xtensa processors. Similar to FPGA boards, the ZeBu system emulates the processor, but has a higher capacity to emulate larger processor configurations and additional peripherals. It also provides direct access to signals for debugging and verification.

See the [[Linux on ZeBu]] page or contact [http://www.eve-team.com Eve] directly to request additional information.

== ASIC Evaluation Platforms ==

=== Stretch S55DVKxx and S56DVKxx ===

[http://www.stretchinc.com Stretch] provides software-configurable processors based on the Xtensa architecture. The S5000 processor supports Linux, and at 300MHz, it runs 5-10 times faster than FPGA based emulation platforms. The S55DVKxx and S56DVKxx development platforms provide 10/100/1000 Ethernet, serial, PCI (only S56DVKxx), and other interfaces.

The Stretch platforms come with RedBoot as the bootloader. It can download and boot the kernel over network using TFTP or from flash. Make sure that RedBoot is configured with a valid Ethernet address or set to DHCP to obtain a valid address. The following commands load the kernel image ''zImage.redboot'' and boot the kernel:

RedBoot> load -r -b 0xd0200000 -h 192.168.1.5 zImage.redboot
RedBoot> exec 0xd0200000

Note that RedBoot requires that the tftp host is in the same subnet as the board.

Evaluation Platforms

2010-03-24T06:12:43Z

Marc: /* SMP HiFi 2 Development Board */ Update link

[[image:board.jpg|right]]
= Evaluation and Prototyping Platforms =

The following boards and simulators can be used for evaluation and prototyping purposes. Evaluation platforms generally fall into one of the following categories:
* instruction set simulators,
* emulation systems that use FPGAs to implement any Xtensa or Diamond core (within the capacity of the FPGAs), and
* boards that integrate a specific configured Xtensa or Diamond core(s) into an ASIC.
Field programmable gate arrays (FPGA) contain programmable logic that can be re-configured to emulate complex logic. Although slower than the dedicated circuitry of an ASIC (application specific integrated circuit), their re-configurability and practically zero NRE make them very useful for prototyping (for example, trying multiple Xtensa processor variants or configurations) or small volume applications.

== Instruction Set Simulator ==

Instruction Set Simulators (ISS) mimic the behavior of processors by simulating instructions, memory interface, and other I/O components. This allows developers to run and test their software long before real hardware becomes available. Functional simulators provide the best performance, whereas cycle-accurate simulators provide timing accuracy compatible to that of real hardware. The latter simulate the processor pipeline and external components synchronized to a virtual clock. Although this overhead reduces their performance, it can provide vital information to improve the implementation of algorithms.

=== Tensilica ISS ===

[http://www.tensilica.com/ Tensilica] offers a commercial functional simulator (TurboXim) and cycle-accurate simulator for the Xtensa processor architecture, as part of their standard software development tools. (You may be able to try a free limited time evaluation copy of this toolset.) Tensilica also offers XTMP and XTSC for modeling systems of one or multiple processors alongside custom functional or cycle-accurate software models for other components. Please visit [http://www.tensilica.com/ Tensilica's] website for further information.

The standalone simulator (xt-iss), for example, simply takes an ELF file as its argument and starts simulating instructions from the reset vector. The option <code>--turbo</code> invokes the (much faster) functional simulator TurboXim.

xt-iss ''[--turbo]'' Image.elf

== Emulation Platforms and Systems ==

=== Avnet Virtex-4 LX60 and LX200 ===

[http://www.em.avnet.com Avnet] offers the following development platforms for the Xilinx Virtex-4 LX FPGA that can emulate various
Xtensa processor configurations. The [http://www.em.avnet.com/tensilica1 LX60] is based on the Xilinx 4VLX60 and comes
with a 10/100 Ethernet PHY, DDR memory, flash memory, serial port, and 2 x 16 character LCD panel. The MAC controller, however, needs to be implemented inside the FPGA. MAC controllers are available from different vendors. [http://opencores.org OpenCores], for example, provides a free Ethernet controller supported by Linux and other operating systems. The [http://www.em.avnet.com/tensilica2 LX200] is based on the Xilinx XC4VLX200 and can emulate more complex processor configurations and extensions (for example the [http://www.tensilica.com/products/hifi_audio.htm HiFi 2 Audio Engine]) and provides the same components as the LX60 except for the LCD panel.

[http://www.tensilica.com Tensilica] provides a bitstream that describes the configuration data to emulate the Diamond Standard DC232L processor (Rev.B) on the LX60 FPGA. Tensilica refers to this board and bitstream combination as the XTAV60 board. It also includes support for the OpenCores Ethernet MAC. For further information, please, contact [http://www.tensilica.com/company/contact_us.htm Tensilica] directly.

=== SMP HiFi 2 Development Board ===
Some info is available on an [[SMP HiFi 2 Development Board]] based on the LX200 board from Tensilica, running SMP Linux.
It has three custom Xtensa [http://www.tensilica.com/products/hifi_audio.htm HiFi 2] cores with coherent shared memory, shared and interprocessor interrupts, and the standard LX200 I/O.
Runs a V2009.8 release of [http://git.linux-xtensa.org/cgi-bin/git.cgi?p=u-boot/u-boot-xtensa.git;a=summary U-boot]. The board boots a [http://git.linux-xtensa.org/cgi-bin/git.cgi?p=kernel/xtensa-2.6.29-smp.git;a=summary 2.6.29 SMP Linux kernel] and runs a
snapshot of [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions buildroot] preconfigured with a C development environment, and the [http://www.tensilica.com/products/literature-docs/application-notes/audio-application-notes/using-tensilica-hifi2-codecs-on-xtensa-linux-with-mplayer.htm Mplayer] media player.

=== Eve ZeBu ===

[http://www.eve-team.com Eve] offers an emulation and verification system that can be used to emulate Xtensa processors. Similar to FPGA boards, the ZeBu system emulates the processor, but has a higher capacity to emulate larger processor configurations and additional peripherals. It also provides direct access to signals for debugging and verification.

See the [[Linux on ZeBu]] page or contact [http://www.eve-team.com Eve] directly to request additional information.

== ASIC Evaluation Platforms ==

=== Stretch S55DVKxx and S56DVKxx ===

[http://www.stretchinc.com Stretch] provides software-configurable processors based on the Xtensa architecture. The S5000 processor supports Linux, and at 300MHz, it runs 5-10 times faster than FPGA based emulation platforms. The S55DVKxx and S56DVKxx development platforms provide 10/100/1000 Ethernet, serial, PCI (only S56DVKxx), and other interfaces.

The Stretch platforms come with RedBoot as the bootloader. It can download and boot the kernel over network using TFTP or from flash. Make sure that RedBoot is configured with a valid Ethernet address or set to DHCP to obtain a valid address. The following commands load the kernel image ''zImage.redboot'' and boot the kernel:

RedBoot> load -r -b 0xd0200000 -h 192.168.1.5 zImage.redboot
RedBoot> exec 0xd0200000

Note that RedBoot requires that the tftp host is in the same subnet as the board.

SMP HiFi 2 Development Board

2009-12-02T08:37:55Z

Marc: /* Regular Use */

This is a "community" guide for how to use the LX200 board based 3-core SMP HiFi-2 Development environment.
If something doesn't work or isn't covered in this guide, please feel free to ask at the [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List].

<div style="margin:0; margin-top:10px; margin-right:10px; border:1px solid #dfdfdf; padding:0 1em 1em 1em; background-color:#ffffcc; align:right; ">
'''NEWS:'''

Some general notes on these instructions:

* They are a work in progress.

* The following was tested on x86 machines running RedHat Fedora Core 5.

* Buildroot build with Fedora Core 9 also seems to be fine; perhaps better than when built on Fedore Core 5.

</div>

== Introduction ==

This document is addressed to someone who received an LX200 board setup by Tensilica
for HiFi2 development.

This document goes over the steps needed to set up the LX200 board for HiFi2 development.
To summarize:
* Setup the board. It likely comes with U-boot preinstalled, ready to boot a linux kernel.
* Install '''git'''.
* Download buildroot and linux kernel trees, pre-configured and built for HiFi-2 development.
* Setup a TFTP server to provide the linux kernel to U-Boot.
* Setup an NFS server to export a linux root file system.
* Setup the Linux kernel to boot from the root file system provided by the NFS server.
Once the development board is up and running, this document:
* Suggests a possible way to tailor the board for easy codec development.
* Shows how to add the Tensilica provided codec packages to the Mplayer packages used by Buildroot, including building and installing.
* Demonstrates two procedures for compiling, linking, and debugging codecs.

All development is expected to be done on a Linux host. (One can in principle use Windows to
develop target libraries. However, linking and subsequent steps need to be done in Linux.)

== Downloading the Latest HiFi-2 Buildroot and Kernel Snapshots ==

The HiFi-2 development environment is maintained in a source code version control system named 'git'. The '''git''' tools are useful when working with this development environment, though they are not strictly necessary. This document generally assumes the use of '''git''', which provides more opportunities for modifying this environment as needed (e.g. building more optional buildroot packages). But points out alternatives to allow getting up and running without having to set it up.

=== Installing git ===

To install '''git''', download a recent tarball from the [http://www.kernel.org/pub/software/scm/git/ official site]. For example, <tt>cd</tt> to a location with enough disk space, and do:

$ '''wget http://www.kernel.org/pub/software/scm/git/git-1.6.5.tar.gz'''

Unpack the tarball, and make and install it. Here we show how to install it to your ~/bin directory:

$ '''gunzip git-1.6.5.tar.gz'''
$ '''tar xf git-1.6.5.tar'''
$ '''cd git-1.6.5'''
$ '''make'''
$ '''make install'''

The git makefile can be instructed to install '''git''' to <tt>/usr/local/bin</tt> as root for system wide access:

$ '''cp git-1.6.5.tar.gz''' /tmp
$ '''su'''
Password:
# '''cd /usr/local/src/'''
# '''mkdir git'''
# '''cd git'''
# '''cp /tmp/git-1.6.5.tar.gz .'''
# '''gunzip git-1.6.5.tar.gz'''
# '''tar xf git-1.6.5.tar'''
# '''cd git-1.6.5'''
# '''make prefix=/usr/local'''
# '''make install'''

See the '''INSTALL'' instruction at the top of the git src directory for details.

Using '''git''' provides easy access to the binaries used to bring up the codec development environment, and leaves in place the infrastructure to modify and build this environment should you wish to. Any changes to '''git'''-managed source trees are easily observed with the '''git''' tools.

=== Installing the Buildroot Snapshot ===

''Note: The HiFi-2 snapshot is in the process of being made.''

To install the buildroot environment (toolchain and root filesystem), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot'''
$ '''cd buildroot-xtensa-HiFi2-Snapshot'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP''' [56 key strokes]
$ '''git checkout snapshot_2+SMP''' [28 key strokes]

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).

You can examine the tree (git repository) and its history visually using <tt>git gui</tt>.
The git GUI is a faster and more convenient method for checking out the HiFi-2 snapshot. To check out the snapshot_2+SMP branch simply run the command 'git gui' and then pull down the branch->create menu. Next select <>Match Tracking Branch Name and click on ''origin/snapshot_2+SMP''. Finally hit the Create Button.

$ '''git gui''''' [8 key strokes]
[Branch] -> Create... [2 key strokes]
<> Match Tracking Branch Name [1 key stroke]
<> Tracking Branch [1 key stroke]
origin/snapshot_2+SMP [1 key stroke]
[Create] [1 key stroke]
[Reposirory]--> Quit [2 key strokes]

If there are issues installing '''git''', as a last resort, an alternative is ftp (may not always get updated, is currenty our of date, waste disk space, so may be dropped at some point):

http://www.linux-xtensa.org/pub/snapshots/buildroot-xtensa-smp.2-Nov-2009.tar.gz

=== Installing the Linux Kernel Snapshot ===

To install the Linux kernel environment (kernel src, config, and HiFi-2 kernel U-Boot image), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp'''
$ '''cd kernel/xtensa-2.6.29-smp'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
$ '''git checkout snapshot_2+SMP'''

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).
As in the build root case, you can also do it from via git gui using the same proceedure
mantioned above.

Now, assuming we are still in the kernel '''xtensa-2.6.29-smp''' directory
copy the kernel U-Boot Image ('''uImage''') to the tftp directory; Ex:

$ '''cp arch/xtensa/boot/uImage /tftpboot/uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'''

NOTE: On some system, like Fedora Core 9, the tftpboot directory has been moved to /var/lib/tftpboot.
In this case we recomend that you just added a symbolic pointer from /etc to /var/lib/tftpboot:

$ '''su'''
# '''cd /etc'''
# '''/var/lib/tftpboot/ tftpboot'''
# '''ls -ld tftpboot'''
lrwxrwxrwx 1 root root 18 2009-11-23 21:14 tftpboot -> /var/lib/tftpboot/
#

== Setting up a TFTP Server to provide the Linux kernel to U-Boot ==

The TFTP service is part of the xinetd and is installed on Fedora workstations.
You can see that it's installed with the check config command which manages the
/etc/rc.d/init.d startup scripts and with the yum search command:

$ '''chkconfig --list'''
NetworkManager 0:off 1:off 2:off 3:off 4:off 5:off 6:off
NetworkManagerDispatcher 0:off 1:off 2:off 3:off 4:off 5:off 6:off
acpid 0:off 1:off 2:off 3:on 4:on 5:on 6:off
.
.
.
xfs 0:off 1:off 2:on 3:on 4:on 5:on 6:off
xinetd 0:off 1:off 2:off 3:on 4:on 5:on 6:off
ypbind 0:off 1:off 2:off 3:on 4:on 5:on 6:off
yum 0:off 1:off 2:off 3:off 4:off 5:off 6:off

xinetd based services:
amanda: off
auth: off
.
.
.
rsync: off
'''tftp: on''' [NOTE that tftp is enabled]
time: off
time-udp: off
uucp: off
$
$
$
$ '''yum search tftp-server'''
Loading "installonlyn" plugin
Searching Packages:
.
.
.
Reading repository metadata in from local files
.
.
.
'''tftp-server.i386 0.41-1.2.1 installed''' [NOTE that tftp server is installed as part of the inet daemon]
Matched from:
tftp-server
The Trivial File Transfer Protocol (TFTP) is normally used only for
booting diskless workstations. The tftp-server package provides the
server for TFTP, which allows users to transfer files to and from a
remote machine. TFTP provides very little security, and should not be
enabled unless it is expressly needed. The TFTP server is run from
/etc/xinetd.d/tftp, and is disabled by default on Red Hat Linux systems.
[piet@pdelaney_fc5 ~]$

TFTP is not normally enabled, to enable it just edit the file /etc/xinetd.d/tftp
and change the disable field to no:

# default: off
# description: The tftp server serves files using the trivial file transfer \
# protocol. The tftp protocol is often used to boot diskless \
# workstations, download configuration files to network-aware printers, \
# and to start the installation process for some operating systems.
service tftp
{
socket_type = dgram
protocol = udp
wait = yes
user = root
server = /usr/sbin/in.tftpd [NOTE: /var/lib/tftpboot on Fedora Core 9]
server_args = -s /tftpboot
'''disable = no'''
per_source = 11
cps = 100 2
flags = IPv4
}

== Setting up an NFS Server to export the Root Filesystem ==

The LX200 board running Linux needs to mount its root filesystem over NFS.
This filesystem was built using buildroot into a cpio format file,
and left in:

buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2/rootfs.xtensa_test_mmuhifi_c3.cpio

We will also be adding an additional minor changes to make your development environment more comfortable.

Pick a place on your workstation to export your root and unpack the cpio file into that directory.
For example here we will set up an export in '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''':

$ '''cd buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2'''
$ '''WHERE=$PWD'''
$ '''mkdir -p /exports/LINUX_ROOT.HiFi-2'''
$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''cpio -i < $WHERE/rootfs.xtensa_test_mmuhifi_c3.cpio'''

Next add a line to /etc/exports:

/exports *(rw,no_root_squash,sync,no_wdelay)

and restart you nfs services:

$ '''/etc/rc.d/init.d/nfs restart'''
or
$ '''/sbin/chkconfig nfs on'''

The showmount command should show your NFS file system now being exported:

$ '''showmount -e'''
Export list for mypc.foobar.com:
/exports *
$

== Configuring U-Boot to Boot Linux ==

Your LX200 board should have arrived with U-Boot installed in the flash ready to use.
The board has a DIP switch (next to the power on/off switch) that provides the 6 LSBs
of the Ethernet MAC, in switch positions 1 thru 6.

DIP Swithes for MAC: 1 2 3 4 5 6 7 8 ethaddr=00:50:C2:13:6f:0a
Little Endian: 0 1 0 1 0 0 * *
^
|
+------ Enables booting U-Boot from Flash

DIP switch 8 should be shipped in the ON position to enable U-Boot booting from flash.
See Sections 4.2.3 and 4.2.4 of the '''Tensilica Avnet (XT-AV200) Board User's Guide'''
for details. Make sure to select a unique MAC address for you board.

Next, connect a serial interface to a text based terminal emulation program,
set to 38400 bps, no parity, 1 stop bit, no handshaking.
For an example of setting [http://en.wikipedia.org/wiki/Minicom minicom]
for this, see [[minicom_xtboard_setup|here]].

Here's how to configure U-Boot to automatically boot the Linux kernel on power-up (using the root file system exported over NFS as described further above).

U-Boot> '''setenv serverip 192.168.11.55''' [TFTP server IP Address: RTOS-LAB2]
U-Boot> '''setenv nfsroot_server 192.168.11.55''' [Root NFS Servers IP Address: My Workstation]
U-Boot> '''setenv ipaddr 192.168.11.155''' [HOST IP address]
U-Boot> '''setenv bootfile uImage.xtensa-2.6.29-smp.test_mmuhifi_c3''' [File to fetch with TFTP and pass to bootm]
U-Boot> '''setenv root-path /exports/LINUX_ROOT.HiFi-2''' [WARNING: Limit path to < 50 characters]
U-Boot> '''setenv bootargs_using_bootp console=ttyS0,38400 ip=bootp root=nfs coredump_filter=0xff''' [Args passed to Linux while booting with BOOTP proto]
U-boot> '''setenv bootargs console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=${nfsroot_server}:${root-path}''' [Args passed to Linux while booting with DHCP proto]
U-boot> '''setenv bootcmd tftpboot\; bootm''' [Boot Linux after fetching it with TFTP]
U-Boot> '''setenv bootdelay 20''' [Delay 20 seconds before booting automaticaly]
U-Boot> '''setenv autostart yes''' [Boot automatically on power-up/reset]
U-Boot> '''saveenv'''
U-Boot>

'''[REMIND: Update the above procedure, show two or thee approaches (ip, dhcp, bootp)]'''

== Tailoring your system prior to Booting ==

There are a few tweaks that developers have found convenient to add to the the root file-system before booting.
As an initial environment for developing we suggest mounting a /home/default files-system that has number of
files useful for getting started. Find another place to tar in the tar ball with the default users file system.
We chose to include this close to the cpio file with the root file-system. Copy the tar bar to where you are
exporting you root file-system and next to it add the 'default' users file-system:

$ '''cd /export'''
$ '''cp /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.10/binaries/default.tar .'''
$ '''tar xf default.tar'''
$ '''cd default'''
$ '''ls'''
[TO BE ADDED]

Notice a file tar ball called '''saved_files.tar'''. This ia a tar file of files that
developers have found convenient to add and replace on the root file system after
adding a new buildroot file system. Here is a list of the files and a brief
explanation on why it's convenient to add or replace them:

root/.bash_profile [added 'ulimit -c unlimited to allow core dumps to be created]
root/.bashrc
etc/profile [added 'ulimit -c unlimited to allow core dumps to be created]
etc/fstab [Tells the system how to mount extra NFS file systems like /home/default]
etc/init.d/S90local [Mounts /home/default]
etc/resolv.conf [Location of DNS servers when your not using DHCP to boot the kernel]
etc/TZ [Your time zone, currently set to California TZ]
etc/dropbear/dropbear_rsa_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/dropbear/dropbear_dss_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/ssh_config [Typically tailored with things like allowing root logins via ssh]
etc/ssh_host_dsa_key [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_dsa_key.pub [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_key
etc/ssh_host_key.pub
etc/ssh_host_rsa_key
etc/ssh_host_rsa_key.pub
etc/sshd_config [Typically tailored with things like allowing root logins via ssh]
etc/rndc.key
etc/random-seed [Generated during 1st boot]
etc/passwd [Changed default user's shell to bash]
etc/shadow [Changed default and root users login password to 'linux1', need to ssh to the board]
exports/ [The path to where the board can mount extra file systems like /home/default.
fac/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]
fac/vol6/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]

Now lets assume your going to stay with these changes and modify them after taring in these changes.
Here we add the tar ball files to the boards root filesystem.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''tar xf /exports/default/'''

This is a good time to edit a few files on the boards file system
before boot it.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''vi etc/fstab''' [Change fstab entry for /home/default and others to your taste]
$ '''vi etc/init.d/S90local''' [You might want to disable mounting of NFS file systems on the 1st Boot and add this once you try it manually]

== Booting Linux for the 1st Time ==

We should now be ready to boot linux on your LX200. You have exported the root file-system and made the
kernel available to a TFTP server. Now let's start with hitting the reset button on the LX200 and it should
auto-boot the kernel, resulting in output such as [[HiFi2_Board_Example_Linux_Boot_Log|this example log]].

== Tailoring your system prior to developing for HiFi 2 ==

To make your experience more pleasant we suggest you tailor your environment.
Here are some of the changes that we have found helpful:

1. Add a root password to that you can login with ssh.
2. Run rdate with an ntp server on booting.
3. Add NFS mounts to /etc/fstab for your code and buildroot code.
4. Copy in previous ssh server encryption keys to /etc/dropbear to speed up your initial boot.
5. Mount a 'default' user home directory with:
a. Linux Test Suite pre-patch to test the system
b. Audio test example files
c. Copies of Mplayer and its Plug-ins from Buildroot modified slightly to make installation easy.
d. Misc audio test programs.

[TO BE DONE - Where to get 'default' user home directory tar ball and 1st boot patch]

== Building Linux Applications ==

=== Building Linux Applications Using GCC on the Host ===

You can use the open source toolchain included in the buildroot tree.

Given the location of the buildroot tree and the name of the core:

$ setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12
$ setenv CORENAME test_mmuhifi_c3

You can either set the PATH and invoke tools prefixed with <tt>xtensa_${CORENAME}-linux-</tt> :

$ setenv PATH ${BUILDROOT_DIR}/build_xtensa_${CORENAME}/staging_dir/usr/bin:${PATH}
$ xtensa_test_mmuhifi_c3-linux-gcc -g hello.c -o hello
$ xtensa_test_mmuhifi_c3-linux-gdb hello

or alternatively invoke the tools with absolute paths:

$ ${BUILDROOT_DIR}/build_xtensa_test_mmuhifi_c3/staging_dir/usr/bin/xtensa_test_mmuhifi_c3-linux-gcc -g hello.c -o hello
$ ${BUILDROOT_DIR}/build_xtensa_test_mmuhifi_c3/staging_dir/usr/bin/xtensa_test_mmuhifi_c3-linux-gdb hello

=== Building Linux Applications Using GCC on the Target ===
This is the simplest. (Much slower of course at 45 MHz across a slow Ethernet link than on a workstation,
but convenient.) Just login to the target system and use the native <tt>cc</tt>.

=== Building Linux Applications Using XCC (Xtensa Tools) ===

There are two approaches to compiling with Tensilica's XCC compiler (part of Xtensa Tools).
The normal one, described below, is to initially setup a virtual core
that has built-in references to the library and include files for the target Linux system.
Alternatively, one could skip this initial setup and just use Xtensa Tools to create
object files and link them using host or target GCC tools.
However, such objects must be built without dependencies on such things as the C library,
which can be harder than it sounds (for example, flags and structures, such as <tt>open()</tt>'s <tt>O_EXCL</tt>
and <tt>stat()</tt>'s <tt>struct stat</tt>, must be avoided because their definitions likely differ between the
Xtensa Tools' default C library and the Linux uClibc library).
''('''Note''': Codecs such as MP3 and AAC are typically written in C with TIE extensions and can only be compiled with XCC.)''

Section 4.3 of the latest ''Xtensa OSKit Guide'' (from Tensilica's
RC-2009.0 release) describes how to setup XCC to compile Linux applications.
For full details, see the guide. A summary follows.

==== Initial Setup ====

The XTENSA_TOOLS_ROOT, XTENSA_ROOT, BUILDROOT_DIR, and TARGET_SYSROOT
environment variables must be set according to where things were installed;
values shown here are for illustration only. The CORENAME variable, set correctly
below for this board, reflects
the name of the core as known to open source tools (as opposed to XTENSA_CORE
which is the core name as known to Xtensa Tools; both happen to match here).

$ setenv USER someuser
$ setenv XTENSA_ROOT /home/${USER}/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
$ setenv XTENSA_TOOLS_ROOT /home/${USER}/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools
$ setenv TARGET_SYSROOT /exports/LINUX_ROOT.HiFi-2
$ setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12

$ setenv CORENAME test_mmuhifi_c3

$ cd ${BUILDROOT_DIR}
$ ${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install \
--sysroot=./build_xtensa_${CORENAME}/staging_dir \
--linux-gcc=./build_xtensa_${CORENAME}/staging_dir/usr/bin/xtensa_${CORENAME}-linux-gcc

==== Regular Use ====

Assuming the above completed successfully, you can now build applications using Xtensa Tools. First set the usual environment variables (assuming values of XTENSA_ROOT and XTENSA_TOOLS_ROOT used earlier):

$ setenv XTENSA_CORE default
$ setenv XTENSA_SYSTEM ${XTENSA_ROOT}-linux/config
$ setenv PATH ${XTENSA_TOOLS_ROOT}/bin:${PATH}

Now you can use Xtensa Tools to assemble, compile, and link applications for the Linux target specified during setup. For example:

$ echo '#include <stdio.h>' > hello.c
$ echo 'int main() {printf("Hello!\\n");return 0;}' >> hello.c
$ xt-xcc -g hello.c -o hello

Then copy it where the target can see it:

$ cp hello ${TARGET_SYSROOT}/root

And run it on the target:

[root@hifi ~]# /root/hello
Hello!
[root@hifi ~]#

Here's a more interesting example that uses Tensilica TIE features.
(This cannot be compiled using GCC.)

$ cd ${TARGET_SYSROOT}/home/default/Audio_Tests
$ xt-xcc -g hifitest.c -o hifitest

In a ssh termulator window on the board you can now run hifitest:

[root@hifi ~]# '''cd /home/default/Audio_Tests/'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:23178; Eatting cpu; time:0 '''<control-C>'''

[root@hifi Audio_Tests]#

Here is the source code for the [[hifitest.c|hifitest.c source file]] used above.

=== Limited (No Setup) Use of Xtensa Tools for Linux Targets ===

Below we illustrate compiling a simple audio test program on a workstation.
We start by referring to the XTENSA tools build by Xplorer, putting XCC into our search path and set the standard XTENSA_* environment variables.
For example:

setenv XTENSA_CORE test_mmuhifi_c3
setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config
setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin

setenv PATH ${XTENSA_TOOLS}:${PATH}

[piet@fc9desktop Tests] $ '''cd /exports/default/Audio_Tests''' [NOTE: This is being done on a Workstation]
[piet@fc9desktop Audio_Tests]$ '''xt-xcc -g3 -O0 -fPIC -c hifitest.c'''

Next we link the object on the LX200 board and run gdb on the TIE enhanced code:

[root@hifi Audio_Tests]# '''gcc -g hifitest.o -o hifitest'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:4640; Eatting cpu; time:0
cnt:0x0, pid:4640; Eating Tie; time:7
^C
[root@hifi Audio_Tests]# '''gdb ./hifitest''' [NOTE: This is being done on the LX200 board]
GNU gdb 6.6
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "xtensa_test_mmuhifi_c3-linux-uclibc"...
Using host libthread_db library "/lib/libthread_db.so.1".
(gdb) '''break main'''
Breakpoint 1 at 0x400401: file /exports/default/Audio_Tests/hifitest.c, line 20.
(gdb) '''run'''
Starting program: /home/default/Audio_Tests/hifitest

Breakpoint 1, main (argc=1, argv=0x3fb3fab4)
at /exports/default/Audio_Tests/hifitest.c:20
20 time_t time0 = time(NULL);
(gdb) '''step'''
21 time_t time1 = time(NULL);

== Compiling Generic GPL Packages ==

For your development you may want to add a few GPL packages that you find helpful.
This can be done on the LX200 just as you would on a normal workstation, though
much slower. For example here we configure and build a few common GPL packages:

[[Building the Strace Package]]

[[Building the vim Package]]

== Compiling the Mplayer Plugins and linking them with MPEG-1 Audio Layer 3 (MP3) and MPEG-4 AAC Codecs ==

Mplayer is provided as an example environment for developing and testing Codecs and HiFi 2 software. There
are two ways to build Mplayer and the plug-in modules that use the codecs. The buildroot
tree (pulled with git) has a copy of mplayer and the plugins that can be built in the
snapshot via 'make menuconfig'. This is a good environment to use once codecs are
developed and debugged.

To facilitate development the mplayer packages can be copied to your NFS mounted development
environment. From there you can just configure mplayer to compile on the board and debug
mplayer and your codecs with gdb locally.

In the default user home directory we have a directory /home/default/buildroot_mplayer_stuff
with a copy of three of the mplayer packages:

[root@hifi buildroot_mplayer_stuff]# '''ls -l'''
drwxr-xr-x 34 root root 4096 Nov 10 05:01 MPlayer-1.0rc2/
drwxr-xr-x 4 root root 4096 Nov 10 01:36 mplayer_hifi2_aacplus_v2_plugin/
drwxr-xr-x 3 root root 4096 Nov 10 00:57 mplayer_hifi2_mp3_plugin/

they were simply copied from the buildroot-xtensa-HiFi2-Snapshot.2/package directory.

To get your development environment ready to compile the mplayer plug-ins you need
to configure Mplayer to use the local C compiler and linker:

# '''cd /home/default/buildroot_mplayer_stuff/MPlayer-1.0rc2/'''
# '''CFLAGS="-g3" ./configure'''

This will take about 15 minutes to configure. After that you can build the
plugins or mplayer. If you want to recompile mplayer it's likely best/necessary
to use the same args to .configure as used by buildroot:

.CFLAGS="-g3" ./configure \
--prefix=/usr \
--confdir=/etc/mplayer \
--with-extraincdir=/usr/include \
--with-extralibdir=/lib \
--disable-gui \
--enable-mad \
--enable-fbdev \
--disable-mencoder \
--disable-dvdnav \
--disable-dvdread \
--disable-dvdread-internal \
--disable-libdvdcss-internal \
--disable-big-endian \
--disable-nemesi \
--disable-tv \
--enable-dynamic-plugins

We are currently able to compile most of mplayer on the LX200 but
due to space limitations it's not possible to compile it -O0.

Now, let's focus on compiling linking the plugins. They are a nice
example of compiling an audio application on the LX200.

We modified the Makefile of the codes slightly, and will make it available.
These additions just instruct make how to install the plugins as explained
in the Chapter 7 of the Linux HiFi application note.

For example the mp3 plugin has this addition:

target_install::
-mkdir /etc/mplayer
cp codecs.conf /etc/mplayer
-mkdir /usr/lib/mplayer
cp ad_xa_mp3_dec.so /usr/lib/mplayer/
cp xa_mp3_dec.so /usr/lib/mplayer
chmod 755 /usr/lib/mplayer/ad_xa_mp3_dec.so
chmod 755 /usr/lib/mplayer/xa_mp3_dec.so

It's just providing a codec config file for mplayer at '''/etc/mplayer/codecs.conf''' and
copying the plug-in to '''/usr/lib/mplayer'''. To install the mp3 codec plugin and mplayer
config file just copy your codec that was compiled with '''xcc''' to the directory, compile it,
and install.

# '''cd /fac/vol6/audio/release/bin/l32r_LE5_pic'''
# '''cp xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz /tmp'''
#
# '''cd /home/default/buildroot_mplayer_stuff'''
# '''cd mplayer_hifi2_mp3_plugin'''
# '''cp /tmp/xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz .'''
# '''gunzip xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz'''
# '''tar xf xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tar'''
# '''make'''
# '''make target_install'''

The unpacking of the Tensilica mp3 codec tarball will install the following files:

xa_mp3_dec/
xa_mp3_dec/README
xa_mp3_dec/include/
xa_mp3_dec/include/mp3_dec/
xa_mp3_dec/include/mp3_dec/xa_mp3_dec_api.h
xa_mp3_dec/include/xa_apicmd_standards.h
xa_mp3_dec/include/xa_error_handler.h
xa_mp3_dec/include/xa_error_standards.h
xa_mp3_dec/include/xa_memory_standards.h
xa_mp3_dec/include/xa_type_def.h
xa_mp3_dec/test/
xa_mp3_dec/test/build/
xa_mp3_dec/test/build/ldscript_stream_data.txt
xa_mp3_dec/test/build/makefile_testbench_sample
xa_mp3_dec/test/build/paramfilesimple.txt
xa_mp3_dec/test/include/
xa_mp3_dec/test/include/id3_tag_decode.h
xa_mp3_dec/test/src/
xa_mp3_dec/test/src/xa_mp3_dec_sample_testbench.c
xa_mp3_dec/test/src/id3_tag_decode.c
xa_mp3_dec/test/src/stream_data.c
xa_mp3_dec/test/src/xa_mp3_dec_error_handler.c
xa_mp3_dec/test/test_inp/
xa_mp3_dec/test/test_inp/compl.mp3
xa_mp3_dec/test/test_inp/hihat.mp3
xa_mp3_dec/test/test_out/
xa_mp3_dec/test/test_out/force_mkdir.txt
xa_mp3_dec/test/test_ref/
xa_mp3_dec/test/test_ref/compl_24bit.wav
xa_mp3_dec/test/test_ref/hihat_16bit.wav
xa_mp3_dec/lib/
xa_mp3_dec/lib/xa_mp3_dec.a
xa_mp3_dec/doc/
xa_mp3_dec/doc/HiFi2-MP3-DecoderProgrammersGuide.pdf

[TO BE DONE - Add missing C file, make clean deletes it!]

The xa_mp3_dec.a archive will be used by the Makefile in
the mplayer_hifi2_mp3_plugin directory to make the mplayer plug-in.
Section 6 of the '''Using Tensilica HiFi 2 Codec on Xtensa Linux with MPlayer'' Application Note
has a detailed description of the encapsulation process used by the plug-ins.

== Adding a Codec to Buildroot ==

Xtensa developers provide detailed instructions on building the root filesystem and the Linux kernel.
* [[Buildroot_Build_Instructions|Instructions for building and booting Linux (buildroot)]].

Building a comprehensive development environment with buildroot can be a challenging experience and
worthy of providing some tips on process.
Here are notes of the configs used for the three menuconfigs in this 2nd snapshot
provided with SMP additions:
$ '''make [[HiFi-2 snapshot_2 SMP Snapshot menuconfig | menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP uclibc-menuconfig | uclibc-menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP busybox-menuconfig | busybox-menuconfig]]'''

[TO BE DONE - making a new tar ball of saved files, building buildroot, ...]

== Known Problems being investigated, suggested that you know about and possibly avoid ==

1. Using NFS mounts with default parameters causes memory congestion. Use these mount options:

'''vers=2,rsize=4096,wsize=4096,hard,nointr,nolock,nolock,timeo=11,retrans=3,noauto'''

this is extremely important to add to your /etc/fstab on the target.

2. Can't swap over NFS yet, memory can get tight and cause application to be killed.
a. Trying procedure documented in U-Boot Manual.

3. Building the C development with X11 doesn't work with buildroot.

4. Though Mplayer plug-in can be compiled, Mplayer can be compiled but still has a few issues:
a. Can't be compiled -O0 due to limited memory while compiling one file,
b. Compiler infrequently crashes and make has to be restarted.
Not seeing this problem with root build on Fedore Core 9.
Perhaps this was caused by debug kernel or LTP using all of the memory.

5. U-boot has flash problems:
a. Sectors marked Read-Only come up Writeable after a reset/reboot.
b. Flashing a large number of sectors (like the kernel) sometimes
results in an Error (Ex: Vcc) and had to be retried.
c. Saw environment variables trashed on reset/reboot once.
It's possible that U-boot in flash could get whacked
and the board will need to be re-flashed. During a week
or two of testing I haven't see environment getting whacked.

6. gdb appears to be crashing on target when debugging
on latest root with uclibc left unstriped and with debug;
core dump sent to maxim.

7. U-Boot seems to hang periodically when loading the kernel with
tftp; appears to be worse when network activity is high.

8. 'top' command only shows all cpu's or cpu0; cpu 1 and 2 missing.

9. Program dore dump require ulimit -c to be set but root uses /bin/sh
which is a link to bash but causes it to skip running the bash
startup scripts. Changing root to /bin/bash seems to mess up
ssh logins.

10. For kernel to be compiled on the LX200 (for self checking:
a. Xtensa makefile needs to be fixed:
CC init/do_mounts.o
LD init/mounts.o
/bin/sh: xtensa_test_mmuhifi_c3-linux-uclibc-ld: command not found
make[1]: *** [init/mounts.o] Error 127

b. Need to add ncurses-devel package for 'make menuconfig'

11. Copying vim-7.2.tar from /home/default/src to /usr/local/src resulted
in a corrupt tar header. Apparently we have a NFS bug lurking in the kernel.
On server tar file looks like this:
vim72/000755 001750 001750 00000000000 11047345123 012000 5
ustar00moolmool000000 000000
vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0
ustar00moolmool000000 000000
README.txt for version 7.2 of Vim: Vi IMproved.

On the target/client it's different:
vim72/000755 001750 001750 00000000000 11047345123 012000 5ustar00moolmool000000 000000 vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0ustar00moolmool000000 000000 README.txt for version 7.2 of Vim: Vi IMproved.

=Further reading=

Main Xtensa Linux resources are:

* [http://linux-xtensa.org/ Linux/Xtensa Wiki]
* [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions Buildroot Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Kernel_Build_Instructions Kernel Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Setting_up_U-Boot Setting up U-Boot]
* [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List]
* http://git.linux-xtensa.org/cgi-bin/git.cgi GIT Repositories]

=Thanks to=

* piet
* marc
* dan

And the rest of the people in the Linux-Xtensa mailing list, if you cannot go through some of the steps, don't hesitate to ask on the mailing list, there's always somebody willing to help you!

SMP HiFi 2 Development Board

2009-12-02T08:26:14Z

Marc: /* Configuring U-Boot to Boot Linux */

This is a "community" guide for how to use the LX200 board based 3-core SMP HiFi-2 Development environment.
If something doesn't work or isn't covered in this guide, please feel free to ask at the [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List].

<div style="margin:0; margin-top:10px; margin-right:10px; border:1px solid #dfdfdf; padding:0 1em 1em 1em; background-color:#ffffcc; align:right; ">
'''NEWS:'''

Some general notes on these instructions:

* They are a work in progress.

* The following was tested on x86 machines running RedHat Fedora Core 5.

* Buildroot build with Fedora Core 9 also seems to be fine; perhaps better than when built on Fedore Core 5.

</div>

== Introduction ==

This document is addressed to someone who received an LX200 board setup by Tensilica
for HiFi2 development.

This document goes over the steps needed to set up the LX200 board for HiFi2 development.
To summarize:
* Setup the board. It likely comes with U-boot preinstalled, ready to boot a linux kernel.
* Install '''git'''.
* Download buildroot and linux kernel trees, pre-configured and built for HiFi-2 development.
* Setup a TFTP server to provide the linux kernel to U-Boot.
* Setup an NFS server to export a linux root file system.
* Setup the Linux kernel to boot from the root file system provided by the NFS server.
Once the development board is up and running, this document:
* Suggests a possible way to tailor the board for easy codec development.
* Shows how to add the Tensilica provided codec packages to the Mplayer packages used by Buildroot, including building and installing.
* Demonstrates two procedures for compiling, linking, and debugging codecs.

All development is expected to be done on a Linux host. (One can in principle use Windows to
develop target libraries. However, linking and subsequent steps need to be done in Linux.)

== Downloading the Latest HiFi-2 Buildroot and Kernel Snapshots ==

The HiFi-2 development environment is maintained in a source code version control system named 'git'. The '''git''' tools are useful when working with this development environment, though they are not strictly necessary. This document generally assumes the use of '''git''', which provides more opportunities for modifying this environment as needed (e.g. building more optional buildroot packages). But points out alternatives to allow getting up and running without having to set it up.

=== Installing git ===

To install '''git''', download a recent tarball from the [http://www.kernel.org/pub/software/scm/git/ official site]. For example, <tt>cd</tt> to a location with enough disk space, and do:

$ '''wget http://www.kernel.org/pub/software/scm/git/git-1.6.5.tar.gz'''

Unpack the tarball, and make and install it. Here we show how to install it to your ~/bin directory:

$ '''gunzip git-1.6.5.tar.gz'''
$ '''tar xf git-1.6.5.tar'''
$ '''cd git-1.6.5'''
$ '''make'''
$ '''make install'''

The git makefile can be instructed to install '''git''' to <tt>/usr/local/bin</tt> as root for system wide access:

$ '''cp git-1.6.5.tar.gz''' /tmp
$ '''su'''
Password:
# '''cd /usr/local/src/'''
# '''mkdir git'''
# '''cd git'''
# '''cp /tmp/git-1.6.5.tar.gz .'''
# '''gunzip git-1.6.5.tar.gz'''
# '''tar xf git-1.6.5.tar'''
# '''cd git-1.6.5'''
# '''make prefix=/usr/local'''
# '''make install'''

See the '''INSTALL'' instruction at the top of the git src directory for details.

Using '''git''' provides easy access to the binaries used to bring up the codec development environment, and leaves in place the infrastructure to modify and build this environment should you wish to. Any changes to '''git'''-managed source trees are easily observed with the '''git''' tools.

=== Installing the Buildroot Snapshot ===

''Note: The HiFi-2 snapshot is in the process of being made.''

To install the buildroot environment (toolchain and root filesystem), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot'''
$ '''cd buildroot-xtensa-HiFi2-Snapshot'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP''' [56 key strokes]
$ '''git checkout snapshot_2+SMP''' [28 key strokes]

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).

You can examine the tree (git repository) and its history visually using <tt>git gui</tt>.
The git GUI is a faster and more convenient method for checking out the HiFi-2 snapshot. To check out the snapshot_2+SMP branch simply run the command 'git gui' and then pull down the branch->create menu. Next select <>Match Tracking Branch Name and click on ''origin/snapshot_2+SMP''. Finally hit the Create Button.

$ '''git gui''''' [8 key strokes]
[Branch] -> Create... [2 key strokes]
<> Match Tracking Branch Name [1 key stroke]
<> Tracking Branch [1 key stroke]
origin/snapshot_2+SMP [1 key stroke]
[Create] [1 key stroke]
[Reposirory]--> Quit [2 key strokes]

If there are issues installing '''git''', as a last resort, an alternative is ftp (may not always get updated, is currenty our of date, waste disk space, so may be dropped at some point):

http://www.linux-xtensa.org/pub/snapshots/buildroot-xtensa-smp.2-Nov-2009.tar.gz

=== Installing the Linux Kernel Snapshot ===

To install the Linux kernel environment (kernel src, config, and HiFi-2 kernel U-Boot image), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp'''
$ '''cd kernel/xtensa-2.6.29-smp'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
$ '''git checkout snapshot_2+SMP'''

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).
As in the build root case, you can also do it from via git gui using the same proceedure
mantioned above.

Now, assuming we are still in the kernel '''xtensa-2.6.29-smp''' directory
copy the kernel U-Boot Image ('''uImage''') to the tftp directory; Ex:

$ '''cp arch/xtensa/boot/uImage /tftpboot/uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'''

NOTE: On some system, like Fedora Core 9, the tftpboot directory has been moved to /var/lib/tftpboot.
In this case we recomend that you just added a symbolic pointer from /etc to /var/lib/tftpboot:

$ '''su'''
# '''cd /etc'''
# '''/var/lib/tftpboot/ tftpboot'''
# '''ls -ld tftpboot'''
lrwxrwxrwx 1 root root 18 2009-11-23 21:14 tftpboot -> /var/lib/tftpboot/
#

== Setting up a TFTP Server to provide the Linux kernel to U-Boot ==

The TFTP service is part of the xinetd and is installed on Fedora workstations.
You can see that it's installed with the check config command which manages the
/etc/rc.d/init.d startup scripts and with the yum search command:

$ '''chkconfig --list'''
NetworkManager 0:off 1:off 2:off 3:off 4:off 5:off 6:off
NetworkManagerDispatcher 0:off 1:off 2:off 3:off 4:off 5:off 6:off
acpid 0:off 1:off 2:off 3:on 4:on 5:on 6:off
.
.
.
xfs 0:off 1:off 2:on 3:on 4:on 5:on 6:off
xinetd 0:off 1:off 2:off 3:on 4:on 5:on 6:off
ypbind 0:off 1:off 2:off 3:on 4:on 5:on 6:off
yum 0:off 1:off 2:off 3:off 4:off 5:off 6:off

xinetd based services:
amanda: off
auth: off
.
.
.
rsync: off
'''tftp: on''' [NOTE that tftp is enabled]
time: off
time-udp: off
uucp: off
$
$
$
$ '''yum search tftp-server'''
Loading "installonlyn" plugin
Searching Packages:
.
.
.
Reading repository metadata in from local files
.
.
.
'''tftp-server.i386 0.41-1.2.1 installed''' [NOTE that tftp server is installed as part of the inet daemon]
Matched from:
tftp-server
The Trivial File Transfer Protocol (TFTP) is normally used only for
booting diskless workstations. The tftp-server package provides the
server for TFTP, which allows users to transfer files to and from a
remote machine. TFTP provides very little security, and should not be
enabled unless it is expressly needed. The TFTP server is run from
/etc/xinetd.d/tftp, and is disabled by default on Red Hat Linux systems.
[piet@pdelaney_fc5 ~]$

TFTP is not normally enabled, to enable it just edit the file /etc/xinetd.d/tftp
and change the disable field to no:

# default: off
# description: The tftp server serves files using the trivial file transfer \
# protocol. The tftp protocol is often used to boot diskless \
# workstations, download configuration files to network-aware printers, \
# and to start the installation process for some operating systems.
service tftp
{
socket_type = dgram
protocol = udp
wait = yes
user = root
server = /usr/sbin/in.tftpd [NOTE: /var/lib/tftpboot on Fedora Core 9]
server_args = -s /tftpboot
'''disable = no'''
per_source = 11
cps = 100 2
flags = IPv4
}

== Setting up an NFS Server to export the Root Filesystem ==

The LX200 board running Linux needs to mount its root filesystem over NFS.
This filesystem was built using buildroot into a cpio format file,
and left in:

buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2/rootfs.xtensa_test_mmuhifi_c3.cpio

We will also be adding an additional minor changes to make your development environment more comfortable.

Pick a place on your workstation to export your root and unpack the cpio file into that directory.
For example here we will set up an export in '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''':

$ '''cd buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2'''
$ '''WHERE=$PWD'''
$ '''mkdir -p /exports/LINUX_ROOT.HiFi-2'''
$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''cpio -i < $WHERE/rootfs.xtensa_test_mmuhifi_c3.cpio'''

Next add a line to /etc/exports:

/exports *(rw,no_root_squash,sync,no_wdelay)

and restart you nfs services:

$ '''/etc/rc.d/init.d/nfs restart'''
or
$ '''/sbin/chkconfig nfs on'''

The showmount command should show your NFS file system now being exported:

$ '''showmount -e'''
Export list for mypc.foobar.com:
/exports *
$

== Configuring U-Boot to Boot Linux ==

Your LX200 board should have arrived with U-Boot installed in the flash ready to use.
The board has a DIP switch (next to the power on/off switch) that provides the 6 LSBs
of the Ethernet MAC, in switch positions 1 thru 6.

DIP Swithes for MAC: 1 2 3 4 5 6 7 8 ethaddr=00:50:C2:13:6f:0a
Little Endian: 0 1 0 1 0 0 * *
^
|
+------ Enables booting U-Boot from Flash

DIP switch 8 should be shipped in the ON position to enable U-Boot booting from flash.
See Sections 4.2.3 and 4.2.4 of the '''Tensilica Avnet (XT-AV200) Board User's Guide'''
for details. Make sure to select a unique MAC address for you board.

Next, connect a serial interface to a text based terminal emulation program,
set to 38400 bps, no parity, 1 stop bit, no handshaking.
For an example of setting [http://en.wikipedia.org/wiki/Minicom minicom]
for this, see [[minicom_xtboard_setup|here]].

Here's how to configure U-Boot to automatically boot the Linux kernel on power-up (using the root file system exported over NFS as described further above).

U-Boot> '''setenv serverip 192.168.11.55''' [TFTP server IP Address: RTOS-LAB2]
U-Boot> '''setenv nfsroot_server 192.168.11.55''' [Root NFS Servers IP Address: My Workstation]
U-Boot> '''setenv ipaddr 192.168.11.155''' [HOST IP address]
U-Boot> '''setenv bootfile uImage.xtensa-2.6.29-smp.test_mmuhifi_c3''' [File to fetch with TFTP and pass to bootm]
U-Boot> '''setenv root-path /exports/LINUX_ROOT.HiFi-2''' [WARNING: Limit path to < 50 characters]
U-Boot> '''setenv bootargs_using_bootp console=ttyS0,38400 ip=bootp root=nfs coredump_filter=0xff''' [Args passed to Linux while booting with BOOTP proto]
U-boot> '''setenv bootargs console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=${nfsroot_server}:${root-path}''' [Args passed to Linux while booting with DHCP proto]
U-boot> '''setenv bootcmd tftpboot\; bootm''' [Boot Linux after fetching it with TFTP]
U-Boot> '''setenv bootdelay 20''' [Delay 20 seconds before booting automaticaly]
U-Boot> '''setenv autostart yes''' [Boot automatically on power-up/reset]
U-Boot> '''saveenv'''
U-Boot>

'''[REMIND: Update the above procedure, show two or thee approaches (ip, dhcp, bootp)]'''

== Tailoring your system prior to Booting ==

There are a few tweaks that developers have found convenient to add to the the root file-system before booting.
As an initial environment for developing we suggest mounting a /home/default files-system that has number of
files useful for getting started. Find another place to tar in the tar ball with the default users file system.
We chose to include this close to the cpio file with the root file-system. Copy the tar bar to where you are
exporting you root file-system and next to it add the 'default' users file-system:

$ '''cd /export'''
$ '''cp /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.10/binaries/default.tar .'''
$ '''tar xf default.tar'''
$ '''cd default'''
$ '''ls'''
[TO BE ADDED]

Notice a file tar ball called '''saved_files.tar'''. This ia a tar file of files that
developers have found convenient to add and replace on the root file system after
adding a new buildroot file system. Here is a list of the files and a brief
explanation on why it's convenient to add or replace them:

root/.bash_profile [added 'ulimit -c unlimited to allow core dumps to be created]
root/.bashrc
etc/profile [added 'ulimit -c unlimited to allow core dumps to be created]
etc/fstab [Tells the system how to mount extra NFS file systems like /home/default]
etc/init.d/S90local [Mounts /home/default]
etc/resolv.conf [Location of DNS servers when your not using DHCP to boot the kernel]
etc/TZ [Your time zone, currently set to California TZ]
etc/dropbear/dropbear_rsa_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/dropbear/dropbear_dss_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/ssh_config [Typically tailored with things like allowing root logins via ssh]
etc/ssh_host_dsa_key [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_dsa_key.pub [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_key
etc/ssh_host_key.pub
etc/ssh_host_rsa_key
etc/ssh_host_rsa_key.pub
etc/sshd_config [Typically tailored with things like allowing root logins via ssh]
etc/rndc.key
etc/random-seed [Generated during 1st boot]
etc/passwd [Changed default user's shell to bash]
etc/shadow [Changed default and root users login password to 'linux1', need to ssh to the board]
exports/ [The path to where the board can mount extra file systems like /home/default.
fac/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]
fac/vol6/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]

Now lets assume your going to stay with these changes and modify them after taring in these changes.
Here we add the tar ball files to the boards root filesystem.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''tar xf /exports/default/'''

This is a good time to edit a few files on the boards file system
before boot it.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''vi etc/fstab''' [Change fstab entry for /home/default and others to your taste]
$ '''vi etc/init.d/S90local''' [You might want to disable mounting of NFS file systems on the 1st Boot and add this once you try it manually]

== Booting Linux for the 1st Time ==

We should now be ready to boot linux on your LX200. You have exported the root file-system and made the
kernel available to a TFTP server. Now let's start with hitting the reset button on the LX200 and it should
auto-boot the kernel, resulting in output such as [[HiFi2_Board_Example_Linux_Boot_Log|this example log]].

== Tailoring your system prior to developing for HiFi 2 ==

To make your experience more pleasant we suggest you tailor your environment.
Here are some of the changes that we have found helpful:

1. Add a root password to that you can login with ssh.
2. Run rdate with an ntp server on booting.
3. Add NFS mounts to /etc/fstab for your code and buildroot code.
4. Copy in previous ssh server encryption keys to /etc/dropbear to speed up your initial boot.
5. Mount a 'default' user home directory with:
a. Linux Test Suite pre-patch to test the system
b. Audio test example files
c. Copies of Mplayer and its Plug-ins from Buildroot modified slightly to make installation easy.
d. Misc audio test programs.

[TO BE DONE - Where to get 'default' user home directory tar ball and 1st boot patch]

== Building Linux Applications ==

=== Building Linux Applications Using GCC on the Host ===

You can use the open source toolchain included in the buildroot tree.

Given the location of the buildroot tree and the name of the core:

$ setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12
$ setenv CORENAME test_mmuhifi_c3

You can either set the PATH and invoke tools prefixed with <tt>xtensa_${CORENAME}-linux-</tt> :

$ setenv PATH ${BUILDROOT_DIR}/build_xtensa_${CORENAME}/staging_dir/usr/bin:${PATH}
$ xtensa_test_mmuhifi_c3-linux-gcc -g hello.c -o hello
$ xtensa_test_mmuhifi_c3-linux-gdb hello

or alternatively invoke the tools with absolute paths:

$ ${BUILDROOT_DIR}/build_xtensa_test_mmuhifi_c3/staging_dir/usr/bin/xtensa_test_mmuhifi_c3-linux-gcc -g hello.c -o hello
$ ${BUILDROOT_DIR}/build_xtensa_test_mmuhifi_c3/staging_dir/usr/bin/xtensa_test_mmuhifi_c3-linux-gdb hello

=== Building Linux Applications Using GCC on the Target ===
This is the simplest. (Much slower of course at 45 MHz across a slow Ethernet link than on a workstation,
but convenient.) Just login to the target system and use the native <tt>cc</tt>.

=== Building Linux Applications Using XCC (Xtensa Tools) ===

There are two approaches to compiling with Tensilica's XCC compiler (part of Xtensa Tools).
The normal one, described below, is to initially setup a virtual core
that has built-in references to the library and include files for the target Linux system.
Alternatively, one could skip this initial setup and just use Xtensa Tools to create
object files and link them using host or target GCC tools.
However, such objects must be built without dependencies on such things as the C library,
which can be harder than it sounds (for example, flags and structures, such as <tt>open()</tt>'s <tt>O_EXCL</tt>
and <tt>stat()</tt>'s <tt>struct stat</tt>, must be avoided because their definitions likely differ between the
Xtensa Tools' default C library and the Linux uClibc library).
''('''Note''': Codecs such as MP3 and AAC are typically written in C with TIE extensions and can only be compiled with XCC.)''

Section 4.3 of the latest ''Xtensa OSKit Guide'' (from Tensilica's
RC-2009.0 release) describes how to setup XCC to compile Linux applications.
For full details, see the guide. A summary follows.

==== Initial Setup ====

The XTENSA_TOOLS_ROOT, XTENSA_ROOT, BUILDROOT_DIR, and TARGET_SYSROOT
environment variables must be set according to where things were installed;
values shown here are for illustration only. The CORENAME variable, set correctly
below for this board, reflects
the name of the core as known to open source tools (as opposed to XTENSA_CORE
which is the core name as known to Xtensa Tools; both happen to match here).

$ setenv USER someuser
$ setenv XTENSA_ROOT /home/${USER}/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
$ setenv XTENSA_TOOLS_ROOT /home/${USER}/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools
$ setenv TARGET_SYSROOT /exports/LINUX_ROOT.HiFi-2
$ setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12

$ setenv CORENAME test_mmuhifi_c3

$ cd ${BUILDROOT_DIR}
$ ${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install \
--sysroot=./build_xtensa_${CORENAME}/staging_dir \
--linux-gcc=./build_xtensa_${CORENAME}/staging_dir/usr/bin/xtensa_${CORENAME}-linux-gcc

==== Regular Use ====

Assuming the above completed successfully, you can now build applications using Xtensa Tools. First set the usual environment variables (assuming values of XTENSA_ROOT and XTENSA_TOOLS_ROOT used earlier):

$ setenv XTENSA_CORE default
$ setenv XTENSA_SYSTEM ${XTENSA_ROOT}-linux/config
$ setenv PATH ${XTENSA_TOOLS_ROOT}/bin:${PATH}

Now you can use Xtensa Tools to assemble, compile, and link applications for the Linux target specified during setup. For example:

$ echo '#include <stdio.h>' > hello.c
$ echo 'int main() {printf("Hello!\n");return 0;}' >> hello.c
$ xt-xcc -g hello.c -o hello

Then copy it where the target can see it:

$ cp hello ${TARGET_SYSROOT}/root

And run it on the target:

[root@hifi ~]# /root/hello
Hello!
[root@hifi ~]#

Here's a more interesting example that uses Tensilica TIE features.
(This cannot be compiled using GCC.)

$ cd ${TARGET_SYSROOT}/home/default/Audio_Tests
$ xt-xcc -g hifitest.c -o hifitest

In a ssh termulator window on the board you can now run hifitest:

[root@hifi ~]# '''cd /home/default/Audio_Tests/'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:23178; Eatting cpu; time:0 '''<control-C>'''

[root@hifi Audio_Tests]#

Here is the source code for the [[hifitest.c|hifitest.c source file]] used above.

=== Limited (No Setup) Use of Xtensa Tools for Linux Targets ===

Below we illustrate compiling a simple audio test program on a workstation.
We start by referring to the XTENSA tools build by Xplorer, putting XCC into our search path and set the standard XTENSA_* environment variables.
For example:

setenv XTENSA_CORE test_mmuhifi_c3
setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config
setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin

setenv PATH ${XTENSA_TOOLS}:${PATH}

[piet@fc9desktop Tests] $ '''cd /exports/default/Audio_Tests''' [NOTE: This is being done on a Workstation]
[piet@fc9desktop Audio_Tests]$ '''xt-xcc -g3 -O0 -fPIC -c hifitest.c'''

Next we link the object on the LX200 board and run gdb on the TIE enhanced code:

[root@hifi Audio_Tests]# '''gcc -g hifitest.o -o hifitest'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:4640; Eatting cpu; time:0
cnt:0x0, pid:4640; Eating Tie; time:7
^C
[root@hifi Audio_Tests]# '''gdb ./hifitest''' [NOTE: This is being done on the LX200 board]
GNU gdb 6.6
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "xtensa_test_mmuhifi_c3-linux-uclibc"...
Using host libthread_db library "/lib/libthread_db.so.1".
(gdb) '''break main'''
Breakpoint 1 at 0x400401: file /exports/default/Audio_Tests/hifitest.c, line 20.
(gdb) '''run'''
Starting program: /home/default/Audio_Tests/hifitest

Breakpoint 1, main (argc=1, argv=0x3fb3fab4)
at /exports/default/Audio_Tests/hifitest.c:20
20 time_t time0 = time(NULL);
(gdb) '''step'''
21 time_t time1 = time(NULL);

== Compiling Generic GPL Packages ==

For your development you may want to add a few GPL packages that you find helpful.
This can be done on the LX200 just as you would on a normal workstation, though
much slower. For example here we configure and build a few common GPL packages:

[[Building the Strace Package]]

[[Building the vim Package]]

== Compiling the Mplayer Plugins and linking them with MPEG-1 Audio Layer 3 (MP3) and MPEG-4 AAC Codecs ==

Mplayer is provided as an example environment for developing and testing Codecs and HiFi 2 software. There
are two ways to build Mplayer and the plug-in modules that use the codecs. The buildroot
tree (pulled with git) has a copy of mplayer and the plugins that can be built in the
snapshot via 'make menuconfig'. This is a good environment to use once codecs are
developed and debugged.

To facilitate development the mplayer packages can be copied to your NFS mounted development
environment. From there you can just configure mplayer to compile on the board and debug
mplayer and your codecs with gdb locally.

In the default user home directory we have a directory /home/default/buildroot_mplayer_stuff
with a copy of three of the mplayer packages:

[root@hifi buildroot_mplayer_stuff]# '''ls -l'''
drwxr-xr-x 34 root root 4096 Nov 10 05:01 MPlayer-1.0rc2/
drwxr-xr-x 4 root root 4096 Nov 10 01:36 mplayer_hifi2_aacplus_v2_plugin/
drwxr-xr-x 3 root root 4096 Nov 10 00:57 mplayer_hifi2_mp3_plugin/

they were simply copied from the buildroot-xtensa-HiFi2-Snapshot.2/package directory.

To get your development environment ready to compile the mplayer plug-ins you need
to configure Mplayer to use the local C compiler and linker:

# '''cd /home/default/buildroot_mplayer_stuff/MPlayer-1.0rc2/'''
# '''CFLAGS="-g3" ./configure'''

This will take about 15 minutes to configure. After that you can build the
plugins or mplayer. If you want to recompile mplayer it's likely best/necessary
to use the same args to .configure as used by buildroot:

.CFLAGS="-g3" ./configure \
--prefix=/usr \
--confdir=/etc/mplayer \
--with-extraincdir=/usr/include \
--with-extralibdir=/lib \
--disable-gui \
--enable-mad \
--enable-fbdev \
--disable-mencoder \
--disable-dvdnav \
--disable-dvdread \
--disable-dvdread-internal \
--disable-libdvdcss-internal \
--disable-big-endian \
--disable-nemesi \
--disable-tv \
--enable-dynamic-plugins

We are currently able to compile most of mplayer on the LX200 but
due to space limitations it's not possible to compile it -O0.

Now, let's focus on compiling linking the plugins. They are a nice
example of compiling an audio application on the LX200.

We modified the Makefile of the codes slightly, and will make it available.
These additions just instruct make how to install the plugins as explained
in the Chapter 7 of the Linux HiFi application note.

For example the mp3 plugin has this addition:

target_install::
-mkdir /etc/mplayer
cp codecs.conf /etc/mplayer
-mkdir /usr/lib/mplayer
cp ad_xa_mp3_dec.so /usr/lib/mplayer/
cp xa_mp3_dec.so /usr/lib/mplayer
chmod 755 /usr/lib/mplayer/ad_xa_mp3_dec.so
chmod 755 /usr/lib/mplayer/xa_mp3_dec.so

It's just providing a codec config file for mplayer at '''/etc/mplayer/codecs.conf''' and
copying the plug-in to '''/usr/lib/mplayer'''. To install the mp3 codec plugin and mplayer
config file just copy your codec that was compiled with '''xcc''' to the directory, compile it,
and install.

# '''cd /fac/vol6/audio/release/bin/l32r_LE5_pic'''
# '''cp xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz /tmp'''
#
# '''cd /home/default/buildroot_mplayer_stuff'''
# '''cd mplayer_hifi2_mp3_plugin'''
# '''cp /tmp/xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz .'''
# '''gunzip xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz'''
# '''tar xf xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tar'''
# '''make'''
# '''make target_install'''

The unpacking of the Tensilica mp3 codec tarball will install the following files:

xa_mp3_dec/
xa_mp3_dec/README
xa_mp3_dec/include/
xa_mp3_dec/include/mp3_dec/
xa_mp3_dec/include/mp3_dec/xa_mp3_dec_api.h
xa_mp3_dec/include/xa_apicmd_standards.h
xa_mp3_dec/include/xa_error_handler.h
xa_mp3_dec/include/xa_error_standards.h
xa_mp3_dec/include/xa_memory_standards.h
xa_mp3_dec/include/xa_type_def.h
xa_mp3_dec/test/
xa_mp3_dec/test/build/
xa_mp3_dec/test/build/ldscript_stream_data.txt
xa_mp3_dec/test/build/makefile_testbench_sample
xa_mp3_dec/test/build/paramfilesimple.txt
xa_mp3_dec/test/include/
xa_mp3_dec/test/include/id3_tag_decode.h
xa_mp3_dec/test/src/
xa_mp3_dec/test/src/xa_mp3_dec_sample_testbench.c
xa_mp3_dec/test/src/id3_tag_decode.c
xa_mp3_dec/test/src/stream_data.c
xa_mp3_dec/test/src/xa_mp3_dec_error_handler.c
xa_mp3_dec/test/test_inp/
xa_mp3_dec/test/test_inp/compl.mp3
xa_mp3_dec/test/test_inp/hihat.mp3
xa_mp3_dec/test/test_out/
xa_mp3_dec/test/test_out/force_mkdir.txt
xa_mp3_dec/test/test_ref/
xa_mp3_dec/test/test_ref/compl_24bit.wav
xa_mp3_dec/test/test_ref/hihat_16bit.wav
xa_mp3_dec/lib/
xa_mp3_dec/lib/xa_mp3_dec.a
xa_mp3_dec/doc/
xa_mp3_dec/doc/HiFi2-MP3-DecoderProgrammersGuide.pdf

[TO BE DONE - Add missing C file, make clean deletes it!]

The xa_mp3_dec.a archive will be used by the Makefile in
the mplayer_hifi2_mp3_plugin directory to make the mplayer plug-in.
Section 6 of the '''Using Tensilica HiFi 2 Codec on Xtensa Linux with MPlayer'' Application Note
has a detailed description of the encapsulation process used by the plug-ins.

== Adding a Codec to Buildroot ==

Xtensa developers provide detailed instructions on building the root filesystem and the Linux kernel.
* [[Buildroot_Build_Instructions|Instructions for building and booting Linux (buildroot)]].

Building a comprehensive development environment with buildroot can be a challenging experience and
worthy of providing some tips on process.
Here are notes of the configs used for the three menuconfigs in this 2nd snapshot
provided with SMP additions:
$ '''make [[HiFi-2 snapshot_2 SMP Snapshot menuconfig | menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP uclibc-menuconfig | uclibc-menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP busybox-menuconfig | busybox-menuconfig]]'''

[TO BE DONE - making a new tar ball of saved files, building buildroot, ...]

== Known Problems being investigated, suggested that you know about and possibly avoid ==

1. Using NFS mounts with default parameters causes memory congestion. Use these mount options:

'''vers=2,rsize=4096,wsize=4096,hard,nointr,nolock,nolock,timeo=11,retrans=3,noauto'''

this is extremely important to add to your /etc/fstab on the target.

2. Can't swap over NFS yet, memory can get tight and cause application to be killed.
a. Trying procedure documented in U-Boot Manual.

3. Building the C development with X11 doesn't work with buildroot.

4. Though Mplayer plug-in can be compiled, Mplayer can be compiled but still has a few issues:
a. Can't be compiled -O0 due to limited memory while compiling one file,
b. Compiler infrequently crashes and make has to be restarted.
Not seeing this problem with root build on Fedore Core 9.
Perhaps this was caused by debug kernel or LTP using all of the memory.

5. U-boot has flash problems:
a. Sectors marked Read-Only come up Writeable after a reset/reboot.
b. Flashing a large number of sectors (like the kernel) sometimes
results in an Error (Ex: Vcc) and had to be retried.
c. Saw environment variables trashed on reset/reboot once.
It's possible that U-boot in flash could get whacked
and the board will need to be re-flashed. During a week
or two of testing I haven't see environment getting whacked.

6. gdb appears to be crashing on target when debugging
on latest root with uclibc left unstriped and with debug;
core dump sent to maxim.

7. U-Boot seems to hang periodically when loading the kernel with
tftp; appears to be worse when network activity is high.

8. 'top' command only shows all cpu's or cpu0; cpu 1 and 2 missing.

9. Program dore dump require ulimit -c to be set but root uses /bin/sh
which is a link to bash but causes it to skip running the bash
startup scripts. Changing root to /bin/bash seems to mess up
ssh logins.

10. For kernel to be compiled on the LX200 (for self checking:
a. Xtensa makefile needs to be fixed:
CC init/do_mounts.o
LD init/mounts.o
/bin/sh: xtensa_test_mmuhifi_c3-linux-uclibc-ld: command not found
make[1]: *** [init/mounts.o] Error 127

b. Need to add ncurses-devel package for 'make menuconfig'

11. Copying vim-7.2.tar from /home/default/src to /usr/local/src resulted
in a corrupt tar header. Apparently we have a NFS bug lurking in the kernel.
On server tar file looks like this:
vim72/000755 001750 001750 00000000000 11047345123 012000 5
ustar00moolmool000000 000000
vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0
ustar00moolmool000000 000000
README.txt for version 7.2 of Vim: Vi IMproved.

On the target/client it's different:
vim72/000755 001750 001750 00000000000 11047345123 012000 5ustar00moolmool000000 000000 vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0ustar00moolmool000000 000000 README.txt for version 7.2 of Vim: Vi IMproved.

=Further reading=

Main Xtensa Linux resources are:

* [http://linux-xtensa.org/ Linux/Xtensa Wiki]
* [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions Buildroot Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Kernel_Build_Instructions Kernel Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Setting_up_U-Boot Setting up U-Boot]
* [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List]
* http://git.linux-xtensa.org/cgi-bin/git.cgi GIT Repositories]

=Thanks to=

* piet
* marc
* dan

And the rest of the people in the Linux-Xtensa mailing list, if you cannot go through some of the steps, don't hesitate to ask on the mailing list, there's always somebody willing to help you!

SMP HiFi 2 Development Board

2009-12-02T08:11:11Z

Marc: /* Building Linux Applications Using GCC on the Host */

This is a "community" guide for how to use the LX200 board based 3-core SMP HiFi-2 Development environment.
If something doesn't work or isn't covered in this guide, please feel free to ask at the [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List].

<div style="margin:0; margin-top:10px; margin-right:10px; border:1px solid #dfdfdf; padding:0 1em 1em 1em; background-color:#ffffcc; align:right; ">
'''NEWS:'''

Some general notes on these instructions:

* They are a work in progress.

* The following was tested on x86 machines running RedHat Fedora Core 5.

* Buildroot build with Fedora Core 9 also seems to be fine; perhaps better than when built on Fedore Core 5.

</div>

== Introduction ==

This document is addressed to someone who received an LX200 board setup by Tensilica
for HiFi2 development.

This document goes over the steps needed to set up the LX200 board for HiFi2 development.
To summarize:
* Setup the board. It likely comes with U-boot preinstalled, ready to boot a linux kernel.
* Install '''git'''.
* Download buildroot and linux kernel trees, pre-configured and built for HiFi-2 development.
* Setup a TFTP server to provide the linux kernel to U-Boot.
* Setup an NFS server to export a linux root file system.
* Setup the Linux kernel to boot from the root file system provided by the NFS server.
Once the development board is up and running, this document:
* Suggests a possible way to tailor the board for easy codec development.
* Shows how to add the Tensilica provided codec packages to the Mplayer packages used by Buildroot, including building and installing.
* Demonstrates two procedures for compiling, linking, and debugging codecs.

All development is expected to be done on a Linux host. (One can in principle use Windows to
develop target libraries. However, linking and subsequent steps need to be done in Linux.)

== Downloading the Latest HiFi-2 Buildroot and Kernel Snapshots ==

The HiFi-2 development environment is maintained in a source code version control system named 'git'. The '''git''' tools are useful when working with this development environment, though they are not strictly necessary. This document generally assumes the use of '''git''', which provides more opportunities for modifying this environment as needed (e.g. building more optional buildroot packages). But points out alternatives to allow getting up and running without having to set it up.

=== Installing git ===

To install '''git''', download a recent tarball from the [http://www.kernel.org/pub/software/scm/git/ official site]. For example, <tt>cd</tt> to a location with enough disk space, and do:

$ '''wget http://www.kernel.org/pub/software/scm/git/git-1.6.5.tar.gz'''

Unpack the tarball, and make and install it. Here we show how to install it to your ~/bin directory:

$ '''gunzip git-1.6.5.tar.gz'''
$ '''tar xf git-1.6.5.tar'''
$ '''cd git-1.6.5'''
$ '''make'''
$ '''make install'''

The git makefile can be instructed to install '''git''' to <tt>/usr/local/bin</tt> as root for system wide access:

$ '''cp git-1.6.5.tar.gz''' /tmp
$ '''su'''
Password:
# '''cd /usr/local/src/'''
# '''mkdir git'''
# '''cd git'''
# '''cp /tmp/git-1.6.5.tar.gz .'''
# '''gunzip git-1.6.5.tar.gz'''
# '''tar xf git-1.6.5.tar'''
# '''cd git-1.6.5'''
# '''make prefix=/usr/local'''
# '''make install'''

See the '''INSTALL'' instruction at the top of the git src directory for details.

Using '''git''' provides easy access to the binaries used to bring up the codec development environment, and leaves in place the infrastructure to modify and build this environment should you wish to. Any changes to '''git'''-managed source trees are easily observed with the '''git''' tools.

=== Installing the Buildroot Snapshot ===

''Note: The HiFi-2 snapshot is in the process of being made.''

To install the buildroot environment (toolchain and root filesystem), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot'''
$ '''cd buildroot-xtensa-HiFi2-Snapshot'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP''' [56 key strokes]
$ '''git checkout snapshot_2+SMP''' [28 key strokes]

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).

You can examine the tree (git repository) and its history visually using <tt>git gui</tt>.
The git GUI is a faster and more convenient method for checking out the HiFi-2 snapshot. To check out the snapshot_2+SMP branch simply run the command 'git gui' and then pull down the branch->create menu. Next select <>Match Tracking Branch Name and click on ''origin/snapshot_2+SMP''. Finally hit the Create Button.

$ '''git gui''''' [8 key strokes]
[Branch] -> Create... [2 key strokes]
<> Match Tracking Branch Name [1 key stroke]
<> Tracking Branch [1 key stroke]
origin/snapshot_2+SMP [1 key stroke]
[Create] [1 key stroke]
[Reposirory]--> Quit [2 key strokes]

If there are issues installing '''git''', as a last resort, an alternative is ftp (may not always get updated, is currenty our of date, waste disk space, so may be dropped at some point):

http://www.linux-xtensa.org/pub/snapshots/buildroot-xtensa-smp.2-Nov-2009.tar.gz

=== Installing the Linux Kernel Snapshot ===

To install the Linux kernel environment (kernel src, config, and HiFi-2 kernel U-Boot image), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp'''
$ '''cd kernel/xtensa-2.6.29-smp'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
$ '''git checkout snapshot_2+SMP'''

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).
As in the build root case, you can also do it from via git gui using the same proceedure
mantioned above.

Now, assuming we are still in the kernel '''xtensa-2.6.29-smp''' directory
copy the kernel U-Boot Image ('''uImage''') to the tftp directory; Ex:

$ '''cp arch/xtensa/boot/uImage /tftpboot/uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'''

NOTE: On some system, like Fedora Core 9, the tftpboot directory has been moved to /var/lib/tftpboot.
In this case we recomend that you just added a symbolic pointer from /etc to /var/lib/tftpboot:

$ '''su'''
# '''cd /etc'''
# '''/var/lib/tftpboot/ tftpboot'''
# '''ls -ld tftpboot'''
lrwxrwxrwx 1 root root 18 2009-11-23 21:14 tftpboot -> /var/lib/tftpboot/
#

== Setting up a TFTP Server to provide the Linux kernel to U-Boot ==

The TFTP service is part of the xinetd and is installed on Fedora workstations.
You can see that it's installed with the check config command which manages the
/etc/rc.d/init.d startup scripts and with the yum search command:

$ '''chkconfig --list'''
NetworkManager 0:off 1:off 2:off 3:off 4:off 5:off 6:off
NetworkManagerDispatcher 0:off 1:off 2:off 3:off 4:off 5:off 6:off
acpid 0:off 1:off 2:off 3:on 4:on 5:on 6:off
.
.
.
xfs 0:off 1:off 2:on 3:on 4:on 5:on 6:off
xinetd 0:off 1:off 2:off 3:on 4:on 5:on 6:off
ypbind 0:off 1:off 2:off 3:on 4:on 5:on 6:off
yum 0:off 1:off 2:off 3:off 4:off 5:off 6:off

xinetd based services:
amanda: off
auth: off
.
.
.
rsync: off
'''tftp: on''' [NOTE that tftp is enabled]
time: off
time-udp: off
uucp: off
$
$
$
$ '''yum search tftp-server'''
Loading "installonlyn" plugin
Searching Packages:
.
.
.
Reading repository metadata in from local files
.
.
.
'''tftp-server.i386 0.41-1.2.1 installed''' [NOTE that tftp server is installed as part of the inet daemon]
Matched from:
tftp-server
The Trivial File Transfer Protocol (TFTP) is normally used only for
booting diskless workstations. The tftp-server package provides the
server for TFTP, which allows users to transfer files to and from a
remote machine. TFTP provides very little security, and should not be
enabled unless it is expressly needed. The TFTP server is run from
/etc/xinetd.d/tftp, and is disabled by default on Red Hat Linux systems.
[piet@pdelaney_fc5 ~]$

TFTP is not normally enabled, to enable it just edit the file /etc/xinetd.d/tftp
and change the disable field to no:

# default: off
# description: The tftp server serves files using the trivial file transfer \
# protocol. The tftp protocol is often used to boot diskless \
# workstations, download configuration files to network-aware printers, \
# and to start the installation process for some operating systems.
service tftp
{
socket_type = dgram
protocol = udp
wait = yes
user = root
server = /usr/sbin/in.tftpd [NOTE: /var/lib/tftpboot on Fedora Core 9]
server_args = -s /tftpboot
'''disable = no'''
per_source = 11
cps = 100 2
flags = IPv4
}

== Setting up an NFS Server to export the Root Filesystem ==

The LX200 board running Linux needs to mount its root filesystem over NFS.
This filesystem was built using buildroot into a cpio format file,
and left in:

buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2/rootfs.xtensa_test_mmuhifi_c3.cpio

We will also be adding an additional minor changes to make your development environment more comfortable.

Pick a place on your workstation to export your root and unpack the cpio file into that directory.
For example here we will set up an export in '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''':

$ '''cd buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2'''
$ '''WHERE=$PWD'''
$ '''mkdir -p /exports/LINUX_ROOT.HiFi-2'''
$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''cpio -i < $WHERE/rootfs.xtensa_test_mmuhifi_c3.cpio'''

Next add a line to /etc/exports:

/exports *(rw,no_root_squash,sync,no_wdelay)

and restart you nfs services:

$ '''/etc/rc.d/init.d/nfs restart'''
or
$ '''/sbin/chkconfig nfs on'''

The showmount command should show your NFS file system now being exported:

$ '''showmount -e'''
Export list for mypc.foobar.com:
/exports *
$

== Configuring U-Boot to Boot Linux ==

Your LX200 board should have arrived with U-Boot installed in the flash ready to use.
The board has a DIP switch (next to the power on/off switch) that provides the 6 LSBs
of the Ethernet MAC, in switch positions 1 thru 6.

DIP Swithes for MAC: 1 2 3 4 5 6 7 8 ethaddr=00:50:C2:13:6f:0a
Little Endian: 0 1 0 1 0 0 * *
^
|
+------ Enables booting U-Boot from Flash

DIP switch 8 should be shipped in the ON position to enable U-Boot booting from flash.
See Sections 4.2.3 and 4.2.4 of the '''Tensilica Avnet (XT-AV200) Board User's Guide'''
for details. Make sure to select a unique MAC address for you board.

Next, connect a serial interface to a text based terminal emulation program,
set to 38400 bps, no parity, 1 stop bit, no handshaking.
For an example of setting [http://en.wikipedia.org/wiki/Minicom minicom]
for this, see [[minicom_xtboard_setup|here]].

Many users of this board are interested in developing codecs and/or HiFi 2 software and will prefer to just boot linux with the root file system we just described how to export on your NFS server. We will use git now to pull a snapshot of a performance 2.6.29 linux kernel and configure U-Boot to automatically boot it after a power cycle.

U-Boot> '''setenv serverip 192.168.11.55''' [TFTP server IP Address: RTOS-LAB2]
U-Boot> '''setenv nfsroot_server 192.168.11.55''' [Root NFS Servers IP Address: My Workstation]
U-Boot> '''setenv ipaddr 192.168.11.155''' [HOST IP address]
U-Boot> '''setenv bootfile uImage.xtensa-2.6.29-smp.test_mmuhifi_c3''' [File to fetch with TFTP and pass to bootm]
U-Boot> '''setenv root-path /exports/LINUX_ROOT.HiFi-2''' [WARNING: Limit path to < 50 characters]
U-Boot> '''setenv bootargs_using_bootp console=ttyS0,38400 ip=bootp root=nfs coredump_filter=0xff''' [Args passed to Linux while booting with BOOTP proto]
U-boot> '''setenv bootargs console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=${nfsroot_server}:${root-path}''' [Args passed to Linux while booting with DHCP proto]
U-boot> '''setenv bootcmd tftpboot\; bootm''' [Boot Linux after fetching it with TFTP]
U-Boot> '''setenv bootdelay 20''' [Delay 20 seconds before booting automaticaly]
U-Boot> '''setenv autostart yes''' [Boot automatically on power-up/reset]
U-Boot> '''saveenv'''
U-Boot>

'''[REMIND: Update the above procedure, show two or thee approaches (ip, dhcp, bootp)]'''

== Tailoring your system prior to Booting ==

There are a few tweaks that developers have found convenient to add to the the root file-system before booting.
As an initial environment for developing we suggest mounting a /home/default files-system that has number of
files useful for getting started. Find another place to tar in the tar ball with the default users file system.
We chose to include this close to the cpio file with the root file-system. Copy the tar bar to where you are
exporting you root file-system and next to it add the 'default' users file-system:

$ '''cd /export'''
$ '''cp /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.10/binaries/default.tar .'''
$ '''tar xf default.tar'''
$ '''cd default'''
$ '''ls'''
[TO BE ADDED]

Notice a file tar ball called '''saved_files.tar'''. This ia a tar file of files that
developers have found convenient to add and replace on the root file system after
adding a new buildroot file system. Here is a list of the files and a brief
explanation on why it's convenient to add or replace them:

root/.bash_profile [added 'ulimit -c unlimited to allow core dumps to be created]
root/.bashrc
etc/profile [added 'ulimit -c unlimited to allow core dumps to be created]
etc/fstab [Tells the system how to mount extra NFS file systems like /home/default]
etc/init.d/S90local [Mounts /home/default]
etc/resolv.conf [Location of DNS servers when your not using DHCP to boot the kernel]
etc/TZ [Your time zone, currently set to California TZ]
etc/dropbear/dropbear_rsa_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/dropbear/dropbear_dss_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/ssh_config [Typically tailored with things like allowing root logins via ssh]
etc/ssh_host_dsa_key [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_dsa_key.pub [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_key
etc/ssh_host_key.pub
etc/ssh_host_rsa_key
etc/ssh_host_rsa_key.pub
etc/sshd_config [Typically tailored with things like allowing root logins via ssh]
etc/rndc.key
etc/random-seed [Generated during 1st boot]
etc/passwd [Changed default user's shell to bash]
etc/shadow [Changed default and root users login password to 'linux1', need to ssh to the board]
exports/ [The path to where the board can mount extra file systems like /home/default.
fac/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]
fac/vol6/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]

Now lets assume your going to stay with these changes and modify them after taring in these changes.
Here we add the tar ball files to the boards root filesystem.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''tar xf /exports/default/'''

This is a good time to edit a few files on the boards file system
before boot it.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''vi etc/fstab''' [Change fstab entry for /home/default and others to your taste]
$ '''vi etc/init.d/S90local''' [You might want to disable mounting of NFS file systems on the 1st Boot and add this once you try it manually]

== Booting Linux for the 1st Time ==

We should now be ready to boot linux on your LX200. You have exported the root file-system and made the
kernel available to a TFTP server. Now let's start with hitting the reset button on the LX200 and it should
auto-boot the kernel, resulting in output such as [[HiFi2_Board_Example_Linux_Boot_Log|this example log]].

== Tailoring your system prior to developing for HiFi 2 ==

To make your experience more pleasant we suggest you tailor your environment.
Here are some of the changes that we have found helpful:

1. Add a root password to that you can login with ssh.
2. Run rdate with an ntp server on booting.
3. Add NFS mounts to /etc/fstab for your code and buildroot code.
4. Copy in previous ssh server encryption keys to /etc/dropbear to speed up your initial boot.
5. Mount a 'default' user home directory with:
a. Linux Test Suite pre-patch to test the system
b. Audio test example files
c. Copies of Mplayer and its Plug-ins from Buildroot modified slightly to make installation easy.
d. Misc audio test programs.

[TO BE DONE - Where to get 'default' user home directory tar ball and 1st boot patch]

== Building Linux Applications ==

=== Building Linux Applications Using GCC on the Host ===

You can use the open source toolchain included in the buildroot tree.

Given the location of the buildroot tree and the name of the core:

$ setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12
$ setenv CORENAME test_mmuhifi_c3

You can either set the PATH and invoke tools prefixed with <tt>xtensa_${CORENAME}-linux-</tt> :

$ setenv PATH ${BUILDROOT_DIR}/build_xtensa_${CORENAME}/staging_dir/usr/bin:${PATH}
$ xtensa_test_mmuhifi_c3-linux-gcc -g hello.c -o hello
$ xtensa_test_mmuhifi_c3-linux-gdb hello

or alternatively invoke the tools with absolute paths:

$ ${BUILDROOT_DIR}/build_xtensa_test_mmuhifi_c3/staging_dir/usr/bin/xtensa_test_mmuhifi_c3-linux-gcc -g hello.c -o hello
$ ${BUILDROOT_DIR}/build_xtensa_test_mmuhifi_c3/staging_dir/usr/bin/xtensa_test_mmuhifi_c3-linux-gdb hello

=== Building Linux Applications Using GCC on the Target ===
This is the simplest. (Much slower of course at 45 MHz across a slow Ethernet link than on a workstation,
but convenient.) Just login to the target system and use the native <tt>cc</tt>.

=== Building Linux Applications Using XCC (Xtensa Tools) ===

There are two approaches to compiling with Tensilica's XCC compiler (part of Xtensa Tools).
The normal one, described below, is to initially setup a virtual core
that has built-in references to the library and include files for the target Linux system.
Alternatively, one could skip this initial setup and just use Xtensa Tools to create
object files and link them using host or target GCC tools.
However, such objects must be built without dependencies on such things as the C library,
which can be harder than it sounds (for example, flags and structures, such as <tt>open()</tt>'s <tt>O_EXCL</tt>
and <tt>stat()</tt>'s <tt>struct stat</tt>, must be avoided because their definitions likely differ between the
Xtensa Tools' default C library and the Linux uClibc library).
''('''Note''': Codecs such as MP3 and AAC are typically written in C with TIE extensions and can only be compiled with XCC.)''

Section 4.3 of the latest ''Xtensa OSKit Guide'' (from Tensilica's
RC-2009.0 release) describes how to setup XCC to compile Linux applications.
For full details, see the guide. A summary follows.

==== Initial Setup ====

The XTENSA_TOOLS_ROOT, XTENSA_ROOT, BUILDROOT_DIR, and TARGET_SYSROOT
environment variables must be set according to where things were installed;
values shown here are for illustration only. The CORENAME variable, set correctly
below for this board, reflects
the name of the core as known to open source tools (as opposed to XTENSA_CORE
which is the core name as known to Xtensa Tools; both happen to match here).

$ setenv USER someuser
$ setenv XTENSA_ROOT /home/${USER}/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
$ setenv XTENSA_TOOLS_ROOT /home/${USER}/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools
$ setenv TARGET_SYSROOT /exports/LINUX_ROOT.HiFi-2
$ setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12

$ setenv CORENAME test_mmuhifi_c3

$ cd ${BUILDROOT_DIR}
$ ${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install \
--sysroot=./build_xtensa_${CORENAME}/staging_dir \
--linux-gcc=./build_xtensa_${CORENAME}/staging_dir/usr/bin/xtensa_${CORENAME}-linux-gcc

==== Regular Use ====

Assuming the above completed successfully, you can now build applications using Xtensa Tools. First set the usual environment variables (assuming values of XTENSA_ROOT and XTENSA_TOOLS_ROOT used earlier):

$ setenv XTENSA_CORE default
$ setenv XTENSA_SYSTEM ${XTENSA_ROOT}-linux/config
$ setenv PATH ${XTENSA_TOOLS_ROOT}/bin:${PATH}

Now you can use Xtensa Tools to assemble, compile, and link applications for the Linux target specified during setup. For example:

$ echo '#include <stdio.h>' > hello.c
$ echo 'int main() {printf("Hello!\n");return 0;}' >> hello.c
$ xt-xcc -g hello.c -o hello

Then copy it where the target can see it:

$ cp hello ${TARGET_SYSROOT}/root

And run it on the target:

[root@hifi ~]# /root/hello
Hello!
[root@hifi ~]#

Here's a more interesting example that uses Tensilica TIE features.
(This cannot be compiled using GCC.)

$ cd ${TARGET_SYSROOT}/home/default/Audio_Tests
$ xt-xcc -g hifitest.c -o hifitest

In a ssh termulator window on the board you can now run hifitest:

[root@hifi ~]# '''cd /home/default/Audio_Tests/'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:23178; Eatting cpu; time:0 '''<control-C>'''

[root@hifi Audio_Tests]#

Here is the source code for the [[hifitest.c|hifitest.c source file]] used above.

=== Limited (No Setup) Use of Xtensa Tools for Linux Targets ===

Below we illustrate compiling a simple audio test program on a workstation.
We start by referring to the XTENSA tools build by Xplorer, putting XCC into our search path and set the standard XTENSA_* environment variables.
For example:

setenv XTENSA_CORE test_mmuhifi_c3
setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config
setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin

setenv PATH ${XTENSA_TOOLS}:${PATH}

[piet@fc9desktop Tests] $ '''cd /exports/default/Audio_Tests''' [NOTE: This is being done on a Workstation]
[piet@fc9desktop Audio_Tests]$ '''xt-xcc -g3 -O0 -fPIC -c hifitest.c'''

Next we link the object on the LX200 board and run gdb on the TIE enhanced code:

[root@hifi Audio_Tests]# '''gcc -g hifitest.o -o hifitest'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:4640; Eatting cpu; time:0
cnt:0x0, pid:4640; Eating Tie; time:7
^C
[root@hifi Audio_Tests]# '''gdb ./hifitest''' [NOTE: This is being done on the LX200 board]
GNU gdb 6.6
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "xtensa_test_mmuhifi_c3-linux-uclibc"...
Using host libthread_db library "/lib/libthread_db.so.1".
(gdb) '''break main'''
Breakpoint 1 at 0x400401: file /exports/default/Audio_Tests/hifitest.c, line 20.
(gdb) '''run'''
Starting program: /home/default/Audio_Tests/hifitest

Breakpoint 1, main (argc=1, argv=0x3fb3fab4)
at /exports/default/Audio_Tests/hifitest.c:20
20 time_t time0 = time(NULL);
(gdb) '''step'''
21 time_t time1 = time(NULL);

== Compiling Generic GPL Packages ==

For your development you may want to add a few GPL packages that you find helpful.
This can be done on the LX200 just as you would on a normal workstation, though
much slower. For example here we configure and build a few common GPL packages:

[[Building the Strace Package]]

[[Building the vim Package]]

== Compiling the Mplayer Plugins and linking them with MPEG-1 Audio Layer 3 (MP3) and MPEG-4 AAC Codecs ==

Mplayer is provided as an example environment for developing and testing Codecs and HiFi 2 software. There
are two ways to build Mplayer and the plug-in modules that use the codecs. The buildroot
tree (pulled with git) has a copy of mplayer and the plugins that can be built in the
snapshot via 'make menuconfig'. This is a good environment to use once codecs are
developed and debugged.

To facilitate development the mplayer packages can be copied to your NFS mounted development
environment. From there you can just configure mplayer to compile on the board and debug
mplayer and your codecs with gdb locally.

In the default user home directory we have a directory /home/default/buildroot_mplayer_stuff
with a copy of three of the mplayer packages:

[root@hifi buildroot_mplayer_stuff]# '''ls -l'''
drwxr-xr-x 34 root root 4096 Nov 10 05:01 MPlayer-1.0rc2/
drwxr-xr-x 4 root root 4096 Nov 10 01:36 mplayer_hifi2_aacplus_v2_plugin/
drwxr-xr-x 3 root root 4096 Nov 10 00:57 mplayer_hifi2_mp3_plugin/

they were simply copied from the buildroot-xtensa-HiFi2-Snapshot.2/package directory.

To get your development environment ready to compile the mplayer plug-ins you need
to configure Mplayer to use the local C compiler and linker:

# '''cd /home/default/buildroot_mplayer_stuff/MPlayer-1.0rc2/'''
# '''CFLAGS="-g3" ./configure'''

This will take about 15 minutes to configure. After that you can build the
plugins or mplayer. If you want to recompile mplayer it's likely best/necessary
to use the same args to .configure as used by buildroot:

.CFLAGS="-g3" ./configure \
--prefix=/usr \
--confdir=/etc/mplayer \
--with-extraincdir=/usr/include \
--with-extralibdir=/lib \
--disable-gui \
--enable-mad \
--enable-fbdev \
--disable-mencoder \
--disable-dvdnav \
--disable-dvdread \
--disable-dvdread-internal \
--disable-libdvdcss-internal \
--disable-big-endian \
--disable-nemesi \
--disable-tv \
--enable-dynamic-plugins

We are currently able to compile most of mplayer on the LX200 but
due to space limitations it's not possible to compile it -O0.

Now, let's focus on compiling linking the plugins. They are a nice
example of compiling an audio application on the LX200.

We modified the Makefile of the codes slightly, and will make it available.
These additions just instruct make how to install the plugins as explained
in the Chapter 7 of the Linux HiFi application note.

For example the mp3 plugin has this addition:

target_install::
-mkdir /etc/mplayer
cp codecs.conf /etc/mplayer
-mkdir /usr/lib/mplayer
cp ad_xa_mp3_dec.so /usr/lib/mplayer/
cp xa_mp3_dec.so /usr/lib/mplayer
chmod 755 /usr/lib/mplayer/ad_xa_mp3_dec.so
chmod 755 /usr/lib/mplayer/xa_mp3_dec.so

It's just providing a codec config file for mplayer at '''/etc/mplayer/codecs.conf''' and
copying the plug-in to '''/usr/lib/mplayer'''. To install the mp3 codec plugin and mplayer
config file just copy your codec that was compiled with '''xcc''' to the directory, compile it,
and install.

# '''cd /fac/vol6/audio/release/bin/l32r_LE5_pic'''
# '''cp xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz /tmp'''
#
# '''cd /home/default/buildroot_mplayer_stuff'''
# '''cd mplayer_hifi2_mp3_plugin'''
# '''cp /tmp/xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz .'''
# '''gunzip xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz'''
# '''tar xf xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tar'''
# '''make'''
# '''make target_install'''

The unpacking of the Tensilica mp3 codec tarball will install the following files:

xa_mp3_dec/
xa_mp3_dec/README
xa_mp3_dec/include/
xa_mp3_dec/include/mp3_dec/
xa_mp3_dec/include/mp3_dec/xa_mp3_dec_api.h
xa_mp3_dec/include/xa_apicmd_standards.h
xa_mp3_dec/include/xa_error_handler.h
xa_mp3_dec/include/xa_error_standards.h
xa_mp3_dec/include/xa_memory_standards.h
xa_mp3_dec/include/xa_type_def.h
xa_mp3_dec/test/
xa_mp3_dec/test/build/
xa_mp3_dec/test/build/ldscript_stream_data.txt
xa_mp3_dec/test/build/makefile_testbench_sample
xa_mp3_dec/test/build/paramfilesimple.txt
xa_mp3_dec/test/include/
xa_mp3_dec/test/include/id3_tag_decode.h
xa_mp3_dec/test/src/
xa_mp3_dec/test/src/xa_mp3_dec_sample_testbench.c
xa_mp3_dec/test/src/id3_tag_decode.c
xa_mp3_dec/test/src/stream_data.c
xa_mp3_dec/test/src/xa_mp3_dec_error_handler.c
xa_mp3_dec/test/test_inp/
xa_mp3_dec/test/test_inp/compl.mp3
xa_mp3_dec/test/test_inp/hihat.mp3
xa_mp3_dec/test/test_out/
xa_mp3_dec/test/test_out/force_mkdir.txt
xa_mp3_dec/test/test_ref/
xa_mp3_dec/test/test_ref/compl_24bit.wav
xa_mp3_dec/test/test_ref/hihat_16bit.wav
xa_mp3_dec/lib/
xa_mp3_dec/lib/xa_mp3_dec.a
xa_mp3_dec/doc/
xa_mp3_dec/doc/HiFi2-MP3-DecoderProgrammersGuide.pdf

[TO BE DONE - Add missing C file, make clean deletes it!]

The xa_mp3_dec.a archive will be used by the Makefile in
the mplayer_hifi2_mp3_plugin directory to make the mplayer plug-in.
Section 6 of the '''Using Tensilica HiFi 2 Codec on Xtensa Linux with MPlayer'' Application Note
has a detailed description of the encapsulation process used by the plug-ins.

== Adding a Codec to Buildroot ==

Xtensa developers provide detailed instructions on building the root filesystem and the Linux kernel.
* [[Buildroot_Build_Instructions|Instructions for building and booting Linux (buildroot)]].

Building a comprehensive development environment with buildroot can be a challenging experience and
worthy of providing some tips on process.
Here are notes of the configs used for the three menuconfigs in this 2nd snapshot
provided with SMP additions:
$ '''make [[HiFi-2 snapshot_2 SMP Snapshot menuconfig | menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP uclibc-menuconfig | uclibc-menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP busybox-menuconfig | busybox-menuconfig]]'''

[TO BE DONE - making a new tar ball of saved files, building buildroot, ...]

== Known Problems being investigated, suggested that you know about and possibly avoid ==

1. Using NFS mounts with default parameters causes memory congestion. Use these mount options:

'''vers=2,rsize=4096,wsize=4096,hard,nointr,nolock,nolock,timeo=11,retrans=3,noauto'''

this is extremely important to add to your /etc/fstab on the target.

2. Can't swap over NFS yet, memory can get tight and cause application to be killed.
a. Trying procedure documented in U-Boot Manual.

3. Building the C development with X11 doesn't work with buildroot.

4. Though Mplayer plug-in can be compiled, Mplayer can be compiled but still has a few issues:
a. Can't be compiled -O0 due to limited memory while compiling one file,
b. Compiler infrequently crashes and make has to be restarted.
Not seeing this problem with root build on Fedore Core 9.
Perhaps this was caused by debug kernel or LTP using all of the memory.

5. U-boot has flash problems:
a. Sectors marked Read-Only come up Writeable after a reset/reboot.
b. Flashing a large number of sectors (like the kernel) sometimes
results in an Error (Ex: Vcc) and had to be retried.
c. Saw environment variables trashed on reset/reboot once.
It's possible that U-boot in flash could get whacked
and the board will need to be re-flashed. During a week
or two of testing I haven't see environment getting whacked.

6. gdb appears to be crashing on target when debugging
on latest root with uclibc left unstriped and with debug;
core dump sent to maxim.

7. U-Boot seems to hang periodically when loading the kernel with
tftp; appears to be worse when network activity is high.

8. 'top' command only shows all cpu's or cpu0; cpu 1 and 2 missing.

9. Program dore dump require ulimit -c to be set but root uses /bin/sh
which is a link to bash but causes it to skip running the bash
startup scripts. Changing root to /bin/bash seems to mess up
ssh logins.

10. For kernel to be compiled on the LX200 (for self checking:
a. Xtensa makefile needs to be fixed:
CC init/do_mounts.o
LD init/mounts.o
/bin/sh: xtensa_test_mmuhifi_c3-linux-uclibc-ld: command not found
make[1]: *** [init/mounts.o] Error 127

b. Need to add ncurses-devel package for 'make menuconfig'

11. Copying vim-7.2.tar from /home/default/src to /usr/local/src resulted
in a corrupt tar header. Apparently we have a NFS bug lurking in the kernel.
On server tar file looks like this:
vim72/000755 001750 001750 00000000000 11047345123 012000 5
ustar00moolmool000000 000000
vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0
ustar00moolmool000000 000000
README.txt for version 7.2 of Vim: Vi IMproved.

On the target/client it's different:
vim72/000755 001750 001750 00000000000 11047345123 012000 5ustar00moolmool000000 000000 vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0ustar00moolmool000000 000000 README.txt for version 7.2 of Vim: Vi IMproved.

=Further reading=

Main Xtensa Linux resources are:

* [http://linux-xtensa.org/ Linux/Xtensa Wiki]
* [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions Buildroot Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Kernel_Build_Instructions Kernel Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Setting_up_U-Boot Setting up U-Boot]
* [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List]
* http://git.linux-xtensa.org/cgi-bin/git.cgi GIT Repositories]

=Thanks to=

* piet
* marc
* dan

And the rest of the people in the Linux-Xtensa mailing list, if you cannot go through some of the steps, don't hesitate to ask on the mailing list, there's always somebody willing to help you!

SMP HiFi 2 Development Board

2009-12-02T08:02:10Z

Marc: /* Building Linux Applications Using GCC on the Target */

This is a "community" guide for how to use the LX200 board based 3-core SMP HiFi-2 Development environment.
If something doesn't work or isn't covered in this guide, please feel free to ask at the [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List].

<div style="margin:0; margin-top:10px; margin-right:10px; border:1px solid #dfdfdf; padding:0 1em 1em 1em; background-color:#ffffcc; align:right; ">
'''NEWS:'''

Some general notes on these instructions:

* They are a work in progress.

* The following was tested on x86 machines running RedHat Fedora Core 5.

* Buildroot build with Fedora Core 9 also seems to be fine; perhaps better than when built on Fedore Core 5.

</div>

== Introduction ==

This document is addressed to someone who received an LX200 board setup by Tensilica
for HiFi2 development.

This document goes over the steps needed to set up the LX200 board for HiFi2 development.
To summarize:
* Setup the board. It likely comes with U-boot preinstalled, ready to boot a linux kernel.
* Install '''git'''.
* Download buildroot and linux kernel trees, pre-configured and built for HiFi-2 development.
* Setup a TFTP server to provide the linux kernel to U-Boot.
* Setup an NFS server to export a linux root file system.
* Setup the Linux kernel to boot from the root file system provided by the NFS server.
Once the development board is up and running, this document:
* Suggests a possible way to tailor the board for easy codec development.
* Shows how to add the Tensilica provided codec packages to the Mplayer packages used by Buildroot, including building and installing.
* Demonstrates two procedures for compiling, linking, and debugging codecs.

All development is expected to be done on a Linux host. (One can in principle use Windows to
develop target libraries. However, linking and subsequent steps need to be done in Linux.)

== Downloading the Latest HiFi-2 Buildroot and Kernel Snapshots ==

The HiFi-2 development environment is maintained in a source code version control system named 'git'. The '''git''' tools are useful when working with this development environment, though they are not strictly necessary. This document generally assumes the use of '''git''', which provides more opportunities for modifying this environment as needed (e.g. building more optional buildroot packages). But points out alternatives to allow getting up and running without having to set it up.

=== Installing git ===

To install '''git''', download a recent tarball from the [http://www.kernel.org/pub/software/scm/git/ official site]. For example, <tt>cd</tt> to a location with enough disk space, and do:

$ '''wget http://www.kernel.org/pub/software/scm/git/git-1.6.5.tar.gz'''

Unpack the tarball, and make and install it. Here we show how to install it to your ~/bin directory:

$ '''gunzip git-1.6.5.tar.gz'''
$ '''tar xf git-1.6.5.tar'''
$ '''cd git-1.6.5'''
$ '''make'''
$ '''make install'''

The git makefile can be instructed to install '''git''' to <tt>/usr/local/bin</tt> as root for system wide access:

$ '''cp git-1.6.5.tar.gz''' /tmp
$ '''su'''
Password:
# '''cd /usr/local/src/'''
# '''mkdir git'''
# '''cd git'''
# '''cp /tmp/git-1.6.5.tar.gz .'''
# '''gunzip git-1.6.5.tar.gz'''
# '''tar xf git-1.6.5.tar'''
# '''cd git-1.6.5'''
# '''make prefix=/usr/local'''
# '''make install'''

See the '''INSTALL'' instruction at the top of the git src directory for details.

Using '''git''' provides easy access to the binaries used to bring up the codec development environment, and leaves in place the infrastructure to modify and build this environment should you wish to. Any changes to '''git'''-managed source trees are easily observed with the '''git''' tools.

=== Installing the Buildroot Snapshot ===

''Note: The HiFi-2 snapshot is in the process of being made.''

To install the buildroot environment (toolchain and root filesystem), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot'''
$ '''cd buildroot-xtensa-HiFi2-Snapshot'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP''' [56 key strokes]
$ '''git checkout snapshot_2+SMP''' [28 key strokes]

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).

You can examine the tree (git repository) and its history visually using <tt>git gui</tt>.
The git GUI is a faster and more convenient method for checking out the HiFi-2 snapshot. To check out the snapshot_2+SMP branch simply run the command 'git gui' and then pull down the branch->create menu. Next select <>Match Tracking Branch Name and click on ''origin/snapshot_2+SMP''. Finally hit the Create Button.

$ '''git gui''''' [8 key strokes]
[Branch] -> Create... [2 key strokes]
<> Match Tracking Branch Name [1 key stroke]
<> Tracking Branch [1 key stroke]
origin/snapshot_2+SMP [1 key stroke]
[Create] [1 key stroke]
[Reposirory]--> Quit [2 key strokes]

If there are issues installing '''git''', as a last resort, an alternative is ftp (may not always get updated, is currenty our of date, waste disk space, so may be dropped at some point):

http://www.linux-xtensa.org/pub/snapshots/buildroot-xtensa-smp.2-Nov-2009.tar.gz

=== Installing the Linux Kernel Snapshot ===

To install the Linux kernel environment (kernel src, config, and HiFi-2 kernel U-Boot image), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp'''
$ '''cd kernel/xtensa-2.6.29-smp'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
$ '''git checkout snapshot_2+SMP'''

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).
As in the build root case, you can also do it from via git gui using the same proceedure
mantioned above.

Now, assuming we are still in the kernel '''xtensa-2.6.29-smp''' directory
copy the kernel U-Boot Image ('''uImage''') to the tftp directory; Ex:

$ '''cp arch/xtensa/boot/uImage /tftpboot/uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'''

NOTE: On some system, like Fedora Core 9, the tftpboot directory has been moved to /var/lib/tftpboot.
In this case we recomend that you just added a symbolic pointer from /etc to /var/lib/tftpboot:

$ '''su'''
# '''cd /etc'''
# '''/var/lib/tftpboot/ tftpboot'''
# '''ls -ld tftpboot'''
lrwxrwxrwx 1 root root 18 2009-11-23 21:14 tftpboot -> /var/lib/tftpboot/
#

== Setting up a TFTP Server to provide the Linux kernel to U-Boot ==

The TFTP service is part of the xinetd and is installed on Fedora workstations.
You can see that it's installed with the check config command which manages the
/etc/rc.d/init.d startup scripts and with the yum search command:

$ '''chkconfig --list'''
NetworkManager 0:off 1:off 2:off 3:off 4:off 5:off 6:off
NetworkManagerDispatcher 0:off 1:off 2:off 3:off 4:off 5:off 6:off
acpid 0:off 1:off 2:off 3:on 4:on 5:on 6:off
.
.
.
xfs 0:off 1:off 2:on 3:on 4:on 5:on 6:off
xinetd 0:off 1:off 2:off 3:on 4:on 5:on 6:off
ypbind 0:off 1:off 2:off 3:on 4:on 5:on 6:off
yum 0:off 1:off 2:off 3:off 4:off 5:off 6:off

xinetd based services:
amanda: off
auth: off
.
.
.
rsync: off
'''tftp: on''' [NOTE that tftp is enabled]
time: off
time-udp: off
uucp: off
$
$
$
$ '''yum search tftp-server'''
Loading "installonlyn" plugin
Searching Packages:
.
.
.
Reading repository metadata in from local files
.
.
.
'''tftp-server.i386 0.41-1.2.1 installed''' [NOTE that tftp server is installed as part of the inet daemon]
Matched from:
tftp-server
The Trivial File Transfer Protocol (TFTP) is normally used only for
booting diskless workstations. The tftp-server package provides the
server for TFTP, which allows users to transfer files to and from a
remote machine. TFTP provides very little security, and should not be
enabled unless it is expressly needed. The TFTP server is run from
/etc/xinetd.d/tftp, and is disabled by default on Red Hat Linux systems.
[piet@pdelaney_fc5 ~]$

TFTP is not normally enabled, to enable it just edit the file /etc/xinetd.d/tftp
and change the disable field to no:

# default: off
# description: The tftp server serves files using the trivial file transfer \
# protocol. The tftp protocol is often used to boot diskless \
# workstations, download configuration files to network-aware printers, \
# and to start the installation process for some operating systems.
service tftp
{
socket_type = dgram
protocol = udp
wait = yes
user = root
server = /usr/sbin/in.tftpd [NOTE: /var/lib/tftpboot on Fedora Core 9]
server_args = -s /tftpboot
'''disable = no'''
per_source = 11
cps = 100 2
flags = IPv4
}

== Setting up an NFS Server to export the Root Filesystem ==

The LX200 board running Linux needs to mount its root filesystem over NFS.
This filesystem was built using buildroot into a cpio format file,
and left in:

buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2/rootfs.xtensa_test_mmuhifi_c3.cpio

We will also be adding an additional minor changes to make your development environment more comfortable.

Pick a place on your workstation to export your root and unpack the cpio file into that directory.
For example here we will set up an export in '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''':

$ '''cd buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2'''
$ '''WHERE=$PWD'''
$ '''mkdir -p /exports/LINUX_ROOT.HiFi-2'''
$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''cpio -i < $WHERE/rootfs.xtensa_test_mmuhifi_c3.cpio'''

Next add a line to /etc/exports:

/exports *(rw,no_root_squash,sync,no_wdelay)

and restart you nfs services:

$ '''/etc/rc.d/init.d/nfs restart'''
or
$ '''/sbin/chkconfig nfs on'''

The showmount command should show your NFS file system now being exported:

$ '''showmount -e'''
Export list for mypc.foobar.com:
/exports *
$

== Configuring U-Boot to Boot Linux ==

Your LX200 board should have arrived with U-Boot installed in the flash ready to use.
The board has a DIP switch (next to the power on/off switch) that provides the 6 LSBs
of the Ethernet MAC, in switch positions 1 thru 6.

DIP Swithes for MAC: 1 2 3 4 5 6 7 8 ethaddr=00:50:C2:13:6f:0a
Little Endian: 0 1 0 1 0 0 * *
^
|
+------ Enables booting U-Boot from Flash

DIP switch 8 should be shipped in the ON position to enable U-Boot booting from flash.
See Sections 4.2.3 and 4.2.4 of the '''Tensilica Avnet (XT-AV200) Board User's Guide'''
for details. Make sure to select a unique MAC address for you board.

Next, connect a serial interface to a text based terminal emulation program,
set to 38400 bps, no parity, 1 stop bit, no handshaking.
For an example of setting [http://en.wikipedia.org/wiki/Minicom minicom]
for this, see [[minicom_xtboard_setup|here]].

Many users of this board are interested in developing codecs and/or HiFi 2 software and will prefer to just boot linux with the root file system we just described how to export on your NFS server. We will use git now to pull a snapshot of a performance 2.6.29 linux kernel and configure U-Boot to automatically boot it after a power cycle.

U-Boot> '''setenv serverip 192.168.11.55''' [TFTP server IP Address: RTOS-LAB2]
U-Boot> '''setenv nfsroot_server 192.168.11.55''' [Root NFS Servers IP Address: My Workstation]
U-Boot> '''setenv ipaddr 192.168.11.155''' [HOST IP address]
U-Boot> '''setenv bootfile uImage.xtensa-2.6.29-smp.test_mmuhifi_c3''' [File to fetch with TFTP and pass to bootm]
U-Boot> '''setenv root-path /exports/LINUX_ROOT.HiFi-2''' [WARNING: Limit path to < 50 characters]
U-Boot> '''setenv bootargs_using_bootp console=ttyS0,38400 ip=bootp root=nfs coredump_filter=0xff''' [Args passed to Linux while booting with BOOTP proto]
U-boot> '''setenv bootargs console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=${nfsroot_server}:${root-path}''' [Args passed to Linux while booting with DHCP proto]
U-boot> '''setenv bootcmd tftpboot\; bootm''' [Boot Linux after fetching it with TFTP]
U-Boot> '''setenv bootdelay 20''' [Delay 20 seconds before booting automaticaly]
U-Boot> '''setenv autostart yes''' [Boot automatically on power-up/reset]
U-Boot> '''saveenv'''
U-Boot>

'''[REMIND: Update the above procedure, show two or thee approaches (ip, dhcp, bootp)]'''

== Tailoring your system prior to Booting ==

There are a few tweaks that developers have found convenient to add to the the root file-system before booting.
As an initial environment for developing we suggest mounting a /home/default files-system that has number of
files useful for getting started. Find another place to tar in the tar ball with the default users file system.
We chose to include this close to the cpio file with the root file-system. Copy the tar bar to where you are
exporting you root file-system and next to it add the 'default' users file-system:

$ '''cd /export'''
$ '''cp /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.10/binaries/default.tar .'''
$ '''tar xf default.tar'''
$ '''cd default'''
$ '''ls'''
[TO BE ADDED]

Notice a file tar ball called '''saved_files.tar'''. This ia a tar file of files that
developers have found convenient to add and replace on the root file system after
adding a new buildroot file system. Here is a list of the files and a brief
explanation on why it's convenient to add or replace them:

root/.bash_profile [added 'ulimit -c unlimited to allow core dumps to be created]
root/.bashrc
etc/profile [added 'ulimit -c unlimited to allow core dumps to be created]
etc/fstab [Tells the system how to mount extra NFS file systems like /home/default]
etc/init.d/S90local [Mounts /home/default]
etc/resolv.conf [Location of DNS servers when your not using DHCP to boot the kernel]
etc/TZ [Your time zone, currently set to California TZ]
etc/dropbear/dropbear_rsa_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/dropbear/dropbear_dss_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/ssh_config [Typically tailored with things like allowing root logins via ssh]
etc/ssh_host_dsa_key [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_dsa_key.pub [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_key
etc/ssh_host_key.pub
etc/ssh_host_rsa_key
etc/ssh_host_rsa_key.pub
etc/sshd_config [Typically tailored with things like allowing root logins via ssh]
etc/rndc.key
etc/random-seed [Generated during 1st boot]
etc/passwd [Changed default user's shell to bash]
etc/shadow [Changed default and root users login password to 'linux1', need to ssh to the board]
exports/ [The path to where the board can mount extra file systems like /home/default.
fac/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]
fac/vol6/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]

Now lets assume your going to stay with these changes and modify them after taring in these changes.
Here we add the tar ball files to the boards root filesystem.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''tar xf /exports/default/'''

This is a good time to edit a few files on the boards file system
before boot it.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''vi etc/fstab''' [Change fstab entry for /home/default and others to your taste]
$ '''vi etc/init.d/S90local''' [You might want to disable mounting of NFS file systems on the 1st Boot and add this once you try it manually]

== Booting Linux for the 1st Time ==

We should now be ready to boot linux on your LX200. You have exported the root file-system and made the
kernel available to a TFTP server. Now let's start with hitting the reset button on the LX200 and it should
auto-boot the kernel, resulting in output such as [[HiFi2_Board_Example_Linux_Boot_Log|this example log]].

== Tailoring your system prior to developing for HiFi 2 ==

To make your experience more pleasant we suggest you tailor your environment.
Here are some of the changes that we have found helpful:

1. Add a root password to that you can login with ssh.
2. Run rdate with an ntp server on booting.
3. Add NFS mounts to /etc/fstab for your code and buildroot code.
4. Copy in previous ssh server encryption keys to /etc/dropbear to speed up your initial boot.
5. Mount a 'default' user home directory with:
a. Linux Test Suite pre-patch to test the system
b. Audio test example files
c. Copies of Mplayer and its Plug-ins from Buildroot modified slightly to make installation easy.
d. Misc audio test programs.

[TO BE DONE - Where to get 'default' user home directory tar ball and 1st boot patch]

== Building Linux Applications ==

=== Building Linux Applications Using GCC on the Host ===
TBD

=== Building Linux Applications Using GCC on the Target ===
This is the simplest. (Much slower of course at 45 MHz across a slow Ethernet link than on a workstation,
but convenient.) Just login to the target system and use the native <tt>cc</tt>.

=== Building Linux Applications Using XCC (Xtensa Tools) ===

There are two approaches to compiling with Tensilica's XCC compiler (part of Xtensa Tools).
The normal one, described below, is to initially setup a virtual core
that has built-in references to the library and include files for the target Linux system.
Alternatively, one could skip this initial setup and just use Xtensa Tools to create
object files and link them using host or target GCC tools.
However, such objects must be built without dependencies on such things as the C library,
which can be harder than it sounds (for example, flags and structures, such as <tt>open()</tt>'s <tt>O_EXCL</tt>
and <tt>stat()</tt>'s <tt>struct stat</tt>, must be avoided because their definitions likely differ between the
Xtensa Tools' default C library and the Linux uClibc library).
''('''Note''': Codecs such as MP3 and AAC are typically written in C with TIE extensions and can only be compiled with XCC.)''

Section 4.3 of the latest ''Xtensa OSKit Guide'' (from Tensilica's
RC-2009.0 release) describes how to setup XCC to compile Linux applications.
For full details, see the guide. A summary follows.

==== Initial Setup ====

The XTENSA_TOOLS_ROOT, XTENSA_ROOT, BUILDROOT_DIR, and TARGET_SYSROOT
environment variables must be set according to where things were installed;
values shown here are for illustration only. The CORENAME variable, set correctly
below for this board, reflects
the name of the core as known to open source tools (as opposed to XTENSA_CORE
which is the core name as known to Xtensa Tools; both happen to match here).

$ setenv USER someuser
$ setenv XTENSA_ROOT /home/${USER}/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
$ setenv XTENSA_TOOLS_ROOT /home/${USER}/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools
$ setenv TARGET_SYSROOT /exports/LINUX_ROOT.HiFi-2
$ setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12

$ setenv CORENAME test_mmuhifi_c3

$ cd ${BUILDROOT_DIR}
$ ${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install \
--sysroot=./build_xtensa_${CORENAME}/staging_dir \
--linux-gcc=./build_xtensa_${CORENAME}/staging_dir/usr/bin/xtensa_${CORENAME}-linux-gcc

==== Regular Use ====

Assuming the above completed successfully, you can now build applications using Xtensa Tools. First set the usual environment variables (assuming values of XTENSA_ROOT and XTENSA_TOOLS_ROOT used earlier):

$ setenv XTENSA_CORE default
$ setenv XTENSA_SYSTEM ${XTENSA_ROOT}-linux/config
$ setenv PATH ${XTENSA_TOOLS_ROOT}/bin:${PATH}

Now you can use Xtensa Tools to assemble, compile, and link applications for the Linux target specified during setup. For example:

$ echo '#include <stdio.h>' > hello.c
$ echo 'int main() {printf("Hello!\n");return 0;}' >> hello.c
$ xt-xcc -g hello.c -o hello

Then copy it where the target can see it:

$ cp hello ${TARGET_SYSROOT}/root

And run it on the target:

[root@hifi ~]# /root/hello
Hello!
[root@hifi ~]#

Here's a more interesting example that uses Tensilica TIE features.
(This cannot be compiled using GCC.)

$ cd ${TARGET_SYSROOT}/home/default/Audio_Tests
$ xt-xcc -g hifitest.c -o hifitest

In a ssh termulator window on the board you can now run hifitest:

[root@hifi ~]# '''cd /home/default/Audio_Tests/'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:23178; Eatting cpu; time:0 '''<control-C>'''

[root@hifi Audio_Tests]#

Here is the source code for the [[hifitest.c|hifitest.c source file]] used above.

=== Limited (No Setup) Use of Xtensa Tools for Linux Targets ===

Below we illustrate compiling a simple audio test program on a workstation.
We start by referring to the XTENSA tools build by Xplorer, putting XCC into our search path and set the standard XTENSA_* environment variables.
For example:

setenv XTENSA_CORE test_mmuhifi_c3
setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config
setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin

setenv PATH ${XTENSA_TOOLS}:${PATH}

[piet@fc9desktop Tests] $ '''cd /exports/default/Audio_Tests''' [NOTE: This is being done on a Workstation]
[piet@fc9desktop Audio_Tests]$ '''xt-xcc -g3 -O0 -fPIC -c hifitest.c'''

Next we link the object on the LX200 board and run gdb on the TIE enhanced code:

[root@hifi Audio_Tests]# '''gcc -g hifitest.o -o hifitest'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:4640; Eatting cpu; time:0
cnt:0x0, pid:4640; Eating Tie; time:7
^C
[root@hifi Audio_Tests]# '''gdb ./hifitest''' [NOTE: This is being done on the LX200 board]
GNU gdb 6.6
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "xtensa_test_mmuhifi_c3-linux-uclibc"...
Using host libthread_db library "/lib/libthread_db.so.1".
(gdb) '''break main'''
Breakpoint 1 at 0x400401: file /exports/default/Audio_Tests/hifitest.c, line 20.
(gdb) '''run'''
Starting program: /home/default/Audio_Tests/hifitest

Breakpoint 1, main (argc=1, argv=0x3fb3fab4)
at /exports/default/Audio_Tests/hifitest.c:20
20 time_t time0 = time(NULL);
(gdb) '''step'''
21 time_t time1 = time(NULL);

== Compiling Generic GPL Packages ==

For your development you may want to add a few GPL packages that you find helpful.
This can be done on the LX200 just as you would on a normal workstation, though
much slower. For example here we configure and build a few common GPL packages:

[[Building the Strace Package]]

[[Building the vim Package]]

== Compiling the Mplayer Plugins and linking them with MPEG-1 Audio Layer 3 (MP3) and MPEG-4 AAC Codecs ==

Mplayer is provided as an example environment for developing and testing Codecs and HiFi 2 software. There
are two ways to build Mplayer and the plug-in modules that use the codecs. The buildroot
tree (pulled with git) has a copy of mplayer and the plugins that can be built in the
snapshot via 'make menuconfig'. This is a good environment to use once codecs are
developed and debugged.

To facilitate development the mplayer packages can be copied to your NFS mounted development
environment. From there you can just configure mplayer to compile on the board and debug
mplayer and your codecs with gdb locally.

In the default user home directory we have a directory /home/default/buildroot_mplayer_stuff
with a copy of three of the mplayer packages:

[root@hifi buildroot_mplayer_stuff]# '''ls -l'''
drwxr-xr-x 34 root root 4096 Nov 10 05:01 MPlayer-1.0rc2/
drwxr-xr-x 4 root root 4096 Nov 10 01:36 mplayer_hifi2_aacplus_v2_plugin/
drwxr-xr-x 3 root root 4096 Nov 10 00:57 mplayer_hifi2_mp3_plugin/

they were simply copied from the buildroot-xtensa-HiFi2-Snapshot.2/package directory.

To get your development environment ready to compile the mplayer plug-ins you need
to configure Mplayer to use the local C compiler and linker:

# '''cd /home/default/buildroot_mplayer_stuff/MPlayer-1.0rc2/'''
# '''CFLAGS="-g3" ./configure'''

This will take about 15 minutes to configure. After that you can build the
plugins or mplayer. If you want to recompile mplayer it's likely best/necessary
to use the same args to .configure as used by buildroot:

.CFLAGS="-g3" ./configure \
--prefix=/usr \
--confdir=/etc/mplayer \
--with-extraincdir=/usr/include \
--with-extralibdir=/lib \
--disable-gui \
--enable-mad \
--enable-fbdev \
--disable-mencoder \
--disable-dvdnav \
--disable-dvdread \
--disable-dvdread-internal \
--disable-libdvdcss-internal \
--disable-big-endian \
--disable-nemesi \
--disable-tv \
--enable-dynamic-plugins

We are currently able to compile most of mplayer on the LX200 but
due to space limitations it's not possible to compile it -O0.

Now, let's focus on compiling linking the plugins. They are a nice
example of compiling an audio application on the LX200.

We modified the Makefile of the codes slightly, and will make it available.
These additions just instruct make how to install the plugins as explained
in the Chapter 7 of the Linux HiFi application note.

For example the mp3 plugin has this addition:

target_install::
-mkdir /etc/mplayer
cp codecs.conf /etc/mplayer
-mkdir /usr/lib/mplayer
cp ad_xa_mp3_dec.so /usr/lib/mplayer/
cp xa_mp3_dec.so /usr/lib/mplayer
chmod 755 /usr/lib/mplayer/ad_xa_mp3_dec.so
chmod 755 /usr/lib/mplayer/xa_mp3_dec.so

It's just providing a codec config file for mplayer at '''/etc/mplayer/codecs.conf''' and
copying the plug-in to '''/usr/lib/mplayer'''. To install the mp3 codec plugin and mplayer
config file just copy your codec that was compiled with '''xcc''' to the directory, compile it,
and install.

# '''cd /fac/vol6/audio/release/bin/l32r_LE5_pic'''
# '''cp xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz /tmp'''
#
# '''cd /home/default/buildroot_mplayer_stuff'''
# '''cd mplayer_hifi2_mp3_plugin'''
# '''cp /tmp/xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz .'''
# '''gunzip xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz'''
# '''tar xf xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tar'''
# '''make'''
# '''make target_install'''

The unpacking of the Tensilica mp3 codec tarball will install the following files:

xa_mp3_dec/
xa_mp3_dec/README
xa_mp3_dec/include/
xa_mp3_dec/include/mp3_dec/
xa_mp3_dec/include/mp3_dec/xa_mp3_dec_api.h
xa_mp3_dec/include/xa_apicmd_standards.h
xa_mp3_dec/include/xa_error_handler.h
xa_mp3_dec/include/xa_error_standards.h
xa_mp3_dec/include/xa_memory_standards.h
xa_mp3_dec/include/xa_type_def.h
xa_mp3_dec/test/
xa_mp3_dec/test/build/
xa_mp3_dec/test/build/ldscript_stream_data.txt
xa_mp3_dec/test/build/makefile_testbench_sample
xa_mp3_dec/test/build/paramfilesimple.txt
xa_mp3_dec/test/include/
xa_mp3_dec/test/include/id3_tag_decode.h
xa_mp3_dec/test/src/
xa_mp3_dec/test/src/xa_mp3_dec_sample_testbench.c
xa_mp3_dec/test/src/id3_tag_decode.c
xa_mp3_dec/test/src/stream_data.c
xa_mp3_dec/test/src/xa_mp3_dec_error_handler.c
xa_mp3_dec/test/test_inp/
xa_mp3_dec/test/test_inp/compl.mp3
xa_mp3_dec/test/test_inp/hihat.mp3
xa_mp3_dec/test/test_out/
xa_mp3_dec/test/test_out/force_mkdir.txt
xa_mp3_dec/test/test_ref/
xa_mp3_dec/test/test_ref/compl_24bit.wav
xa_mp3_dec/test/test_ref/hihat_16bit.wav
xa_mp3_dec/lib/
xa_mp3_dec/lib/xa_mp3_dec.a
xa_mp3_dec/doc/
xa_mp3_dec/doc/HiFi2-MP3-DecoderProgrammersGuide.pdf

[TO BE DONE - Add missing C file, make clean deletes it!]

The xa_mp3_dec.a archive will be used by the Makefile in
the mplayer_hifi2_mp3_plugin directory to make the mplayer plug-in.
Section 6 of the '''Using Tensilica HiFi 2 Codec on Xtensa Linux with MPlayer'' Application Note
has a detailed description of the encapsulation process used by the plug-ins.

== Adding a Codec to Buildroot ==

Xtensa developers provide detailed instructions on building the root filesystem and the Linux kernel.
* [[Buildroot_Build_Instructions|Instructions for building and booting Linux (buildroot)]].

Building a comprehensive development environment with buildroot can be a challenging experience and
worthy of providing some tips on process.
Here are notes of the configs used for the three menuconfigs in this 2nd snapshot
provided with SMP additions:
$ '''make [[HiFi-2 snapshot_2 SMP Snapshot menuconfig | menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP uclibc-menuconfig | uclibc-menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP busybox-menuconfig | busybox-menuconfig]]'''

[TO BE DONE - making a new tar ball of saved files, building buildroot, ...]

== Known Problems being investigated, suggested that you know about and possibly avoid ==

1. Using NFS mounts with default parameters causes memory congestion. Use these mount options:

'''vers=2,rsize=4096,wsize=4096,hard,nointr,nolock,nolock,timeo=11,retrans=3,noauto'''

this is extremely important to add to your /etc/fstab on the target.

2. Can't swap over NFS yet, memory can get tight and cause application to be killed.
a. Trying procedure documented in U-Boot Manual.

3. Building the C development with X11 doesn't work with buildroot.

4. Though Mplayer plug-in can be compiled, Mplayer can be compiled but still has a few issues:
a. Can't be compiled -O0 due to limited memory while compiling one file,
b. Compiler infrequently crashes and make has to be restarted.
Not seeing this problem with root build on Fedore Core 9.
Perhaps this was caused by debug kernel or LTP using all of the memory.

5. U-boot has flash problems:
a. Sectors marked Read-Only come up Writeable after a reset/reboot.
b. Flashing a large number of sectors (like the kernel) sometimes
results in an Error (Ex: Vcc) and had to be retried.
c. Saw environment variables trashed on reset/reboot once.
It's possible that U-boot in flash could get whacked
and the board will need to be re-flashed. During a week
or two of testing I haven't see environment getting whacked.

6. gdb appears to be crashing on target when debugging
on latest root with uclibc left unstriped and with debug;
core dump sent to maxim.

7. U-Boot seems to hang periodically when loading the kernel with
tftp; appears to be worse when network activity is high.

8. 'top' command only shows all cpu's or cpu0; cpu 1 and 2 missing.

9. Program dore dump require ulimit -c to be set but root uses /bin/sh
which is a link to bash but causes it to skip running the bash
startup scripts. Changing root to /bin/bash seems to mess up
ssh logins.

10. For kernel to be compiled on the LX200 (for self checking:
a. Xtensa makefile needs to be fixed:
CC init/do_mounts.o
LD init/mounts.o
/bin/sh: xtensa_test_mmuhifi_c3-linux-uclibc-ld: command not found
make[1]: *** [init/mounts.o] Error 127

b. Need to add ncurses-devel package for 'make menuconfig'

11. Copying vim-7.2.tar from /home/default/src to /usr/local/src resulted
in a corrupt tar header. Apparently we have a NFS bug lurking in the kernel.
On server tar file looks like this:
vim72/000755 001750 001750 00000000000 11047345123 012000 5
ustar00moolmool000000 000000
vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0
ustar00moolmool000000 000000
README.txt for version 7.2 of Vim: Vi IMproved.

On the target/client it's different:
vim72/000755 001750 001750 00000000000 11047345123 012000 5ustar00moolmool000000 000000 vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0ustar00moolmool000000 000000 README.txt for version 7.2 of Vim: Vi IMproved.

=Further reading=

Main Xtensa Linux resources are:

* [http://linux-xtensa.org/ Linux/Xtensa Wiki]
* [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions Buildroot Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Kernel_Build_Instructions Kernel Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Setting_up_U-Boot Setting up U-Boot]
* [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List]
* http://git.linux-xtensa.org/cgi-bin/git.cgi GIT Repositories]

=Thanks to=

* piet
* marc
* dan

And the rest of the people in the Linux-Xtensa mailing list, if you cannot go through some of the steps, don't hesitate to ask on the mailing list, there's always somebody willing to help you!

SMP HiFi 2 Development Board

2009-12-02T07:57:12Z

Marc: /* Building Linux Applications Using XCC (Xtensa Tools) */ Intro and sections

This is a "community" guide for how to use the LX200 board based 3-core SMP HiFi-2 Development environment.
If something doesn't work or isn't covered in this guide, please feel free to ask at the [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List].

<div style="margin:0; margin-top:10px; margin-right:10px; border:1px solid #dfdfdf; padding:0 1em 1em 1em; background-color:#ffffcc; align:right; ">
'''NEWS:'''

Some general notes on these instructions:

* They are a work in progress.

* The following was tested on x86 machines running RedHat Fedora Core 5.

* Buildroot build with Fedora Core 9 also seems to be fine; perhaps better than when built on Fedore Core 5.

</div>

== Introduction ==

This document is addressed to someone who received an LX200 board setup by Tensilica
for HiFi2 development.

This document goes over the steps needed to set up the LX200 board for HiFi2 development.
To summarize:
* Setup the board. It likely comes with U-boot preinstalled, ready to boot a linux kernel.
* Install '''git'''.
* Download buildroot and linux kernel trees, pre-configured and built for HiFi-2 development.
* Setup a TFTP server to provide the linux kernel to U-Boot.
* Setup an NFS server to export a linux root file system.
* Setup the Linux kernel to boot from the root file system provided by the NFS server.
Once the development board is up and running, this document:
* Suggests a possible way to tailor the board for easy codec development.
* Shows how to add the Tensilica provided codec packages to the Mplayer packages used by Buildroot, including building and installing.
* Demonstrates two procedures for compiling, linking, and debugging codecs.

All development is expected to be done on a Linux host. (One can in principle use Windows to
develop target libraries. However, linking and subsequent steps need to be done in Linux.)

== Downloading the Latest HiFi-2 Buildroot and Kernel Snapshots ==

The HiFi-2 development environment is maintained in a source code version control system named 'git'. The '''git''' tools are useful when working with this development environment, though they are not strictly necessary. This document generally assumes the use of '''git''', which provides more opportunities for modifying this environment as needed (e.g. building more optional buildroot packages). But points out alternatives to allow getting up and running without having to set it up.

=== Installing git ===

To install '''git''', download a recent tarball from the [http://www.kernel.org/pub/software/scm/git/ official site]. For example, <tt>cd</tt> to a location with enough disk space, and do:

$ '''wget http://www.kernel.org/pub/software/scm/git/git-1.6.5.tar.gz'''

Unpack the tarball, and make and install it. Here we show how to install it to your ~/bin directory:

$ '''gunzip git-1.6.5.tar.gz'''
$ '''tar xf git-1.6.5.tar'''
$ '''cd git-1.6.5'''
$ '''make'''
$ '''make install'''

The git makefile can be instructed to install '''git''' to <tt>/usr/local/bin</tt> as root for system wide access:

$ '''cp git-1.6.5.tar.gz''' /tmp
$ '''su'''
Password:
# '''cd /usr/local/src/'''
# '''mkdir git'''
# '''cd git'''
# '''cp /tmp/git-1.6.5.tar.gz .'''
# '''gunzip git-1.6.5.tar.gz'''
# '''tar xf git-1.6.5.tar'''
# '''cd git-1.6.5'''
# '''make prefix=/usr/local'''
# '''make install'''

See the '''INSTALL'' instruction at the top of the git src directory for details.

Using '''git''' provides easy access to the binaries used to bring up the codec development environment, and leaves in place the infrastructure to modify and build this environment should you wish to. Any changes to '''git'''-managed source trees are easily observed with the '''git''' tools.

=== Installing the Buildroot Snapshot ===

''Note: The HiFi-2 snapshot is in the process of being made.''

To install the buildroot environment (toolchain and root filesystem), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot'''
$ '''cd buildroot-xtensa-HiFi2-Snapshot'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP''' [56 key strokes]
$ '''git checkout snapshot_2+SMP''' [28 key strokes]

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).

You can examine the tree (git repository) and its history visually using <tt>git gui</tt>.
The git GUI is a faster and more convenient method for checking out the HiFi-2 snapshot. To check out the snapshot_2+SMP branch simply run the command 'git gui' and then pull down the branch->create menu. Next select <>Match Tracking Branch Name and click on ''origin/snapshot_2+SMP''. Finally hit the Create Button.

$ '''git gui''''' [8 key strokes]
[Branch] -> Create... [2 key strokes]
<> Match Tracking Branch Name [1 key stroke]
<> Tracking Branch [1 key stroke]
origin/snapshot_2+SMP [1 key stroke]
[Create] [1 key stroke]
[Reposirory]--> Quit [2 key strokes]

If there are issues installing '''git''', as a last resort, an alternative is ftp (may not always get updated, is currenty our of date, waste disk space, so may be dropped at some point):

http://www.linux-xtensa.org/pub/snapshots/buildroot-xtensa-smp.2-Nov-2009.tar.gz

=== Installing the Linux Kernel Snapshot ===

To install the Linux kernel environment (kernel src, config, and HiFi-2 kernel U-Boot image), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp'''
$ '''cd kernel/xtensa-2.6.29-smp'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
$ '''git checkout snapshot_2+SMP'''

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).
As in the build root case, you can also do it from via git gui using the same proceedure
mantioned above.

Now, assuming we are still in the kernel '''xtensa-2.6.29-smp''' directory
copy the kernel U-Boot Image ('''uImage''') to the tftp directory; Ex:

$ '''cp arch/xtensa/boot/uImage /tftpboot/uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'''

NOTE: On some system, like Fedora Core 9, the tftpboot directory has been moved to /var/lib/tftpboot.
In this case we recomend that you just added a symbolic pointer from /etc to /var/lib/tftpboot:

$ '''su'''
# '''cd /etc'''
# '''/var/lib/tftpboot/ tftpboot'''
# '''ls -ld tftpboot'''
lrwxrwxrwx 1 root root 18 2009-11-23 21:14 tftpboot -> /var/lib/tftpboot/
#

== Setting up a TFTP Server to provide the Linux kernel to U-Boot ==

The TFTP service is part of the xinetd and is installed on Fedora workstations.
You can see that it's installed with the check config command which manages the
/etc/rc.d/init.d startup scripts and with the yum search command:

$ '''chkconfig --list'''
NetworkManager 0:off 1:off 2:off 3:off 4:off 5:off 6:off
NetworkManagerDispatcher 0:off 1:off 2:off 3:off 4:off 5:off 6:off
acpid 0:off 1:off 2:off 3:on 4:on 5:on 6:off
.
.
.
xfs 0:off 1:off 2:on 3:on 4:on 5:on 6:off
xinetd 0:off 1:off 2:off 3:on 4:on 5:on 6:off
ypbind 0:off 1:off 2:off 3:on 4:on 5:on 6:off
yum 0:off 1:off 2:off 3:off 4:off 5:off 6:off

xinetd based services:
amanda: off
auth: off
.
.
.
rsync: off
'''tftp: on''' [NOTE that tftp is enabled]
time: off
time-udp: off
uucp: off
$
$
$
$ '''yum search tftp-server'''
Loading "installonlyn" plugin
Searching Packages:
.
.
.
Reading repository metadata in from local files
.
.
.
'''tftp-server.i386 0.41-1.2.1 installed''' [NOTE that tftp server is installed as part of the inet daemon]
Matched from:
tftp-server
The Trivial File Transfer Protocol (TFTP) is normally used only for
booting diskless workstations. The tftp-server package provides the
server for TFTP, which allows users to transfer files to and from a
remote machine. TFTP provides very little security, and should not be
enabled unless it is expressly needed. The TFTP server is run from
/etc/xinetd.d/tftp, and is disabled by default on Red Hat Linux systems.
[piet@pdelaney_fc5 ~]$

TFTP is not normally enabled, to enable it just edit the file /etc/xinetd.d/tftp
and change the disable field to no:

# default: off
# description: The tftp server serves files using the trivial file transfer \
# protocol. The tftp protocol is often used to boot diskless \
# workstations, download configuration files to network-aware printers, \
# and to start the installation process for some operating systems.
service tftp
{
socket_type = dgram
protocol = udp
wait = yes
user = root
server = /usr/sbin/in.tftpd [NOTE: /var/lib/tftpboot on Fedora Core 9]
server_args = -s /tftpboot
'''disable = no'''
per_source = 11
cps = 100 2
flags = IPv4
}

== Setting up an NFS Server to export the Root Filesystem ==

The LX200 board running Linux needs to mount its root filesystem over NFS.
This filesystem was built using buildroot into a cpio format file,
and left in:

buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2/rootfs.xtensa_test_mmuhifi_c3.cpio

We will also be adding an additional minor changes to make your development environment more comfortable.

Pick a place on your workstation to export your root and unpack the cpio file into that directory.
For example here we will set up an export in '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''':

$ '''cd buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2'''
$ '''WHERE=$PWD'''
$ '''mkdir -p /exports/LINUX_ROOT.HiFi-2'''
$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''cpio -i < $WHERE/rootfs.xtensa_test_mmuhifi_c3.cpio'''

Next add a line to /etc/exports:

/exports *(rw,no_root_squash,sync,no_wdelay)

and restart you nfs services:

$ '''/etc/rc.d/init.d/nfs restart'''
or
$ '''/sbin/chkconfig nfs on'''

The showmount command should show your NFS file system now being exported:

$ '''showmount -e'''
Export list for mypc.foobar.com:
/exports *
$

== Configuring U-Boot to Boot Linux ==

Your LX200 board should have arrived with U-Boot installed in the flash ready to use.
The board has a DIP switch (next to the power on/off switch) that provides the 6 LSBs
of the Ethernet MAC, in switch positions 1 thru 6.

DIP Swithes for MAC: 1 2 3 4 5 6 7 8 ethaddr=00:50:C2:13:6f:0a
Little Endian: 0 1 0 1 0 0 * *
^
|
+------ Enables booting U-Boot from Flash

DIP switch 8 should be shipped in the ON position to enable U-Boot booting from flash.
See Sections 4.2.3 and 4.2.4 of the '''Tensilica Avnet (XT-AV200) Board User's Guide'''
for details. Make sure to select a unique MAC address for you board.

Next, connect a serial interface to a text based terminal emulation program,
set to 38400 bps, no parity, 1 stop bit, no handshaking.
For an example of setting [http://en.wikipedia.org/wiki/Minicom minicom]
for this, see [[minicom_xtboard_setup|here]].

Many users of this board are interested in developing codecs and/or HiFi 2 software and will prefer to just boot linux with the root file system we just described how to export on your NFS server. We will use git now to pull a snapshot of a performance 2.6.29 linux kernel and configure U-Boot to automatically boot it after a power cycle.

U-Boot> '''setenv serverip 192.168.11.55''' [TFTP server IP Address: RTOS-LAB2]
U-Boot> '''setenv nfsroot_server 192.168.11.55''' [Root NFS Servers IP Address: My Workstation]
U-Boot> '''setenv ipaddr 192.168.11.155''' [HOST IP address]
U-Boot> '''setenv bootfile uImage.xtensa-2.6.29-smp.test_mmuhifi_c3''' [File to fetch with TFTP and pass to bootm]
U-Boot> '''setenv root-path /exports/LINUX_ROOT.HiFi-2''' [WARNING: Limit path to < 50 characters]
U-Boot> '''setenv bootargs_using_bootp console=ttyS0,38400 ip=bootp root=nfs coredump_filter=0xff''' [Args passed to Linux while booting with BOOTP proto]
U-boot> '''setenv bootargs console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=${nfsroot_server}:${root-path}''' [Args passed to Linux while booting with DHCP proto]
U-boot> '''setenv bootcmd tftpboot\; bootm''' [Boot Linux after fetching it with TFTP]
U-Boot> '''setenv bootdelay 20''' [Delay 20 seconds before booting automaticaly]
U-Boot> '''setenv autostart yes''' [Boot automatically on power-up/reset]
U-Boot> '''saveenv'''
U-Boot>

'''[REMIND: Update the above procedure, show two or thee approaches (ip, dhcp, bootp)]'''

== Tailoring your system prior to Booting ==

There are a few tweaks that developers have found convenient to add to the the root file-system before booting.
As an initial environment for developing we suggest mounting a /home/default files-system that has number of
files useful for getting started. Find another place to tar in the tar ball with the default users file system.
We chose to include this close to the cpio file with the root file-system. Copy the tar bar to where you are
exporting you root file-system and next to it add the 'default' users file-system:

$ '''cd /export'''
$ '''cp /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.10/binaries/default.tar .'''
$ '''tar xf default.tar'''
$ '''cd default'''
$ '''ls'''
[TO BE ADDED]

Notice a file tar ball called '''saved_files.tar'''. This ia a tar file of files that
developers have found convenient to add and replace on the root file system after
adding a new buildroot file system. Here is a list of the files and a brief
explanation on why it's convenient to add or replace them:

root/.bash_profile [added 'ulimit -c unlimited to allow core dumps to be created]
root/.bashrc
etc/profile [added 'ulimit -c unlimited to allow core dumps to be created]
etc/fstab [Tells the system how to mount extra NFS file systems like /home/default]
etc/init.d/S90local [Mounts /home/default]
etc/resolv.conf [Location of DNS servers when your not using DHCP to boot the kernel]
etc/TZ [Your time zone, currently set to California TZ]
etc/dropbear/dropbear_rsa_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/dropbear/dropbear_dss_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/ssh_config [Typically tailored with things like allowing root logins via ssh]
etc/ssh_host_dsa_key [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_dsa_key.pub [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_key
etc/ssh_host_key.pub
etc/ssh_host_rsa_key
etc/ssh_host_rsa_key.pub
etc/sshd_config [Typically tailored with things like allowing root logins via ssh]
etc/rndc.key
etc/random-seed [Generated during 1st boot]
etc/passwd [Changed default user's shell to bash]
etc/shadow [Changed default and root users login password to 'linux1', need to ssh to the board]
exports/ [The path to where the board can mount extra file systems like /home/default.
fac/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]
fac/vol6/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]

Now lets assume your going to stay with these changes and modify them after taring in these changes.
Here we add the tar ball files to the boards root filesystem.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''tar xf /exports/default/'''

This is a good time to edit a few files on the boards file system
before boot it.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''vi etc/fstab''' [Change fstab entry for /home/default and others to your taste]
$ '''vi etc/init.d/S90local''' [You might want to disable mounting of NFS file systems on the 1st Boot and add this once you try it manually]

== Booting Linux for the 1st Time ==

We should now be ready to boot linux on your LX200. You have exported the root file-system and made the
kernel available to a TFTP server. Now let's start with hitting the reset button on the LX200 and it should
auto-boot the kernel, resulting in output such as [[HiFi2_Board_Example_Linux_Boot_Log|this example log]].

== Tailoring your system prior to developing for HiFi 2 ==

To make your experience more pleasant we suggest you tailor your environment.
Here are some of the changes that we have found helpful:

1. Add a root password to that you can login with ssh.
2. Run rdate with an ntp server on booting.
3. Add NFS mounts to /etc/fstab for your code and buildroot code.
4. Copy in previous ssh server encryption keys to /etc/dropbear to speed up your initial boot.
5. Mount a 'default' user home directory with:
a. Linux Test Suite pre-patch to test the system
b. Audio test example files
c. Copies of Mplayer and its Plug-ins from Buildroot modified slightly to make installation easy.
d. Misc audio test programs.

[TO BE DONE - Where to get 'default' user home directory tar ball and 1st boot patch]

== Building Linux Applications ==

=== Building Linux Applications Using GCC on the Host ===
TBD

=== Building Linux Applications Using GCC on the Target ===
TBD

=== Building Linux Applications Using XCC (Xtensa Tools) ===

There are two approaches to compiling with Tensilica's XCC compiler (part of Xtensa Tools).
The normal one, described below, is to initially setup a virtual core
that has built-in references to the library and include files for the target Linux system.
Alternatively, one could skip this initial setup and just use Xtensa Tools to create
object files and link them using host or target GCC tools.
However, such objects must be built without dependencies on such things as the C library,
which can be harder than it sounds (for example, flags and structures, such as <tt>open()</tt>'s <tt>O_EXCL</tt>
and <tt>stat()</tt>'s <tt>struct stat</tt>, must be avoided because their definitions likely differ between the
Xtensa Tools' default C library and the Linux uClibc library).
''('''Note''': Codecs such as MP3 and AAC are typically written in C with TIE extensions and can only be compiled with XCC.)''

Section 4.3 of the latest ''Xtensa OSKit Guide'' (from Tensilica's
RC-2009.0 release) describes how to setup XCC to compile Linux applications.
For full details, see the guide. A summary follows.

==== Initial Setup ====

The XTENSA_TOOLS_ROOT, XTENSA_ROOT, BUILDROOT_DIR, and TARGET_SYSROOT
environment variables must be set according to where things were installed;
values shown here are for illustration only. The CORENAME variable, set correctly
below for this board, reflects
the name of the core as known to open source tools (as opposed to XTENSA_CORE
which is the core name as known to Xtensa Tools; both happen to match here).

$ setenv USER someuser
$ setenv XTENSA_ROOT /home/${USER}/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
$ setenv XTENSA_TOOLS_ROOT /home/${USER}/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools
$ setenv TARGET_SYSROOT /exports/LINUX_ROOT.HiFi-2
$ setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12

$ setenv CORENAME test_mmuhifi_c3

$ cd ${BUILDROOT_DIR}
$ ${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install \
--sysroot=./build_xtensa_${CORENAME}/staging_dir \
--linux-gcc=./build_xtensa_${CORENAME}/staging_dir/usr/bin/xtensa_${CORENAME}-linux-gcc

==== Regular Use ====

Assuming the above completed successfully, you can now build applications using Xtensa Tools. First set the usual environment variables (assuming values of XTENSA_ROOT and XTENSA_TOOLS_ROOT used earlier):

$ setenv XTENSA_CORE default
$ setenv XTENSA_SYSTEM ${XTENSA_ROOT}-linux/config
$ setenv PATH ${XTENSA_TOOLS_ROOT}/bin:${PATH}

Now you can use Xtensa Tools to assemble, compile, and link applications for the Linux target specified during setup. For example:

$ echo '#include <stdio.h>' > hello.c
$ echo 'int main() {printf("Hello!\n");return 0;}' >> hello.c
$ xt-xcc -g hello.c -o hello

Then copy it where the target can see it:

$ cp hello ${TARGET_SYSROOT}/root

And run it on the target:

[root@hifi ~]# /root/hello
Hello!
[root@hifi ~]#

Here's a more interesting example that uses Tensilica TIE features.
(This cannot be compiled using GCC.)

$ cd ${TARGET_SYSROOT}/home/default/Audio_Tests
$ xt-xcc -g hifitest.c -o hifitest

In a ssh termulator window on the board you can now run hifitest:

[root@hifi ~]# '''cd /home/default/Audio_Tests/'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:23178; Eatting cpu; time:0 '''<control-C>'''

[root@hifi Audio_Tests]#

Here is the source code for the [[hifitest.c|hifitest.c source file]] used above.

=== Limited (No Setup) Use of Xtensa Tools for Linux Targets ===

Below we illustrate compiling a simple audio test program on a workstation.
We start by referring to the XTENSA tools build by Xplorer, putting XCC into our search path and set the standard XTENSA_* environment variables.
For example:

setenv XTENSA_CORE test_mmuhifi_c3
setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config
setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin

setenv PATH ${XTENSA_TOOLS}:${PATH}

[piet@fc9desktop Tests] $ '''cd /exports/default/Audio_Tests''' [NOTE: This is being done on a Workstation]
[piet@fc9desktop Audio_Tests]$ '''xt-xcc -g3 -O0 -fPIC -c hifitest.c'''

Next we link the object on the LX200 board and run gdb on the TIE enhanced code:

[root@hifi Audio_Tests]# '''gcc -g hifitest.o -o hifitest'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:4640; Eatting cpu; time:0
cnt:0x0, pid:4640; Eating Tie; time:7
^C
[root@hifi Audio_Tests]# '''gdb ./hifitest''' [NOTE: This is being done on the LX200 board]
GNU gdb 6.6
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "xtensa_test_mmuhifi_c3-linux-uclibc"...
Using host libthread_db library "/lib/libthread_db.so.1".
(gdb) '''break main'''
Breakpoint 1 at 0x400401: file /exports/default/Audio_Tests/hifitest.c, line 20.
(gdb) '''run'''
Starting program: /home/default/Audio_Tests/hifitest

Breakpoint 1, main (argc=1, argv=0x3fb3fab4)
at /exports/default/Audio_Tests/hifitest.c:20
20 time_t time0 = time(NULL);
(gdb) '''step'''
21 time_t time1 = time(NULL);

== Compiling Generic GPL Packages ==

For your development you may want to add a few GPL packages that you find helpful.
This can be done on the LX200 just as you would on a normal workstation, though
much slower. For example here we configure and build a few common GPL packages:

[[Building the Strace Package]]

[[Building the vim Package]]

== Compiling the Mplayer Plugins and linking them with MPEG-1 Audio Layer 3 (MP3) and MPEG-4 AAC Codecs ==

Mplayer is provided as an example environment for developing and testing Codecs and HiFi 2 software. There
are two ways to build Mplayer and the plug-in modules that use the codecs. The buildroot
tree (pulled with git) has a copy of mplayer and the plugins that can be built in the
snapshot via 'make menuconfig'. This is a good environment to use once codecs are
developed and debugged.

To facilitate development the mplayer packages can be copied to your NFS mounted development
environment. From there you can just configure mplayer to compile on the board and debug
mplayer and your codecs with gdb locally.

In the default user home directory we have a directory /home/default/buildroot_mplayer_stuff
with a copy of three of the mplayer packages:

[root@hifi buildroot_mplayer_stuff]# '''ls -l'''
drwxr-xr-x 34 root root 4096 Nov 10 05:01 MPlayer-1.0rc2/
drwxr-xr-x 4 root root 4096 Nov 10 01:36 mplayer_hifi2_aacplus_v2_plugin/
drwxr-xr-x 3 root root 4096 Nov 10 00:57 mplayer_hifi2_mp3_plugin/

they were simply copied from the buildroot-xtensa-HiFi2-Snapshot.2/package directory.

To get your development environment ready to compile the mplayer plug-ins you need
to configure Mplayer to use the local C compiler and linker:

# '''cd /home/default/buildroot_mplayer_stuff/MPlayer-1.0rc2/'''
# '''CFLAGS="-g3" ./configure'''

This will take about 15 minutes to configure. After that you can build the
plugins or mplayer. If you want to recompile mplayer it's likely best/necessary
to use the same args to .configure as used by buildroot:

.CFLAGS="-g3" ./configure \
--prefix=/usr \
--confdir=/etc/mplayer \
--with-extraincdir=/usr/include \
--with-extralibdir=/lib \
--disable-gui \
--enable-mad \
--enable-fbdev \
--disable-mencoder \
--disable-dvdnav \
--disable-dvdread \
--disable-dvdread-internal \
--disable-libdvdcss-internal \
--disable-big-endian \
--disable-nemesi \
--disable-tv \
--enable-dynamic-plugins

We are currently able to compile most of mplayer on the LX200 but
due to space limitations it's not possible to compile it -O0.

Now, let's focus on compiling linking the plugins. They are a nice
example of compiling an audio application on the LX200.

We modified the Makefile of the codes slightly, and will make it available.
These additions just instruct make how to install the plugins as explained
in the Chapter 7 of the Linux HiFi application note.

For example the mp3 plugin has this addition:

target_install::
-mkdir /etc/mplayer
cp codecs.conf /etc/mplayer
-mkdir /usr/lib/mplayer
cp ad_xa_mp3_dec.so /usr/lib/mplayer/
cp xa_mp3_dec.so /usr/lib/mplayer
chmod 755 /usr/lib/mplayer/ad_xa_mp3_dec.so
chmod 755 /usr/lib/mplayer/xa_mp3_dec.so

It's just providing a codec config file for mplayer at '''/etc/mplayer/codecs.conf''' and
copying the plug-in to '''/usr/lib/mplayer'''. To install the mp3 codec plugin and mplayer
config file just copy your codec that was compiled with '''xcc''' to the directory, compile it,
and install.

# '''cd /fac/vol6/audio/release/bin/l32r_LE5_pic'''
# '''cp xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz /tmp'''
#
# '''cd /home/default/buildroot_mplayer_stuff'''
# '''cd mplayer_hifi2_mp3_plugin'''
# '''cp /tmp/xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz .'''
# '''gunzip xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz'''
# '''tar xf xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tar'''
# '''make'''
# '''make target_install'''

The unpacking of the Tensilica mp3 codec tarball will install the following files:

xa_mp3_dec/
xa_mp3_dec/README
xa_mp3_dec/include/
xa_mp3_dec/include/mp3_dec/
xa_mp3_dec/include/mp3_dec/xa_mp3_dec_api.h
xa_mp3_dec/include/xa_apicmd_standards.h
xa_mp3_dec/include/xa_error_handler.h
xa_mp3_dec/include/xa_error_standards.h
xa_mp3_dec/include/xa_memory_standards.h
xa_mp3_dec/include/xa_type_def.h
xa_mp3_dec/test/
xa_mp3_dec/test/build/
xa_mp3_dec/test/build/ldscript_stream_data.txt
xa_mp3_dec/test/build/makefile_testbench_sample
xa_mp3_dec/test/build/paramfilesimple.txt
xa_mp3_dec/test/include/
xa_mp3_dec/test/include/id3_tag_decode.h
xa_mp3_dec/test/src/
xa_mp3_dec/test/src/xa_mp3_dec_sample_testbench.c
xa_mp3_dec/test/src/id3_tag_decode.c
xa_mp3_dec/test/src/stream_data.c
xa_mp3_dec/test/src/xa_mp3_dec_error_handler.c
xa_mp3_dec/test/test_inp/
xa_mp3_dec/test/test_inp/compl.mp3
xa_mp3_dec/test/test_inp/hihat.mp3
xa_mp3_dec/test/test_out/
xa_mp3_dec/test/test_out/force_mkdir.txt
xa_mp3_dec/test/test_ref/
xa_mp3_dec/test/test_ref/compl_24bit.wav
xa_mp3_dec/test/test_ref/hihat_16bit.wav
xa_mp3_dec/lib/
xa_mp3_dec/lib/xa_mp3_dec.a
xa_mp3_dec/doc/
xa_mp3_dec/doc/HiFi2-MP3-DecoderProgrammersGuide.pdf

[TO BE DONE - Add missing C file, make clean deletes it!]

The xa_mp3_dec.a archive will be used by the Makefile in
the mplayer_hifi2_mp3_plugin directory to make the mplayer plug-in.
Section 6 of the '''Using Tensilica HiFi 2 Codec on Xtensa Linux with MPlayer'' Application Note
has a detailed description of the encapsulation process used by the plug-ins.

== Adding a Codec to Buildroot ==

Xtensa developers provide detailed instructions on building the root filesystem and the Linux kernel.
* [[Buildroot_Build_Instructions|Instructions for building and booting Linux (buildroot)]].

Building a comprehensive development environment with buildroot can be a challenging experience and
worthy of providing some tips on process.
Here are notes of the configs used for the three menuconfigs in this 2nd snapshot
provided with SMP additions:
$ '''make [[HiFi-2 snapshot_2 SMP Snapshot menuconfig | menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP uclibc-menuconfig | uclibc-menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP busybox-menuconfig | busybox-menuconfig]]'''

[TO BE DONE - making a new tar ball of saved files, building buildroot, ...]

== Known Problems being investigated, suggested that you know about and possibly avoid ==

1. Using NFS mounts with default parameters causes memory congestion. Use these mount options:

'''vers=2,rsize=4096,wsize=4096,hard,nointr,nolock,nolock,timeo=11,retrans=3,noauto'''

this is extremely important to add to your /etc/fstab on the target.

2. Can't swap over NFS yet, memory can get tight and cause application to be killed.
a. Trying procedure documented in U-Boot Manual.

3. Building the C development with X11 doesn't work with buildroot.

4. Though Mplayer plug-in can be compiled, Mplayer can be compiled but still has a few issues:
a. Can't be compiled -O0 due to limited memory while compiling one file,
b. Compiler infrequently crashes and make has to be restarted.
Not seeing this problem with root build on Fedore Core 9.
Perhaps this was caused by debug kernel or LTP using all of the memory.

5. U-boot has flash problems:
a. Sectors marked Read-Only come up Writeable after a reset/reboot.
b. Flashing a large number of sectors (like the kernel) sometimes
results in an Error (Ex: Vcc) and had to be retried.
c. Saw environment variables trashed on reset/reboot once.
It's possible that U-boot in flash could get whacked
and the board will need to be re-flashed. During a week
or two of testing I haven't see environment getting whacked.

6. gdb appears to be crashing on target when debugging
on latest root with uclibc left unstriped and with debug;
core dump sent to maxim.

7. U-Boot seems to hang periodically when loading the kernel with
tftp; appears to be worse when network activity is high.

8. 'top' command only shows all cpu's or cpu0; cpu 1 and 2 missing.

9. Program dore dump require ulimit -c to be set but root uses /bin/sh
which is a link to bash but causes it to skip running the bash
startup scripts. Changing root to /bin/bash seems to mess up
ssh logins.

10. For kernel to be compiled on the LX200 (for self checking:
a. Xtensa makefile needs to be fixed:
CC init/do_mounts.o
LD init/mounts.o
/bin/sh: xtensa_test_mmuhifi_c3-linux-uclibc-ld: command not found
make[1]: *** [init/mounts.o] Error 127

b. Need to add ncurses-devel package for 'make menuconfig'

11. Copying vim-7.2.tar from /home/default/src to /usr/local/src resulted
in a corrupt tar header. Apparently we have a NFS bug lurking in the kernel.
On server tar file looks like this:
vim72/000755 001750 001750 00000000000 11047345123 012000 5
ustar00moolmool000000 000000
vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0
ustar00moolmool000000 000000
README.txt for version 7.2 of Vim: Vi IMproved.

On the target/client it's different:
vim72/000755 001750 001750 00000000000 11047345123 012000 5ustar00moolmool000000 000000 vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0ustar00moolmool000000 000000 README.txt for version 7.2 of Vim: Vi IMproved.

=Further reading=

Main Xtensa Linux resources are:

* [http://linux-xtensa.org/ Linux/Xtensa Wiki]
* [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions Buildroot Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Kernel_Build_Instructions Kernel Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Setting_up_U-Boot Setting up U-Boot]
* [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List]
* http://git.linux-xtensa.org/cgi-bin/git.cgi GIT Repositories]

=Thanks to=

* piet
* marc
* dan

And the rest of the people in the Linux-Xtensa mailing list, if you cannot go through some of the steps, don't hesitate to ask on the mailing list, there's always somebody willing to help you!

SMP HiFi 2 Development Board

2009-12-02T07:46:24Z

Marc: Re-order things by relevance

This is a "community" guide for how to use the LX200 board based 3-core SMP HiFi-2 Development environment.
If something doesn't work or isn't covered in this guide, please feel free to ask at the [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List].

<div style="margin:0; margin-top:10px; margin-right:10px; border:1px solid #dfdfdf; padding:0 1em 1em 1em; background-color:#ffffcc; align:right; ">
'''NEWS:'''

Some general notes on these instructions:

* They are a work in progress.

* The following was tested on x86 machines running RedHat Fedora Core 5.

* Buildroot build with Fedora Core 9 also seems to be fine; perhaps better than when built on Fedore Core 5.

</div>

== Introduction ==

This document is addressed to someone who received an LX200 board setup by Tensilica
for HiFi2 development.

This document goes over the steps needed to set up the LX200 board for HiFi2 development.
To summarize:
* Setup the board. It likely comes with U-boot preinstalled, ready to boot a linux kernel.
* Install '''git'''.
* Download buildroot and linux kernel trees, pre-configured and built for HiFi-2 development.
* Setup a TFTP server to provide the linux kernel to U-Boot.
* Setup an NFS server to export a linux root file system.
* Setup the Linux kernel to boot from the root file system provided by the NFS server.
Once the development board is up and running, this document:
* Suggests a possible way to tailor the board for easy codec development.
* Shows how to add the Tensilica provided codec packages to the Mplayer packages used by Buildroot, including building and installing.
* Demonstrates two procedures for compiling, linking, and debugging codecs.

All development is expected to be done on a Linux host. (One can in principle use Windows to
develop target libraries. However, linking and subsequent steps need to be done in Linux.)

== Downloading the Latest HiFi-2 Buildroot and Kernel Snapshots ==

The HiFi-2 development environment is maintained in a source code version control system named 'git'. The '''git''' tools are useful when working with this development environment, though they are not strictly necessary. This document generally assumes the use of '''git''', which provides more opportunities for modifying this environment as needed (e.g. building more optional buildroot packages). But points out alternatives to allow getting up and running without having to set it up.

=== Installing git ===

To install '''git''', download a recent tarball from the [http://www.kernel.org/pub/software/scm/git/ official site]. For example, <tt>cd</tt> to a location with enough disk space, and do:

$ '''wget http://www.kernel.org/pub/software/scm/git/git-1.6.5.tar.gz'''

Unpack the tarball, and make and install it. Here we show how to install it to your ~/bin directory:

$ '''gunzip git-1.6.5.tar.gz'''
$ '''tar xf git-1.6.5.tar'''
$ '''cd git-1.6.5'''
$ '''make'''
$ '''make install'''

The git makefile can be instructed to install '''git''' to <tt>/usr/local/bin</tt> as root for system wide access:

$ '''cp git-1.6.5.tar.gz''' /tmp
$ '''su'''
Password:
# '''cd /usr/local/src/'''
# '''mkdir git'''
# '''cd git'''
# '''cp /tmp/git-1.6.5.tar.gz .'''
# '''gunzip git-1.6.5.tar.gz'''
# '''tar xf git-1.6.5.tar'''
# '''cd git-1.6.5'''
# '''make prefix=/usr/local'''
# '''make install'''

See the '''INSTALL'' instruction at the top of the git src directory for details.

Using '''git''' provides easy access to the binaries used to bring up the codec development environment, and leaves in place the infrastructure to modify and build this environment should you wish to. Any changes to '''git'''-managed source trees are easily observed with the '''git''' tools.

=== Installing the Buildroot Snapshot ===

''Note: The HiFi-2 snapshot is in the process of being made.''

To install the buildroot environment (toolchain and root filesystem), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot'''
$ '''cd buildroot-xtensa-HiFi2-Snapshot'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP''' [56 key strokes]
$ '''git checkout snapshot_2+SMP''' [28 key strokes]

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).

You can examine the tree (git repository) and its history visually using <tt>git gui</tt>.
The git GUI is a faster and more convenient method for checking out the HiFi-2 snapshot. To check out the snapshot_2+SMP branch simply run the command 'git gui' and then pull down the branch->create menu. Next select <>Match Tracking Branch Name and click on ''origin/snapshot_2+SMP''. Finally hit the Create Button.

$ '''git gui''''' [8 key strokes]
[Branch] -> Create... [2 key strokes]
<> Match Tracking Branch Name [1 key stroke]
<> Tracking Branch [1 key stroke]
origin/snapshot_2+SMP [1 key stroke]
[Create] [1 key stroke]
[Reposirory]--> Quit [2 key strokes]

If there are issues installing '''git''', as a last resort, an alternative is ftp (may not always get updated, is currenty our of date, waste disk space, so may be dropped at some point):

http://www.linux-xtensa.org/pub/snapshots/buildroot-xtensa-smp.2-Nov-2009.tar.gz

=== Installing the Linux Kernel Snapshot ===

To install the Linux kernel environment (kernel src, config, and HiFi-2 kernel U-Boot image), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp'''
$ '''cd kernel/xtensa-2.6.29-smp'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
$ '''git checkout snapshot_2+SMP'''

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).
As in the build root case, you can also do it from via git gui using the same proceedure
mantioned above.

Now, assuming we are still in the kernel '''xtensa-2.6.29-smp''' directory
copy the kernel U-Boot Image ('''uImage''') to the tftp directory; Ex:

$ '''cp arch/xtensa/boot/uImage /tftpboot/uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'''

NOTE: On some system, like Fedora Core 9, the tftpboot directory has been moved to /var/lib/tftpboot.
In this case we recomend that you just added a symbolic pointer from /etc to /var/lib/tftpboot:

$ '''su'''
# '''cd /etc'''
# '''/var/lib/tftpboot/ tftpboot'''
# '''ls -ld tftpboot'''
lrwxrwxrwx 1 root root 18 2009-11-23 21:14 tftpboot -> /var/lib/tftpboot/
#

== Setting up a TFTP Server to provide the Linux kernel to U-Boot ==

The TFTP service is part of the xinetd and is installed on Fedora workstations.
You can see that it's installed with the check config command which manages the
/etc/rc.d/init.d startup scripts and with the yum search command:

$ '''chkconfig --list'''
NetworkManager 0:off 1:off 2:off 3:off 4:off 5:off 6:off
NetworkManagerDispatcher 0:off 1:off 2:off 3:off 4:off 5:off 6:off
acpid 0:off 1:off 2:off 3:on 4:on 5:on 6:off
.
.
.
xfs 0:off 1:off 2:on 3:on 4:on 5:on 6:off
xinetd 0:off 1:off 2:off 3:on 4:on 5:on 6:off
ypbind 0:off 1:off 2:off 3:on 4:on 5:on 6:off
yum 0:off 1:off 2:off 3:off 4:off 5:off 6:off

xinetd based services:
amanda: off
auth: off
.
.
.
rsync: off
'''tftp: on''' [NOTE that tftp is enabled]
time: off
time-udp: off
uucp: off
$
$
$
$ '''yum search tftp-server'''
Loading "installonlyn" plugin
Searching Packages:
.
.
.
Reading repository metadata in from local files
.
.
.
'''tftp-server.i386 0.41-1.2.1 installed''' [NOTE that tftp server is installed as part of the inet daemon]
Matched from:
tftp-server
The Trivial File Transfer Protocol (TFTP) is normally used only for
booting diskless workstations. The tftp-server package provides the
server for TFTP, which allows users to transfer files to and from a
remote machine. TFTP provides very little security, and should not be
enabled unless it is expressly needed. The TFTP server is run from
/etc/xinetd.d/tftp, and is disabled by default on Red Hat Linux systems.
[piet@pdelaney_fc5 ~]$

TFTP is not normally enabled, to enable it just edit the file /etc/xinetd.d/tftp
and change the disable field to no:

# default: off
# description: The tftp server serves files using the trivial file transfer \
# protocol. The tftp protocol is often used to boot diskless \
# workstations, download configuration files to network-aware printers, \
# and to start the installation process for some operating systems.
service tftp
{
socket_type = dgram
protocol = udp
wait = yes
user = root
server = /usr/sbin/in.tftpd [NOTE: /var/lib/tftpboot on Fedora Core 9]
server_args = -s /tftpboot
'''disable = no'''
per_source = 11
cps = 100 2
flags = IPv4
}

== Setting up an NFS Server to export the Root Filesystem ==

The LX200 board running Linux needs to mount its root filesystem over NFS.
This filesystem was built using buildroot into a cpio format file,
and left in:

buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2/rootfs.xtensa_test_mmuhifi_c3.cpio

We will also be adding an additional minor changes to make your development environment more comfortable.

Pick a place on your workstation to export your root and unpack the cpio file into that directory.
For example here we will set up an export in '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''':

$ '''cd buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2'''
$ '''WHERE=$PWD'''
$ '''mkdir -p /exports/LINUX_ROOT.HiFi-2'''
$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''cpio -i < $WHERE/rootfs.xtensa_test_mmuhifi_c3.cpio'''

Next add a line to /etc/exports:

/exports *(rw,no_root_squash,sync,no_wdelay)

and restart you nfs services:

$ '''/etc/rc.d/init.d/nfs restart'''
or
$ '''/sbin/chkconfig nfs on'''

The showmount command should show your NFS file system now being exported:

$ '''showmount -e'''
Export list for mypc.foobar.com:
/exports *
$

== Configuring U-Boot to Boot Linux ==

Your LX200 board should have arrived with U-Boot installed in the flash ready to use.
The board has a DIP switch (next to the power on/off switch) that provides the 6 LSBs
of the Ethernet MAC, in switch positions 1 thru 6.

DIP Swithes for MAC: 1 2 3 4 5 6 7 8 ethaddr=00:50:C2:13:6f:0a
Little Endian: 0 1 0 1 0 0 * *
^
|
+------ Enables booting U-Boot from Flash

DIP switch 8 should be shipped in the ON position to enable U-Boot booting from flash.
See Sections 4.2.3 and 4.2.4 of the '''Tensilica Avnet (XT-AV200) Board User's Guide'''
for details. Make sure to select a unique MAC address for you board.

Next, connect a serial interface to a text based terminal emulation program,
set to 38400 bps, no parity, 1 stop bit, no handshaking.
For an example of setting [http://en.wikipedia.org/wiki/Minicom minicom]
for this, see [[minicom_xtboard_setup|here]].

Many users of this board are interested in developing codecs and/or HiFi 2 software and will prefer to just boot linux with the root file system we just described how to export on your NFS server. We will use git now to pull a snapshot of a performance 2.6.29 linux kernel and configure U-Boot to automatically boot it after a power cycle.

U-Boot> '''setenv serverip 192.168.11.55''' [TFTP server IP Address: RTOS-LAB2]
U-Boot> '''setenv nfsroot_server 192.168.11.55''' [Root NFS Servers IP Address: My Workstation]
U-Boot> '''setenv ipaddr 192.168.11.155''' [HOST IP address]
U-Boot> '''setenv bootfile uImage.xtensa-2.6.29-smp.test_mmuhifi_c3''' [File to fetch with TFTP and pass to bootm]
U-Boot> '''setenv root-path /exports/LINUX_ROOT.HiFi-2''' [WARNING: Limit path to < 50 characters]
U-Boot> '''setenv bootargs_using_bootp console=ttyS0,38400 ip=bootp root=nfs coredump_filter=0xff''' [Args passed to Linux while booting with BOOTP proto]
U-boot> '''setenv bootargs console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=${nfsroot_server}:${root-path}''' [Args passed to Linux while booting with DHCP proto]
U-boot> '''setenv bootcmd tftpboot\; bootm''' [Boot Linux after fetching it with TFTP]
U-Boot> '''setenv bootdelay 20''' [Delay 20 seconds before booting automaticaly]
U-Boot> '''setenv autostart yes''' [Boot automatically on power-up/reset]
U-Boot> '''saveenv'''
U-Boot>

'''[REMIND: Update the above procedure, show two or thee approaches (ip, dhcp, bootp)]'''

== Tailoring your system prior to Booting ==

There are a few tweaks that developers have found convenient to add to the the root file-system before booting.
As an initial environment for developing we suggest mounting a /home/default files-system that has number of
files useful for getting started. Find another place to tar in the tar ball with the default users file system.
We chose to include this close to the cpio file with the root file-system. Copy the tar bar to where you are
exporting you root file-system and next to it add the 'default' users file-system:

$ '''cd /export'''
$ '''cp /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.10/binaries/default.tar .'''
$ '''tar xf default.tar'''
$ '''cd default'''
$ '''ls'''
[TO BE ADDED]

Notice a file tar ball called '''saved_files.tar'''. This ia a tar file of files that
developers have found convenient to add and replace on the root file system after
adding a new buildroot file system. Here is a list of the files and a brief
explanation on why it's convenient to add or replace them:

root/.bash_profile [added 'ulimit -c unlimited to allow core dumps to be created]
root/.bashrc
etc/profile [added 'ulimit -c unlimited to allow core dumps to be created]
etc/fstab [Tells the system how to mount extra NFS file systems like /home/default]
etc/init.d/S90local [Mounts /home/default]
etc/resolv.conf [Location of DNS servers when your not using DHCP to boot the kernel]
etc/TZ [Your time zone, currently set to California TZ]
etc/dropbear/dropbear_rsa_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/dropbear/dropbear_dss_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/ssh_config [Typically tailored with things like allowing root logins via ssh]
etc/ssh_host_dsa_key [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_dsa_key.pub [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_key
etc/ssh_host_key.pub
etc/ssh_host_rsa_key
etc/ssh_host_rsa_key.pub
etc/sshd_config [Typically tailored with things like allowing root logins via ssh]
etc/rndc.key
etc/random-seed [Generated during 1st boot]
etc/passwd [Changed default user's shell to bash]
etc/shadow [Changed default and root users login password to 'linux1', need to ssh to the board]
exports/ [The path to where the board can mount extra file systems like /home/default.
fac/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]
fac/vol6/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]

Now lets assume your going to stay with these changes and modify them after taring in these changes.
Here we add the tar ball files to the boards root filesystem.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''tar xf /exports/default/'''

This is a good time to edit a few files on the boards file system
before boot it.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''vi etc/fstab''' [Change fstab entry for /home/default and others to your taste]
$ '''vi etc/init.d/S90local''' [You might want to disable mounting of NFS file systems on the 1st Boot and add this once you try it manually]

== Booting Linux for the 1st Time ==

We should now be ready to boot linux on your LX200. You have exported the root file-system and made the
kernel available to a TFTP server. Now let's start with hitting the reset button on the LX200 and it should
auto-boot the kernel, resulting in output such as [[HiFi2_Board_Example_Linux_Boot_Log|this example log]].

== Tailoring your system prior to developing for HiFi 2 ==

To make your experience more pleasant we suggest you tailor your environment.
Here are some of the changes that we have found helpful:

1. Add a root password to that you can login with ssh.
2. Run rdate with an ntp server on booting.
3. Add NFS mounts to /etc/fstab for your code and buildroot code.
4. Copy in previous ssh server encryption keys to /etc/dropbear to speed up your initial boot.
5. Mount a 'default' user home directory with:
a. Linux Test Suite pre-patch to test the system
b. Audio test example files
c. Copies of Mplayer and its Plug-ins from Buildroot modified slightly to make installation easy.
d. Misc audio test programs.

[TO BE DONE - Where to get 'default' user home directory tar ball and 1st boot patch]

== Building Linux Applications ==

=== Building Linux Applications Using GCC on the Host ===
TBD

=== Building Linux Applications Using GCC on the Target ===
TBD

=== Building Linux Applications Using XCC (Xtensa Tools) ===

Codecs like MP3 and AAC have been written in C with TIE extensions and can only be compiled with XCC.

There are two approaches to compiling with Tensilica's XCC compiler (part of Xtensa Tools).
The normal one, described below, is to initially setup a virtual core
that has built-in references to the library and include files for the target Linux system.
Alternatively, one could skip this initial setup and just use Xtensa Tools to create
object files and link them using host or target GCC tools.
However, such objects must be built without dependencies on such things as the C library,
which can be harder than it sounds (for example, flags such as <tt>open()</tt>'s <tt>O_EXCL</tt>, and structures
such as <tt>struct stat</tt> must be avoided, as their definitions likely differ between the
Xtensa Tools' default C library and the Linux uClibc library).

Section 4.3 of the latest ''Xtensa OSKit Guide'' (from Tensilica's
RC-2009.0 release) describes how to setup XCC to compile Linux applications.
For details, see the guide.

A summary follows. The XTENSA_TOOLS_ROOT, XTENSA_ROOT, BUILDROOT_DIR, and TARGET_SYSROOT
environment variables must be set according to where things were installed;
values shown here are for illustration only. The CORENAME variable, set correctly
below for this board, reflects
the name of the core as known to open source tools (as opposed to XTENSA_CORE
which is the core name as known to Xtensa Tools; both happen to match here).

$ setenv USER someuser
$ setenv XTENSA_ROOT /home/${USER}/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
$ setenv XTENSA_TOOLS_ROOT /home/${USER}/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools
$ setenv TARGET_SYSROOT /exports/LINUX_ROOT.HiFi-2
$ setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12

$ setenv CORENAME test_mmuhifi_c3

$ cd ${BUILDROOT_DIR}
$ ${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install \
--sysroot=./build_xtensa_${CORENAME}/staging_dir \
--linux-gcc=./build_xtensa_${CORENAME}/staging_dir/usr/bin/xtensa_${CORENAME}-linux-gcc

Assuming the above completes successfully, you can now build applications using Xtensa Tools. First set the usual environment variables:

$ setenv XTENSA_CORE default
$ setenv XTENSA_SYSTEM ${XTENSA_ROOT}-linux/config
$ setenv PATH ${XTENSA_TOOLS_ROOT}/bin:${PATH}

And build something:

$ echo '#include <stdio.h>' > hello.c
$ echo 'int main() {printf("Hello!\n");return 0;}' >> hello.c
$ xt-xcc -g hello.c -o hello

Then copy it where the target can see it:

$ cp hello ${TARGET_SYSROOT}/root

And run it on the target:

[root@hifi ~]# /root/hello

Here's a more interesting example that uses Tensilica TIE features.
(This cannot be compiled using GCC.)

$ cd ${TARGET_SYSROOT}/home/default/Audio_Tests
$ xt-xcc -g hifitest.c -o hifitest

In a ssh termulator window on the board you can now run hifitest:

[root@hifi ~]# '''cd /home/default/Audio_Tests/'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:23178; Eatting cpu; time:0 '''<control-C>'''

[root@hifi Audio_Tests]#

Here is the source code for the [[hifitest.c|hifitest.c source file]] used above.

=== Limited (No Setup) Use of Xtensa Tools for Linux Targets ===

Below we illustrate compiling a simple audio test program on a workstation.
We start by referring to the XTENSA tools build by Xplorer, putting XCC into our search path and set the standard XTENSA_* environment variables.
For example:

setenv XTENSA_CORE test_mmuhifi_c3
setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config
setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin

setenv PATH ${XTENSA_TOOLS}:${PATH}

[piet@fc9desktop Tests] $ '''cd /exports/default/Audio_Tests''' [NOTE: This is being done on a Workstation]
[piet@fc9desktop Audio_Tests]$ '''xt-xcc -g3 -O0 -fPIC -c hifitest.c'''

Next we link the object on the LX200 board and run gdb on the TIE enhanced code:

[root@hifi Audio_Tests]# '''gcc -g hifitest.o -o hifitest'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:4640; Eatting cpu; time:0
cnt:0x0, pid:4640; Eating Tie; time:7
^C
[root@hifi Audio_Tests]# '''gdb ./hifitest''' [NOTE: This is being done on the LX200 board]
GNU gdb 6.6
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "xtensa_test_mmuhifi_c3-linux-uclibc"...
Using host libthread_db library "/lib/libthread_db.so.1".
(gdb) '''break main'''
Breakpoint 1 at 0x400401: file /exports/default/Audio_Tests/hifitest.c, line 20.
(gdb) '''run'''
Starting program: /home/default/Audio_Tests/hifitest

Breakpoint 1, main (argc=1, argv=0x3fb3fab4)
at /exports/default/Audio_Tests/hifitest.c:20
20 time_t time0 = time(NULL);
(gdb) '''step'''
21 time_t time1 = time(NULL);

== Compiling Generic GPL Packages ==

For your development you may want to add a few GPL packages that you find helpful.
This can be done on the LX200 just as you would on a normal workstation, though
much slower. For example here we configure and build a few common GPL packages:

[[Building the Strace Package]]

[[Building the vim Package]]

== Compiling the Mplayer Plugins and linking them with MPEG-1 Audio Layer 3 (MP3) and MPEG-4 AAC Codecs ==

Mplayer is provided as an example environment for developing and testing Codecs and HiFi 2 software. There
are two ways to build Mplayer and the plug-in modules that use the codecs. The buildroot
tree (pulled with git) has a copy of mplayer and the plugins that can be built in the
snapshot via 'make menuconfig'. This is a good environment to use once codecs are
developed and debugged.

To facilitate development the mplayer packages can be copied to your NFS mounted development
environment. From there you can just configure mplayer to compile on the board and debug
mplayer and your codecs with gdb locally.

In the default user home directory we have a directory /home/default/buildroot_mplayer_stuff
with a copy of three of the mplayer packages:

[root@hifi buildroot_mplayer_stuff]# '''ls -l'''
drwxr-xr-x 34 root root 4096 Nov 10 05:01 MPlayer-1.0rc2/
drwxr-xr-x 4 root root 4096 Nov 10 01:36 mplayer_hifi2_aacplus_v2_plugin/
drwxr-xr-x 3 root root 4096 Nov 10 00:57 mplayer_hifi2_mp3_plugin/

they were simply copied from the buildroot-xtensa-HiFi2-Snapshot.2/package directory.

To get your development environment ready to compile the mplayer plug-ins you need
to configure Mplayer to use the local C compiler and linker:

# '''cd /home/default/buildroot_mplayer_stuff/MPlayer-1.0rc2/'''
# '''CFLAGS="-g3" ./configure'''

This will take about 15 minutes to configure. After that you can build the
plugins or mplayer. If you want to recompile mplayer it's likely best/necessary
to use the same args to .configure as used by buildroot:

.CFLAGS="-g3" ./configure \
--prefix=/usr \
--confdir=/etc/mplayer \
--with-extraincdir=/usr/include \
--with-extralibdir=/lib \
--disable-gui \
--enable-mad \
--enable-fbdev \
--disable-mencoder \
--disable-dvdnav \
--disable-dvdread \
--disable-dvdread-internal \
--disable-libdvdcss-internal \
--disable-big-endian \
--disable-nemesi \
--disable-tv \
--enable-dynamic-plugins

We are currently able to compile most of mplayer on the LX200 but
due to space limitations it's not possible to compile it -O0.

Now, let's focus on compiling linking the plugins. They are a nice
example of compiling an audio application on the LX200.

We modified the Makefile of the codes slightly, and will make it available.
These additions just instruct make how to install the plugins as explained
in the Chapter 7 of the Linux HiFi application note.

For example the mp3 plugin has this addition:

target_install::
-mkdir /etc/mplayer
cp codecs.conf /etc/mplayer
-mkdir /usr/lib/mplayer
cp ad_xa_mp3_dec.so /usr/lib/mplayer/
cp xa_mp3_dec.so /usr/lib/mplayer
chmod 755 /usr/lib/mplayer/ad_xa_mp3_dec.so
chmod 755 /usr/lib/mplayer/xa_mp3_dec.so

It's just providing a codec config file for mplayer at '''/etc/mplayer/codecs.conf''' and
copying the plug-in to '''/usr/lib/mplayer'''. To install the mp3 codec plugin and mplayer
config file just copy your codec that was compiled with '''xcc''' to the directory, compile it,
and install.

# '''cd /fac/vol6/audio/release/bin/l32r_LE5_pic'''
# '''cp xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz /tmp'''
#
# '''cd /home/default/buildroot_mplayer_stuff'''
# '''cd mplayer_hifi2_mp3_plugin'''
# '''cp /tmp/xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz .'''
# '''gunzip xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz'''
# '''tar xf xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tar'''
# '''make'''
# '''make target_install'''

The unpacking of the Tensilica mp3 codec tarball will install the following files:

xa_mp3_dec/
xa_mp3_dec/README
xa_mp3_dec/include/
xa_mp3_dec/include/mp3_dec/
xa_mp3_dec/include/mp3_dec/xa_mp3_dec_api.h
xa_mp3_dec/include/xa_apicmd_standards.h
xa_mp3_dec/include/xa_error_handler.h
xa_mp3_dec/include/xa_error_standards.h
xa_mp3_dec/include/xa_memory_standards.h
xa_mp3_dec/include/xa_type_def.h
xa_mp3_dec/test/
xa_mp3_dec/test/build/
xa_mp3_dec/test/build/ldscript_stream_data.txt
xa_mp3_dec/test/build/makefile_testbench_sample
xa_mp3_dec/test/build/paramfilesimple.txt
xa_mp3_dec/test/include/
xa_mp3_dec/test/include/id3_tag_decode.h
xa_mp3_dec/test/src/
xa_mp3_dec/test/src/xa_mp3_dec_sample_testbench.c
xa_mp3_dec/test/src/id3_tag_decode.c
xa_mp3_dec/test/src/stream_data.c
xa_mp3_dec/test/src/xa_mp3_dec_error_handler.c
xa_mp3_dec/test/test_inp/
xa_mp3_dec/test/test_inp/compl.mp3
xa_mp3_dec/test/test_inp/hihat.mp3
xa_mp3_dec/test/test_out/
xa_mp3_dec/test/test_out/force_mkdir.txt
xa_mp3_dec/test/test_ref/
xa_mp3_dec/test/test_ref/compl_24bit.wav
xa_mp3_dec/test/test_ref/hihat_16bit.wav
xa_mp3_dec/lib/
xa_mp3_dec/lib/xa_mp3_dec.a
xa_mp3_dec/doc/
xa_mp3_dec/doc/HiFi2-MP3-DecoderProgrammersGuide.pdf

[TO BE DONE - Add missing C file, make clean deletes it!]

The xa_mp3_dec.a archive will be used by the Makefile in
the mplayer_hifi2_mp3_plugin directory to make the mplayer plug-in.
Section 6 of the '''Using Tensilica HiFi 2 Codec on Xtensa Linux with MPlayer'' Application Note
has a detailed description of the encapsulation process used by the plug-ins.

== Adding a Codec to Buildroot ==

Xtensa developers provide detailed instructions on building the root filesystem and the Linux kernel.
* [[Buildroot_Build_Instructions|Instructions for building and booting Linux (buildroot)]].

Building a comprehensive development environment with buildroot can be a challenging experience and
worthy of providing some tips on process.
Here are notes of the configs used for the three menuconfigs in this 2nd snapshot
provided with SMP additions:
$ '''make [[HiFi-2 snapshot_2 SMP Snapshot menuconfig | menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP uclibc-menuconfig | uclibc-menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP busybox-menuconfig | busybox-menuconfig]]'''

[TO BE DONE - making a new tar ball of saved files, building buildroot, ...]

== Known Problems being investigated, suggested that you know about and possibly avoid ==

1. Using NFS mounts with default parameters causes memory congestion. Use these mount options:

'''vers=2,rsize=4096,wsize=4096,hard,nointr,nolock,nolock,timeo=11,retrans=3,noauto'''

this is extremely important to add to your /etc/fstab on the target.

2. Can't swap over NFS yet, memory can get tight and cause application to be killed.
a. Trying procedure documented in U-Boot Manual.

3. Building the C development with X11 doesn't work with buildroot.

4. Though Mplayer plug-in can be compiled, Mplayer can be compiled but still has a few issues:
a. Can't be compiled -O0 due to limited memory while compiling one file,
b. Compiler infrequently crashes and make has to be restarted.
Not seeing this problem with root build on Fedore Core 9.
Perhaps this was caused by debug kernel or LTP using all of the memory.

5. U-boot has flash problems:
a. Sectors marked Read-Only come up Writeable after a reset/reboot.
b. Flashing a large number of sectors (like the kernel) sometimes
results in an Error (Ex: Vcc) and had to be retried.
c. Saw environment variables trashed on reset/reboot once.
It's possible that U-boot in flash could get whacked
and the board will need to be re-flashed. During a week
or two of testing I haven't see environment getting whacked.

6. gdb appears to be crashing on target when debugging
on latest root with uclibc left unstriped and with debug;
core dump sent to maxim.

7. U-Boot seems to hang periodically when loading the kernel with
tftp; appears to be worse when network activity is high.

8. 'top' command only shows all cpu's or cpu0; cpu 1 and 2 missing.

9. Program dore dump require ulimit -c to be set but root uses /bin/sh
which is a link to bash but causes it to skip running the bash
startup scripts. Changing root to /bin/bash seems to mess up
ssh logins.

10. For kernel to be compiled on the LX200 (for self checking:
a. Xtensa makefile needs to be fixed:
CC init/do_mounts.o
LD init/mounts.o
/bin/sh: xtensa_test_mmuhifi_c3-linux-uclibc-ld: command not found
make[1]: *** [init/mounts.o] Error 127

b. Need to add ncurses-devel package for 'make menuconfig'

11. Copying vim-7.2.tar from /home/default/src to /usr/local/src resulted
in a corrupt tar header. Apparently we have a NFS bug lurking in the kernel.
On server tar file looks like this:
vim72/000755 001750 001750 00000000000 11047345123 012000 5
ustar00moolmool000000 000000
vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0
ustar00moolmool000000 000000
README.txt for version 7.2 of Vim: Vi IMproved.

On the target/client it's different:
vim72/000755 001750 001750 00000000000 11047345123 012000 5ustar00moolmool000000 000000 vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0ustar00moolmool000000 000000 README.txt for version 7.2 of Vim: Vi IMproved.

=Further reading=

Main Xtensa Linux resources are:

* [http://linux-xtensa.org/ Linux/Xtensa Wiki]
* [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions Buildroot Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Kernel_Build_Instructions Kernel Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Setting_up_U-Boot Setting up U-Boot]
* [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List]
* http://git.linux-xtensa.org/cgi-bin/git.cgi GIT Repositories]

=Thanks to=

* piet
* marc
* dan

And the rest of the people in the Linux-Xtensa mailing list, if you cannot go through some of the steps, don't hesitate to ask on the mailing list, there's always somebody willing to help you!

Evaluation Platforms

2009-12-02T07:09:04Z

Marc: /* Mplayer HiFi 2 Codec Development Board */ Rename and reword a bit

[[image:board.jpg|right]]
= Evaluation and Prototyping Platforms =

The following boards and simulators can be used for evaluation and prototyping purposes. Evaluation platforms generally fall into one of the following categories:
* instruction set simulators,
* emulation systems that use FPGAs to implement any Xtensa or Diamond core (within the capacity of the FPGAs), and
* boards that integrate a specific configured Xtensa or Diamond core(s) into an ASIC.
Field programmable gate arrays (FPGA) contain programmable logic that can be re-configured to emulate complex logic. Although slower than the dedicated circuitry of an ASIC (application specific integrated circuit), their re-configurability and practically zero NRE make them very useful for prototyping (for example, trying multiple Xtensa processor variants or configurations) or small volume applications.

== Instruction Set Simulator ==

Instruction Set Simulators (ISS) mimic the behavior of processors by simulating instructions, memory interface, and other I/O components. This allows developers to run and test their software long before real hardware becomes available. Functional simulators provide the best performance, whereas cycle-accurate simulators provide timing accuracy compatible to that of real hardware. The latter simulate the processor pipeline and external components synchronized to a virtual clock. Although this overhead reduces their performance, it can provide vital information to improve the implementation of algorithms.

=== Tensilica ISS ===

[http://www.tensilica.com/ Tensilica] offers a commercial functional simulator (TurboXim) and cycle-accurate simulator for the Xtensa processor architecture, as part of their standard software development tools. (You may be able to try a free limited time evaluation copy of this toolset.) Tensilica also offers XTMP and XTSC for modeling systems of one or multiple processors alongside custom functional or cycle-accurate software models for other components. Please visit [http://www.tensilica.com/ Tensilica's] website for further information.

The standalone simulator (xt-iss), for example, simply takes an ELF file as its argument and starts simulating instructions from the reset vector. The option <code>--turbo</code> invokes the (much faster) functional simulator TurboXim.

xt-iss ''[--turbo]'' Image.elf

== Emulation Platforms and Systems ==

=== Avnet Virtex-4 LX60 and LX200 ===

[http://www.em.avnet.com Avnet] offers the following development platforms for the Xilinx Virtex-4 LX FPGA that can emulate various
Xtensa processor configurations. The [http://www.em.avnet.com/tensilica1 LX60] is based on the Xilinx 4VLX60 and comes
with a 10/100 Ethernet PHY, DDR memory, flash memory, serial port, and 2 x 16 character LCD panel. The MAC controller, however, needs to be implemented inside the FPGA. MAC controllers are available from different vendors. [http://opencores.org OpenCores], for example, provides a free Ethernet controller supported by Linux and other operating systems. The [http://www.em.avnet.com/tensilica2 LX200] is based on the Xilinx XC4VLX200 and can emulate more complex processor configurations and extensions (for example the [http://www.tensilica.com/products/hifi_audio.htm HiFi 2 Audio Engine]) and provides the same components as the LX60 except for the LCD panel.

[http://www.tensilica.com Tensilica] provides a bitstream that describes the configuration data to emulate the Diamond Standard DC232L processor (Rev.B) on the LX60 FPGA. Tensilica refers to this board and bitstream combination as the XTAV60 board. It also includes support for the OpenCores Ethernet MAC. For further information, please, contact [http://www.tensilica.com/company/contact_us.htm Tensilica] directly.

=== SMP HiFi 2 Development Board ===
Some info is available on an [[SMP HiFi 2 Development Board]] based on the LX200 board from Tensilica, running SMP Linux.
It has three custom Xtensa [http://www.tensilica.com/products/hifi_audio.htm HiFi 2] cores with coherent shared memory, shared and interprocessor interrupts, and the standard LX200 I/O.
Runs a V2009.8 release of [http://git.linux-xtensa.org/cgi-bin/git.cgi?p=u-boot/u-boot-xtensa.git;a=summary U-boot]. The board boots a [http://git.linux-xtensa.org/cgi-bin/git.cgi?p=kernel/xtensa-2.6.29-smp;a=summary 2.6.29 SMP Linux kernel] and runs a
snapshot of [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions buildroot] preconfigured with a C development environment, and the [http://www.tensilica.com/products/literature-docs/application-notes/audio-application-notes/using-tensilica-hifi2-codecs-on-xtensa-linux-with-mplayer.htm Mplayer] media player.

=== Eve ZeBu ===

[http://www.eve-team.com Eve] offers an emulation and verification system that can be used to emulate Xtensa processors. Similar to FPGA boards, the ZeBu system emulates the processor, but has a higher capacity to emulate larger processor configurations and additional peripherals. It also provides direct access to signals for debugging and verification.

See the [[Linux on ZeBu]] page or contact [http://www.eve-team.com Eve] directly to request additional information.

== ASIC Evaluation Platforms ==

=== Stretch S55DVKxx and S56DVKxx ===

[http://www.stretchinc.com Stretch] provides software-configurable processors based on the Xtensa architecture. The S5000 processor supports Linux, and at 300MHz, it runs 5-10 times faster than FPGA based emulation platforms. The S55DVKxx and S56DVKxx development platforms provide 10/100/1000 Ethernet, serial, PCI (only S56DVKxx), and other interfaces.

The Stretch platforms come with RedBoot as the bootloader. It can download and boot the kernel over network using TFTP or from flash. Make sure that RedBoot is configured with a valid Ethernet address or set to DHCP to obtain a valid address. The following commands load the kernel image ''zImage.redboot'' and boot the kernel:

RedBoot> load -r -b 0xd0200000 -h 192.168.1.5 zImage.redboot
RedBoot> exec 0xd0200000

Note that RedBoot requires that the tftp host is in the same subnet as the board.

Mplayer Hifi 2 Codec Development Board

2009-12-02T07:00:37Z

Marc: Mplayer Hifi 2 Codec Development Board moved to SMP HiFi 2 Development Board: Appropriate title

#REDIRECT [[SMP HiFi 2 Development Board]]

SMP HiFi 2 Development Board

2009-12-02T07:00:37Z

Marc: Mplayer Hifi 2 Codec Development Board moved to SMP HiFi 2 Development Board: Appropriate title

This is a "community" guide for how to use the LX200 board based 3-core SMP HiFi-2 Development environment.
If something doesn't work or isn't covered in this guide, please feel free to ask at the [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List].

<div style="margin:0; margin-top:10px; margin-right:10px; border:1px solid #dfdfdf; padding:0 1em 1em 1em; background-color:#ffffcc; align:right; ">
'''NEWS:'''

Some general notes on these instructions:

* They are a work in progress.

* The following was tested on x86 machines running RedHat Fedora Core 5.

* Buildroot build with Fedora Core 9 also seems to be fine; perhaps better than when built on Fedore Core 5.

</div>

== Introduction ==

This document is addressed to someone who received an LX200 board setup by Tensilica
for HiFi2 development.

This document goes over the steps needed to set up the LX200 board for HiFi2 development.
To summarize:
* Setup the board. It likely comes with U-boot preinstalled, ready to boot a linux kernel.
* Install '''git'''.
* Download buildroot and linux kernel trees, pre-configured and built for HiFi-2 development.
* Setup a TFTP server to provide the linux kernel to U-Boot.
* Setup an NFS server to export a linux root file system.
* Setup the Linux kernel to boot from the root file system provided by the NFS server.
Once the development board is up and running, this document:
* Suggests a possible way to tailor the board for easy codec development.
* Shows how to add the Tensilica provided codec packages to the Mplayer packages used by Buildroot, including building and installing.
* Demonstrates two procedures for compiling, linking, and debugging codecs.

All development is expected to be done on a Linux host. (One can in principle use Windows to
develop target libraries. However, linking and subsequent steps need to be done in Linux.)

== Downloading the Latest HiFi-2 Buildroot and Kernel Snapshots ==

The HiFi-2 development environment is maintained in a source code version control system named 'git'. The '''git''' tools are useful when working with this development environment, though they are not strictly necessary. This document generally assumes the use of '''git''', which provides more opportunities for modifying this environment as needed (e.g. building more optional buildroot packages). But points out alternatives to allow getting up and running without having to set it up.

=== Installing git ===

To install '''git''', download a recent tarball from the [http://www.kernel.org/pub/software/scm/git/ official site]. For example, <tt>cd</tt> to a location with enough disk space, and do:

$ '''wget http://www.kernel.org/pub/software/scm/git/git-1.6.5.tar.gz'''

Unpack the tarball, and make and install it. Here we show how to install it to your ~/bin directory:

$ '''gunzip git-1.6.5.tar.gz'''
$ '''tar xf git-1.6.5.tar'''
$ '''cd git-1.6.5'''
$ '''make'''
$ '''make install'''

The git makefile can be instructed to install '''git''' to <tt>/usr/local/bin</tt> as root for system wide access:

$ '''cp git-1.6.5.tar.gz''' /tmp
$ '''su'''
Password:
# '''cd /usr/local/src/'''
# '''mkdir git'''
# '''cd git'''
# '''cp /tmp/git-1.6.5.tar.gz .'''
# '''gunzip git-1.6.5.tar.gz'''
# '''tar xf git-1.6.5.tar'''
# '''cd git-1.6.5'''
# '''make prefix=/usr/local'''
# '''make install'''

See the '''INSTALL'' instruction at the top of the git src directory for details.

Using '''git''' provides easy access to the binaries used to bring up the codec development environment, and leaves in place the infrastructure to modify and build this environment should you wish to. Any changes to '''git'''-managed source trees are easily observed with the '''git''' tools.

=== Installing the Buildroot Snapshot ===

''Note: The HiFi-2 snapshot is in the process of being made.''

To install the buildroot environment (toolchain and root filesystem), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot'''
$ '''cd buildroot-xtensa-HiFi2-Snapshot'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP''' [56 key strokes]
$ '''git checkout snapshot_2+SMP''' [28 key strokes]

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).

You can examine the tree (git repository) and its history visually using <tt>git gui</tt>.
The git GUI is a faster and more convenient method for checking out the HiFi-2 snapshot. To check out the snapshot_2+SMP branch simply run the command 'git gui' and then pull down the branch->create menu. Next select <>Match Tracking Branch Name and click on ''origin/snapshot_2+SMP''. Finally hit the Create Button.

$ '''git gui''''' [8 key strokes]
[Branch] -> Create... [2 key strokes]
<> Match Tracking Branch Name [1 key stroke]
<> Tracking Branch [1 key stroke]
origin/snapshot_2+SMP [1 key stroke]
[Create] [1 key stroke]
[Reposirory]--> Quit [2 key strokes]

If there are issues installing '''git''', as a last resort, an alternative is ftp (may not always get updated, is currenty our of date, waste disk space, so may be dropped at some point):

http://www.linux-xtensa.org/pub/snapshots/buildroot-xtensa-smp.2-Nov-2009.tar.gz

=== Installing the Linux Kernel Snapshot ===

To install the Linux kernel environment (kernel src, config, and HiFi-2 kernel U-Boot image), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp'''
$ '''cd kernel/xtensa-2.6.29-smp'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
$ '''git checkout snapshot_2+SMP'''

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).
As in the build root case, you can also do it from via git gui using the same proceedure
mantioned above.

Now, assuming we are still in the kernel '''xtensa-2.6.29-smp''' directory
copy the kernel U-Boot Image ('''uImage''') to the tftp directory; Ex:

$ '''cp arch/xtensa/boot/uImage /tftpboot/uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'''

NOTE: On some system, like Fedora Core 9, the tftpboot directory has been moved to /var/lib/tftpboot.
In this case we recomend that you just added a symbolic pointer from /etc to /var/lib/tftpboot:

$ '''su'''
# '''cd /etc'''
# '''/var/lib/tftpboot/ tftpboot'''
# '''ls -ld tftpboot'''
lrwxrwxrwx 1 root root 18 2009-11-23 21:14 tftpboot -> /var/lib/tftpboot/
#

== Setting up a TFTP Server to provide the Linux kernel to U-Boot ==

The TFTP service is part of the xinetd and is installed on Fedora workstations.
You can see that it's installed with the check config command which manages the
/etc/rc.d/init.d startup scripts and with the yum search command:

$ '''chkconfig --list'''
NetworkManager 0:off 1:off 2:off 3:off 4:off 5:off 6:off
NetworkManagerDispatcher 0:off 1:off 2:off 3:off 4:off 5:off 6:off
acpid 0:off 1:off 2:off 3:on 4:on 5:on 6:off
.
.
.
xfs 0:off 1:off 2:on 3:on 4:on 5:on 6:off
xinetd 0:off 1:off 2:off 3:on 4:on 5:on 6:off
ypbind 0:off 1:off 2:off 3:on 4:on 5:on 6:off
yum 0:off 1:off 2:off 3:off 4:off 5:off 6:off

xinetd based services:
amanda: off
auth: off
.
.
.
rsync: off
'''tftp: on''' [NOTE that tftp is enabled]
time: off
time-udp: off
uucp: off
$
$
$
$ '''yum search tftp-server'''
Loading "installonlyn" plugin
Searching Packages:
.
.
.
Reading repository metadata in from local files
.
.
.
'''tftp-server.i386 0.41-1.2.1 installed''' [NOTE that tftp server is installed as part of the inet daemon]
Matched from:
tftp-server
The Trivial File Transfer Protocol (TFTP) is normally used only for
booting diskless workstations. The tftp-server package provides the
server for TFTP, which allows users to transfer files to and from a
remote machine. TFTP provides very little security, and should not be
enabled unless it is expressly needed. The TFTP server is run from
/etc/xinetd.d/tftp, and is disabled by default on Red Hat Linux systems.
[piet@pdelaney_fc5 ~]$

TFTP is not normally enabled, to enable it just edit the file /etc/xinetd.d/tftp
and change the disable field to no:

# default: off
# description: The tftp server serves files using the trivial file transfer \
# protocol. The tftp protocol is often used to boot diskless \
# workstations, download configuration files to network-aware printers, \
# and to start the installation process for some operating systems.
service tftp
{
socket_type = dgram
protocol = udp
wait = yes
user = root
server = /usr/sbin/in.tftpd [NOTE: /var/lib/tftpboot on Fedora Core 9]
server_args = -s /tftpboot
'''disable = no'''
per_source = 11
cps = 100 2
flags = IPv4
}

== Setting up an NFS Server to export the Root Filesystem ==

The LX200 board running Linux needs to mount its root filesystem over NFS.
This filesystem was built using buildroot into a cpio format file,
and left in:

buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2/rootfs.xtensa_test_mmuhifi_c3.cpio

We will also be adding an additional minor changes to make your development environment more comfortable.

Pick a place on your workstation to export your root and unpack the cpio file into that directory.
For example here we will set up an export in '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''':

$ '''cd buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2'''
$ '''WHERE=$PWD'''
$ '''mkdir -p /exports/LINUX_ROOT.HiFi-2'''
$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''cpio -i < $WHERE/rootfs.xtensa_test_mmuhifi_c3.cpio'''

Next add a line to /etc/exports:

/exports *(rw,no_root_squash,sync,no_wdelay)

and restart you nfs services:

$ '''/etc/rc.d/init.d/nfs restart'''
or
$ '''/sbin/chkconfig nfs on'''

The showmount command should show your NFS file system now being exported:

$ '''showmount -e'''
Export list for mypc.foobar.com:
/exports *
$

== Configuring U-Boot to Boot Linux ==

Your LX200 board should have arrived with U-Boot installed in the flash ready to use.
The board has a DIP switch (next to the power on/off switch) that provides the 6 LSBs
of the Ethernet MAC, in switch positions 1 thru 6.

DIP Swithes for MAC: 1 2 3 4 5 6 7 8 ethaddr=00:50:C2:13:6f:0a
Little Endian: 0 1 0 1 0 0 * *
^
|
+------ Enables booting U-Boot from Flash

DIP switch 8 should be shipped in the ON position to enable U-Boot booting from flash.
See Sections 4.2.3 and 4.2.4 of the '''Tensilica Avnet (XT-AV200) Board User's Guide'''
for details. Make sure to select a unique MAC address for you board.

Next, connect a serial interface to a text based terminal emulation program,
set to 38400 bps, no parity, 1 stop bit, no handshaking.
For an example of setting [http://en.wikipedia.org/wiki/Minicom minicom]
for this, see [[minicom_xtboard_setup|here]].

Many users of this board are interested in developing codecs and/or HiFi 2 software and will prefer to just boot linux with the root file system we just described how to export on your NFS server. We will use git now to pull a snapshot of a performance 2.6.29 linux kernel and configure U-Boot to automatically boot it after a power cycle.

U-Boot> '''setenv serverip 192.168.11.55''' [TFTP server IP Address: RTOS-LAB2]
U-Boot> '''setenv nfsroot_server 192.168.11.55''' [Root NFS Servers IP Address: My Workstation]
U-Boot> '''setenv ipaddr 192.168.11.155''' [HOST IP address]
U-Boot> '''setenv bootfile uImage.xtensa-2.6.29-smp.test_mmuhifi_c3''' [File to fetch with TFTP and pass to bootm]
U-Boot> '''setenv root-path /exports/LINUX_ROOT.HiFi-2''' [WARNING: Limit path to < 50 characters]
U-Boot> '''setenv bootargs_using_bootp console=ttyS0,38400 ip=bootp root=nfs coredump_filter=0xff''' [Args passed to Linux while booting with BOOTP proto]
U-boot> '''setenv bootargs console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=${nfsroot_server}:${root-path}''' [Args passed to Linux while booting with DHCP proto]
U-boot> '''setenv bootcmd tftpboot\; bootm''' [Boot Linux after fetching it with TFTP]
U-Boot> '''setenv bootdelay 20''' [Delay 20 seconds before booting automaticaly]
U-Boot> '''setenv autostart yes''' [Boot automatically on power-up/reset]
U-Boot> '''saveenv'''
U-Boot>

'''[REMIND: Update the above procedure, show two or thee approaches (ip, dhcp, bootp)]'''

== Tailoring your system prior to Booting ==

There are a few tweaks that developers have found convenient to add to the the root file-system before booting.
As an initial environment for developing we suggest mounting a /home/default files-system that has number of
files useful for getting started. Find another place to tar in the tar ball with the default users file system.
We chose to include this close to the cpio file with the root file-system. Copy the tar bar to where you are
exporting you root file-system and next to it add the 'default' users file-system:

$ '''cd /export'''
$ '''cp /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.10/binaries/default.tar .'''
$ '''tar xf default.tar'''
$ '''cd default'''
$ '''ls'''
[TO BE ADDED]

Notice a file tar ball called '''saved_files.tar'''. This ia a tar file of files that
developers have found convenient to add and replace on the root file system after
adding a new buildroot file system. Here is a list of the files and a brief
explanation on why it's convenient to add or replace them:

root/.bash_profile [added 'ulimit -c unlimited to allow core dumps to be created]
root/.bashrc
etc/profile [added 'ulimit -c unlimited to allow core dumps to be created]
etc/fstab [Tells the system how to mount extra NFS file systems like /home/default]
etc/init.d/S90local [Mounts /home/default]
etc/resolv.conf [Location of DNS servers when your not using DHCP to boot the kernel]
etc/TZ [Your time zone, currently set to California TZ]
etc/dropbear/dropbear_rsa_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/dropbear/dropbear_dss_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/ssh_config [Typically tailored with things like allowing root logins via ssh]
etc/ssh_host_dsa_key [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_dsa_key.pub [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_key
etc/ssh_host_key.pub
etc/ssh_host_rsa_key
etc/ssh_host_rsa_key.pub
etc/sshd_config [Typically tailored with things like allowing root logins via ssh]
etc/rndc.key
etc/random-seed [Generated during 1st boot]
etc/passwd [Changed default user's shell to bash]
etc/shadow [Changed default and root users login password to 'linux1', need to ssh to the board]
exports/ [The path to where the board can mount extra file systems like /home/default.
fac/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]
fac/vol6/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]

Now lets assume your going to stay with these changes and modify them after taring in these changes.
Here we add the tar ball files to the boards root filesystem.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''tar xf /exports/default/'''

This is a good time to edit a few files on the boards file system
before boot it.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''vi etc/fstab''' [Change fstab entry for /home/default and others to your taste]
$ '''vi etc/init.d/S90local''' [You might want to disable mounting of NFS file systems on the 1st Boot and add this once you try it manually]

== Booting Linux for the 1st Time ==

We should now be ready to boot linux on your LX200. You have exported the root file-system and made the
kernel available to a TFTP server. Now let's start with hitting the reset button on the LX200 and it should
auto-boot the kernel, resulting in output such as [[HiFi2_Board_Example_Linux_Boot_Log|this example log]].

== Tailoring your system prior to developing your codec ==

To make your experience more pleasant we suggest you tailor your environment.
Here are some of the changes that we have found helpful:

1. Add a root password to that you can login with ssh.
2. Run rdate with an ntp server on booting.
3. Add NFS mounts to /etc/fstab for your code and buildroot code.
4. Copy in previous ssh server encryption keys to /etc/dropbear to speed up your initial boot.
5. Mount a 'default' user home directory with:
a. Linux Test Suite pre-patch to test the system
b. Audio test example files
c. Copies of Mplayer and its Plug-ins from Buildroot modified slightly to make installation easy.
d. Misc audio test programs.

[TO BE DONE - Where to get 'default' user home directory tar ball and 1st boot patch]

== Compiling the Mplayer Plugins and linking them with MPEG-1 Audio Layer 3 (MP3) and MPEG-4 AAC Codecs ==

Mplayer is provided as an example environment for developing and testing Codecs and HiFi 2 software. There
are two ways to build Mplayer and the plug-in modules that use the codecs. The buildroot
tree (pulled with git) has a copy of mplayer and the plugins that can be built in the
snapshot via 'make menuconfig'. This is a good environment to use once codecs are
developed and debugged.

To facilitate development the mplayer packages can be copied to your NFS mounted development
environment. From there you can just configure mplayer to compile on the board and debug
mplayer and your codecs with gdb locally.

In the default user home directory we have a directory /home/default/buildroot_mplayer_stuff
with a copy of three of the mplayer packages:

[root@hifi buildroot_mplayer_stuff]# '''ls -l'''
drwxr-xr-x 34 root root 4096 Nov 10 05:01 MPlayer-1.0rc2/
drwxr-xr-x 4 root root 4096 Nov 10 01:36 mplayer_hifi2_aacplus_v2_plugin/
drwxr-xr-x 3 root root 4096 Nov 10 00:57 mplayer_hifi2_mp3_plugin/

they were simply copied from the buildroot-xtensa-HiFi2-Snapshot.2/package directory.

To get your development environment ready to compile the mplayer plug-ins you need
to configure Mplayer to use the local C compiler and linker:

# '''cd /home/default/buildroot_mplayer_stuff/MPlayer-1.0rc2/'''
# '''CFLAGS="-g3" ./configure'''

This will take about 15 minutes to configure. After that you can build the
plugins or mplayer. If you want to recompile mplayer it's likely best/necessary
to use the same args to .configure as used by buildroot:

.CFLAGS="-g3" ./configure \
--prefix=/usr \
--confdir=/etc/mplayer \
--with-extraincdir=/usr/include \
--with-extralibdir=/lib \
--disable-gui \
--enable-mad \
--enable-fbdev \
--disable-mencoder \
--disable-dvdnav \
--disable-dvdread \
--disable-dvdread-internal \
--disable-libdvdcss-internal \
--disable-big-endian \
--disable-nemesi \
--disable-tv \
--enable-dynamic-plugins

We are currently able to compile most of mplayer on the XL200 but
due to space limitations it's not possible to compile it -O0.

Now, lets focus on compiling linking the plugins. They are a nice
example of compiling a audio application on the LX200.

We modified the Makefile of the codes slightly, and will make it available.
These additions just instruct make how to install the plugins as explained
in the Chapter 7 of the Linux HiFi application note.

For example the mp3 plugin has this addition:

target_install::
-mkdir /etc/mplayer
cp codecs.conf /etc/mplayer
-mkdir /usr/lib/mplayer
cp ad_xa_mp3_dec.so /usr/lib/mplayer/
cp xa_mp3_dec.so /usr/lib/mplayer
chmod 755 /usr/lib/mplayer/ad_xa_mp3_dec.so
chmod 755 /usr/lib/mplayer/xa_mp3_dec.so

It's just providing a codec config file for mplayer at '''/etc/mplayer/codecs.conf''' and
copying the plug-in to '''/usr/lib/mplayer'''. To install the mp3 codec plugin and mplayer
config file just copy your codec that was compiled with '''xcc''' to the directory, compile it,
and install.

# '''cd /fac/vol6/audio/release/bin/l32r_LE5_pic'''
# '''cp xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz /tmp'''
#
# '''cd /home/default/buildroot_mplayer_stuff'''
# '''cd mplayer_hifi2_mp3_plugin'''
# '''cp /tmp/xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz .'''
# '''gunzip xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz'''
# '''tar xf xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tar'''
# '''make'''
# '''make target_install'''

The unpacking of the Tensilica mp3 codec tar ball will install the following files:

xa_mp3_dec/
xa_mp3_dec/README
xa_mp3_dec/include/
xa_mp3_dec/include/mp3_dec/
xa_mp3_dec/include/mp3_dec/xa_mp3_dec_api.h
xa_mp3_dec/include/xa_apicmd_standards.h
xa_mp3_dec/include/xa_error_handler.h
xa_mp3_dec/include/xa_error_standards.h
xa_mp3_dec/include/xa_memory_standards.h
xa_mp3_dec/include/xa_type_def.h
xa_mp3_dec/test/
xa_mp3_dec/test/build/
xa_mp3_dec/test/build/ldscript_stream_data.txt
xa_mp3_dec/test/build/makefile_testbench_sample
xa_mp3_dec/test/build/paramfilesimple.txt
xa_mp3_dec/test/include/
xa_mp3_dec/test/include/id3_tag_decode.h
xa_mp3_dec/test/src/
xa_mp3_dec/test/src/xa_mp3_dec_sample_testbench.c
xa_mp3_dec/test/src/id3_tag_decode.c
xa_mp3_dec/test/src/stream_data.c
xa_mp3_dec/test/src/xa_mp3_dec_error_handler.c
xa_mp3_dec/test/test_inp/
xa_mp3_dec/test/test_inp/compl.mp3
xa_mp3_dec/test/test_inp/hihat.mp3
xa_mp3_dec/test/test_out/
xa_mp3_dec/test/test_out/force_mkdir.txt
xa_mp3_dec/test/test_ref/
xa_mp3_dec/test/test_ref/compl_24bit.wav
xa_mp3_dec/test/test_ref/hihat_16bit.wav
xa_mp3_dec/lib/
xa_mp3_dec/lib/xa_mp3_dec.a
xa_mp3_dec/doc/
xa_mp3_dec/doc/HiFi2-MP3-DecoderProgrammersGuide.pdf

[TO BE DONE - Add missing C file, make clean deletes it!]

The xa_mp3_dec.a archive will be used by the Makefile in
the mplayer_hifi2_mp3_plugin directory to make the mplayer plug-in.
Section 6 of the '''Using Tensilica HiFi 2 Codec on Xtensa Linux with MPlayer'' Application Note
has a detailed description of the encapsulation process used by the plug-ins.

== Compiling Generic GPL Packages ==

For your development you may want to add a few GPL packages that you find helpfull.
This can be done on the LX200 just as you would on a normal workstation, thought
much slower. For example here we configure and build a few common GPL packages:

[[Building the Strace Package]]

[[Building the vim Package]]

== Compiling Tie Code with XCC ==

Codecs like MP3 and AAC have been written in C with TIE extensions and can only be compiled with '''xcc'''.
XCC is likely to large to run on the board without virtual memory. There are two approaches to compiling
Linux TIE code with '''xcc'''. The simple approach assumes the host workstation and target code running of the board
are similar enough that the library interfaces defined by the include files are compatable. This is often the
case for standard system calls, libc, and stdio.The proper approach uses a virtual core that we will create
that has built in references to the library and include files on the target code running on the LX200.

=== Simply using Xtensa Tools to compile the TIE code on a workstation ===

Below we illustrate compiling a simple audio test program on a workstation.
We start by referring to the XTENSA tools build by Xplorer, putting '''xcc''' into our search path and set the standard XTENSA_* environement variables.
For example:

setenv XTENSA_CORE test_mmuhifi_c3
setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config
setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin

setenv PATH ${XTENSA_TOOLS}:${PATH}

[piet@fc9desktop Tests] $ '''cd /exports/default/Audio_Tests''' [NOTE: This is being done on a Workstation]
[piet@fc9desktop Audio_Tests]$ '''xt-xcc -g3 -O0 -fPIC -c hifitest.c'''

Next we link the object on the XL200 board and run gdb on the TIE enhanced code:

[root@hifi Audio_Tests]# '''gcc -g hifitest.o -o hifitest'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:4640; Eatting cpu; time:0
cnt:0x0, pid:4640; Eating Tie; time:7
^C
[root@hifi Audio_Tests]# '''gdb ./hifitest''' [NOTE: This is being done on the LX200 board]
GNU gdb 6.6
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "xtensa_test_mmuhifi_c3-linux-uclibc"...
Using host libthread_db library "/lib/libthread_db.so.1".
(gdb) '''break main'''
Breakpoint 1 at 0x400401: file /exports/default/Audio_Tests/hifitest.c, line 20.
(gdb) '''run'''
Starting program: /home/default/Audio_Tests/hifitest

Breakpoint 1, main (argc=1, argv=0x3fb3fab4)
at /exports/default/Audio_Tests/hifitest.c:20
20 time_t time0 = time(NULL);
(gdb) '''step'''
21 time_t time1 = time(NULL);

=== Building Linux Applications Using Tensilica's XCC Compiler ===

Section 4.3 of the latest ''Xtensa OSKit Guide'' (from Tensilica's
RC-2009.0 release) describes how to setup XCC to compile Linux applications.
For details, see the guide.

A summary follows. The XTENSA_TOOLS_ROOT, XTENSA_ROOT, BUILDROOT_DIR, and TARGET_SYSROOT
environment variables must be set according to where things were installed;
values shown here are for illustration only. The CORENAME variable, set correctly
below for this board, reflects
the name of the core as known to open source tools (as opposed to XTENSA_CORE
which is the core name as known to Xtensa Tools; both happen to match here).

$ setenv XTENSA_ROOT /home/someuser/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
$ setenv XTENSA_TOOLS_ROOT /home/someuser/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools
$ setenv TARGET_SYSROOT /exports/LINUX_ROOT.HiFi-2
$ setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12

$ setenv CORENAME test_mmuhifi_c3

$ cd ${BUILDROOT_DIR}
$ ${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install \
--sysroot=./build_xtensa_${CORENAME}/staging_dir \
--linux-gcc=./build_xtensa_${CORENAME}/staging_dir/usr/bin/xtensa_${CORENAME}-linux-gcc

Assuming the above completes successfully, you can now build applications using Xtensa Tools. First set the usual environment variables:

$ setenv XTENSA_CORE default
$ setenv XTENSA_SYSTEM ${XTENSA_ROOT}-linux/config
$ setenv PATH ${XTENSA_TOOLS_ROOT}/bin:${PATH}

And build something:

$ echo '#include <stdio.h>' > hello.c
$ echo 'int main() {printf("Hello!\n");return 0;}' >> hello.c
$ xt-xcc -g hello.c -o hello

Then copy it where the target can see it:

$ cp hello ${TARGET_SYSROOT}/root

And run it on the target:

[root@hifi ~]# /root/hello

Here's a more interesting example that uses Tensilica TIE features.
(This cannot be compiled using GCC.)

$ cd ${TARGET_SYSROOT}/home/default/Audio_Tests
$ xt-xcc -g hifitest.c -o hifitest

In a ssh termulator window on the board you can now run hifitest:

[root@hifi ~]# '''cd /home/default/Audio_Tests/'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:23178; Eatting cpu; time:0 '''<control-C>'''

[root@hifi Audio_Tests]#

Here is the source code for the [[hifitest.c|hifitest.c source file]] used above.

== Adding your codec to Buildroot ==

Xtensa developers provide detailed instructions on building the root filesystem and the Linux kernel.
* [[Buildroot_Build_Instructions|Instructions for building and booting Linux (buildroot)]].

Building a comprehensive development environment with buildroot can be a chalanging experience and worthy of providing some tips on process.
Here are notes of the configs used for the three menuconfigs in this 2nd snapshot
provided with SMP additions:
$ '''make [[HiFi-2 snapshot_2 SMP Snapshot menuconfig | menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP uclibc-menuconfig | uclibc-menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP busybox-menuconfig | busybox-menuconfig]]'''

[TO BE DONE - making a new tar ball of saved files, building buildroot, ...]

== Known Problems being investigated, suggested that you know about and possibly avoid ==

1. Using NFS mounts with default parameters causes memory congestion. Use these mount options:

'''vers=2,rsize=4096,wsize=4096,hard,nointr,nolock,nolock,timeo=11,retrans=3,noauto'''

this is extremely important to add to your /etc/fstab on the target.

2. Can't swap over NFS yet, memory can get tight and cause application to be killed.
a. Trying procedure documented in U-Boot Manual.

3. Building the C development with X11 doesn't work with buildroot.

4. Though Mplayer plug-in can be compiled, Mplayer can be compiled but still has a few issues:
a. Can't be compiled -O0 due to limited memory while compiling one file,
b. Compiler infrequently crashes and make has to be restarted.
Not seeing this problem with root build on Fedore Core 9.
Perhaps this was caused by debug kernel or LTP using all of the memory.

5. U-boot has flash problems:
a. Sectors marked Read-Only come up Writeable after a reset/reboot.
b. Flashing a large number of sectors (like the kernel) sometimes
results in an Error (Ex: Vcc) and had to be retried.
c. Saw environment variables trashed on reset/reboot once.
It's possible that U-boot in flash could get whacked
and the board will need to be re-flashed. During a week
or two of testing I haven't see environment getting whacked.

6. gdb appears to be crashing on target when debugging
on latest root with uclibc left unstriped and with debug;
core dump sent to maxim.

7. U-Boot seems to hang periodically when loading the kernel with
tftp; appears to be worse when network activity is high.

8. 'top' command only shows all cpu's or cpu0; cpu 1 and 2 missing.

9. Program dore dump require ulimit -c to be set but root uses /bin/sh
which is a link to bash but causes it to skip running the bash
startup scripts. Changing root to /bin/bash seems to mess up
ssh logins.

10. For kernel to be compiled on the LX200 (for self checking:
a. Xtensa makefile needs to be fixed:
CC init/do_mounts.o
LD init/mounts.o
/bin/sh: xtensa_test_mmuhifi_c3-linux-uclibc-ld: command not found
make[1]: *** [init/mounts.o] Error 127

b. Need to add ncurses-devel package for 'make menuconfig'

11. Copying vim-7.2.tar from /home/default/src to /usr/local/src resulted
in a corrupt tar header. Apparently we have a NFS bug lurking in the kernel.
On server tar file looks like this:
vim72/000755 001750 001750 00000000000 11047345123 012000 5
ustar00moolmool000000 000000
vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0
ustar00moolmool000000 000000
README.txt for version 7.2 of Vim: Vi IMproved.

On the target/client it's different:
vim72/000755 001750 001750 00000000000 11047345123 012000 5ustar00moolmool000000 000000 vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0ustar00moolmool000000 000000 README.txt for version 7.2 of Vim: Vi IMproved.

=Further reading=

Main Xtensa Linux resources are:

* [http://linux-xtensa.org/ Linux/Xtensa Wiki]
* [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions Buildroot Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Kernel_Build_Instructions Kernel Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Setting_up_U-Boot Setting up U-Boot]
* [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List]
* http://git.linux-xtensa.org/cgi-bin/git.cgi GIT Repositories]

=Thanks to=

* piet
* marc
* dan

And the rest of the people in the Linux-Xtensa mailing list, if you cannot go through some of the steps, don't hesitate to ask on the mailing list, there's always somebody willing to help you!

SMP HiFi 2 Development Board

2009-12-02T05:48:54Z

Marc: Fix typos

This is a "community" guide for how to use the LX200 board based 3-core SMP HiFi-2 Development environment.
If something doesn't work or isn't covered in this guide, please feel free to ask at the [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List].

<div style="margin:0; margin-top:10px; margin-right:10px; border:1px solid #dfdfdf; padding:0 1em 1em 1em; background-color:#ffffcc; align:right; ">
'''NEWS:'''

Some general notes on these instructions:

* They are a work in progress.

* The following was tested on x86 machines running RedHat Fedora Core 5.

* Buildroot build with Fedora Core 9 also seems to be fine; perhaps better than when built on Fedore Core 5.

</div>

== Introduction ==

This document is addressed to someone who received an LX200 board setup by Tensilica
for HiFi2 development.

This document goes over the steps needed to set up the LX200 board for HiFi2 development.
To summarize:
* Setup the board. It likely comes with U-boot preinstalled, ready to boot a linux kernel.
* Install '''git'''.
* Download buildroot and linux kernel trees, pre-configured and built for HiFi-2 development.
* Setup a TFTP server to provide the linux kernel to U-Boot.
* Setup an NFS server to export a linux root file system.
* Setup the Linux kernel to boot from the root file system provided by the NFS server.
Once the development board is up and running, this document:
* Suggests a possible way to tailor the board for easy codec development.
* Shows how to add the Tensilica provided codec packages to the Mplayer packages used by Buildroot, including building and installing.
* Demonstrates two procedures for compiling, linking, and debugging codecs.

All development is expected to be done on a Linux host. (One can in principle use Windows to
develop target libraries. However, linking and subsequent steps need to be done in Linux.)

== Downloading the Latest HiFi-2 Buildroot and Kernel Snapshots ==

The HiFi-2 development environment is maintained in a source code version control system named 'git'. The '''git''' tools are useful when working with this development environment, though they are not strictly necessary. This document generally assumes the use of '''git''', which provides more opportunities for modifying this environment as needed (e.g. building more optional buildroot packages). But points out alternatives to allow getting up and running without having to set it up.

=== Installing git ===

To install '''git''', download a recent tarball from the [http://www.kernel.org/pub/software/scm/git/ official site]. For example, <tt>cd</tt> to a location with enough disk space, and do:

$ '''wget http://www.kernel.org/pub/software/scm/git/git-1.6.5.tar.gz'''

Unpack the tarball, and make and install it. Here we show how to install it to your ~/bin directory:

$ '''gunzip git-1.6.5.tar.gz'''
$ '''tar xf git-1.6.5.tar'''
$ '''cd git-1.6.5'''
$ '''make'''
$ '''make install'''

The git makefile can be instructed to install '''git''' to <tt>/usr/local/bin</tt> as root for system wide access:

$ '''cp git-1.6.5.tar.gz''' /tmp
$ '''su'''
Password:
# '''cd /usr/local/src/'''
# '''mkdir git'''
# '''cd git'''
# '''cp /tmp/git-1.6.5.tar.gz .'''
# '''gunzip git-1.6.5.tar.gz'''
# '''tar xf git-1.6.5.tar'''
# '''cd git-1.6.5'''
# '''make prefix=/usr/local'''
# '''make install'''

See the '''INSTALL'' instruction at the top of the git src directory for details.

Using '''git''' provides easy access to the binaries used to bring up the codec development environment, and leaves in place the infrastructure to modify and build this environment should you wish to. Any changes to '''git'''-managed source trees are easily observed with the '''git''' tools.

=== Installing the Buildroot Snapshot ===

''Note: The HiFi-2 snapshot is in the process of being made.''

To install the buildroot environment (toolchain and root filesystem), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot'''
$ '''cd buildroot-xtensa-HiFi2-Snapshot'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP''' [56 key strokes]
$ '''git checkout snapshot_2+SMP''' [28 key strokes]

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).

You can examine the tree (git repository) and its history visually using <tt>git gui</tt>.
The git GUI is a faster and more convenient method for checking out the HiFi-2 snapshot. To check out the snapshot_2+SMP branch simply run the command 'git gui' and then pull down the branch->create menu. Next select <>Match Tracking Branch Name and click on ''origin/snapshot_2+SMP''. Finally hit the Create Button.

$ '''git gui''''' [8 key strokes]
[Branch] -> Create... [2 key strokes]
<> Match Tracking Branch Name [1 key stroke]
<> Tracking Branch [1 key stroke]
origin/snapshot_2+SMP [1 key stroke]
[Create] [1 key stroke]
[Reposirory]--> Quit [2 key strokes]

If there are issues installing '''git''', as a last resort, an alternative is ftp (may not always get updated, is currenty our of date, waste disk space, so may be dropped at some point):

http://www.linux-xtensa.org/pub/snapshots/buildroot-xtensa-smp.2-Nov-2009.tar.gz

=== Installing the Linux Kernel Snapshot ===

To install the Linux kernel environment (kernel src, config, and HiFi-2 kernel U-Boot image), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp'''
$ '''cd kernel/xtensa-2.6.29-smp'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
$ '''git checkout snapshot_2+SMP'''

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).
As in the build root case, you can also do it from via git gui using the same proceedure
mantioned above.

Now, assuming we are still in the kernel '''xtensa-2.6.29-smp''' directory
copy the kernel U-Boot Image ('''uImage''') to the tftp directory; Ex:

$ '''cp arch/xtensa/boot/uImage /tftpboot/uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'''

NOTE: On some system, like Fedora Core 9, the tftpboot directory has been moved to /var/lib/tftpboot.
In this case we recomend that you just added a symbolic pointer from /etc to /var/lib/tftpboot:

$ '''su'''
# '''cd /etc'''
# '''/var/lib/tftpboot/ tftpboot'''
# '''ls -ld tftpboot'''
lrwxrwxrwx 1 root root 18 2009-11-23 21:14 tftpboot -> /var/lib/tftpboot/
#

== Setting up a TFTP Server to provide the Linux kernel to U-Boot ==

The TFTP service is part of the xinetd and is installed on Fedora workstations.
You can see that it's installed with the check config command which manages the
/etc/rc.d/init.d startup scripts and with the yum search command:

$ '''chkconfig --list'''
NetworkManager 0:off 1:off 2:off 3:off 4:off 5:off 6:off
NetworkManagerDispatcher 0:off 1:off 2:off 3:off 4:off 5:off 6:off
acpid 0:off 1:off 2:off 3:on 4:on 5:on 6:off
.
.
.
xfs 0:off 1:off 2:on 3:on 4:on 5:on 6:off
xinetd 0:off 1:off 2:off 3:on 4:on 5:on 6:off
ypbind 0:off 1:off 2:off 3:on 4:on 5:on 6:off
yum 0:off 1:off 2:off 3:off 4:off 5:off 6:off

xinetd based services:
amanda: off
auth: off
.
.
.
rsync: off
'''tftp: on''' [NOTE that tftp is enabled]
time: off
time-udp: off
uucp: off
$
$
$
$ '''yum search tftp-server'''
Loading "installonlyn" plugin
Searching Packages:
.
.
.
Reading repository metadata in from local files
.
.
.
'''tftp-server.i386 0.41-1.2.1 installed''' [NOTE that tftp server is installed as part of the inet daemon]
Matched from:
tftp-server
The Trivial File Transfer Protocol (TFTP) is normally used only for
booting diskless workstations. The tftp-server package provides the
server for TFTP, which allows users to transfer files to and from a
remote machine. TFTP provides very little security, and should not be
enabled unless it is expressly needed. The TFTP server is run from
/etc/xinetd.d/tftp, and is disabled by default on Red Hat Linux systems.
[piet@pdelaney_fc5 ~]$

TFTP is not normally enabled, to enable it just edit the file /etc/xinetd.d/tftp
and change the disable field to no:

# default: off
# description: The tftp server serves files using the trivial file transfer \
# protocol. The tftp protocol is often used to boot diskless \
# workstations, download configuration files to network-aware printers, \
# and to start the installation process for some operating systems.
service tftp
{
socket_type = dgram
protocol = udp
wait = yes
user = root
server = /usr/sbin/in.tftpd [NOTE: /var/lib/tftpboot on Fedora Core 9]
server_args = -s /tftpboot
'''disable = no'''
per_source = 11
cps = 100 2
flags = IPv4
}

== Setting up an NFS Server to export the Root Filesystem ==

The LX200 board running Linux needs to mount its root filesystem over NFS.
This filesystem was built using buildroot into a cpio format file,
and left in:

buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2/rootfs.xtensa_test_mmuhifi_c3.cpio

We will also be adding an additional minor changes to make your development environment more comfortable.

Pick a place on your workstation to export your root and unpack the cpio file into that directory.
For example here we will set up an export in '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''':

$ '''cd buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2'''
$ '''WHERE=$PWD'''
$ '''mkdir -p /exports/LINUX_ROOT.HiFi-2'''
$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''cpio -i < $WHERE/rootfs.xtensa_test_mmuhifi_c3.cpio'''

Next add a line to /etc/exports:

/exports *(rw,no_root_squash,sync,no_wdelay)

and restart you nfs services:

$ '''/etc/rc.d/init.d/nfs restart'''
or
$ '''/sbin/chkconfig nfs on'''

The showmount command should show your NFS file system now being exported:

$ '''showmount -e'''
Export list for mypc.foobar.com:
/exports *
$

== Configuring U-Boot to Boot Linux ==

Your LX200 board should have arrived with U-Boot installed in the flash ready to use.
The board has a DIP switch (next to the power on/off switch) that provides the 6 LSBs
of the Ethernet MAC, in switch positions 1 thru 6.

DIP Swithes for MAC: 1 2 3 4 5 6 7 8 ethaddr=00:50:C2:13:6f:0a
Little Endian: 0 1 0 1 0 0 * *
^
|
+------ Enables booting U-Boot from Flash

DIP switch 8 should be shipped in the ON position to enable U-Boot booting from flash.
See Sections 4.2.3 and 4.2.4 of the '''Tensilica Avnet (XT-AV200) Board User's Guide'''
for details. Make sure to select a unique MAC address for you board.

Next, connect a serial interface to a text based terminal emulation program,
set to 38400 bps, no parity, 1 stop bit, no handshaking.
For an example of setting [http://en.wikipedia.org/wiki/Minicom minicom]
for this, see [[minicom_xtboard_setup|here]].

Many users of this board are interested in developing codecs and/or HiFi 2 software and will prefer to just boot linux with the root file system we just described how to export on your NFS server. We will use git now to pull a snapshot of a performance 2.6.29 linux kernel and configure U-Boot to automatically boot it after a power cycle.

U-Boot> '''setenv serverip 192.168.11.55''' [TFTP server IP Address: RTOS-LAB2]
U-Boot> '''setenv nfsroot_server 192.168.11.55''' [Root NFS Servers IP Address: My Workstation]
U-Boot> '''setenv ipaddr 192.168.11.155''' [HOST IP address]
U-Boot> '''setenv bootfile uImage.xtensa-2.6.29-smp.test_mmuhifi_c3''' [File to fetch with TFTP and pass to bootm]
U-Boot> '''setenv root-path /exports/LINUX_ROOT.HiFi-2''' [WARNING: Limit path to < 50 characters]
U-Boot> '''setenv bootargs_using_bootp console=ttyS0,38400 ip=bootp root=nfs coredump_filter=0xff''' [Args passed to Linux while booting with BOOTP proto]
U-boot> '''setenv bootargs console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=${nfsroot_server}:${root-path}''' [Args passed to Linux while booting with DHCP proto]
U-boot> '''setenv bootcmd tftpboot\; bootm''' [Boot Linux after fetching it with TFTP]
U-Boot> '''setenv bootdelay 20''' [Delay 20 seconds before booting automaticaly]
U-Boot> '''setenv autostart yes''' [Boot automatically on power-up/reset]
U-Boot> '''saveenv'''
U-Boot>

'''[REMIND: Update the above procedure, show two or thee approaches (ip, dhcp, bootp)]'''

== Tailoring your system prior to Booting ==

There are a few tweaks that developers have found convenient to add to the the root file-system before booting.
As an initial environment for developing we suggest mounting a /home/default files-system that has number of
files useful for getting started. Find another place to tar in the tar ball with the default users file system.
We chose to include this close to the cpio file with the root file-system. Copy the tar bar to where you are
exporting you root file-system and next to it add the 'default' users file-system:

$ '''cd /export'''
$ '''cp /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.10/binaries/default.tar .'''
$ '''tar xf default.tar'''
$ '''cd default'''
$ '''ls'''
[TO BE ADDED]

Notice a file tar ball called '''saved_files.tar'''. This ia a tar file of files that
developers have found convenient to add and replace on the root file system after
adding a new buildroot file system. Here is a list of the files and a brief
explanation on why it's convenient to add or replace them:

root/.bash_profile [added 'ulimit -c unlimited to allow core dumps to be created]
root/.bashrc
etc/profile [added 'ulimit -c unlimited to allow core dumps to be created]
etc/fstab [Tells the system how to mount extra NFS file systems like /home/default]
etc/init.d/S90local [Mounts /home/default]
etc/resolv.conf [Location of DNS servers when your not using DHCP to boot the kernel]
etc/TZ [Your time zone, currently set to California TZ]
etc/dropbear/dropbear_rsa_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/dropbear/dropbear_dss_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/ssh_config [Typically tailored with things like allowing root logins via ssh]
etc/ssh_host_dsa_key [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_dsa_key.pub [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_key
etc/ssh_host_key.pub
etc/ssh_host_rsa_key
etc/ssh_host_rsa_key.pub
etc/sshd_config [Typically tailored with things like allowing root logins via ssh]
etc/rndc.key
etc/random-seed [Generated during 1st boot]
etc/passwd [Changed default user's shell to bash]
etc/shadow [Changed default and root users login password to 'linux1', need to ssh to the board]
exports/ [The path to where the board can mount extra file systems like /home/default.
fac/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]
fac/vol6/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]

Now lets assume your going to stay with these changes and modify them after taring in these changes.
Here we add the tar ball files to the boards root filesystem.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''tar xf /exports/default/'''

This is a good time to edit a few files on the boards file system
before boot it.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''vi etc/fstab''' [Change fstab entry for /home/default and others to your taste]
$ '''vi etc/init.d/S90local''' [You might want to disable mounting of NFS file systems on the 1st Boot and add this once you try it manually]

== Booting Linux for the 1st Time ==

We should now be ready to boot linux on your LX200. You have exported the root file-system and made the
kernel available to a TFTP server. Now let's start with hitting the reset button on the LX200 and it should
auto-boot the kernel, resulting in output such as [[HiFi2_Board_Example_Linux_Boot_Log|this example log]].

== Tailoring your system prior to developing your codec ==

To make your experience more pleasant we suggest you tailor your environment.
Here are some of the changes that we have found helpful:

1. Add a root password to that you can login with ssh.
2. Run rdate with an ntp server on booting.
3. Add NFS mounts to /etc/fstab for your code and buildroot code.
4. Copy in previous ssh server encryption keys to /etc/dropbear to speed up your initial boot.
5. Mount a 'default' user home directory with:
a. Linux Test Suite pre-patch to test the system
b. Audio test example files
c. Copies of Mplayer and its Plug-ins from Buildroot modified slightly to make installation easy.
d. Misc audio test programs.

[TO BE DONE - Where to get 'default' user home directory tar ball and 1st boot patch]

== Compiling the Mplayer Plugins and linking them with MPEG-1 Audio Layer 3 (MP3) and MPEG-4 AAC Codecs ==

Mplayer is provided as an example environment for developing and testing Codecs and HiFi 2 software. There
are two ways to build Mplayer and the plug-in modules that use the codecs. The buildroot
tree (pulled with git) has a copy of mplayer and the plugins that can be built in the
snapshot via 'make menuconfig'. This is a good environment to use once codecs are
developed and debugged.

To facilitate development the mplayer packages can be copied to your NFS mounted development
environment. From there you can just configure mplayer to compile on the board and debug
mplayer and your codecs with gdb locally.

In the default user home directory we have a directory /home/default/buildroot_mplayer_stuff
with a copy of three of the mplayer packages:

[root@hifi buildroot_mplayer_stuff]# '''ls -l'''
drwxr-xr-x 34 root root 4096 Nov 10 05:01 MPlayer-1.0rc2/
drwxr-xr-x 4 root root 4096 Nov 10 01:36 mplayer_hifi2_aacplus_v2_plugin/
drwxr-xr-x 3 root root 4096 Nov 10 00:57 mplayer_hifi2_mp3_plugin/

they were simply copied from the buildroot-xtensa-HiFi2-Snapshot.2/package directory.

To get your development environment ready to compile the mplayer plug-ins you need
to configure Mplayer to use the local C compiler and linker:

# '''cd /home/default/buildroot_mplayer_stuff/MPlayer-1.0rc2/'''
# '''CFLAGS="-g3" ./configure'''

This will take about 15 minutes to configure. After that you can build the
plugins or mplayer. If you want to recompile mplayer it's likely best/necessary
to use the same args to .configure as used by buildroot:

.CFLAGS="-g3" ./configure \
--prefix=/usr \
--confdir=/etc/mplayer \
--with-extraincdir=/usr/include \
--with-extralibdir=/lib \
--disable-gui \
--enable-mad \
--enable-fbdev \
--disable-mencoder \
--disable-dvdnav \
--disable-dvdread \
--disable-dvdread-internal \
--disable-libdvdcss-internal \
--disable-big-endian \
--disable-nemesi \
--disable-tv \
--enable-dynamic-plugins

We are currently able to compile most of mplayer on the XL200 but
due to space limitations it's not possible to compile it -O0.

Now, lets focus on compiling linking the plugins. They are a nice
example of compiling a audio application on the LX200.

We modified the Makefile of the codes slightly, and will make it available.
These additions just instruct make how to install the plugins as explained
in the Chapter 7 of the Linux HiFi application note.

For example the mp3 plugin has this addition:

target_install::
-mkdir /etc/mplayer
cp codecs.conf /etc/mplayer
-mkdir /usr/lib/mplayer
cp ad_xa_mp3_dec.so /usr/lib/mplayer/
cp xa_mp3_dec.so /usr/lib/mplayer
chmod 755 /usr/lib/mplayer/ad_xa_mp3_dec.so
chmod 755 /usr/lib/mplayer/xa_mp3_dec.so

It's just providing a codec config file for mplayer at '''/etc/mplayer/codecs.conf''' and
copying the plug-in to '''/usr/lib/mplayer'''. To install the mp3 codec plugin and mplayer
config file just copy your codec that was compiled with '''xcc''' to the directory, compile it,
and install.

# '''cd /fac/vol6/audio/release/bin/l32r_LE5_pic'''
# '''cp xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz /tmp'''
#
# '''cd /home/default/buildroot_mplayer_stuff'''
# '''cd mplayer_hifi2_mp3_plugin'''
# '''cp /tmp/xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz .'''
# '''gunzip xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz'''
# '''tar xf xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tar'''
# '''make'''
# '''make target_install'''

The unpacking of the Tensilica mp3 codec tar ball will install the following files:

xa_mp3_dec/
xa_mp3_dec/README
xa_mp3_dec/include/
xa_mp3_dec/include/mp3_dec/
xa_mp3_dec/include/mp3_dec/xa_mp3_dec_api.h
xa_mp3_dec/include/xa_apicmd_standards.h
xa_mp3_dec/include/xa_error_handler.h
xa_mp3_dec/include/xa_error_standards.h
xa_mp3_dec/include/xa_memory_standards.h
xa_mp3_dec/include/xa_type_def.h
xa_mp3_dec/test/
xa_mp3_dec/test/build/
xa_mp3_dec/test/build/ldscript_stream_data.txt
xa_mp3_dec/test/build/makefile_testbench_sample
xa_mp3_dec/test/build/paramfilesimple.txt
xa_mp3_dec/test/include/
xa_mp3_dec/test/include/id3_tag_decode.h
xa_mp3_dec/test/src/
xa_mp3_dec/test/src/xa_mp3_dec_sample_testbench.c
xa_mp3_dec/test/src/id3_tag_decode.c
xa_mp3_dec/test/src/stream_data.c
xa_mp3_dec/test/src/xa_mp3_dec_error_handler.c
xa_mp3_dec/test/test_inp/
xa_mp3_dec/test/test_inp/compl.mp3
xa_mp3_dec/test/test_inp/hihat.mp3
xa_mp3_dec/test/test_out/
xa_mp3_dec/test/test_out/force_mkdir.txt
xa_mp3_dec/test/test_ref/
xa_mp3_dec/test/test_ref/compl_24bit.wav
xa_mp3_dec/test/test_ref/hihat_16bit.wav
xa_mp3_dec/lib/
xa_mp3_dec/lib/xa_mp3_dec.a
xa_mp3_dec/doc/
xa_mp3_dec/doc/HiFi2-MP3-DecoderProgrammersGuide.pdf

[TO BE DONE - Add missing C file, make clean deletes it!]

The xa_mp3_dec.a archive will be used by the Makefile in
the mplayer_hifi2_mp3_plugin directory to make the mplayer plug-in.
Section 6 of the '''Using Tensilica HiFi 2 Codec on Xtensa Linux with MPlayer'' Application Note
has a detailed description of the encapsulation process used by the plug-ins.

== Compiling Generic GPL Packages ==

For your development you may want to add a few GPL packages that you find helpfull.
This can be done on the LX200 just as you would on a normal workstation, thought
much slower. For example here we configure and build a few common GPL packages:

[[Building the Strace Package]]

[[Building the vim Package]]

== Compiling Tie Code with XCC ==

Codecs like MP3 and AAC have been written in C with TIE extensions and can only be compiled with '''xcc'''.
XCC is likely to large to run on the board without virtual memory. There are two approaches to compiling
Linux TIE code with '''xcc'''. The simple approach assumes the host workstation and target code running of the board
are similar enough that the library interfaces defined by the include files are compatable. This is often the
case for standard system calls, libc, and stdio.The proper approach uses a virtual core that we will create
that has built in references to the library and include files on the target code running on the LX200.

=== Simply using Xtensa Tools to compile the TIE code on a workstation ===

Below we illustrate compiling a simple audio test program on a workstation.
We start by referring to the XTENSA tools build by Xplorer, putting '''xcc''' into our search path and set the standard XTENSA_* environement variables.
For example:

setenv XTENSA_CORE test_mmuhifi_c3
setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config
setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin

setenv PATH ${XTENSA_TOOLS}:${PATH}

[piet@fc9desktop Tests] $ '''cd /exports/default/Audio_Tests''' [NOTE: This is being done on a Workstation]
[piet@fc9desktop Audio_Tests]$ '''xt-xcc -g3 -O0 -fPIC -c hifitest.c'''

Next we link the object on the XL200 board and run gdb on the TIE enhanced code:

[root@hifi Audio_Tests]# '''gcc -g hifitest.o -o hifitest'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:4640; Eatting cpu; time:0
cnt:0x0, pid:4640; Eating Tie; time:7
^C
[root@hifi Audio_Tests]# '''gdb ./hifitest''' [NOTE: This is being done on the LX200 board]
GNU gdb 6.6
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "xtensa_test_mmuhifi_c3-linux-uclibc"...
Using host libthread_db library "/lib/libthread_db.so.1".
(gdb) '''break main'''
Breakpoint 1 at 0x400401: file /exports/default/Audio_Tests/hifitest.c, line 20.
(gdb) '''run'''
Starting program: /home/default/Audio_Tests/hifitest

Breakpoint 1, main (argc=1, argv=0x3fb3fab4)
at /exports/default/Audio_Tests/hifitest.c:20
20 time_t time0 = time(NULL);
(gdb) '''step'''
21 time_t time1 = time(NULL);

=== Building Linux Applications Using Tensilica's XCC Compiler ===

Section 4.3 of the latest ''Xtensa OSKit Guide'' (from Tensilica's
RC-2009.0 release) describes how to setup XCC to compile Linux applications.
For details, see the guide.

A summary follows. The XTENSA_TOOLS_ROOT, XTENSA_ROOT, BUILDROOT_DIR, and TARGET_SYSROOT
environment variables must be set according to where things were installed;
values shown here are for illustration only. The CORENAME variable, set correctly
below for this board, reflects
the name of the core as known to open source tools (as opposed to XTENSA_CORE
which is the core name as known to Xtensa Tools; both happen to match here).

$ setenv XTENSA_ROOT /home/someuser/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
$ setenv XTENSA_TOOLS_ROOT /home/someuser/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools
$ setenv TARGET_SYSROOT /exports/LINUX_ROOT.HiFi-2
$ setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12

$ setenv CORENAME test_mmuhifi_c3

$ cd ${BUILDROOT_DIR}
$ ${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install \
--sysroot=./build_xtensa_${CORENAME}/staging_dir \
--linux-gcc=./build_xtensa_${CORENAME}/staging_dir/usr/bin/xtensa_${CORENAME}-linux-gcc

Assuming the above completes successfully, you can now build applications using Xtensa Tools. First set the usual environment variables:

$ setenv XTENSA_CORE default
$ setenv XTENSA_SYSTEM ${XTENSA_ROOT}-linux/config
$ setenv PATH ${XTENSA_TOOLS_ROOT}/bin:${PATH}

And build something:

$ echo '#include <stdio.h>' > hello.c
$ echo 'int main() {printf("Hello!\n");return 0;}' >> hello.c
$ xt-xcc -g hello.c -o hello

Then copy it where the target can see it:

$ cp hello ${TARGET_SYSROOT}/root

And run it on the target:

[root@hifi ~]# /root/hello

Here's a more interesting example that uses Tensilica TIE features.
(This cannot be compiled using GCC.)

$ cd ${TARGET_SYSROOT}/home/default/Audio_Tests
$ xt-xcc -g hifitest.c -o hifitest

In a ssh termulator window on the board you can now run hifitest:

[root@hifi ~]# '''cd /home/default/Audio_Tests/'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:23178; Eatting cpu; time:0 '''<control-C>'''

[root@hifi Audio_Tests]#

Here is the source code for the [[hifitest.c|hifitest.c source file]] used above.

== Adding your codec to Buildroot ==

Xtensa developers provide detailed instructions on building the root filesystem and the Linux kernel.
* [[Buildroot_Build_Instructions|Instructions for building and booting Linux (buildroot)]].

Building a comprehensive development environment with buildroot can be a chalanging experience and worthy of providing some tips on process.
Here are notes of the configs used for the three menuconfigs in this 2nd snapshot
provided with SMP additions:
$ '''make [[HiFi-2 snapshot_2 SMP Snapshot menuconfig | menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP uclibc-menuconfig | uclibc-menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP busybox-menuconfig | busybox-menuconfig]]'''

[TO BE DONE - making a new tar ball of saved files, building buildroot, ...]

== Known Problems being investigated, suggested that you know about and possibly avoid ==

1. Using NFS mounts with default parameters causes memory congestion. Use these mount options:

'''vers=2,rsize=4096,wsize=4096,hard,nointr,nolock,nolock,timeo=11,retrans=3,noauto'''

this is extremely important to add to your /etc/fstab on the target.

2. Can't swap over NFS yet, memory can get tight and cause application to be killed.
a. Trying procedure documented in U-Boot Manual.

3. Building the C development with X11 doesn't work with buildroot.

4. Though Mplayer plug-in can be compiled, Mplayer can be compiled but still has a few issues:
a. Can't be compiled -O0 due to limited memory while compiling one file,
b. Compiler infrequently crashes and make has to be restarted.
Not seeing this problem with root build on Fedore Core 9.
Perhaps this was caused by debug kernel or LTP using all of the memory.

5. U-boot has flash problems:
a. Sectors marked Read-Only come up Writeable after a reset/reboot.
b. Flashing a large number of sectors (like the kernel) sometimes
results in an Error (Ex: Vcc) and had to be retried.
c. Saw environment variables trashed on reset/reboot once.
It's possible that U-boot in flash could get whacked
and the board will need to be re-flashed. During a week
or two of testing I haven't see environment getting whacked.

6. gdb appears to be crashing on target when debugging
on latest root with uclibc left unstriped and with debug;
core dump sent to maxim.

7. U-Boot seems to hang periodically when loading the kernel with
tftp; appears to be worse when network activity is high.

8. 'top' command only shows all cpu's or cpu0; cpu 1 and 2 missing.

9. Program dore dump require ulimit -c to be set but root uses /bin/sh
which is a link to bash but causes it to skip running the bash
startup scripts. Changing root to /bin/bash seems to mess up
ssh logins.

10. For kernel to be compiled on the LX200 (for self checking:
a. Xtensa makefile needs to be fixed:
CC init/do_mounts.o
LD init/mounts.o
/bin/sh: xtensa_test_mmuhifi_c3-linux-uclibc-ld: command not found
make[1]: *** [init/mounts.o] Error 127

b. Need to add ncurses-devel package for 'make menuconfig'

11. Copying vim-7.2.tar from /home/default/src to /usr/local/src resulted
in a corrupt tar header. Apparently we have a NFS bug lurking in the kernel.
On server tar file looks like this:
vim72/000755 001750 001750 00000000000 11047345123 012000 5
ustar00moolmool000000 000000
vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0
ustar00moolmool000000 000000
README.txt for version 7.2 of Vim: Vi IMproved.

On the target/client it's different:
vim72/000755 001750 001750 00000000000 11047345123 012000 5ustar00moolmool000000 000000 vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0ustar00moolmool000000 000000 README.txt for version 7.2 of Vim: Vi IMproved.

=Further reading=

Main Xtensa Linux resources are:

* [http://linux-xtensa.org/ Linux/Xtensa Wiki]
* [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions Buildroot Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Kernel_Build_Instructions Kernel Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Setting_up_U-Boot Setting up U-Boot]
* [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List]
* http://git.linux-xtensa.org/cgi-bin/git.cgi GIT Repositories]

=Thanks to=

* piet
* marc
* dan

And the rest of the people in the Linux-Xtensa mailing list, if you cannot go through some of the steps, don't hesitate to ask on the mailing list, there's always somebody willing to help you!

SMP HiFi 2 Development Board

2009-12-02T04:24:21Z

Marc: /* Booting Linux for the 1st Time */

This is the "communitee"" guide for how to use HiFi-2 Codec Development environment on an LX200 FPGA board.
If somethinig doesn't work ir isn't vovered in these guides, please feel free to ask at the [http://lists.linux-xtensa.org/mailman/listinfo Linux//Xtensa Mailing List]]

<div style="margin:0; margin-top:10px; margin-right:10px; border:1px solid #dfdfdf; padding:0 1em 1em 1em; background-color:#ffffcc; align:right; ">
'''NEWS:'''

Some general notes on these instructions:

* They are a work in progress.

* The following was tested on x86 machines running RedHat Fedora Core 5.

* Buildroot build with Fedora Core 9 also seems to be fine; perhaps better than when built on Fedore Core 5.

</div>

== Introduction ==

This document is addressed to someone who received an LX200 board setup by Tensilica
for HiFi2 codec development.

This document goes over the steps needed to set up the LX200 board for codec development.
To summarize:
* Setup the board. It likely comes with U-boot preinstalled, ready to boot a linux kernel.
* Install '''git'''.
* Download buildroot and linux kernel trees, pre-configured and built for HiFi-2 development.
* Setup a TFTP server to provide the linux kernel to U-Boot.
* Setup an NFS server to export a linux root file system.
* Setup the Linux kernel to boot from the root file system provided by the NFS server.
Once the development board is up and running, this document:
* Suggests a possible way to tailor the board for easy codec development.
* Shows how to add the Tensilica provided codec packages to the Mplayer packages used by Buildroot, including building and installing.
* Demonstrates two procedures for compiling, linking, and debugging codecs.

All development is expected to be done on a Linux host. (One can in principle use Windows to
develop target libraries. However, linking and subsequent steps need to be done in Linux.)

== Downloading the Latest HiFI-2 Buildroot and Kernel Snapshots ==

The HiFi-2 development environment is maintained in a source code version control system named 'git'. The '''git''' tools are useful when working with this development environment, though they are not strictly necessary. This document generally assumes the use of '''git''', which provides more opportunities for modifying this environment as needed (e.g. building more optional buildroot packages). But points out alternatives to allow getting up and running without having to set it up.

=== Installing git ===

To install '''git''', download a recent tarball from the [http://www.kernel.org/pub/software/scm/git/ official site]. For example, <tt>cd</tt> to a location with enough disk space, and do:

$ '''wget http://www.kernel.org/pub/software/scm/git/git-1.6.5.tar.gz'''

Unpack the tarball, and make and install it. Here we show how to install it to your ~/bin directory:

$ '''gunzip git-1.6.5.tar.gz'''
$ '''tar xf git-1.6.5.tar'''
$ '''cd git-1.6.5'''
$ '''make'''
$ '''make install'''

The git makefile can be instructed to install '''git''' to <tt>/usr/local/bin</tt> as root for system wide access:

$ '''cp git-1.6.5.tar.gz''' /tmp
$ '''su'''
Password:
# '''cd /usr/local/src/'''
# '''mkdir git'''
# '''cd git'''
# '''cp /tmp/git-1.6.5.tar.gz .'''
# '''gunzip git-1.6.5.tar.gz'''
# '''tar xf git-1.6.5.tar'''
# '''cd git-1.6.5'''
# '''make prefix=/usr/local'''
# '''make install'''

See the '''INSTALL'' instruction at the top of the git src directory for details.

Using '''git''' provides easy access to the binaries used to bring up the codec development environment, and leaves in place the infrastructure to modify and build this environment should you wish to. Any changes to '''git'''-managed source trees are easily observed with the '''git''' tools.

=== Installing the Buildroot Snapshot ===

''Note: The HiFi-2 snapshot is in the process of being made.''

To install the buildroot environment (toolchain and root filesystem), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot'''
$ '''cd buildroot-xtensa-HiFi2-Snapshot'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP''' [56 key strokes]
$ '''git checkout snapshot_2+SMP''' [28 key strokes]

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).

You can examine the tree (git repository) and its history visually using <tt>git gui</tt>.
The git GUI is a faster and more convenient method for checking out the HiFi-2 snapshot. To check out the snapshot_2+SMP branch simply run the command 'git gui' and then pull down the branch->create menu. Next select <>Match Tracking Branch Name and click on ''origin/snapshot_2+SMP''. Finally hit the Create Button.

$ '''git gui''''' [8 key strokes]
[Branch] -> Create... [2 key strokes]
<> Match Tracking Branch Name [1 key stroke]
<> Tracking Branch [1 key stroke]
origin/snapshot_2+SMP [1 key stroke]
[Create] [1 key stroke]
[Reposirory]--> Quit [2 key strokes]

If there are issues installing '''git''', as a last resort, an alternative is ftp (may not always get updated, is currenty our of date, waste disk space, so may be dropped at some point):

http://www.linux-xtensa.org/pub/snapshots/buildroot-xtensa-smp.2-Nov-2009.tar.gz

=== Installing the Linux Kernel Snapshot ===

To install the Linux kernel environment (kernel src, config, and HiFi-2 kernel U-Boot image), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp'''
$ '''cd kernel/xtensa-2.6.29-smp'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
$ '''git checkout snapshot_2+SMP'''

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).
As in the build root case, you can also do it from via git gui using the same proceedure
mantioned above.

Now, assuming we are still in the kernel '''xtensa-2.6.29-smp''' directory
copy the kernel U-Boot Image ('''uImage''') to the tftp directory; Ex:

$ '''cp arch/xtensa/boot/uImage /tftpboot/uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'''

NOTE: On some system, like Fedora Core 9, the tftpboot directory has been moved to /var/lib/tftpboot.
In this case we recomend that you just added a symbolic pointer from /etc to /var/lib/tftpboot:

$ '''su'''
# '''cd /etc'''
# '''/var/lib/tftpboot/ tftpboot'''
# '''ls -ld tftpboot'''
lrwxrwxrwx 1 root root 18 2009-11-23 21:14 tftpboot -> /var/lib/tftpboot/
#

== Setting up a TFTP Server to provide the Linux kernel to U-Boot ==

The TFTP service is part of the xinetd and is installed on Fedora workstations.
You can see that it's installed with the check config command which manages the
/etc/rc.d/init.d startup scripts and with the yum search command:

$ '''chkconfig --list'''
NetworkManager 0:off 1:off 2:off 3:off 4:off 5:off 6:off
NetworkManagerDispatcher 0:off 1:off 2:off 3:off 4:off 5:off 6:off
acpid 0:off 1:off 2:off 3:on 4:on 5:on 6:off
.
.
.
xfs 0:off 1:off 2:on 3:on 4:on 5:on 6:off
xinetd 0:off 1:off 2:off 3:on 4:on 5:on 6:off
ypbind 0:off 1:off 2:off 3:on 4:on 5:on 6:off
yum 0:off 1:off 2:off 3:off 4:off 5:off 6:off

xinetd based services:
amanda: off
auth: off
.
.
.
rsync: off
'''tftp: on''' [NOTE that tftp is enabled]
time: off
time-udp: off
uucp: off
$
$
$
$ '''yum search tftp-server'''
Loading "installonlyn" plugin
Searching Packages:
.
.
.
Reading repository metadata in from local files
.
.
.
'''tftp-server.i386 0.41-1.2.1 installed''' [NOTE that tftp server is installed as part of the inet daemon]
Matched from:
tftp-server
The Trivial File Transfer Protocol (TFTP) is normally used only for
booting diskless workstations. The tftp-server package provides the
server for TFTP, which allows users to transfer files to and from a
remote machine. TFTP provides very little security, and should not be
enabled unless it is expressly needed. The TFTP server is run from
/etc/xinetd.d/tftp, and is disabled by default on Red Hat Linux systems.
[piet@pdelaney_fc5 ~]$

TFTP is not normally enabled, to enable it just edit the file /etc/xinetd.d/tftp
and change the disable field to no:

# default: off
# description: The tftp server serves files using the trivial file transfer \
# protocol. The tftp protocol is often used to boot diskless \
# workstations, download configuration files to network-aware printers, \
# and to start the installation process for some operating systems.
service tftp
{
socket_type = dgram
protocol = udp
wait = yes
user = root
server = /usr/sbin/in.tftpd [NOTE: /var/lib/tftpboot on Fedora Core 9]
server_args = -s /tftpboot
'''disable = no'''
per_source = 11
cps = 100 2
flags = IPv4
}

== Setting up an NFS Server to export the Root Filesystem ==

The LX200 board running Linux needs to mount its root filesystem over NFS.
This filesystem was built using buildroot into a cpio format file,
and left in:

buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2/rootfs.xtensa_test_mmuhifi_c3.cpio

We will also be adding an additional minor changes to make your development environment more comfortable.

Pick a place on your workstation to export your root and unpack the cpio file into that directory.
For example here we will set up an export in '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''':

$ '''cd buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2'''
$ '''WHERE=$PWD'''
$ '''mkdir -p /exports/LINUX_ROOT.HiFi-2'''
$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''cpio -i < $WHERE/rootfs.xtensa_test_mmuhifi_c3.cpio'''

Next add a line to /etc/exports:

/exports *(rw,no_root_squash,sync,no_wdelay)

and restart you nfs services:

$ '''/etc/rc.d/init.d/nfs restart'''
or
$ '''/sbin/chkconfig nfs on'''

The showmount command should show your NFS file system now being exported:

$ '''showmount -e'''
Export list for mypc.foobar.com:
/exports *
$

== Configuring U-Boot to Boot Linux ==

Your LX200 board should have arrived with U-Boot installed in the flash ready to use.
The board has a DIP switch (next to the power on/off switch) that provides the 6 LSBs
of the Ethernet MAC, in switch positions 1 thru 6.

DIP Swithes for MAC: 1 2 3 4 5 6 7 8 ethaddr=00:50:C2:13:6f:0a
Little Endian: 0 1 0 1 0 0 * *
^
|
+------ Enables booting U-Boot from Flash

DIP switch 8 should be shipped in the ON position to enable U-Boot booting from flash.
See Sections 4.2.3 and 4.2.4 of the '''Tensilica Avnet (XT-AV200) Board User's Guide'''
for details. Make sure to select a unique MAC address for you board.

Next, connect a serial interface to a text based terminal emulation program,
set to 38400 bps, no parity, 1 stop bit, no handshaking.
For an example of setting [http://en.wikipedia.org/wiki/Minicom minicom]
for this, see [[minicom_xtboard_setup|here]].

Many users of this board are interested in developing codecs and/or HiFi 2 software and will prefer to just boot linux with the root file system we just described how to export on your NFS server. We will use git now to pull a snapshot of a performance 2.6.29 linux kernel and configure U-Boot to automatically boot it after a power cycle.

U-Boot> '''setenv serverip 192.168.11.55''' [TFTP server IP Address: RTOS-LAB2]
U-Boot> '''setenv nfsroot_server 192.168.11.55''' [Root NFS Servers IP Address: My Workstation]
U-Boot> '''setenv ipaddr 192.168.11.155''' [HOST IP address]
U-Boot> '''setenv bootfile uImage.xtensa-2.6.29-smp.test_mmuhifi_c3''' [File to fetch with TFTP and pass to bootm]
U-Boot> '''setenv root-path /exports/LINUX_ROOT.HiFi-2''' [WARNING: Limit path to < 50 characters]
U-Boot> '''setenv bootargs_using_bootp console=ttyS0,38400 ip=bootp root=nfs coredump_filter=0xff''' [Args passed to Linux while booting with BOOTP proto]
U-boot> '''setenv bootargs console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=${nfsroot_server}:${root-path}''' [Args passed to Linux while booting with DHCP proto]
U-boot> '''setenv bootcmd tftpboot\; bootm''' [Boot Linux after fetching it with TFTP]
U-Boot> '''setenv bootdelay 20''' [Delay 20 seconds before booting automaticaly]
U-Boot> '''setenv autostart yes''' [Boot automatically on power-up/reset]
U-Boot> '''saveenv'''
U-Boot>

'''[REMIND: Update the above procedure, show two or thee approaches (ip, dhcp, bootp)]'''

== Tailoring your system prior to Booting ==

There are a few tweaks that developers have found convenient to add to the the root file-system before booting.
As an initial environment for developing we suggest mounting a /home/default files-system that has number of
files useful for getting started. Find another place to tar in the tar ball with the default users file system.
We chose to include this close to the cpio file with the root file-system. Copy the tar bar to where you are
exporting you root file-system and next to it add the 'default' users file-system:

$ '''cd /export'''
$ '''cp /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.10/binaries/default.tar .'''
$ '''tar xf default.tar'''
$ '''cd default'''
$ '''ls'''
[TO BE ADDED]

Notice a file tar ball called '''saved_files.tar'''. This ia a tar file of files that
developers have found convenient to add and replace on the root file system after
adding a new buildroot file system. Here is a list of the files and a brief
explanation on why it's convenient to add or replace them:

root/.bash_profile [added 'ulimit -c unlimited to allow core dumps to be created]
root/.bashrc
etc/profile [added 'ulimit -c unlimited to allow core dumps to be created]
etc/fstab [Tells the system how to mount extra NFS file systems like /home/default]
etc/init.d/S90local [Mounts /home/default]
etc/resolv.conf [Location of DNS servers when your not using DHCP to boot the kernel]
etc/TZ [Your time zone, currently set to California TZ]
etc/dropbear/dropbear_rsa_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/dropbear/dropbear_dss_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/ssh_config [Typically tailored with things like allowing root logins via ssh]
etc/ssh_host_dsa_key [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_dsa_key.pub [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_key
etc/ssh_host_key.pub
etc/ssh_host_rsa_key
etc/ssh_host_rsa_key.pub
etc/sshd_config [Typically tailored with things like allowing root logins via ssh]
etc/rndc.key
etc/random-seed [Generated during 1st boot]
etc/passwd [Changed default user's shell to bash]
etc/shadow [Changed default and root users login password to 'linux1', need to ssh to the board]
exports/ [The path to where the board can mount extra file systems like /home/default.
fac/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]
fac/vol6/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]

Now lets assume your going to stay with these changes and modify them after taring in these changes.
Here we add the tar ball files to the boards root filesystem.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''tar xf /exports/default/'''

This is a good time to edit a few files on the boards file system
before boot it.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''vi etc/fstab''' [Change fstab entry for /home/default and others to your taste]
$ '''vi etc/init.d/S90local''' [You might want to disable mounting of NFS file systems on the 1st Boot and add this once you try it manually]

== Booting Linux for the 1st Time ==

We should now be ready to boot linux on your LX200. You have exported the root file-system and made the
kernel available to a TFTP server. Now let's start with hitting the reset button on the LX200 and it should
auto-boot the kernel, resulting in output such as [[HiFi2_Board_Example_Linux_Boot_Log|this example log]].

== Tailoring your system prior to developing your codec ==

To make your experience more pleasant we suggest you tailor your environment.
Here are some of the changes that we have found helpful:

1. Add a root password to that you can login with ssh.
2. Run rdate with an ntp server on booting.
3. Add NFS mounts to /etc/fstab for your code and buildroot code.
4. Copy in previous ssh server encryption keys to /etc/dropbear to speed up your initial boot.
5. Mount a 'default' user home directory with:
a. Linux Test Suite pre-patch to test the system
b. Audio test example files
c. Copies of Mplayer and its Plug-ins from Buildroot modified slightly to make installation easy.
d. Misc audio test programs.

[TO BE DONE - Where to get 'default' user home directory tar ball and 1st boot patch]

== Compiling the Mplayer Plugins and linking them with MPEG-1 Audio Layer 3 (MP3) and MPEG-4 AAC Codecs ==

Mplayer is provided as an example environment for developing and testing Codecs and HiFi 2 software. There
are two ways to build Mplayer and the plug-in modules that use the codecs. The buildroot
tree (pulled with git) has a copy of mplayer and the plugins that can be built in the
snapshot via 'make menuconfig'. This is a good environment to use once codecs are
developed and debugged.

To facilitate development the mplayer packages can be copied to your NFS mounted development
environment. From there you can just configure mplayer to compile on the board and debug
mplayer and your codecs with gdb locally.

In the default user home directory we have a directory /home/default/buildroot_mplayer_stuff
with a copy of three of the mplayer packages:

[root@hifi buildroot_mplayer_stuff]# '''ls -l'''
drwxr-xr-x 34 root root 4096 Nov 10 05:01 MPlayer-1.0rc2/
drwxr-xr-x 4 root root 4096 Nov 10 01:36 mplayer_hifi2_aacplus_v2_plugin/
drwxr-xr-x 3 root root 4096 Nov 10 00:57 mplayer_hifi2_mp3_plugin/

they were simply copied from the buildroot-xtensa-HiFi2-Snapshot.2/package directory.

To get your development environment ready to compile the mplayer plug-ins you need
to configure Mplayer to use the local C compiler and linker:

# '''cd /home/default/buildroot_mplayer_stuff/MPlayer-1.0rc2/'''
# '''CFLAGS="-g3" ./configure'''

This will take about 15 minutes to configure. After that you can build the
plugins or mplayer. If you want to recompile mplayer it's likely best/necessary
to use the same args to .configure as used by buildroot:

.CFLAGS="-g3" ./configure \
--prefix=/usr \
--confdir=/etc/mplayer \
--with-extraincdir=/usr/include \
--with-extralibdir=/lib \
--disable-gui \
--enable-mad \
--enable-fbdev \
--disable-mencoder \
--disable-dvdnav \
--disable-dvdread \
--disable-dvdread-internal \
--disable-libdvdcss-internal \
--disable-big-endian \
--disable-nemesi \
--disable-tv \
--enable-dynamic-plugins

We are currently able to compile most of mplayer on the XL200 but
due to space limitations it's not possible to compile it -O0.

Now, lets focus on compiling linking the plugins. They are a nice
example of compiling a audio application on the LX200.

We modified the Makefile of the codes slightly, and will make it available.
These additions just instruct make how to install the plugins as explained
in the Chapter 7 of the Linux HiFi application note.

For example the mp3 plugin has this addition:

target_install::
-mkdir /etc/mplayer
cp codecs.conf /etc/mplayer
-mkdir /usr/lib/mplayer
cp ad_xa_mp3_dec.so /usr/lib/mplayer/
cp xa_mp3_dec.so /usr/lib/mplayer
chmod 755 /usr/lib/mplayer/ad_xa_mp3_dec.so
chmod 755 /usr/lib/mplayer/xa_mp3_dec.so

It's just providing a codec config file for mplayer at '''/etc/mplayer/codecs.conf''' and
copying the plug-in to '''/usr/lib/mplayer'''. To install the mp3 codec plugin and mplayer
config file just copy your codec that was compiled with '''xcc''' to the directory, compile it,
and install.

# '''cd /fac/vol6/audio/release/bin/l32r_LE5_pic'''
# '''cp xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz /tmp'''
#
# '''cd /home/default/buildroot_mplayer_stuff'''
# '''cd mplayer_hifi2_mp3_plugin'''
# '''cp /tmp/xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz .'''
# '''gunzip xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz'''
# '''tar xf xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tar'''
# '''make'''
# '''make target_install'''

The unpacking of the Tensilica mp3 codec tar ball will install the following files:

xa_mp3_dec/
xa_mp3_dec/README
xa_mp3_dec/include/
xa_mp3_dec/include/mp3_dec/
xa_mp3_dec/include/mp3_dec/xa_mp3_dec_api.h
xa_mp3_dec/include/xa_apicmd_standards.h
xa_mp3_dec/include/xa_error_handler.h
xa_mp3_dec/include/xa_error_standards.h
xa_mp3_dec/include/xa_memory_standards.h
xa_mp3_dec/include/xa_type_def.h
xa_mp3_dec/test/
xa_mp3_dec/test/build/
xa_mp3_dec/test/build/ldscript_stream_data.txt
xa_mp3_dec/test/build/makefile_testbench_sample
xa_mp3_dec/test/build/paramfilesimple.txt
xa_mp3_dec/test/include/
xa_mp3_dec/test/include/id3_tag_decode.h
xa_mp3_dec/test/src/
xa_mp3_dec/test/src/xa_mp3_dec_sample_testbench.c
xa_mp3_dec/test/src/id3_tag_decode.c
xa_mp3_dec/test/src/stream_data.c
xa_mp3_dec/test/src/xa_mp3_dec_error_handler.c
xa_mp3_dec/test/test_inp/
xa_mp3_dec/test/test_inp/compl.mp3
xa_mp3_dec/test/test_inp/hihat.mp3
xa_mp3_dec/test/test_out/
xa_mp3_dec/test/test_out/force_mkdir.txt
xa_mp3_dec/test/test_ref/
xa_mp3_dec/test/test_ref/compl_24bit.wav
xa_mp3_dec/test/test_ref/hihat_16bit.wav
xa_mp3_dec/lib/
xa_mp3_dec/lib/xa_mp3_dec.a
xa_mp3_dec/doc/
xa_mp3_dec/doc/HiFi2-MP3-DecoderProgrammersGuide.pdf

[TO BE DONE - Add missing C file, make clean deletes it!]

The xa_mp3_dec.a archive will be used by the Makefile in
the mplayer_hifi2_mp3_plugin directory to make the mplayer plug-in.
Section 6 of the '''Using Tensilica HiFi 2 Codec on Xtensa Linux with MPlayer'' Application Note
has a detailed description of the encapsulation process used by the plug-ins.

== Compiling Generic GPL Packages ==

For your development you may want to add a few GPL packages that you find helpfull.
This can be done on the LX200 just as you would on a normal workstation, thought
much slower. For example here we configure and build a few common GPL packages:

[[Building the Strace Package]]

[[Building the vim Package]]

== Compiling Tie Code with XCC ==

Codecs like MP3 and AAC have been written in C with TIE extensions and can only be compiled with '''xcc'''.
XCC is likely to large to run on the board without virtual memory. There are two approaches to compiling
Linux TIE code with '''xcc'''. The simple approach assumes the host workstation and target code running of the board
are similar enough that the library interfaces defined by the include files are compatable. This is often the
case for standard system calls, libc, and stdio.The proper approach uses a virtual core that we will create
that has built in references to the library and include files on the target code running on the LX200.

=== Simply using Xtensa Tools to compile the TIE code on a workstation ===

Below we illustrate compiling a simple audio test program on a workstation.
We start by referring to the XTENSA tools build by Xplorer, putting '''xcc''' into our search path and set the standard XTENSA_* environement variables.
For example:

setenv XTENSA_CORE test_mmuhifi_c3
setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config
setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin

setenv PATH ${XTENSA_TOOLS}:${PATH}

[piet@fc9desktop Tests] $ '''cd /exports/default/Audio_Tests''' [NOTE: This is being done on a Workstation]
[piet@fc9desktop Audio_Tests]$ '''xt-xcc -g3 -O0 -fPIC -c hifitest.c'''

Next we link the object on the XL200 board and run gdb on the TIE enhanced code:

[root@hifi Audio_Tests]# '''gcc -g hifitest.o -o hifitest'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:4640; Eatting cpu; time:0
cnt:0x0, pid:4640; Eating Tie; time:7
^C
[root@hifi Audio_Tests]# '''gdb ./hifitest''' [NOTE: This is being done on the LX200 board]
GNU gdb 6.6
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "xtensa_test_mmuhifi_c3-linux-uclibc"...
Using host libthread_db library "/lib/libthread_db.so.1".
(gdb) '''break main'''
Breakpoint 1 at 0x400401: file /exports/default/Audio_Tests/hifitest.c, line 20.
(gdb) '''run'''
Starting program: /home/default/Audio_Tests/hifitest

Breakpoint 1, main (argc=1, argv=0x3fb3fab4)
at /exports/default/Audio_Tests/hifitest.c:20
20 time_t time0 = time(NULL);
(gdb) '''step'''
21 time_t time1 = time(NULL);

=== Building Linux Applications Using Tensilica's XCC Compiler ===

Section 4.3 of the latest ''Xtensa OSKit Guide'' (from Tensilica's
RC-2009.0 release) describes how to setup XCC to compile Linux applications.
For details, see the guide.

A summary follows. The XTENSA_TOOLS_ROOT, XTENSA_ROOT, BUILDROOT_DIR, and TARGET_SYSROOT
environment variables must be set according to where things were installed;
values shown here are for illustration only. The CORENAME variable, set correctly
below for this board, reflects
the name of the core as known to open source tools (as opposed to XTENSA_CORE
which is the core name as known to Xtensa Tools; both happen to match here).

$ setenv XTENSA_ROOT /home/someuser/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
$ setenv XTENSA_TOOLS_ROOT /home/someuser/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools
$ setenv TARGET_SYSROOT /exports/LINUX_ROOT.HiFi-2
$ setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12

$ setenv CORENAME test_mmuhifi_c3

$ cd ${BUILDROOT_DIR}
$ ${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install \
--sysroot=./build_xtensa_${CORENAME}/staging_dir \
--linux-gcc=./build_xtensa_${CORENAME}/staging_dir/usr/bin/xtensa_${CORENAME}-linux-gcc

Assuming the above completes successfully, you can now build applications using Xtensa Tools. First set the usual environment variables:

$ setenv XTENSA_CORE default
$ setenv XTENSA_SYSTEM ${XTENSA_ROOT}-linux/config
$ setenv PATH ${XTENSA_TOOLS_ROOT}/bin:${PATH}

And build something:

$ echo '#include <stdio.h>' > hello.c
$ echo 'int main() {printf("Hello!\n");return 0;}' >> hello.c
$ xt-xcc -g hello.c -o hello

Then copy it where the target can see it:

$ cp hello ${TARGET_SYSROOT}/root

And run it on the target:

[root@hifi ~]# /root/hello

Here's a more interesting example that uses Tensilica TIE features.
(This cannot be compiled using GCC.)

$ cd ${TARGET_SYSROOT}/home/default/Audio_Tests
$ xt-xcc -g hifitest.c -o hifitest

In a ssh termulator window on the board you can now run hifitest:

[root@hifi ~]# '''cd /home/default/Audio_Tests/'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:23178; Eatting cpu; time:0 '''<control-C>'''

[root@hifi Audio_Tests]#

Here is the source code for the [[hifitest.c|hifitest.c source file]] used above.

== Adding your codec to Buildroot ==

Xtensa developers provide detailed instructions on building the root filesystem and the Linux kernel.
* [[Buildroot_Build_Instructions|Instructions for building and booting Linux (buildroot)]].

Building a comprehensive development environment with buildroot can be a chalanging experience and worthy of providing some tips on process.
Here are notes of the configs used for the three menuconfigs in this 2nd snapshot
provided with SMP additions:
$ '''make [[HiFi-2 snapshot_2 SMP Snapshot menuconfig | menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP uclibc-menuconfig | uclibc-menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP busybox-menuconfig | busybox-menuconfig]]'''

[TO BE DONE - making a new tar ball of saved files, building buildroot, ...]

== Known Problems being investigated, suggested that you know about and possibly avoid ==

1. Using NFS mounts with default parameters causes memory congestion. Use these mount options:

'''vers=2,rsize=4096,wsize=4096,hard,nointr,nolock,nolock,timeo=11,retrans=3,noauto'''

this is extremely important to add to your /etc/fstab on the target.

2. Can't swap over NFS yet, memory can get tight and cause application to be killed.
a. Trying procedure documented in U-Boot Manual.

3. Building the C development with X11 doesn't work with buildroot.

4. Though Mplayer plug-in can be compiled, Mplayer can be compiled but still has a few issues:
a. Can't be compiled -O0 due to limited memory while compiling one file,
b. Compiler infrequently crashes and make has to be restarted.
Not seeing this problem with root build on Fedore Core 9.
Perhaps this was caused by debug kernel or LTP using all of the memory.

5. U-boot has flash problems:
a. Sectors marked Read-Only come up Writeable after a reset/reboot.
b. Flashing a large number of sectors (like the kernel) sometimes
results in an Error (Ex: Vcc) and had to be retried.
c. Saw environment variables trashed on reset/reboot once.
It's possible that U-boot in flash could get whacked
and the board will need to be re-flashed. During a week
or two of testing I haven't see environment getting whacked.

6. gdb appears to be crashing on target when debugging
on latest root with uclibc left unstriped and with debug;
core dump sent to maxim.

7. U-Boot seems to hang periodically when loading the kernel with
tftp; appears to be worse when network activity is high.

8. 'top' command only shows all cpu's or cpu0; cpu 1 and 2 missing.

9. Program dore dump require ulimit -c to be set but root uses /bin/sh
which is a link to bash but causes it to skip running the bash
startup scripts. Changing root to /bin/bash seems to mess up
ssh logins.

10. For kernel to be compiled on the LX200 (for self checking:
a. Xtensa makefile needs to be fixed:
CC init/do_mounts.o
LD init/mounts.o
/bin/sh: xtensa_test_mmuhifi_c3-linux-uclibc-ld: command not found
make[1]: *** [init/mounts.o] Error 127

b. Need to add ncurses-devel package for 'make menuconfig'

11. Copying vim-7.2.tar from /home/default/src to /usr/local/src resulted
in a corrupt tar header. Apparently we have a NFS bug lurking in the kernel.
On server tar file looks like this:
vim72/000755 001750 001750 00000000000 11047345123 012000 5
ustar00moolmool000000 000000
vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0
ustar00moolmool000000 000000
README.txt for version 7.2 of Vim: Vi IMproved.

On the target/client it's different:
vim72/000755 001750 001750 00000000000 11047345123 012000 5ustar00moolmool000000 000000 vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0ustar00moolmool000000 000000 README.txt for version 7.2 of Vim: Vi IMproved.

=Further reading=

Main Xtensa Linux resources are:

* [http://linux-xtensa.org/ Linux/Xtensa Wiki]
* [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions Buildroot Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Kernel_Build_Instructions Kernel Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Setting_up_U-Boot Setting up U-Boot]
* [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List]
* http://git.linux-xtensa.org/cgi-bin/git.cgi GIT Repositories]

=Thanks to=

* piet
* marc
* dan

And the rest of the people in the Linux-Xtensa mailing list, if you cannot go through some of the steps, don't hesitate to ask on the mailing list, there's always somebody willing to help you!

SMP HiFi 2 Development Board

2009-12-02T04:23:36Z

Marc: /* Booting Linux for the 1st Time */ Moved example log to separate page

This is the "communitee"" guide for how to use HiFi-2 Codec Development environment on an LX200 FPGA board.
If somethinig doesn't work ir isn't vovered in these guides, please feel free to ask at the [http://lists.linux-xtensa.org/mailman/listinfo Linux//Xtensa Mailing List]]

<div style="margin:0; margin-top:10px; margin-right:10px; border:1px solid #dfdfdf; padding:0 1em 1em 1em; background-color:#ffffcc; align:right; ">
'''NEWS:'''

Some general notes on these instructions:

* They are a work in progress.

* The following was tested on x86 machines running RedHat Fedora Core 5.

* Buildroot build with Fedora Core 9 also seems to be fine; perhaps better than when built on Fedore Core 5.

</div>

== Introduction ==

This document is addressed to someone who received an LX200 board setup by Tensilica
for HiFi2 codec development.

This document goes over the steps needed to set up the LX200 board for codec development.
To summarize:
* Setup the board. It likely comes with U-boot preinstalled, ready to boot a linux kernel.
* Install '''git'''.
* Download buildroot and linux kernel trees, pre-configured and built for HiFi-2 development.
* Setup a TFTP server to provide the linux kernel to U-Boot.
* Setup an NFS server to export a linux root file system.
* Setup the Linux kernel to boot from the root file system provided by the NFS server.
Once the development board is up and running, this document:
* Suggests a possible way to tailor the board for easy codec development.
* Shows how to add the Tensilica provided codec packages to the Mplayer packages used by Buildroot, including building and installing.
* Demonstrates two procedures for compiling, linking, and debugging codecs.

All development is expected to be done on a Linux host. (One can in principle use Windows to
develop target libraries. However, linking and subsequent steps need to be done in Linux.)

== Downloading the Latest HiFI-2 Buildroot and Kernel Snapshots ==

The HiFi-2 development environment is maintained in a source code version control system named 'git'. The '''git''' tools are useful when working with this development environment, though they are not strictly necessary. This document generally assumes the use of '''git''', which provides more opportunities for modifying this environment as needed (e.g. building more optional buildroot packages). But points out alternatives to allow getting up and running without having to set it up.

=== Installing git ===

To install '''git''', download a recent tarball from the [http://www.kernel.org/pub/software/scm/git/ official site]. For example, <tt>cd</tt> to a location with enough disk space, and do:

$ '''wget http://www.kernel.org/pub/software/scm/git/git-1.6.5.tar.gz'''

Unpack the tarball, and make and install it. Here we show how to install it to your ~/bin directory:

$ '''gunzip git-1.6.5.tar.gz'''
$ '''tar xf git-1.6.5.tar'''
$ '''cd git-1.6.5'''
$ '''make'''
$ '''make install'''

The git makefile can be instructed to install '''git''' to <tt>/usr/local/bin</tt> as root for system wide access:

$ '''cp git-1.6.5.tar.gz''' /tmp
$ '''su'''
Password:
# '''cd /usr/local/src/'''
# '''mkdir git'''
# '''cd git'''
# '''cp /tmp/git-1.6.5.tar.gz .'''
# '''gunzip git-1.6.5.tar.gz'''
# '''tar xf git-1.6.5.tar'''
# '''cd git-1.6.5'''
# '''make prefix=/usr/local'''
# '''make install'''

See the '''INSTALL'' instruction at the top of the git src directory for details.

Using '''git''' provides easy access to the binaries used to bring up the codec development environment, and leaves in place the infrastructure to modify and build this environment should you wish to. Any changes to '''git'''-managed source trees are easily observed with the '''git''' tools.

=== Installing the Buildroot Snapshot ===

''Note: The HiFi-2 snapshot is in the process of being made.''

To install the buildroot environment (toolchain and root filesystem), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot'''
$ '''cd buildroot-xtensa-HiFi2-Snapshot'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP''' [56 key strokes]
$ '''git checkout snapshot_2+SMP''' [28 key strokes]

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).

You can examine the tree (git repository) and its history visually using <tt>git gui</tt>.
The git GUI is a faster and more convenient method for checking out the HiFi-2 snapshot. To check out the snapshot_2+SMP branch simply run the command 'git gui' and then pull down the branch->create menu. Next select <>Match Tracking Branch Name and click on ''origin/snapshot_2+SMP''. Finally hit the Create Button.

$ '''git gui''''' [8 key strokes]
[Branch] -> Create... [2 key strokes]
<> Match Tracking Branch Name [1 key stroke]
<> Tracking Branch [1 key stroke]
origin/snapshot_2+SMP [1 key stroke]
[Create] [1 key stroke]
[Reposirory]--> Quit [2 key strokes]

If there are issues installing '''git''', as a last resort, an alternative is ftp (may not always get updated, is currenty our of date, waste disk space, so may be dropped at some point):

http://www.linux-xtensa.org/pub/snapshots/buildroot-xtensa-smp.2-Nov-2009.tar.gz

=== Installing the Linux Kernel Snapshot ===

To install the Linux kernel environment (kernel src, config, and HiFi-2 kernel U-Boot image), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp'''
$ '''cd kernel/xtensa-2.6.29-smp'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
$ '''git checkout snapshot_2+SMP'''

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).
As in the build root case, you can also do it from via git gui using the same proceedure
mantioned above.

Now, assuming we are still in the kernel '''xtensa-2.6.29-smp''' directory
copy the kernel U-Boot Image ('''uImage''') to the tftp directory; Ex:

$ '''cp arch/xtensa/boot/uImage /tftpboot/uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'''

NOTE: On some system, like Fedora Core 9, the tftpboot directory has been moved to /var/lib/tftpboot.
In this case we recomend that you just added a symbolic pointer from /etc to /var/lib/tftpboot:

$ '''su'''
# '''cd /etc'''
# '''/var/lib/tftpboot/ tftpboot'''
# '''ls -ld tftpboot'''
lrwxrwxrwx 1 root root 18 2009-11-23 21:14 tftpboot -> /var/lib/tftpboot/
#

== Setting up a TFTP Server to provide the Linux kernel to U-Boot ==

The TFTP service is part of the xinetd and is installed on Fedora workstations.
You can see that it's installed with the check config command which manages the
/etc/rc.d/init.d startup scripts and with the yum search command:

$ '''chkconfig --list'''
NetworkManager 0:off 1:off 2:off 3:off 4:off 5:off 6:off
NetworkManagerDispatcher 0:off 1:off 2:off 3:off 4:off 5:off 6:off
acpid 0:off 1:off 2:off 3:on 4:on 5:on 6:off
.
.
.
xfs 0:off 1:off 2:on 3:on 4:on 5:on 6:off
xinetd 0:off 1:off 2:off 3:on 4:on 5:on 6:off
ypbind 0:off 1:off 2:off 3:on 4:on 5:on 6:off
yum 0:off 1:off 2:off 3:off 4:off 5:off 6:off

xinetd based services:
amanda: off
auth: off
.
.
.
rsync: off
'''tftp: on''' [NOTE that tftp is enabled]
time: off
time-udp: off
uucp: off
$
$
$
$ '''yum search tftp-server'''
Loading "installonlyn" plugin
Searching Packages:
.
.
.
Reading repository metadata in from local files
.
.
.
'''tftp-server.i386 0.41-1.2.1 installed''' [NOTE that tftp server is installed as part of the inet daemon]
Matched from:
tftp-server
The Trivial File Transfer Protocol (TFTP) is normally used only for
booting diskless workstations. The tftp-server package provides the
server for TFTP, which allows users to transfer files to and from a
remote machine. TFTP provides very little security, and should not be
enabled unless it is expressly needed. The TFTP server is run from
/etc/xinetd.d/tftp, and is disabled by default on Red Hat Linux systems.
[piet@pdelaney_fc5 ~]$

TFTP is not normally enabled, to enable it just edit the file /etc/xinetd.d/tftp
and change the disable field to no:

# default: off
# description: The tftp server serves files using the trivial file transfer \
# protocol. The tftp protocol is often used to boot diskless \
# workstations, download configuration files to network-aware printers, \
# and to start the installation process for some operating systems.
service tftp
{
socket_type = dgram
protocol = udp
wait = yes
user = root
server = /usr/sbin/in.tftpd [NOTE: /var/lib/tftpboot on Fedora Core 9]
server_args = -s /tftpboot
'''disable = no'''
per_source = 11
cps = 100 2
flags = IPv4
}

== Setting up an NFS Server to export the Root Filesystem ==

The LX200 board running Linux needs to mount its root filesystem over NFS.
This filesystem was built using buildroot into a cpio format file,
and left in:

buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2/rootfs.xtensa_test_mmuhifi_c3.cpio

We will also be adding an additional minor changes to make your development environment more comfortable.

Pick a place on your workstation to export your root and unpack the cpio file into that directory.
For example here we will set up an export in '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''':

$ '''cd buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2'''
$ '''WHERE=$PWD'''
$ '''mkdir -p /exports/LINUX_ROOT.HiFi-2'''
$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''cpio -i < $WHERE/rootfs.xtensa_test_mmuhifi_c3.cpio'''

Next add a line to /etc/exports:

/exports *(rw,no_root_squash,sync,no_wdelay)

and restart you nfs services:

$ '''/etc/rc.d/init.d/nfs restart'''
or
$ '''/sbin/chkconfig nfs on'''

The showmount command should show your NFS file system now being exported:

$ '''showmount -e'''
Export list for mypc.foobar.com:
/exports *
$

== Configuring U-Boot to Boot Linux ==

Your LX200 board should have arrived with U-Boot installed in the flash ready to use.
The board has a DIP switch (next to the power on/off switch) that provides the 6 LSBs
of the Ethernet MAC, in switch positions 1 thru 6.

DIP Swithes for MAC: 1 2 3 4 5 6 7 8 ethaddr=00:50:C2:13:6f:0a
Little Endian: 0 1 0 1 0 0 * *
^
|
+------ Enables booting U-Boot from Flash

DIP switch 8 should be shipped in the ON position to enable U-Boot booting from flash.
See Sections 4.2.3 and 4.2.4 of the '''Tensilica Avnet (XT-AV200) Board User's Guide'''
for details. Make sure to select a unique MAC address for you board.

Next, connect a serial interface to a text based terminal emulation program,
set to 38400 bps, no parity, 1 stop bit, no handshaking.
For an example of setting [http://en.wikipedia.org/wiki/Minicom minicom]
for this, see [[minicom_xtboard_setup|here]].

Many users of this board are interested in developing codecs and/or HiFi 2 software and will prefer to just boot linux with the root file system we just described how to export on your NFS server. We will use git now to pull a snapshot of a performance 2.6.29 linux kernel and configure U-Boot to automatically boot it after a power cycle.

U-Boot> '''setenv serverip 192.168.11.55''' [TFTP server IP Address: RTOS-LAB2]
U-Boot> '''setenv nfsroot_server 192.168.11.55''' [Root NFS Servers IP Address: My Workstation]
U-Boot> '''setenv ipaddr 192.168.11.155''' [HOST IP address]
U-Boot> '''setenv bootfile uImage.xtensa-2.6.29-smp.test_mmuhifi_c3''' [File to fetch with TFTP and pass to bootm]
U-Boot> '''setenv root-path /exports/LINUX_ROOT.HiFi-2''' [WARNING: Limit path to < 50 characters]
U-Boot> '''setenv bootargs_using_bootp console=ttyS0,38400 ip=bootp root=nfs coredump_filter=0xff''' [Args passed to Linux while booting with BOOTP proto]
U-boot> '''setenv bootargs console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=${nfsroot_server}:${root-path}''' [Args passed to Linux while booting with DHCP proto]
U-boot> '''setenv bootcmd tftpboot\; bootm''' [Boot Linux after fetching it with TFTP]
U-Boot> '''setenv bootdelay 20''' [Delay 20 seconds before booting automaticaly]
U-Boot> '''setenv autostart yes''' [Boot automatically on power-up/reset]
U-Boot> '''saveenv'''
U-Boot>

'''[REMIND: Update the above procedure, show two or thee approaches (ip, dhcp, bootp)]'''

== Tailoring your system prior to Booting ==

There are a few tweaks that developers have found convenient to add to the the root file-system before booting.
As an initial environment for developing we suggest mounting a /home/default files-system that has number of
files useful for getting started. Find another place to tar in the tar ball with the default users file system.
We chose to include this close to the cpio file with the root file-system. Copy the tar bar to where you are
exporting you root file-system and next to it add the 'default' users file-system:

$ '''cd /export'''
$ '''cp /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.10/binaries/default.tar .'''
$ '''tar xf default.tar'''
$ '''cd default'''
$ '''ls'''
[TO BE ADDED]

Notice a file tar ball called '''saved_files.tar'''. This ia a tar file of files that
developers have found convenient to add and replace on the root file system after
adding a new buildroot file system. Here is a list of the files and a brief
explanation on why it's convenient to add or replace them:

root/.bash_profile [added 'ulimit -c unlimited to allow core dumps to be created]
root/.bashrc
etc/profile [added 'ulimit -c unlimited to allow core dumps to be created]
etc/fstab [Tells the system how to mount extra NFS file systems like /home/default]
etc/init.d/S90local [Mounts /home/default]
etc/resolv.conf [Location of DNS servers when your not using DHCP to boot the kernel]
etc/TZ [Your time zone, currently set to California TZ]
etc/dropbear/dropbear_rsa_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/dropbear/dropbear_dss_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/ssh_config [Typically tailored with things like allowing root logins via ssh]
etc/ssh_host_dsa_key [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_dsa_key.pub [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_key
etc/ssh_host_key.pub
etc/ssh_host_rsa_key
etc/ssh_host_rsa_key.pub
etc/sshd_config [Typically tailored with things like allowing root logins via ssh]
etc/rndc.key
etc/random-seed [Generated during 1st boot]
etc/passwd [Changed default user's shell to bash]
etc/shadow [Changed default and root users login password to 'linux1', need to ssh to the board]
exports/ [The path to where the board can mount extra file systems like /home/default.
fac/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]
fac/vol6/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]

Now lets assume your going to stay with these changes and modify them after taring in these changes.
Here we add the tar ball files to the boards root filesystem.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''tar xf /exports/default/'''

This is a good time to edit a few files on the boards file system
before boot it.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''vi etc/fstab''' [Change fstab entry for /home/default and others to your taste]
$ '''vi etc/init.d/S90local''' [You might want to disable mounting of NFS file systems on the 1st Boot and add this once you try it manually]

== Booting Linux for the 1st Time ==

We should now be ready to boot linux on your LX200. You have exported the root file-system and made the
kernel available to a TFTP server. Now let's start with hitting the reset button on the LX200 and it should
auto-boot the kernel, resulting in output such as [[HiFi2_Board_Example_Linux_Boot_Log|this]].

== Tailoring your system prior to developing your codec ==

To make your experience more pleasant we suggest you tailor your environment.
Here are some of the changes that we have found helpful:

1. Add a root password to that you can login with ssh.
2. Run rdate with an ntp server on booting.
3. Add NFS mounts to /etc/fstab for your code and buildroot code.
4. Copy in previous ssh server encryption keys to /etc/dropbear to speed up your initial boot.
5. Mount a 'default' user home directory with:
a. Linux Test Suite pre-patch to test the system
b. Audio test example files
c. Copies of Mplayer and its Plug-ins from Buildroot modified slightly to make installation easy.
d. Misc audio test programs.

[TO BE DONE - Where to get 'default' user home directory tar ball and 1st boot patch]

== Compiling the Mplayer Plugins and linking them with MPEG-1 Audio Layer 3 (MP3) and MPEG-4 AAC Codecs ==

Mplayer is provided as an example environment for developing and testing Codecs and HiFi 2 software. There
are two ways to build Mplayer and the plug-in modules that use the codecs. The buildroot
tree (pulled with git) has a copy of mplayer and the plugins that can be built in the
snapshot via 'make menuconfig'. This is a good environment to use once codecs are
developed and debugged.

To facilitate development the mplayer packages can be copied to your NFS mounted development
environment. From there you can just configure mplayer to compile on the board and debug
mplayer and your codecs with gdb locally.

In the default user home directory we have a directory /home/default/buildroot_mplayer_stuff
with a copy of three of the mplayer packages:

[root@hifi buildroot_mplayer_stuff]# '''ls -l'''
drwxr-xr-x 34 root root 4096 Nov 10 05:01 MPlayer-1.0rc2/
drwxr-xr-x 4 root root 4096 Nov 10 01:36 mplayer_hifi2_aacplus_v2_plugin/
drwxr-xr-x 3 root root 4096 Nov 10 00:57 mplayer_hifi2_mp3_plugin/

they were simply copied from the buildroot-xtensa-HiFi2-Snapshot.2/package directory.

To get your development environment ready to compile the mplayer plug-ins you need
to configure Mplayer to use the local C compiler and linker:

# '''cd /home/default/buildroot_mplayer_stuff/MPlayer-1.0rc2/'''
# '''CFLAGS="-g3" ./configure'''

This will take about 15 minutes to configure. After that you can build the
plugins or mplayer. If you want to recompile mplayer it's likely best/necessary
to use the same args to .configure as used by buildroot:

.CFLAGS="-g3" ./configure \
--prefix=/usr \
--confdir=/etc/mplayer \
--with-extraincdir=/usr/include \
--with-extralibdir=/lib \
--disable-gui \
--enable-mad \
--enable-fbdev \
--disable-mencoder \
--disable-dvdnav \
--disable-dvdread \
--disable-dvdread-internal \
--disable-libdvdcss-internal \
--disable-big-endian \
--disable-nemesi \
--disable-tv \
--enable-dynamic-plugins

We are currently able to compile most of mplayer on the XL200 but
due to space limitations it's not possible to compile it -O0.

Now, lets focus on compiling linking the plugins. They are a nice
example of compiling a audio application on the LX200.

We modified the Makefile of the codes slightly, and will make it available.
These additions just instruct make how to install the plugins as explained
in the Chapter 7 of the Linux HiFi application note.

For example the mp3 plugin has this addition:

target_install::
-mkdir /etc/mplayer
cp codecs.conf /etc/mplayer
-mkdir /usr/lib/mplayer
cp ad_xa_mp3_dec.so /usr/lib/mplayer/
cp xa_mp3_dec.so /usr/lib/mplayer
chmod 755 /usr/lib/mplayer/ad_xa_mp3_dec.so
chmod 755 /usr/lib/mplayer/xa_mp3_dec.so

It's just providing a codec config file for mplayer at '''/etc/mplayer/codecs.conf''' and
copying the plug-in to '''/usr/lib/mplayer'''. To install the mp3 codec plugin and mplayer
config file just copy your codec that was compiled with '''xcc''' to the directory, compile it,
and install.

# '''cd /fac/vol6/audio/release/bin/l32r_LE5_pic'''
# '''cp xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz /tmp'''
#
# '''cd /home/default/buildroot_mplayer_stuff'''
# '''cd mplayer_hifi2_mp3_plugin'''
# '''cp /tmp/xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz .'''
# '''gunzip xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz'''
# '''tar xf xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tar'''
# '''make'''
# '''make target_install'''

The unpacking of the Tensilica mp3 codec tar ball will install the following files:

xa_mp3_dec/
xa_mp3_dec/README
xa_mp3_dec/include/
xa_mp3_dec/include/mp3_dec/
xa_mp3_dec/include/mp3_dec/xa_mp3_dec_api.h
xa_mp3_dec/include/xa_apicmd_standards.h
xa_mp3_dec/include/xa_error_handler.h
xa_mp3_dec/include/xa_error_standards.h
xa_mp3_dec/include/xa_memory_standards.h
xa_mp3_dec/include/xa_type_def.h
xa_mp3_dec/test/
xa_mp3_dec/test/build/
xa_mp3_dec/test/build/ldscript_stream_data.txt
xa_mp3_dec/test/build/makefile_testbench_sample
xa_mp3_dec/test/build/paramfilesimple.txt
xa_mp3_dec/test/include/
xa_mp3_dec/test/include/id3_tag_decode.h
xa_mp3_dec/test/src/
xa_mp3_dec/test/src/xa_mp3_dec_sample_testbench.c
xa_mp3_dec/test/src/id3_tag_decode.c
xa_mp3_dec/test/src/stream_data.c
xa_mp3_dec/test/src/xa_mp3_dec_error_handler.c
xa_mp3_dec/test/test_inp/
xa_mp3_dec/test/test_inp/compl.mp3
xa_mp3_dec/test/test_inp/hihat.mp3
xa_mp3_dec/test/test_out/
xa_mp3_dec/test/test_out/force_mkdir.txt
xa_mp3_dec/test/test_ref/
xa_mp3_dec/test/test_ref/compl_24bit.wav
xa_mp3_dec/test/test_ref/hihat_16bit.wav
xa_mp3_dec/lib/
xa_mp3_dec/lib/xa_mp3_dec.a
xa_mp3_dec/doc/
xa_mp3_dec/doc/HiFi2-MP3-DecoderProgrammersGuide.pdf

[TO BE DONE - Add missing C file, make clean deletes it!]

The xa_mp3_dec.a archive will be used by the Makefile in
the mplayer_hifi2_mp3_plugin directory to make the mplayer plug-in.
Section 6 of the '''Using Tensilica HiFi 2 Codec on Xtensa Linux with MPlayer'' Application Note
has a detailed description of the encapsulation process used by the plug-ins.

== Compiling Generic GPL Packages ==

For your development you may want to add a few GPL packages that you find helpfull.
This can be done on the LX200 just as you would on a normal workstation, thought
much slower. For example here we configure and build a few common GPL packages:

[[Building the Strace Package]]

[[Building the vim Package]]

== Compiling Tie Code with XCC ==

Codecs like MP3 and AAC have been written in C with TIE extensions and can only be compiled with '''xcc'''.
XCC is likely to large to run on the board without virtual memory. There are two approaches to compiling
Linux TIE code with '''xcc'''. The simple approach assumes the host workstation and target code running of the board
are similar enough that the library interfaces defined by the include files are compatable. This is often the
case for standard system calls, libc, and stdio.The proper approach uses a virtual core that we will create
that has built in references to the library and include files on the target code running on the LX200.

=== Simply using Xtensa Tools to compile the TIE code on a workstation ===

Below we illustrate compiling a simple audio test program on a workstation.
We start by referring to the XTENSA tools build by Xplorer, putting '''xcc''' into our search path and set the standard XTENSA_* environement variables.
For example:

setenv XTENSA_CORE test_mmuhifi_c3
setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config
setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin

setenv PATH ${XTENSA_TOOLS}:${PATH}

[piet@fc9desktop Tests] $ '''cd /exports/default/Audio_Tests''' [NOTE: This is being done on a Workstation]
[piet@fc9desktop Audio_Tests]$ '''xt-xcc -g3 -O0 -fPIC -c hifitest.c'''

Next we link the object on the XL200 board and run gdb on the TIE enhanced code:

[root@hifi Audio_Tests]# '''gcc -g hifitest.o -o hifitest'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:4640; Eatting cpu; time:0
cnt:0x0, pid:4640; Eating Tie; time:7
^C
[root@hifi Audio_Tests]# '''gdb ./hifitest''' [NOTE: This is being done on the LX200 board]
GNU gdb 6.6
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "xtensa_test_mmuhifi_c3-linux-uclibc"...
Using host libthread_db library "/lib/libthread_db.so.1".
(gdb) '''break main'''
Breakpoint 1 at 0x400401: file /exports/default/Audio_Tests/hifitest.c, line 20.
(gdb) '''run'''
Starting program: /home/default/Audio_Tests/hifitest

Breakpoint 1, main (argc=1, argv=0x3fb3fab4)
at /exports/default/Audio_Tests/hifitest.c:20
20 time_t time0 = time(NULL);
(gdb) '''step'''
21 time_t time1 = time(NULL);

=== Building Linux Applications Using Tensilica's XCC Compiler ===

Section 4.3 of the latest ''Xtensa OSKit Guide'' (from Tensilica's
RC-2009.0 release) describes how to setup XCC to compile Linux applications.
For details, see the guide.

A summary follows. The XTENSA_TOOLS_ROOT, XTENSA_ROOT, BUILDROOT_DIR, and TARGET_SYSROOT
environment variables must be set according to where things were installed;
values shown here are for illustration only. The CORENAME variable, set correctly
below for this board, reflects
the name of the core as known to open source tools (as opposed to XTENSA_CORE
which is the core name as known to Xtensa Tools; both happen to match here).

$ setenv XTENSA_ROOT /home/someuser/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
$ setenv XTENSA_TOOLS_ROOT /home/someuser/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools
$ setenv TARGET_SYSROOT /exports/LINUX_ROOT.HiFi-2
$ setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12

$ setenv CORENAME test_mmuhifi_c3

$ cd ${BUILDROOT_DIR}
$ ${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install \
--sysroot=./build_xtensa_${CORENAME}/staging_dir \
--linux-gcc=./build_xtensa_${CORENAME}/staging_dir/usr/bin/xtensa_${CORENAME}-linux-gcc

Assuming the above completes successfully, you can now build applications using Xtensa Tools. First set the usual environment variables:

$ setenv XTENSA_CORE default
$ setenv XTENSA_SYSTEM ${XTENSA_ROOT}-linux/config
$ setenv PATH ${XTENSA_TOOLS_ROOT}/bin:${PATH}

And build something:

$ echo '#include <stdio.h>' > hello.c
$ echo 'int main() {printf("Hello!\n");return 0;}' >> hello.c
$ xt-xcc -g hello.c -o hello

Then copy it where the target can see it:

$ cp hello ${TARGET_SYSROOT}/root

And run it on the target:

[root@hifi ~]# /root/hello

Here's a more interesting example that uses Tensilica TIE features.
(This cannot be compiled using GCC.)

$ cd ${TARGET_SYSROOT}/home/default/Audio_Tests
$ xt-xcc -g hifitest.c -o hifitest

In a ssh termulator window on the board you can now run hifitest:

[root@hifi ~]# '''cd /home/default/Audio_Tests/'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:23178; Eatting cpu; time:0 '''<control-C>'''

[root@hifi Audio_Tests]#

Here is the source code for the [[hifitest.c|hifitest.c source file]] used above.

== Adding your codec to Buildroot ==

Xtensa developers provide detailed instructions on building the root filesystem and the Linux kernel.
* [[Buildroot_Build_Instructions|Instructions for building and booting Linux (buildroot)]].

Building a comprehensive development environment with buildroot can be a chalanging experience and worthy of providing some tips on process.
Here are notes of the configs used for the three menuconfigs in this 2nd snapshot
provided with SMP additions:
$ '''make [[HiFi-2 snapshot_2 SMP Snapshot menuconfig | menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP uclibc-menuconfig | uclibc-menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP busybox-menuconfig | busybox-menuconfig]]'''

[TO BE DONE - making a new tar ball of saved files, building buildroot, ...]

== Known Problems being investigated, suggested that you know about and possibly avoid ==

1. Using NFS mounts with default parameters causes memory congestion. Use these mount options:

'''vers=2,rsize=4096,wsize=4096,hard,nointr,nolock,nolock,timeo=11,retrans=3,noauto'''

this is extremely important to add to your /etc/fstab on the target.

2. Can't swap over NFS yet, memory can get tight and cause application to be killed.
a. Trying procedure documented in U-Boot Manual.

3. Building the C development with X11 doesn't work with buildroot.

4. Though Mplayer plug-in can be compiled, Mplayer can be compiled but still has a few issues:
a. Can't be compiled -O0 due to limited memory while compiling one file,
b. Compiler infrequently crashes and make has to be restarted.
Not seeing this problem with root build on Fedore Core 9.
Perhaps this was caused by debug kernel or LTP using all of the memory.

5. U-boot has flash problems:
a. Sectors marked Read-Only come up Writeable after a reset/reboot.
b. Flashing a large number of sectors (like the kernel) sometimes
results in an Error (Ex: Vcc) and had to be retried.
c. Saw environment variables trashed on reset/reboot once.
It's possible that U-boot in flash could get whacked
and the board will need to be re-flashed. During a week
or two of testing I haven't see environment getting whacked.

6. gdb appears to be crashing on target when debugging
on latest root with uclibc left unstriped and with debug;
core dump sent to maxim.

7. U-Boot seems to hang periodically when loading the kernel with
tftp; appears to be worse when network activity is high.

8. 'top' command only shows all cpu's or cpu0; cpu 1 and 2 missing.

9. Program dore dump require ulimit -c to be set but root uses /bin/sh
which is a link to bash but causes it to skip running the bash
startup scripts. Changing root to /bin/bash seems to mess up
ssh logins.

10. For kernel to be compiled on the LX200 (for self checking:
a. Xtensa makefile needs to be fixed:
CC init/do_mounts.o
LD init/mounts.o
/bin/sh: xtensa_test_mmuhifi_c3-linux-uclibc-ld: command not found
make[1]: *** [init/mounts.o] Error 127

b. Need to add ncurses-devel package for 'make menuconfig'

11. Copying vim-7.2.tar from /home/default/src to /usr/local/src resulted
in a corrupt tar header. Apparently we have a NFS bug lurking in the kernel.
On server tar file looks like this:
vim72/000755 001750 001750 00000000000 11047345123 012000 5
ustar00moolmool000000 000000
vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0
ustar00moolmool000000 000000
README.txt for version 7.2 of Vim: Vi IMproved.

On the target/client it's different:
vim72/000755 001750 001750 00000000000 11047345123 012000 5ustar00moolmool000000 000000 vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0ustar00moolmool000000 000000 README.txt for version 7.2 of Vim: Vi IMproved.

=Further reading=

Main Xtensa Linux resources are:

* [http://linux-xtensa.org/ Linux/Xtensa Wiki]
* [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions Buildroot Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Kernel_Build_Instructions Kernel Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Setting_up_U-Boot Setting up U-Boot]
* [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List]
* http://git.linux-xtensa.org/cgi-bin/git.cgi GIT Repositories]

=Thanks to=

* piet
* marc
* dan

And the rest of the people in the Linux-Xtensa mailing list, if you cannot go through some of the steps, don't hesitate to ask on the mailing list, there's always somebody willing to help you!

HiFi2 Board Example Linux Boot Log

2009-12-02T04:22:57Z

Marc: Example log in separate page

U-Boot 2009.08 (Nov 15 2009 - 22:03:26)

CPU: Xtensa test_mmuhifi_c3 at 41.6777 MHz
Board: XT-AV200: Avnet board + Xilinx LX200 FPGA + Tensilica bitstream
SysRAM: 96 MB
Flash: 16 MB
In: serial
Out: serial
Err: serial
MAC: 00:50:C2:13:6f:07
IP: 192.168.11.105
open_ethernet
Autobooting in 5 seconds, press <SPACE> to stop
Using open_ethernet device
TFTP from server 192.168.11.55; our IP address is 192.168.11.105
Filename 'uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'.
Load address: 0xd2000000
Loading: #################################################################
###############
done
Bytes transferred = 1161826 (11ba62 hex)
Automatic boot of image at addr 0xD2000000 ...
## Booting kernel from Legacy Image at d2000000 ...
Image Name: Linux-2.6.29-rc7
Image Type: Xtensa Linux Kernel Image (gzip compressed)
Data Size: 1161762 Bytes = 1.1 MB
Load Address: d0001000
Entry Point: d0001000
Verifying Checksum ... OK
Uncompressing Kernel Image ... OK

## Linux Boot Params Starting At Address:0xd5f50000
MEMORY: tag:0x1003, type:0X1000, start:0X0, end:0X6000000
COMMAND_LINE: tag:0x1001, size:188, data:'console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff'
SERIAL_BAUDRATE: tag:0x1004, size:4, baudrate:38400

## Transferring Control to Linux Kernel At Address 0xd0001000 ...

parse_bootparam: Ignoring tag 0x1004
lx60 platform_init(bootparams:d5f50000)
Linux version 2.6.29-rc7 (pdelaney@pdelaney_fc5.hq.tensilica.com) (gcc version 4.2.1) #201 SMP Tue Nov 17 23:49:39 PST 2009
lx60 platform_setup(cmdline[0]:'console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff')
smp_init_cpus: Core Count = 3
smp_init_cpus: Core Id = 9320
On node 0 totalpages: 24576
free_area_init_node: node 0, pgdat d0196540, node_mem_map d01fa000
Normal zone: 216 pages used for memmap
Normal zone: 24360 pages, LIFO batch:3
smp_prepare_boot_cpu:
Built 1 zonelists in Zone order, mobility grouping on. Total pages: 24360
Kernel command line: console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff
trap_init 0
PID hash table entries: 512 (order: 9, 2048 bytes)
time_init: Platform Calibrating CPU frequency
time_init: ccount_per_jiffy:416777 [41.67 MHz], nsec_per_ccount:23
Console: colour dummy device 80x25
console [ttyS0] enabled
Dentry cache hash table entries: 16384 (order: 4, 65536 bytes)
Inode-cache hash table entries: 8192 (order: 3, 32768 bytes)
Memory: 95196k/98304k available (1229k kernel code, 3040k reserved, 28k data, 72k init 0k highmem)
Calibrating delay loop... 41.26 BogoMIPS (lpj=206336)
Mount-cache hash table entries: 512
cpu 1 fffd
secondary_trap_init 1
Calibrating delay loop... 41.67 BogoMIPS (lpj=208384)
secondary_irq_init: set cached_irq_mask and enable interrupts))
secondary_time_init()
secondary_irq_enable(intrnum:6): cpu:1, INTENABLE:7c
secondary_irq_enable(intrnum:0): cpu:1, INTENABLE:7d
cpu 2 fff9
secondary_trap_init 2
Calibrating delay loop... 41.57 BogoMIPS (lpj=207872)
secondary_irq_init: set cached_irq_mask and enable interrupts))
secondary_time_init()
secondary_irq_enable(intrnum:6): cpu:2, INTENABLE:7c
secondary_irq_enable(intrnum:0): cpu:2, INTENABLE:7d
Brought up 3 CPUs
smp_cpus_done:
net_namespace: 304 bytes
NET: Registered protocol family 16
lx60_init()
bio: create slab <bio-0> at 0
NET: Registered protocol family 2
IP route cache hash table entries: 1024 (order: 0, 4096 bytes)
TCP established hash table entries: 4096 (order: 3, 32768 bytes)
TCP bind hash table entries: 4096 (order: 3, 32768 bytes)
TCP: Hash tables configured (established 4096 bind 4096)
TCP reno registered
NET: Registered protocol family 1
msgmni has been set to 186
alg: No test for md5 (md5-generic)
alg: No test for des (des-generic)
alg: No test for des3_ede (des3_ede-generic)
alg: No test for stdrng (krng)
io scheduler noop registered (default)
Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled
serial8250: ttyS0 at MMIO 0x0 (irq = 3) is a 16550A
oeth_probe: {
oeth_setup: Open Ethernet Core Version 1.0.1
: oeth_setup: Found id1:2000, id2:5c30 at phy_id:3.
: Hardware MAC Address: 00:50:c2:13:6f:0f
eth0 (): not using net_device_ops yet
oeth_probe: }
mice: PS/2 mouse device common for all mice
TCP cubic registered
NET: Registered protocol family 17
RPC: Registered udp transport module.
RPC: Registered tcp transport module.
oeth_open: Ready to process packets now on dev->name:'eth0', dev:d597d800;
IP-Config: Complete:
device=eth0, addr=192.168.11.105, mask=255.255.255.0, gw=192.168.11.1,
host="HiFi-2 Demo", domain=, nis-domain=(none),
bootserver=192.168.11.55, rootserver=192.168.11.55, rootpath=
Looking up port of RPC 100003/2 on 192.168.11.55
Looking up port of RPC 100005/1 on 192.168.11.55
VFS: Mounted root (nfs filesystem) on device 0:11.
Freeing unused kernel memory: 72k freed
Starting portmap: done
Initializing random number generator... done.
Starting network...
ip: RTNETLINK answers: File exists
Starting sshd: OK
Starting NFS statd: done
Starting NFS services: done
Starting NFS daemon: done
Starting NFS mountd: done
Starting domain name daemon: namedwarning: `named' uses 32-bit capabilities (legacy support in use)
failed
Fri Nov 20 17:10:37 2009
Mounting Other NFS Filesystems

Welcome to your custom Xtensa HiFi-2 Codec Developemnt System
hifi login: '''''root'''''
Password: '''''linux1'''''

SMP HiFi 2 Development Board

2009-12-02T04:22:01Z

Marc: /* Booting Linux for the 1st Time */ Add link

This is the "communitee"" guide for how to use HiFi-2 Codec Development environment on an LX200 FPGA board.
If somethinig doesn't work ir isn't vovered in these guides, please feel free to ask at the [http://lists.linux-xtensa.org/mailman/listinfo Linux//Xtensa Mailing List]]

<div style="margin:0; margin-top:10px; margin-right:10px; border:1px solid #dfdfdf; padding:0 1em 1em 1em; background-color:#ffffcc; align:right; ">
'''NEWS:'''

Some general notes on these instructions:

* They are a work in progress.

* The following was tested on x86 machines running RedHat Fedora Core 5.

* Buildroot build with Fedora Core 9 also seems to be fine; perhaps better than when built on Fedore Core 5.

</div>

== Introduction ==

This document is addressed to someone who received an LX200 board setup by Tensilica
for HiFi2 codec development.

This document goes over the steps needed to set up the LX200 board for codec development.
To summarize:
* Setup the board. It likely comes with U-boot preinstalled, ready to boot a linux kernel.
* Install '''git'''.
* Download buildroot and linux kernel trees, pre-configured and built for HiFi-2 development.
* Setup a TFTP server to provide the linux kernel to U-Boot.
* Setup an NFS server to export a linux root file system.
* Setup the Linux kernel to boot from the root file system provided by the NFS server.
Once the development board is up and running, this document:
* Suggests a possible way to tailor the board for easy codec development.
* Shows how to add the Tensilica provided codec packages to the Mplayer packages used by Buildroot, including building and installing.
* Demonstrates two procedures for compiling, linking, and debugging codecs.

All development is expected to be done on a Linux host. (One can in principle use Windows to
develop target libraries. However, linking and subsequent steps need to be done in Linux.)

== Downloading the Latest HiFI-2 Buildroot and Kernel Snapshots ==

The HiFi-2 development environment is maintained in a source code version control system named 'git'. The '''git''' tools are useful when working with this development environment, though they are not strictly necessary. This document generally assumes the use of '''git''', which provides more opportunities for modifying this environment as needed (e.g. building more optional buildroot packages). But points out alternatives to allow getting up and running without having to set it up.

=== Installing git ===

To install '''git''', download a recent tarball from the [http://www.kernel.org/pub/software/scm/git/ official site]. For example, <tt>cd</tt> to a location with enough disk space, and do:

$ '''wget http://www.kernel.org/pub/software/scm/git/git-1.6.5.tar.gz'''

Unpack the tarball, and make and install it. Here we show how to install it to your ~/bin directory:

$ '''gunzip git-1.6.5.tar.gz'''
$ '''tar xf git-1.6.5.tar'''
$ '''cd git-1.6.5'''
$ '''make'''
$ '''make install'''

The git makefile can be instructed to install '''git''' to <tt>/usr/local/bin</tt> as root for system wide access:

$ '''cp git-1.6.5.tar.gz''' /tmp
$ '''su'''
Password:
# '''cd /usr/local/src/'''
# '''mkdir git'''
# '''cd git'''
# '''cp /tmp/git-1.6.5.tar.gz .'''
# '''gunzip git-1.6.5.tar.gz'''
# '''tar xf git-1.6.5.tar'''
# '''cd git-1.6.5'''
# '''make prefix=/usr/local'''
# '''make install'''

See the '''INSTALL'' instruction at the top of the git src directory for details.

Using '''git''' provides easy access to the binaries used to bring up the codec development environment, and leaves in place the infrastructure to modify and build this environment should you wish to. Any changes to '''git'''-managed source trees are easily observed with the '''git''' tools.

=== Installing the Buildroot Snapshot ===

''Note: The HiFi-2 snapshot is in the process of being made.''

To install the buildroot environment (toolchain and root filesystem), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot'''
$ '''cd buildroot-xtensa-HiFi2-Snapshot'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP''' [56 key strokes]
$ '''git checkout snapshot_2+SMP''' [28 key strokes]

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).

You can examine the tree (git repository) and its history visually using <tt>git gui</tt>.
The git GUI is a faster and more convenient method for checking out the HiFi-2 snapshot. To check out the snapshot_2+SMP branch simply run the command 'git gui' and then pull down the branch->create menu. Next select <>Match Tracking Branch Name and click on ''origin/snapshot_2+SMP''. Finally hit the Create Button.

$ '''git gui''''' [8 key strokes]
[Branch] -> Create... [2 key strokes]
<> Match Tracking Branch Name [1 key stroke]
<> Tracking Branch [1 key stroke]
origin/snapshot_2+SMP [1 key stroke]
[Create] [1 key stroke]
[Reposirory]--> Quit [2 key strokes]

If there are issues installing '''git''', as a last resort, an alternative is ftp (may not always get updated, is currenty our of date, waste disk space, so may be dropped at some point):

http://www.linux-xtensa.org/pub/snapshots/buildroot-xtensa-smp.2-Nov-2009.tar.gz

=== Installing the Linux Kernel Snapshot ===

To install the Linux kernel environment (kernel src, config, and HiFi-2 kernel U-Boot image), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp'''
$ '''cd kernel/xtensa-2.6.29-smp'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
$ '''git checkout snapshot_2+SMP'''

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).
As in the build root case, you can also do it from via git gui using the same proceedure
mantioned above.

Now, assuming we are still in the kernel '''xtensa-2.6.29-smp''' directory
copy the kernel U-Boot Image ('''uImage''') to the tftp directory; Ex:

$ '''cp arch/xtensa/boot/uImage /tftpboot/uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'''

NOTE: On some system, like Fedora Core 9, the tftpboot directory has been moved to /var/lib/tftpboot.
In this case we recomend that you just added a symbolic pointer from /etc to /var/lib/tftpboot:

$ '''su'''
# '''cd /etc'''
# '''/var/lib/tftpboot/ tftpboot'''
# '''ls -ld tftpboot'''
lrwxrwxrwx 1 root root 18 2009-11-23 21:14 tftpboot -> /var/lib/tftpboot/
#

== Setting up a TFTP Server to provide the Linux kernel to U-Boot ==

The TFTP service is part of the xinetd and is installed on Fedora workstations.
You can see that it's installed with the check config command which manages the
/etc/rc.d/init.d startup scripts and with the yum search command:

$ '''chkconfig --list'''
NetworkManager 0:off 1:off 2:off 3:off 4:off 5:off 6:off
NetworkManagerDispatcher 0:off 1:off 2:off 3:off 4:off 5:off 6:off
acpid 0:off 1:off 2:off 3:on 4:on 5:on 6:off
.
.
.
xfs 0:off 1:off 2:on 3:on 4:on 5:on 6:off
xinetd 0:off 1:off 2:off 3:on 4:on 5:on 6:off
ypbind 0:off 1:off 2:off 3:on 4:on 5:on 6:off
yum 0:off 1:off 2:off 3:off 4:off 5:off 6:off

xinetd based services:
amanda: off
auth: off
.
.
.
rsync: off
'''tftp: on''' [NOTE that tftp is enabled]
time: off
time-udp: off
uucp: off
$
$
$
$ '''yum search tftp-server'''
Loading "installonlyn" plugin
Searching Packages:
.
.
.
Reading repository metadata in from local files
.
.
.
'''tftp-server.i386 0.41-1.2.1 installed''' [NOTE that tftp server is installed as part of the inet daemon]
Matched from:
tftp-server
The Trivial File Transfer Protocol (TFTP) is normally used only for
booting diskless workstations. The tftp-server package provides the
server for TFTP, which allows users to transfer files to and from a
remote machine. TFTP provides very little security, and should not be
enabled unless it is expressly needed. The TFTP server is run from
/etc/xinetd.d/tftp, and is disabled by default on Red Hat Linux systems.
[piet@pdelaney_fc5 ~]$

TFTP is not normally enabled, to enable it just edit the file /etc/xinetd.d/tftp
and change the disable field to no:

# default: off
# description: The tftp server serves files using the trivial file transfer \
# protocol. The tftp protocol is often used to boot diskless \
# workstations, download configuration files to network-aware printers, \
# and to start the installation process for some operating systems.
service tftp
{
socket_type = dgram
protocol = udp
wait = yes
user = root
server = /usr/sbin/in.tftpd [NOTE: /var/lib/tftpboot on Fedora Core 9]
server_args = -s /tftpboot
'''disable = no'''
per_source = 11
cps = 100 2
flags = IPv4
}

== Setting up an NFS Server to export the Root Filesystem ==

The LX200 board running Linux needs to mount its root filesystem over NFS.
This filesystem was built using buildroot into a cpio format file,
and left in:

buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2/rootfs.xtensa_test_mmuhifi_c3.cpio

We will also be adding an additional minor changes to make your development environment more comfortable.

Pick a place on your workstation to export your root and unpack the cpio file into that directory.
For example here we will set up an export in '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''':

$ '''cd buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2'''
$ '''WHERE=$PWD'''
$ '''mkdir -p /exports/LINUX_ROOT.HiFi-2'''
$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''cpio -i < $WHERE/rootfs.xtensa_test_mmuhifi_c3.cpio'''

Next add a line to /etc/exports:

/exports *(rw,no_root_squash,sync,no_wdelay)

and restart you nfs services:

$ '''/etc/rc.d/init.d/nfs restart'''
or
$ '''/sbin/chkconfig nfs on'''

The showmount command should show your NFS file system now being exported:

$ '''showmount -e'''
Export list for mypc.foobar.com:
/exports *
$

== Configuring U-Boot to Boot Linux ==

Your LX200 board should have arrived with U-Boot installed in the flash ready to use.
The board has a DIP switch (next to the power on/off switch) that provides the 6 LSBs
of the Ethernet MAC, in switch positions 1 thru 6.

DIP Swithes for MAC: 1 2 3 4 5 6 7 8 ethaddr=00:50:C2:13:6f:0a
Little Endian: 0 1 0 1 0 0 * *
^
|
+------ Enables booting U-Boot from Flash

DIP switch 8 should be shipped in the ON position to enable U-Boot booting from flash.
See Sections 4.2.3 and 4.2.4 of the '''Tensilica Avnet (XT-AV200) Board User's Guide'''
for details. Make sure to select a unique MAC address for you board.

Next, connect a serial interface to a text based terminal emulation program,
set to 38400 bps, no parity, 1 stop bit, no handshaking.
For an example of setting [http://en.wikipedia.org/wiki/Minicom minicom]
for this, see [[minicom_xtboard_setup|here]].

Many users of this board are interested in developing codecs and/or HiFi 2 software and will prefer to just boot linux with the root file system we just described how to export on your NFS server. We will use git now to pull a snapshot of a performance 2.6.29 linux kernel and configure U-Boot to automatically boot it after a power cycle.

U-Boot> '''setenv serverip 192.168.11.55''' [TFTP server IP Address: RTOS-LAB2]
U-Boot> '''setenv nfsroot_server 192.168.11.55''' [Root NFS Servers IP Address: My Workstation]
U-Boot> '''setenv ipaddr 192.168.11.155''' [HOST IP address]
U-Boot> '''setenv bootfile uImage.xtensa-2.6.29-smp.test_mmuhifi_c3''' [File to fetch with TFTP and pass to bootm]
U-Boot> '''setenv root-path /exports/LINUX_ROOT.HiFi-2''' [WARNING: Limit path to < 50 characters]
U-Boot> '''setenv bootargs_using_bootp console=ttyS0,38400 ip=bootp root=nfs coredump_filter=0xff''' [Args passed to Linux while booting with BOOTP proto]
U-boot> '''setenv bootargs console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=${nfsroot_server}:${root-path}''' [Args passed to Linux while booting with DHCP proto]
U-boot> '''setenv bootcmd tftpboot\; bootm''' [Boot Linux after fetching it with TFTP]
U-Boot> '''setenv bootdelay 20''' [Delay 20 seconds before booting automaticaly]
U-Boot> '''setenv autostart yes''' [Boot automatically on power-up/reset]
U-Boot> '''saveenv'''
U-Boot>

'''[REMIND: Update the above procedure, show two or thee approaches (ip, dhcp, bootp)]'''

== Tailoring your system prior to Booting ==

There are a few tweaks that developers have found convenient to add to the the root file-system before booting.
As an initial environment for developing we suggest mounting a /home/default files-system that has number of
files useful for getting started. Find another place to tar in the tar ball with the default users file system.
We chose to include this close to the cpio file with the root file-system. Copy the tar bar to where you are
exporting you root file-system and next to it add the 'default' users file-system:

$ '''cd /export'''
$ '''cp /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.10/binaries/default.tar .'''
$ '''tar xf default.tar'''
$ '''cd default'''
$ '''ls'''
[TO BE ADDED]

Notice a file tar ball called '''saved_files.tar'''. This ia a tar file of files that
developers have found convenient to add and replace on the root file system after
adding a new buildroot file system. Here is a list of the files and a brief
explanation on why it's convenient to add or replace them:

root/.bash_profile [added 'ulimit -c unlimited to allow core dumps to be created]
root/.bashrc
etc/profile [added 'ulimit -c unlimited to allow core dumps to be created]
etc/fstab [Tells the system how to mount extra NFS file systems like /home/default]
etc/init.d/S90local [Mounts /home/default]
etc/resolv.conf [Location of DNS servers when your not using DHCP to boot the kernel]
etc/TZ [Your time zone, currently set to California TZ]
etc/dropbear/dropbear_rsa_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/dropbear/dropbear_dss_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/ssh_config [Typically tailored with things like allowing root logins via ssh]
etc/ssh_host_dsa_key [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_dsa_key.pub [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_key
etc/ssh_host_key.pub
etc/ssh_host_rsa_key
etc/ssh_host_rsa_key.pub
etc/sshd_config [Typically tailored with things like allowing root logins via ssh]
etc/rndc.key
etc/random-seed [Generated during 1st boot]
etc/passwd [Changed default user's shell to bash]
etc/shadow [Changed default and root users login password to 'linux1', need to ssh to the board]
exports/ [The path to where the board can mount extra file systems like /home/default.
fac/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]
fac/vol6/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]

Now lets assume your going to stay with these changes and modify them after taring in these changes.
Here we add the tar ball files to the boards root filesystem.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''tar xf /exports/default/'''

This is a good time to edit a few files on the boards file system
before boot it.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''vi etc/fstab''' [Change fstab entry for /home/default and others to your taste]
$ '''vi etc/init.d/S90local''' [You might want to disable mounting of NFS file systems on the 1st Boot and add this once you try it manually]

== Booting Linux for the 1st Time ==

We should now be ready to boot linux on your LX200. You have exported the root file-system and made the
kernel available to a TFTP server. Now let's start with hitting the reset button on the LX200 and it should
auto-boot the kernel, resulting in output such as [[HiFi2_Board_Example_Linux_Boot_Log|this]].

U-Boot 2009.08 (Nov 15 2009 - 22:03:26)

CPU: Xtensa test_mmuhifi_c3 at 41.6777 MHz
Board: XT-AV200: Avnet board + Xilinx LX200 FPGA + Tensilica bitstream
SysRAM: 96 MB
Flash: 16 MB
In: serial
Out: serial
Err: serial
MAC: 00:50:C2:13:6f:07
IP: 192.168.11.105
open_ethernet
Autobooting in 5 seconds, press <SPACE> to stop
Using open_ethernet device
TFTP from server 192.168.11.55; our IP address is 192.168.11.105
Filename 'uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'.
Load address: 0xd2000000
Loading: #################################################################
###############
done
Bytes transferred = 1161826 (11ba62 hex)
Automatic boot of image at addr 0xD2000000 ...
## Booting kernel from Legacy Image at d2000000 ...
Image Name: Linux-2.6.29-rc7
Image Type: Xtensa Linux Kernel Image (gzip compressed)
Data Size: 1161762 Bytes = 1.1 MB
Load Address: d0001000
Entry Point: d0001000
Verifying Checksum ... OK
Uncompressing Kernel Image ... OK

## Linux Boot Params Starting At Address:0xd5f50000
MEMORY: tag:0x1003, type:0X1000, start:0X0, end:0X6000000
COMMAND_LINE: tag:0x1001, size:188, data:'console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff'
SERIAL_BAUDRATE: tag:0x1004, size:4, baudrate:38400

## Transferring Control to Linux Kernel At Address 0xd0001000 ...

parse_bootparam: Ignoring tag 0x1004
lx60 platform_init(bootparams:d5f50000)
Linux version 2.6.29-rc7 (pdelaney@pdelaney_fc5.hq.tensilica.com) (gcc version 4.2.1) #201 SMP Tue Nov 17 23:49:39 PST 2009
lx60 platform_setup(cmdline[0]:'console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff')
smp_init_cpus: Core Count = 3
smp_init_cpus: Core Id = 9320
On node 0 totalpages: 24576
free_area_init_node: node 0, pgdat d0196540, node_mem_map d01fa000
Normal zone: 216 pages used for memmap
Normal zone: 24360 pages, LIFO batch:3
smp_prepare_boot_cpu:
Built 1 zonelists in Zone order, mobility grouping on. Total pages: 24360
Kernel command line: console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff
trap_init 0
PID hash table entries: 512 (order: 9, 2048 bytes)
time_init: Platform Calibrating CPU frequency
time_init: ccount_per_jiffy:416777 [41.67 MHz], nsec_per_ccount:23
Console: colour dummy device 80x25
console [ttyS0] enabled
Dentry cache hash table entries: 16384 (order: 4, 65536 bytes)
Inode-cache hash table entries: 8192 (order: 3, 32768 bytes)
Memory: 95196k/98304k available (1229k kernel code, 3040k reserved, 28k data, 72k init 0k highmem)
Calibrating delay loop... 41.26 BogoMIPS (lpj=206336)
Mount-cache hash table entries: 512
cpu 1 fffd
secondary_trap_init 1
Calibrating delay loop... 41.67 BogoMIPS (lpj=208384)
secondary_irq_init: set cached_irq_mask and enable interrupts))
secondary_time_init()
secondary_irq_enable(intrnum:6): cpu:1, INTENABLE:7c
secondary_irq_enable(intrnum:0): cpu:1, INTENABLE:7d
cpu 2 fff9
secondary_trap_init 2
Calibrating delay loop... 41.57 BogoMIPS (lpj=207872)
secondary_irq_init: set cached_irq_mask and enable interrupts))
secondary_time_init()
secondary_irq_enable(intrnum:6): cpu:2, INTENABLE:7c
secondary_irq_enable(intrnum:0): cpu:2, INTENABLE:7d
Brought up 3 CPUs
smp_cpus_done:
net_namespace: 304 bytes
NET: Registered protocol family 16
lx60_init()
bio: create slab <bio-0> at 0
NET: Registered protocol family 2
IP route cache hash table entries: 1024 (order: 0, 4096 bytes)
TCP established hash table entries: 4096 (order: 3, 32768 bytes)
TCP bind hash table entries: 4096 (order: 3, 32768 bytes)
TCP: Hash tables configured (established 4096 bind 4096)
TCP reno registered
NET: Registered protocol family 1
msgmni has been set to 186
alg: No test for md5 (md5-generic)
alg: No test for des (des-generic)
alg: No test for des3_ede (des3_ede-generic)
alg: No test for stdrng (krng)
io scheduler noop registered (default)
Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled
serial8250: ttyS0 at MMIO 0x0 (irq = 3) is a 16550A
oeth_probe: {
oeth_setup: Open Ethernet Core Version 1.0.1
: oeth_setup: Found id1:2000, id2:5c30 at phy_id:3.
: Hardware MAC Address: 00:50:c2:13:6f:0f
eth0 (): not using net_device_ops yet
oeth_probe: }
mice: PS/2 mouse device common for all mice
TCP cubic registered
NET: Registered protocol family 17
RPC: Registered udp transport module.
RPC: Registered tcp transport module.
oeth_open: Ready to process packets now on dev->name:'eth0', dev:d597d800;
IP-Config: Complete:
device=eth0, addr=192.168.11.105, mask=255.255.255.0, gw=192.168.11.1,
host="HiFi-2 Demo", domain=, nis-domain=(none),
bootserver=192.168.11.55, rootserver=192.168.11.55, rootpath=
Looking up port of RPC 100003/2 on 192.168.11.55
Looking up port of RPC 100005/1 on 192.168.11.55
VFS: Mounted root (nfs filesystem) on device 0:11.
Freeing unused kernel memory: 72k freed
Starting portmap: done
Initializing random number generator... done.
Starting network...
ip: RTNETLINK answers: File exists
Starting sshd: OK
Starting NFS statd: done
Starting NFS services: done
Starting NFS daemon: done
Starting NFS mountd: done
Starting domain name daemon: namedwarning: `named' uses 32-bit capabilities (legacy support in use)
failed
Fri Nov 20 17:10:37 2009
Mounting Other NFS Filesystems

Welcome to your custom Xtensa HiFi-2 Codec Developemnt System
hifi login: '''root'''
Password: '''linux1'''

== Tailoring your system prior to developing your codec ==

To make your experience more pleasant we suggest you tailor your environment.
Here are some of the changes that we have found helpful:

1. Add a root password to that you can login with ssh.
2. Run rdate with an ntp server on booting.
3. Add NFS mounts to /etc/fstab for your code and buildroot code.
4. Copy in previous ssh server encryption keys to /etc/dropbear to speed up your initial boot.
5. Mount a 'default' user home directory with:
a. Linux Test Suite pre-patch to test the system
b. Audio test example files
c. Copies of Mplayer and its Plug-ins from Buildroot modified slightly to make installation easy.
d. Misc audio test programs.

[TO BE DONE - Where to get 'default' user home directory tar ball and 1st boot patch]

== Compiling the Mplayer Plugins and linking them with MPEG-1 Audio Layer 3 (MP3) and MPEG-4 AAC Codecs ==

Mplayer is provided as an example environment for developing and testing Codecs and HiFi 2 software. There
are two ways to build Mplayer and the plug-in modules that use the codecs. The buildroot
tree (pulled with git) has a copy of mplayer and the plugins that can be built in the
snapshot via 'make menuconfig'. This is a good environment to use once codecs are
developed and debugged.

To facilitate development the mplayer packages can be copied to your NFS mounted development
environment. From there you can just configure mplayer to compile on the board and debug
mplayer and your codecs with gdb locally.

In the default user home directory we have a directory /home/default/buildroot_mplayer_stuff
with a copy of three of the mplayer packages:

[root@hifi buildroot_mplayer_stuff]# '''ls -l'''
drwxr-xr-x 34 root root 4096 Nov 10 05:01 MPlayer-1.0rc2/
drwxr-xr-x 4 root root 4096 Nov 10 01:36 mplayer_hifi2_aacplus_v2_plugin/
drwxr-xr-x 3 root root 4096 Nov 10 00:57 mplayer_hifi2_mp3_plugin/

they were simply copied from the buildroot-xtensa-HiFi2-Snapshot.2/package directory.

To get your development environment ready to compile the mplayer plug-ins you need
to configure Mplayer to use the local C compiler and linker:

# '''cd /home/default/buildroot_mplayer_stuff/MPlayer-1.0rc2/'''
# '''CFLAGS="-g3" ./configure'''

This will take about 15 minutes to configure. After that you can build the
plugins or mplayer. If you want to recompile mplayer it's likely best/necessary
to use the same args to .configure as used by buildroot:

.CFLAGS="-g3" ./configure \
--prefix=/usr \
--confdir=/etc/mplayer \
--with-extraincdir=/usr/include \
--with-extralibdir=/lib \
--disable-gui \
--enable-mad \
--enable-fbdev \
--disable-mencoder \
--disable-dvdnav \
--disable-dvdread \
--disable-dvdread-internal \
--disable-libdvdcss-internal \
--disable-big-endian \
--disable-nemesi \
--disable-tv \
--enable-dynamic-plugins

We are currently able to compile most of mplayer on the XL200 but
due to space limitations it's not possible to compile it -O0.

Now, lets focus on compiling linking the plugins. They are a nice
example of compiling a audio application on the LX200.

We modified the Makefile of the codes slightly, and will make it available.
These additions just instruct make how to install the plugins as explained
in the Chapter 7 of the Linux HiFi application note.

For example the mp3 plugin has this addition:

target_install::
-mkdir /etc/mplayer
cp codecs.conf /etc/mplayer
-mkdir /usr/lib/mplayer
cp ad_xa_mp3_dec.so /usr/lib/mplayer/
cp xa_mp3_dec.so /usr/lib/mplayer
chmod 755 /usr/lib/mplayer/ad_xa_mp3_dec.so
chmod 755 /usr/lib/mplayer/xa_mp3_dec.so

It's just providing a codec config file for mplayer at '''/etc/mplayer/codecs.conf''' and
copying the plug-in to '''/usr/lib/mplayer'''. To install the mp3 codec plugin and mplayer
config file just copy your codec that was compiled with '''xcc''' to the directory, compile it,
and install.

# '''cd /fac/vol6/audio/release/bin/l32r_LE5_pic'''
# '''cp xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz /tmp'''
#
# '''cd /home/default/buildroot_mplayer_stuff'''
# '''cd mplayer_hifi2_mp3_plugin'''
# '''cp /tmp/xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz .'''
# '''gunzip xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz'''
# '''tar xf xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tar'''
# '''make'''
# '''make target_install'''

The unpacking of the Tensilica mp3 codec tar ball will install the following files:

xa_mp3_dec/
xa_mp3_dec/README
xa_mp3_dec/include/
xa_mp3_dec/include/mp3_dec/
xa_mp3_dec/include/mp3_dec/xa_mp3_dec_api.h
xa_mp3_dec/include/xa_apicmd_standards.h
xa_mp3_dec/include/xa_error_handler.h
xa_mp3_dec/include/xa_error_standards.h
xa_mp3_dec/include/xa_memory_standards.h
xa_mp3_dec/include/xa_type_def.h
xa_mp3_dec/test/
xa_mp3_dec/test/build/
xa_mp3_dec/test/build/ldscript_stream_data.txt
xa_mp3_dec/test/build/makefile_testbench_sample
xa_mp3_dec/test/build/paramfilesimple.txt
xa_mp3_dec/test/include/
xa_mp3_dec/test/include/id3_tag_decode.h
xa_mp3_dec/test/src/
xa_mp3_dec/test/src/xa_mp3_dec_sample_testbench.c
xa_mp3_dec/test/src/id3_tag_decode.c
xa_mp3_dec/test/src/stream_data.c
xa_mp3_dec/test/src/xa_mp3_dec_error_handler.c
xa_mp3_dec/test/test_inp/
xa_mp3_dec/test/test_inp/compl.mp3
xa_mp3_dec/test/test_inp/hihat.mp3
xa_mp3_dec/test/test_out/
xa_mp3_dec/test/test_out/force_mkdir.txt
xa_mp3_dec/test/test_ref/
xa_mp3_dec/test/test_ref/compl_24bit.wav
xa_mp3_dec/test/test_ref/hihat_16bit.wav
xa_mp3_dec/lib/
xa_mp3_dec/lib/xa_mp3_dec.a
xa_mp3_dec/doc/
xa_mp3_dec/doc/HiFi2-MP3-DecoderProgrammersGuide.pdf

[TO BE DONE - Add missing C file, make clean deletes it!]

The xa_mp3_dec.a archive will be used by the Makefile in
the mplayer_hifi2_mp3_plugin directory to make the mplayer plug-in.
Section 6 of the '''Using Tensilica HiFi 2 Codec on Xtensa Linux with MPlayer'' Application Note
has a detailed description of the encapsulation process used by the plug-ins.

== Compiling Generic GPL Packages ==

For your development you may want to add a few GPL packages that you find helpfull.
This can be done on the LX200 just as you would on a normal workstation, thought
much slower. For example here we configure and build a few common GPL packages:

[[Building the Strace Package]]

[[Building the vim Package]]

== Compiling Tie Code with XCC ==

Codecs like MP3 and AAC have been written in C with TIE extensions and can only be compiled with '''xcc'''.
XCC is likely to large to run on the board without virtual memory. There are two approaches to compiling
Linux TIE code with '''xcc'''. The simple approach assumes the host workstation and target code running of the board
are similar enough that the library interfaces defined by the include files are compatable. This is often the
case for standard system calls, libc, and stdio.The proper approach uses a virtual core that we will create
that has built in references to the library and include files on the target code running on the LX200.

=== Simply using Xtensa Tools to compile the TIE code on a workstation ===

Below we illustrate compiling a simple audio test program on a workstation.
We start by referring to the XTENSA tools build by Xplorer, putting '''xcc''' into our search path and set the standard XTENSA_* environement variables.
For example:

setenv XTENSA_CORE test_mmuhifi_c3
setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config
setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin

setenv PATH ${XTENSA_TOOLS}:${PATH}

[piet@fc9desktop Tests] $ '''cd /exports/default/Audio_Tests''' [NOTE: This is being done on a Workstation]
[piet@fc9desktop Audio_Tests]$ '''xt-xcc -g3 -O0 -fPIC -c hifitest.c'''

Next we link the object on the XL200 board and run gdb on the TIE enhanced code:

[root@hifi Audio_Tests]# '''gcc -g hifitest.o -o hifitest'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:4640; Eatting cpu; time:0
cnt:0x0, pid:4640; Eating Tie; time:7
^C
[root@hifi Audio_Tests]# '''gdb ./hifitest''' [NOTE: This is being done on the LX200 board]
GNU gdb 6.6
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "xtensa_test_mmuhifi_c3-linux-uclibc"...
Using host libthread_db library "/lib/libthread_db.so.1".
(gdb) '''break main'''
Breakpoint 1 at 0x400401: file /exports/default/Audio_Tests/hifitest.c, line 20.
(gdb) '''run'''
Starting program: /home/default/Audio_Tests/hifitest

Breakpoint 1, main (argc=1, argv=0x3fb3fab4)
at /exports/default/Audio_Tests/hifitest.c:20
20 time_t time0 = time(NULL);
(gdb) '''step'''
21 time_t time1 = time(NULL);

=== Building Linux Applications Using Tensilica's XCC Compiler ===

Section 4.3 of the latest ''Xtensa OSKit Guide'' (from Tensilica's
RC-2009.0 release) describes how to setup XCC to compile Linux applications.
For details, see the guide.

A summary follows. The XTENSA_TOOLS_ROOT, XTENSA_ROOT, BUILDROOT_DIR, and TARGET_SYSROOT
environment variables must be set according to where things were installed;
values shown here are for illustration only. The CORENAME variable, set correctly
below for this board, reflects
the name of the core as known to open source tools (as opposed to XTENSA_CORE
which is the core name as known to Xtensa Tools; both happen to match here).

$ setenv XTENSA_ROOT /home/someuser/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
$ setenv XTENSA_TOOLS_ROOT /home/someuser/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools
$ setenv TARGET_SYSROOT /exports/LINUX_ROOT.HiFi-2
$ setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12

$ setenv CORENAME test_mmuhifi_c3

$ cd ${BUILDROOT_DIR}
$ ${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install \
--sysroot=./build_xtensa_${CORENAME}/staging_dir \
--linux-gcc=./build_xtensa_${CORENAME}/staging_dir/usr/bin/xtensa_${CORENAME}-linux-gcc

Assuming the above completes successfully, you can now build applications using Xtensa Tools. First set the usual environment variables:

$ setenv XTENSA_CORE default
$ setenv XTENSA_SYSTEM ${XTENSA_ROOT}-linux/config
$ setenv PATH ${XTENSA_TOOLS_ROOT}/bin:${PATH}

And build something:

$ echo '#include <stdio.h>' > hello.c
$ echo 'int main() {printf("Hello!\n");return 0;}' >> hello.c
$ xt-xcc -g hello.c -o hello

Then copy it where the target can see it:

$ cp hello ${TARGET_SYSROOT}/root

And run it on the target:

[root@hifi ~]# /root/hello

Here's a more interesting example that uses Tensilica TIE features.
(This cannot be compiled using GCC.)

$ cd ${TARGET_SYSROOT}/home/default/Audio_Tests
$ xt-xcc -g hifitest.c -o hifitest

In a ssh termulator window on the board you can now run hifitest:

[root@hifi ~]# '''cd /home/default/Audio_Tests/'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:23178; Eatting cpu; time:0 '''<control-C>'''

[root@hifi Audio_Tests]#

Here is the source code for the [[hifitest.c|hifitest.c source file]] used above.

== Adding your codec to Buildroot ==

Xtensa developers provide detailed instructions on building the root filesystem and the Linux kernel.
* [[Buildroot_Build_Instructions|Instructions for building and booting Linux (buildroot)]].

Building a comprehensive development environment with buildroot can be a chalanging experience and worthy of providing some tips on process.
Here are notes of the configs used for the three menuconfigs in this 2nd snapshot
provided with SMP additions:
$ '''make [[HiFi-2 snapshot_2 SMP Snapshot menuconfig | menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP uclibc-menuconfig | uclibc-menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP busybox-menuconfig | busybox-menuconfig]]'''

[TO BE DONE - making a new tar ball of saved files, building buildroot, ...]

== Known Problems being investigated, suggested that you know about and possibly avoid ==

1. Using NFS mounts with default parameters causes memory congestion. Use these mount options:

'''vers=2,rsize=4096,wsize=4096,hard,nointr,nolock,nolock,timeo=11,retrans=3,noauto'''

this is extremely important to add to your /etc/fstab on the target.

2. Can't swap over NFS yet, memory can get tight and cause application to be killed.
a. Trying procedure documented in U-Boot Manual.

3. Building the C development with X11 doesn't work with buildroot.

4. Though Mplayer plug-in can be compiled, Mplayer can be compiled but still has a few issues:
a. Can't be compiled -O0 due to limited memory while compiling one file,
b. Compiler infrequently crashes and make has to be restarted.
Not seeing this problem with root build on Fedore Core 9.
Perhaps this was caused by debug kernel or LTP using all of the memory.

5. U-boot has flash problems:
a. Sectors marked Read-Only come up Writeable after a reset/reboot.
b. Flashing a large number of sectors (like the kernel) sometimes
results in an Error (Ex: Vcc) and had to be retried.
c. Saw environment variables trashed on reset/reboot once.
It's possible that U-boot in flash could get whacked
and the board will need to be re-flashed. During a week
or two of testing I haven't see environment getting whacked.

6. gdb appears to be crashing on target when debugging
on latest root with uclibc left unstriped and with debug;
core dump sent to maxim.

7. U-Boot seems to hang periodically when loading the kernel with
tftp; appears to be worse when network activity is high.

8. 'top' command only shows all cpu's or cpu0; cpu 1 and 2 missing.

9. Program dore dump require ulimit -c to be set but root uses /bin/sh
which is a link to bash but causes it to skip running the bash
startup scripts. Changing root to /bin/bash seems to mess up
ssh logins.

10. For kernel to be compiled on the LX200 (for self checking:
a. Xtensa makefile needs to be fixed:
CC init/do_mounts.o
LD init/mounts.o
/bin/sh: xtensa_test_mmuhifi_c3-linux-uclibc-ld: command not found
make[1]: *** [init/mounts.o] Error 127

b. Need to add ncurses-devel package for 'make menuconfig'

11. Copying vim-7.2.tar from /home/default/src to /usr/local/src resulted
in a corrupt tar header. Apparently we have a NFS bug lurking in the kernel.
On server tar file looks like this:
vim72/000755 001750 001750 00000000000 11047345123 012000 5
ustar00moolmool000000 000000
vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0
ustar00moolmool000000 000000
README.txt for version 7.2 of Vim: Vi IMproved.

On the target/client it's different:
vim72/000755 001750 001750 00000000000 11047345123 012000 5ustar00moolmool000000 000000 vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0ustar00moolmool000000 000000 README.txt for version 7.2 of Vim: Vi IMproved.

=Further reading=

Main Xtensa Linux resources are:

* [http://linux-xtensa.org/ Linux/Xtensa Wiki]
* [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions Buildroot Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Kernel_Build_Instructions Kernel Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Setting_up_U-Boot Setting up U-Boot]
* [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List]
* http://git.linux-xtensa.org/cgi-bin/git.cgi GIT Repositories]

=Thanks to=

* piet
* marc
* dan

And the rest of the people in the Linux-Xtensa mailing list, if you cannot go through some of the steps, don't hesitate to ask on the mailing list, there's always somebody willing to help you!

SMP HiFi 2 Development Board

2009-12-02T04:00:05Z

Marc: /* Building Linux Applications Using Tensilica's XCC Compiler */ Remove sources now in separate page

This is the "communitee"" guide for how to use HiFi-2 Codec Development environment on an LX200 FPGA board.
If somethinig doesn't work ir isn't vovered in these guides, please feel free to ask at the [http://lists.linux-xtensa.org/mailman/listinfo Linux//Xtensa Mailing List]]

<div style="margin:0; margin-top:10px; margin-right:10px; border:1px solid #dfdfdf; padding:0 1em 1em 1em; background-color:#ffffcc; align:right; ">
'''NEWS:'''

Some general notes on these instructions:

* They are a work in progress.

* The following was tested on x86 machines running RedHat Fedora Core 5.

* Buildroot build with Fedora Core 9 also seems to be fine; perhaps better than when built on Fedore Core 5.

</div>

== Introduction ==

This document is addressed to someone who received an LX200 board setup by Tensilica
for HiFi2 codec development.

This document goes over the steps needed to set up the LX200 board for codec development.
To summarize:
* Setup the board. It likely comes with U-boot preinstalled, ready to boot a linux kernel.
* Install '''git'''.
* Download buildroot and linux kernel trees, pre-configured and built for HiFi-2 development.
* Setup a TFTP server to provide the linux kernel to U-Boot.
* Setup an NFS server to export a linux root file system.
* Setup the Linux kernel to boot from the root file system provided by the NFS server.
Once the development board is up and running, this document:
* Suggests a possible way to tailor the board for easy codec development.
* Shows how to add the Tensilica provided codec packages to the Mplayer packages used by Buildroot, including building and installing.
* Demonstrates two procedures for compiling, linking, and debugging codecs.

All development is expected to be done on a Linux host. (One can in principle use Windows to
develop target libraries. However, linking and subsequent steps need to be done in Linux.)

== Downloading the Latest HiFI-2 Buildroot and Kernel Snapshots ==

The HiFi-2 development environment is maintained in a source code version control system named 'git'. The '''git''' tools are useful when working with this development environment, though they are not strictly necessary. This document generally assumes the use of '''git''', which provides more opportunities for modifying this environment as needed (e.g. building more optional buildroot packages). But points out alternatives to allow getting up and running without having to set it up.

=== Installing git ===

To install '''git''', download a recent tarball from the [http://www.kernel.org/pub/software/scm/git/ official site]. For example, <tt>cd</tt> to a location with enough disk space, and do:

$ '''wget http://www.kernel.org/pub/software/scm/git/git-1.6.5.tar.gz'''

Unpack the tarball, and make and install it. Here we show how to install it to your ~/bin directory:

$ '''gunzip git-1.6.5.tar.gz'''
$ '''tar xf git-1.6.5.tar'''
$ '''cd git-1.6.5'''
$ '''make'''
$ '''make install'''

The git makefile can be instructed to install '''git''' to <tt>/usr/local/bin</tt> as root for system wide access:

$ '''cp git-1.6.5.tar.gz''' /tmp
$ '''su'''
Password:
# '''cd /usr/local/src/'''
# '''mkdir git'''
# '''cd git'''
# '''cp /tmp/git-1.6.5.tar.gz .'''
# '''gunzip git-1.6.5.tar.gz'''
# '''tar xf git-1.6.5.tar'''
# '''cd git-1.6.5'''
# '''make prefix=/usr/local'''
# '''make install'''

See the '''INSTALL'' instruction at the top of the git src directory for details.

Using '''git''' provides easy access to the binaries used to bring up the codec development environment, and leaves in place the infrastructure to modify and build this environment should you wish to. Any changes to '''git'''-managed source trees are easily observed with the '''git''' tools.

=== Installing the Buildroot Snapshot ===

''Note: The HiFi-2 snapshot is in the process of being made.''

To install the buildroot environment (toolchain and root filesystem), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot'''
$ '''cd buildroot-xtensa-HiFi2-Snapshot'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP''' [56 key strokes]
$ '''git checkout snapshot_2+SMP''' [28 key strokes]

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).

You can examine the tree (git repository) and its history visually using <tt>git gui</tt>.
The git GUI is a faster and more convenient method for checking out the HiFi-2 snapshot. To check out the snapshot_2+SMP branch simply run the command 'git gui' and then pull down the branch->create menu. Next select <>Match Tracking Branch Name and click on ''origin/snapshot_2+SMP''. Finally hit the Create Button.

$ '''git gui''''' [8 key strokes]
[Branch] -> Create... [2 key strokes]
<> Match Tracking Branch Name [1 key stroke]
<> Tracking Branch [1 key stroke]
origin/snapshot_2+SMP [1 key stroke]
[Create] [1 key stroke]
[Reposirory]--> Quit [2 key strokes]

If there are issues installing '''git''', as a last resort, an alternative is ftp (may not always get updated, is currenty our of date, waste disk space, so may be dropped at some point):

http://www.linux-xtensa.org/pub/snapshots/buildroot-xtensa-smp.2-Nov-2009.tar.gz

=== Installing the Linux Kernel Snapshot ===

To install the Linux kernel environment (kernel src, config, and HiFi-2 kernel U-Boot image), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp'''
$ '''cd kernel/xtensa-2.6.29-smp'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
$ '''git checkout snapshot_2+SMP'''

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).
As in the build root case, you can also do it from via git gui using the same proceedure
mantioned above.

Now, assuming we are still in the kernel '''xtensa-2.6.29-smp''' directory
copy the kernel U-Boot Image ('''uImage''') to the tftp directory; Ex:

$ '''cp arch/xtensa/boot/uImage /tftpboot/uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'''

NOTE: On some system, like Fedora Core 9, the tftpboot directory has been moved to /var/lib/tftpboot.
In this case we recomend that you just added a symbolic pointer from /etc to /var/lib/tftpboot:

$ '''su'''
# '''cd /etc'''
# '''/var/lib/tftpboot/ tftpboot'''
# '''ls -ld tftpboot'''
lrwxrwxrwx 1 root root 18 2009-11-23 21:14 tftpboot -> /var/lib/tftpboot/
#

== Setting up a TFTP Server to provide the Linux kernel to U-Boot ==

The TFTP service is part of the xinetd and is installed on Fedora workstations.
You can see that it's installed with the check config command which manages the
/etc/rc.d/init.d startup scripts and with the yum search command:

$ '''chkconfig --list'''
NetworkManager 0:off 1:off 2:off 3:off 4:off 5:off 6:off
NetworkManagerDispatcher 0:off 1:off 2:off 3:off 4:off 5:off 6:off
acpid 0:off 1:off 2:off 3:on 4:on 5:on 6:off
.
.
.
xfs 0:off 1:off 2:on 3:on 4:on 5:on 6:off
xinetd 0:off 1:off 2:off 3:on 4:on 5:on 6:off
ypbind 0:off 1:off 2:off 3:on 4:on 5:on 6:off
yum 0:off 1:off 2:off 3:off 4:off 5:off 6:off

xinetd based services:
amanda: off
auth: off
.
.
.
rsync: off
'''tftp: on''' [NOTE that tftp is enabled]
time: off
time-udp: off
uucp: off
$
$
$
$ '''yum search tftp-server'''
Loading "installonlyn" plugin
Searching Packages:
.
.
.
Reading repository metadata in from local files
.
.
.
'''tftp-server.i386 0.41-1.2.1 installed''' [NOTE that tftp server is installed as part of the inet daemon]
Matched from:
tftp-server
The Trivial File Transfer Protocol (TFTP) is normally used only for
booting diskless workstations. The tftp-server package provides the
server for TFTP, which allows users to transfer files to and from a
remote machine. TFTP provides very little security, and should not be
enabled unless it is expressly needed. The TFTP server is run from
/etc/xinetd.d/tftp, and is disabled by default on Red Hat Linux systems.
[piet@pdelaney_fc5 ~]$

TFTP is not normally enabled, to enable it just edit the file /etc/xinetd.d/tftp
and change the disable field to no:

# default: off
# description: The tftp server serves files using the trivial file transfer \
# protocol. The tftp protocol is often used to boot diskless \
# workstations, download configuration files to network-aware printers, \
# and to start the installation process for some operating systems.
service tftp
{
socket_type = dgram
protocol = udp
wait = yes
user = root
server = /usr/sbin/in.tftpd [NOTE: /var/lib/tftpboot on Fedora Core 9]
server_args = -s /tftpboot
'''disable = no'''
per_source = 11
cps = 100 2
flags = IPv4
}

== Setting up an NFS Server to export the Root Filesystem ==

The LX200 board running Linux needs to mount its root filesystem over NFS.
This filesystem was built using buildroot into a cpio format file,
and left in:

buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2/rootfs.xtensa_test_mmuhifi_c3.cpio

We will also be adding an additional minor changes to make your development environment more comfortable.

Pick a place on your workstation to export your root and unpack the cpio file into that directory.
For example here we will set up an export in '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''':

$ '''cd buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2'''
$ '''WHERE=$PWD'''
$ '''mkdir -p /exports/LINUX_ROOT.HiFi-2'''
$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''cpio -i < $WHERE/rootfs.xtensa_test_mmuhifi_c3.cpio'''

Next add a line to /etc/exports:

/exports *(rw,no_root_squash,sync,no_wdelay)

and restart you nfs services:

$ '''/etc/rc.d/init.d/nfs restart'''
or
$ '''/sbin/chkconfig nfs on'''

The showmount command should show your NFS file system now being exported:

$ '''showmount -e'''
Export list for mypc.foobar.com:
/exports *
$

== Configuring U-Boot to Boot Linux ==

Your LX200 board should have arrived with U-Boot installed in the flash ready to use.
The board has a DIP switch (next to the power on/off switch) that provides the 6 LSBs
of the Ethernet MAC, in switch positions 1 thru 6.

DIP Swithes for MAC: 1 2 3 4 5 6 7 8 ethaddr=00:50:C2:13:6f:0a
Little Endian: 0 1 0 1 0 0 * *
^
|
+------ Enables booting U-Boot from Flash

DIP switch 8 should be shipped in the ON position to enable U-Boot booting from flash.
See Sections 4.2.3 and 4.2.4 of the '''Tensilica Avnet (XT-AV200) Board User's Guide'''
for details. Make sure to select a unique MAC address for you board.

Next, connect a serial interface to a text based terminal emulation program,
set to 38400 bps, no parity, 1 stop bit, no handshaking.
For an example of setting [http://en.wikipedia.org/wiki/Minicom minicom]
for this, see [[minicom_xtboard_setup|here]].

Many users of this board are interested in developing codecs and/or HiFi 2 software and will prefer to just boot linux with the root file system we just described how to export on your NFS server. We will use git now to pull a snapshot of a performance 2.6.29 linux kernel and configure U-Boot to automatically boot it after a power cycle.

U-Boot> '''setenv serverip 192.168.11.55''' [TFTP server IP Address: RTOS-LAB2]
U-Boot> '''setenv nfsroot_server 192.168.11.55''' [Root NFS Servers IP Address: My Workstation]
U-Boot> '''setenv ipaddr 192.168.11.155''' [HOST IP address]
U-Boot> '''setenv bootfile uImage.xtensa-2.6.29-smp.test_mmuhifi_c3''' [File to fetch with TFTP and pass to bootm]
U-Boot> '''setenv root-path /exports/LINUX_ROOT.HiFi-2''' [WARNING: Limit path to < 50 characters]
U-Boot> '''setenv bootargs_using_bootp console=ttyS0,38400 ip=bootp root=nfs coredump_filter=0xff''' [Args passed to Linux while booting with BOOTP proto]
U-boot> '''setenv bootargs console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=${nfsroot_server}:${root-path}''' [Args passed to Linux while booting with DHCP proto]
U-boot> '''setenv bootcmd tftpboot\; bootm''' [Boot Linux after fetching it with TFTP]
U-Boot> '''setenv bootdelay 20''' [Delay 20 seconds before booting automaticaly]
U-Boot> '''setenv autostart yes''' [Boot automatically on power-up/reset]
U-Boot> '''saveenv'''
U-Boot>

'''[REMIND: Update the above procedure, show two or thee approaches (ip, dhcp, bootp)]'''

== Tailoring your system prior to Booting ==

There are a few tweaks that developers have found convenient to add to the the root file-system before booting.
As an initial environment for developing we suggest mounting a /home/default files-system that has number of
files useful for getting started. Find another place to tar in the tar ball with the default users file system.
We chose to include this close to the cpio file with the root file-system. Copy the tar bar to where you are
exporting you root file-system and next to it add the 'default' users file-system:

$ '''cd /export'''
$ '''cp /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.10/binaries/default.tar .'''
$ '''tar xf default.tar'''
$ '''cd default'''
$ '''ls'''
[TO BE ADDED]

Notice a file tar ball called '''saved_files.tar'''. This ia a tar file of files that
developers have found convenient to add and replace on the root file system after
adding a new buildroot file system. Here is a list of the files and a brief
explanation on why it's convenient to add or replace them:

root/.bash_profile [added 'ulimit -c unlimited to allow core dumps to be created]
root/.bashrc
etc/profile [added 'ulimit -c unlimited to allow core dumps to be created]
etc/fstab [Tells the system how to mount extra NFS file systems like /home/default]
etc/init.d/S90local [Mounts /home/default]
etc/resolv.conf [Location of DNS servers when your not using DHCP to boot the kernel]
etc/TZ [Your time zone, currently set to California TZ]
etc/dropbear/dropbear_rsa_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/dropbear/dropbear_dss_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/ssh_config [Typically tailored with things like allowing root logins via ssh]
etc/ssh_host_dsa_key [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_dsa_key.pub [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_key
etc/ssh_host_key.pub
etc/ssh_host_rsa_key
etc/ssh_host_rsa_key.pub
etc/sshd_config [Typically tailored with things like allowing root logins via ssh]
etc/rndc.key
etc/random-seed [Generated during 1st boot]
etc/passwd [Changed default user's shell to bash]
etc/shadow [Changed default and root users login password to 'linux1', need to ssh to the board]
exports/ [The path to where the board can mount extra file systems like /home/default.
fac/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]
fac/vol6/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]

Now lets assume your going to stay with these changes and modify them after taring in these changes.
Here we add the tar ball files to the boards root filesystem.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''tar xf /exports/default/'''

This is a good time to edit a few files on the boards file system
before boot it.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''vi etc/fstab''' [Change fstab entry for /home/default and others to your taste]
$ '''vi etc/init.d/S90local''' [You might want to disable mounting of NFS file systems on the 1st Boot and add this once you try it manually]

== Booting Linux for the 1st Time ==

We should now be ready to boot linux on your LX200. You have exported the root file-system and made the
kernel available to a TFTP server. Now lets start with hitting the reset button on the X200 and it should
auto-boot the kernel:

U-Boot 2009.08 (Nov 15 2009 - 22:03:26)

CPU: Xtensa test_mmuhifi_c3 at 41.6777 MHz
Board: XT-AV200: Avnet board + Xilinx LX200 FPGA + Tensilica bitstream
SysRAM: 96 MB
Flash: 16 MB
In: serial
Out: serial
Err: serial
MAC: 00:50:C2:13:6f:07
IP: 192.168.11.105
open_ethernet
Autobooting in 5 seconds, press <SPACE> to stop
Using open_ethernet device
TFTP from server 192.168.11.55; our IP address is 192.168.11.105
Filename 'uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'.
Load address: 0xd2000000
Loading: #################################################################
###############
done
Bytes transferred = 1161826 (11ba62 hex)
Automatic boot of image at addr 0xD2000000 ...
## Booting kernel from Legacy Image at d2000000 ...
Image Name: Linux-2.6.29-rc7
Image Type: Xtensa Linux Kernel Image (gzip compressed)
Data Size: 1161762 Bytes = 1.1 MB
Load Address: d0001000
Entry Point: d0001000
Verifying Checksum ... OK
Uncompressing Kernel Image ... OK

## Linux Boot Params Starting At Address:0xd5f50000
MEMORY: tag:0x1003, type:0X1000, start:0X0, end:0X6000000
COMMAND_LINE: tag:0x1001, size:188, data:'console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff'
SERIAL_BAUDRATE: tag:0x1004, size:4, baudrate:38400

## Transferring Control to Linux Kernel At Address 0xd0001000 ...

parse_bootparam: Ignoring tag 0x1004
lx60 platform_init(bootparams:d5f50000)
Linux version 2.6.29-rc7 (pdelaney@pdelaney_fc5.hq.tensilica.com) (gcc version 4.2.1) #201 SMP Tue Nov 17 23:49:39 PST 2009
lx60 platform_setup(cmdline[0]:'console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff')
smp_init_cpus: Core Count = 3
smp_init_cpus: Core Id = 9320
On node 0 totalpages: 24576
free_area_init_node: node 0, pgdat d0196540, node_mem_map d01fa000
Normal zone: 216 pages used for memmap
Normal zone: 24360 pages, LIFO batch:3
smp_prepare_boot_cpu:
Built 1 zonelists in Zone order, mobility grouping on. Total pages: 24360
Kernel command line: console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff
trap_init 0
PID hash table entries: 512 (order: 9, 2048 bytes)
time_init: Platform Calibrating CPU frequency
time_init: ccount_per_jiffy:416777 [41.67 MHz], nsec_per_ccount:23
Console: colour dummy device 80x25
console [ttyS0] enabled
Dentry cache hash table entries: 16384 (order: 4, 65536 bytes)
Inode-cache hash table entries: 8192 (order: 3, 32768 bytes)
Memory: 95196k/98304k available (1229k kernel code, 3040k reserved, 28k data, 72k init 0k highmem)
Calibrating delay loop... 41.26 BogoMIPS (lpj=206336)
Mount-cache hash table entries: 512
cpu 1 fffd
secondary_trap_init 1
Calibrating delay loop... 41.67 BogoMIPS (lpj=208384)
secondary_irq_init: set cached_irq_mask and enable interrupts))
secondary_time_init()
secondary_irq_enable(intrnum:6): cpu:1, INTENABLE:7c
secondary_irq_enable(intrnum:0): cpu:1, INTENABLE:7d
cpu 2 fff9
secondary_trap_init 2
Calibrating delay loop... 41.57 BogoMIPS (lpj=207872)
secondary_irq_init: set cached_irq_mask and enable interrupts))
secondary_time_init()
secondary_irq_enable(intrnum:6): cpu:2, INTENABLE:7c
secondary_irq_enable(intrnum:0): cpu:2, INTENABLE:7d
Brought up 3 CPUs
smp_cpus_done:
net_namespace: 304 bytes
NET: Registered protocol family 16
lx60_init()
bio: create slab <bio-0> at 0
NET: Registered protocol family 2
IP route cache hash table entries: 1024 (order: 0, 4096 bytes)
TCP established hash table entries: 4096 (order: 3, 32768 bytes)
TCP bind hash table entries: 4096 (order: 3, 32768 bytes)
TCP: Hash tables configured (established 4096 bind 4096)
TCP reno registered
NET: Registered protocol family 1
msgmni has been set to 186
alg: No test for md5 (md5-generic)
alg: No test for des (des-generic)
alg: No test for des3_ede (des3_ede-generic)
alg: No test for stdrng (krng)
io scheduler noop registered (default)
Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled
serial8250: ttyS0 at MMIO 0x0 (irq = 3) is a 16550A
oeth_probe: {
oeth_setup: Open Ethernet Core Version 1.0.1
: oeth_setup: Found id1:2000, id2:5c30 at phy_id:3.
: Hardware MAC Address: 00:50:c2:13:6f:0f
eth0 (): not using net_device_ops yet
oeth_probe: }
mice: PS/2 mouse device common for all mice
TCP cubic registered
NET: Registered protocol family 17
RPC: Registered udp transport module.
RPC: Registered tcp transport module.
oeth_open: Ready to process packets now on dev->name:'eth0', dev:d597d800;
IP-Config: Complete:
device=eth0, addr=192.168.11.105, mask=255.255.255.0, gw=192.168.11.1,
host="HiFi-2 Demo", domain=, nis-domain=(none),
bootserver=192.168.11.55, rootserver=192.168.11.55, rootpath=
Looking up port of RPC 100003/2 on 192.168.11.55
Looking up port of RPC 100005/1 on 192.168.11.55
VFS: Mounted root (nfs filesystem) on device 0:11.
Freeing unused kernel memory: 72k freed
Starting portmap: done
Initializing random number generator... done.
Starting network...
ip: RTNETLINK answers: File exists
Starting sshd: OK
Starting NFS statd: done
Starting NFS services: done
Starting NFS daemon: done
Starting NFS mountd: done
Starting domain name daemon: namedwarning: `named' uses 32-bit capabilities (legacy support in use)
failed
Fri Nov 20 17:10:37 2009
Mounting Other NFS Filesystems

Welcome to your custom Xtensa HiFi-2 Codec Developemnt System
hifi login: '''root'''
Password: '''linux1'''

== Tailoring your system prior to developing your codec ==

To make your experience more pleasant we suggest you tailor your environment.
Here are some of the changes that we have found helpful:

1. Add a root password to that you can login with ssh.
2. Run rdate with an ntp server on booting.
3. Add NFS mounts to /etc/fstab for your code and buildroot code.
4. Copy in previous ssh server encryption keys to /etc/dropbear to speed up your initial boot.
5. Mount a 'default' user home directory with:
a. Linux Test Suite pre-patch to test the system
b. Audio test example files
c. Copies of Mplayer and its Plug-ins from Buildroot modified slightly to make installation easy.
d. Misc audio test programs.

[TO BE DONE - Where to get 'default' user home directory tar ball and 1st boot patch]

== Compiling the Mplayer Plugins and linking them with MPEG-1 Audio Layer 3 (MP3) and MPEG-4 AAC Codecs ==

Mplayer is provided as an example environment for developing and testing Codecs and HiFi 2 software. There
are two ways to build Mplayer and the plug-in modules that use the codecs. The buildroot
tree (pulled with git) has a copy of mplayer and the plugins that can be built in the
snapshot via 'make menuconfig'. This is a good environment to use once codecs are
developed and debugged.

To facilitate development the mplayer packages can be copied to your NFS mounted development
environment. From there you can just configure mplayer to compile on the board and debug
mplayer and your codecs with gdb locally.

In the default user home directory we have a directory /home/default/buildroot_mplayer_stuff
with a copy of three of the mplayer packages:

[root@hifi buildroot_mplayer_stuff]# '''ls -l'''
drwxr-xr-x 34 root root 4096 Nov 10 05:01 MPlayer-1.0rc2/
drwxr-xr-x 4 root root 4096 Nov 10 01:36 mplayer_hifi2_aacplus_v2_plugin/
drwxr-xr-x 3 root root 4096 Nov 10 00:57 mplayer_hifi2_mp3_plugin/

they were simply copied from the buildroot-xtensa-HiFi2-Snapshot.2/package directory.

To get your development environment ready to compile the mplayer plug-ins you need
to configure Mplayer to use the local C compiler and linker:

# '''cd /home/default/buildroot_mplayer_stuff/MPlayer-1.0rc2/'''
# '''CFLAGS="-g3" ./configure'''

This will take about 15 minutes to configure. After that you can build the
plugins or mplayer. If you want to recompile mplayer it's likely best/necessary
to use the same args to .configure as used by buildroot:

.CFLAGS="-g3" ./configure \
--prefix=/usr \
--confdir=/etc/mplayer \
--with-extraincdir=/usr/include \
--with-extralibdir=/lib \
--disable-gui \
--enable-mad \
--enable-fbdev \
--disable-mencoder \
--disable-dvdnav \
--disable-dvdread \
--disable-dvdread-internal \
--disable-libdvdcss-internal \
--disable-big-endian \
--disable-nemesi \
--disable-tv \
--enable-dynamic-plugins

We are currently able to compile most of mplayer on the XL200 but
due to space limitations it's not possible to compile it -O0.

Now, lets focus on compiling linking the plugins. They are a nice
example of compiling a audio application on the LX200.

We modified the Makefile of the codes slightly, and will make it available.
These additions just instruct make how to install the plugins as explained
in the Chapter 7 of the Linux HiFi application note.

For example the mp3 plugin has this addition:

target_install::
-mkdir /etc/mplayer
cp codecs.conf /etc/mplayer
-mkdir /usr/lib/mplayer
cp ad_xa_mp3_dec.so /usr/lib/mplayer/
cp xa_mp3_dec.so /usr/lib/mplayer
chmod 755 /usr/lib/mplayer/ad_xa_mp3_dec.so
chmod 755 /usr/lib/mplayer/xa_mp3_dec.so

It's just providing a codec config file for mplayer at '''/etc/mplayer/codecs.conf''' and
copying the plug-in to '''/usr/lib/mplayer'''. To install the mp3 codec plugin and mplayer
config file just copy your codec that was compiled with '''xcc''' to the directory, compile it,
and install.

# '''cd /fac/vol6/audio/release/bin/l32r_LE5_pic'''
# '''cp xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz /tmp'''
#
# '''cd /home/default/buildroot_mplayer_stuff'''
# '''cd mplayer_hifi2_mp3_plugin'''
# '''cp /tmp/xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz .'''
# '''gunzip xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz'''
# '''tar xf xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tar'''
# '''make'''
# '''make target_install'''

The unpacking of the Tensilica mp3 codec tar ball will install the following files:

xa_mp3_dec/
xa_mp3_dec/README
xa_mp3_dec/include/
xa_mp3_dec/include/mp3_dec/
xa_mp3_dec/include/mp3_dec/xa_mp3_dec_api.h
xa_mp3_dec/include/xa_apicmd_standards.h
xa_mp3_dec/include/xa_error_handler.h
xa_mp3_dec/include/xa_error_standards.h
xa_mp3_dec/include/xa_memory_standards.h
xa_mp3_dec/include/xa_type_def.h
xa_mp3_dec/test/
xa_mp3_dec/test/build/
xa_mp3_dec/test/build/ldscript_stream_data.txt
xa_mp3_dec/test/build/makefile_testbench_sample
xa_mp3_dec/test/build/paramfilesimple.txt
xa_mp3_dec/test/include/
xa_mp3_dec/test/include/id3_tag_decode.h
xa_mp3_dec/test/src/
xa_mp3_dec/test/src/xa_mp3_dec_sample_testbench.c
xa_mp3_dec/test/src/id3_tag_decode.c
xa_mp3_dec/test/src/stream_data.c
xa_mp3_dec/test/src/xa_mp3_dec_error_handler.c
xa_mp3_dec/test/test_inp/
xa_mp3_dec/test/test_inp/compl.mp3
xa_mp3_dec/test/test_inp/hihat.mp3
xa_mp3_dec/test/test_out/
xa_mp3_dec/test/test_out/force_mkdir.txt
xa_mp3_dec/test/test_ref/
xa_mp3_dec/test/test_ref/compl_24bit.wav
xa_mp3_dec/test/test_ref/hihat_16bit.wav
xa_mp3_dec/lib/
xa_mp3_dec/lib/xa_mp3_dec.a
xa_mp3_dec/doc/
xa_mp3_dec/doc/HiFi2-MP3-DecoderProgrammersGuide.pdf

[TO BE DONE - Add missing C file, make clean deletes it!]

The xa_mp3_dec.a archive will be used by the Makefile in
the mplayer_hifi2_mp3_plugin directory to make the mplayer plug-in.
Section 6 of the '''Using Tensilica HiFi 2 Codec on Xtensa Linux with MPlayer'' Application Note
has a detailed description of the encapsulation process used by the plug-ins.

== Compiling Generic GPL Packages ==

For your development you may want to add a few GPL packages that you find helpfull.
This can be done on the LX200 just as you would on a normal workstation, thought
much slower. For example here we configure and build a few common GPL packages:

[[Building the Strace Package]]

[[Building the vim Package]]

== Compiling Tie Code with XCC ==

Codecs like MP3 and AAC have been written in C with TIE extensions and can only be compiled with '''xcc'''.
XCC is likely to large to run on the board without virtual memory. There are two approaches to compiling
Linux TIE code with '''xcc'''. The simple approach assumes the host workstation and target code running of the board
are similar enough that the library interfaces defined by the include files are compatable. This is often the
case for standard system calls, libc, and stdio.The proper approach uses a virtual core that we will create
that has built in references to the library and include files on the target code running on the LX200.

=== Simply using Xtensa Tools to compile the TIE code on a workstation ===

Below we illustrate compiling a simple audio test program on a workstation.
We start by referring to the XTENSA tools build by Xplorer, putting '''xcc''' into our search path and set the standard XTENSA_* environement variables.
For example:

setenv XTENSA_CORE test_mmuhifi_c3
setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config
setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin

setenv PATH ${XTENSA_TOOLS}:${PATH}

[piet@fc9desktop Tests] $ '''cd /exports/default/Audio_Tests''' [NOTE: This is being done on a Workstation]
[piet@fc9desktop Audio_Tests]$ '''xt-xcc -g3 -O0 -fPIC -c hifitest.c'''

Next we link the object on the XL200 board and run gdb on the TIE enhanced code:

[root@hifi Audio_Tests]# '''gcc -g hifitest.o -o hifitest'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:4640; Eatting cpu; time:0
cnt:0x0, pid:4640; Eating Tie; time:7
^C
[root@hifi Audio_Tests]# '''gdb ./hifitest''' [NOTE: This is being done on the LX200 board]
GNU gdb 6.6
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "xtensa_test_mmuhifi_c3-linux-uclibc"...
Using host libthread_db library "/lib/libthread_db.so.1".
(gdb) '''break main'''
Breakpoint 1 at 0x400401: file /exports/default/Audio_Tests/hifitest.c, line 20.
(gdb) '''run'''
Starting program: /home/default/Audio_Tests/hifitest

Breakpoint 1, main (argc=1, argv=0x3fb3fab4)
at /exports/default/Audio_Tests/hifitest.c:20
20 time_t time0 = time(NULL);
(gdb) '''step'''
21 time_t time1 = time(NULL);

=== Building Linux Applications Using Tensilica's XCC Compiler ===

Section 4.3 of the latest ''Xtensa OSKit Guide'' (from Tensilica's
RC-2009.0 release) describes how to setup XCC to compile Linux applications.
For details, see the guide.

A summary follows. The XTENSA_TOOLS_ROOT, XTENSA_ROOT, BUILDROOT_DIR, and TARGET_SYSROOT
environment variables must be set according to where things were installed;
values shown here are for illustration only. The CORENAME variable, set correctly
below for this board, reflects
the name of the core as known to open source tools (as opposed to XTENSA_CORE
which is the core name as known to Xtensa Tools; both happen to match here).

$ setenv XTENSA_ROOT /home/someuser/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
$ setenv XTENSA_TOOLS_ROOT /home/someuser/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools
$ setenv TARGET_SYSROOT /exports/LINUX_ROOT.HiFi-2
$ setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12

$ setenv CORENAME test_mmuhifi_c3

$ cd ${BUILDROOT_DIR}
$ ${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install \
--sysroot=./build_xtensa_${CORENAME}/staging_dir \
--linux-gcc=./build_xtensa_${CORENAME}/staging_dir/usr/bin/xtensa_${CORENAME}-linux-gcc

Assuming the above completes successfully, you can now build applications using Xtensa Tools. First set the usual environment variables:

$ setenv XTENSA_CORE default
$ setenv XTENSA_SYSTEM ${XTENSA_ROOT}-linux/config
$ setenv PATH ${XTENSA_TOOLS_ROOT}/bin:${PATH}

And build something:

$ echo '#include <stdio.h>' > hello.c
$ echo 'int main() {printf("Hello!\n");return 0;}' >> hello.c
$ xt-xcc -g hello.c -o hello

Then copy it where the target can see it:

$ cp hello ${TARGET_SYSROOT}/root

And run it on the target:

[root@hifi ~]# /root/hello

Here's a more interesting example that uses Tensilica TIE features.
(This cannot be compiled using GCC.)

$ cd ${TARGET_SYSROOT}/home/default/Audio_Tests
$ xt-xcc -g hifitest.c -o hifitest

In a ssh termulator window on the board you can now run hifitest:

[root@hifi ~]# '''cd /home/default/Audio_Tests/'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:23178; Eatting cpu; time:0 '''<control-C>'''

[root@hifi Audio_Tests]#

Here is the source code for the [[hifitest.c|hifitest.c source file]] used above.

== Adding your codec to Buildroot ==

Xtensa developers provide detailed instructions on building the root filesystem and the Linux kernel.
* [[Buildroot_Build_Instructions|Instructions for building and booting Linux (buildroot)]].

Building a comprehensive development environment with buildroot can be a chalanging experience and worthy of providing some tips on process.
Here are notes of the configs used for the three menuconfigs in this 2nd snapshot
provided with SMP additions:
$ '''make [[HiFi-2 snapshot_2 SMP Snapshot menuconfig | menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP uclibc-menuconfig | uclibc-menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP busybox-menuconfig | busybox-menuconfig]]'''

[TO BE DONE - making a new tar ball of saved files, building buildroot, ...]

== Known Problems being investigated, suggested that you know about and possibly avoid ==

1. Using NFS mounts with default parameters causes memory congestion. Use these mount options:

'''vers=2,rsize=4096,wsize=4096,hard,nointr,nolock,nolock,timeo=11,retrans=3,noauto'''

this is extremely important to add to your /etc/fstab on the target.

2. Can't swap over NFS yet, memory can get tight and cause application to be killed.
a. Trying procedure documented in U-Boot Manual.

3. Building the C development with X11 doesn't work with buildroot.

4. Though Mplayer plug-in can be compiled, Mplayer can be compiled but still has a few issues:
a. Can't be compiled -O0 due to limited memory while compiling one file,
b. Compiler infrequently crashes and make has to be restarted.
Not seeing this problem with root build on Fedore Core 9.
Perhaps this was caused by debug kernel or LTP using all of the memory.

5. U-boot has flash problems:
a. Sectors marked Read-Only come up Writeable after a reset/reboot.
b. Flashing a large number of sectors (like the kernel) sometimes
results in an Error (Ex: Vcc) and had to be retried.
c. Saw environment variables trashed on reset/reboot once.
It's possible that U-boot in flash could get whacked
and the board will need to be re-flashed. During a week
or two of testing I haven't see environment getting whacked.

6. gdb appears to be crashing on target when debugging
on latest root with uclibc left unstriped and with debug;
core dump sent to maxim.

7. U-Boot seems to hang periodically when loading the kernel with
tftp; appears to be worse when network activity is high.

8. 'top' command only shows all cpu's or cpu0; cpu 1 and 2 missing.

9. Program dore dump require ulimit -c to be set but root uses /bin/sh
which is a link to bash but causes it to skip running the bash
startup scripts. Changing root to /bin/bash seems to mess up
ssh logins.

10. For kernel to be compiled on the LX200 (for self checking:
a. Xtensa makefile needs to be fixed:
CC init/do_mounts.o
LD init/mounts.o
/bin/sh: xtensa_test_mmuhifi_c3-linux-uclibc-ld: command not found
make[1]: *** [init/mounts.o] Error 127

b. Need to add ncurses-devel package for 'make menuconfig'

11. Copying vim-7.2.tar from /home/default/src to /usr/local/src resulted
in a corrupt tar header. Apparently we have a NFS bug lurking in the kernel.
On server tar file looks like this:
vim72/000755 001750 001750 00000000000 11047345123 012000 5
ustar00moolmool000000 000000
vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0
ustar00moolmool000000 000000
README.txt for version 7.2 of Vim: Vi IMproved.

On the target/client it's different:
vim72/000755 001750 001750 00000000000 11047345123 012000 5ustar00moolmool000000 000000 vim72/README.txt000644 001750 001750 00000011342 11047324103 013472 0ustar00moolmool000000 000000 README.txt for version 7.2 of Vim: Vi IMproved.

=Further reading=

Main Xtensa Linux resources are:

* [http://linux-xtensa.org/ Linux/Xtensa Wiki]
* [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions Buildroot Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Kernel_Build_Instructions Kernel Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Setting_up_U-Boot Setting up U-Boot]
* [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List]
* http://git.linux-xtensa.org/cgi-bin/git.cgi GIT Repositories]

=Thanks to=

* piet
* marc
* dan

And the rest of the people in the Linux-Xtensa mailing list, if you cannot go through some of the steps, don't hesitate to ask on the mailing list, there's always somebody willing to help you!

Hifitest.c

2009-12-02T03:56:17Z

Marc: Example code in a separate page

#include <stdio.h>
#include <time.h>
#include <xtensa/tie/xt_hifi2.h>

#define INC 1

main(int argc, char **argv)
{
int inc;
int inc2;
register ae_p24x2s p24_cnt;
register ae_p24x2s p24_inc;
register ae_p24x2s p24_pid;
int cnt;
int cnt2;
int pid;
int pid2;
volatile int i, j, k, l;
time_t time0 = time(NULL);
time_t time1 = time(NULL);

restart:
cnt = 0;
cnt2 = 0;
inc = INC;
pid = getpid();
p24_cnt = AE_ZEROP48();
p24_inc = AE_MOVPA24(inc);
p24_pid = AE_MOVPA24(pid);

while (1)
{
int errors = 0;

if ((cnt & 0xffffff) == 0) {
time0 = time1;
time1 = time(NULL);
printf("cnt:0x%x, pid:%d; Eatting cpu; time:%ld\n", cnt, pid, (time1 - time0));
for(i = 0; i<1000; i++) {
for(j = 0; j < 1000; j++) {
for(k = 0; k < 10; k++) {
l++;
}
}
}
time0 = time1;
time1 = time(NULL);
printf("cnt:0x%x, pid:%d; Eating Tie; time:%ld\n", cnt, pid, (time1 - time0));
}
cnt = (cnt + inc) & 0xffffff;
p24_cnt = AE_ADDP24(p24_cnt, p24_inc);
cnt2 = AE_MOVAP24S_L(p24_cnt) & 0xffffff;
pid2 = AE_MOVAP24S_L(p24_pid) & 0xffffff;
inc2 = AE_MOVAP24S_L(p24_inc) & 0xffffff;

if (cnt2 != cnt)
{
swapon("/tmp/cmt2", 0);
printf("Error: cnt2:0x%x != cnt:0x%x\n", cnt2, cnt);
errors++;
}
if (inc2 != inc)
{
swapon("/tmp/inc2", 0);
printf("Error: inc2:%d != inc:%d\n", cnt2, cnt);
errors++;
}
if ( pid2 != pid)
{
swapon("/tmp/pid2", 0);
printf("Error: pid2:%d != pid:%d\n", pid2, pid);
errors++;
}

if (errors) {
printf("for...\n");
for(i=0; i < 0x3FFFF; i++)
j++;
printf("sleep 10\n");
sleep(10);
printf("for...\n");
for(i=0; i < 0x3FFFF; i++)
j++;
printf("restart\n");
goto restart;
}
}
}

SMP HiFi 2 Development Board

2009-12-01T22:02:02Z

Marc: /* Building Linux Applications Using Tensilica's XCC Compiler */ Remove odd comments, simplify

This is the "communitee"" guide for how to use HiFi-2 Codec Development environment on an LX200 FPGA board.
If somethinig doesn't work ir isn't vovered in these guides, please feel free to ask at the [http://lists.linux-xtensa.org/mailman/listinfo Linux//Xtensa Mailing List]]

<div style="margin:0; margin-top:10px; margin-right:10px; border:1px solid #dfdfdf; padding:0 1em 1em 1em; background-color:#ffffcc; align:right; ">
'''NEWS:'''

Some general notes on these instructions:

* They are a work in progress.

* The following was tested on x86 machines running RedHat Fedora Core 5.

* Buildroot build with Fedora Core 9 also seems to be fine; perhaps better than when built on Fedore Core 5.

</div>

== Introduction ==

This document is addressed to someone who received an LX200 board setup by Tensilica
for HiFi2 codec development.

This document goes over the steps needed to set up the LX200 board for codec development.
To summarize:
* Setup the board. It likely comes with U-boot preinstalled, ready to boot a linux kernel.
* Install '''git'''.
* Download buildroot and linux kernel trees, pre-configured and built for HiFi-2 development.
* Setup a TFTP server to provide the linux kernel to U-Boot.
* Setup an NFS server to export a linux root file system.
* Setup the Linux kernel to boot from the root file system provided by the NFS server.
Once the development board is up and running, this document:
* Suggests a possible way to tailor the board for easy codec development.
* Shows how to add the Tensilica provided codec packages to the Mplayer packages used by Buildroot, including building and installing.
* Demonstrates two procedures for compiling, linking, and debugging codecs.

All development is expected to be done on a Linux host. (One can in principle use Windows to
develop target libraries. However, linking and subsequent steps need to be done in Linux.)

== Downloading the Latest HiFI-2 Buildroot and Kernel Snapshots ==

The HiFi-2 development environment is maintained in a source code version control system named 'git'. The '''git''' tools are useful when working with this development environment, though they are not strictly necessary. This document generally assumes the use of '''git''', which provides more opportunities for modifying this environment as needed (e.g. building more optional buildroot packages). But points out alternatives to allow getting up and running without having to set it up.

=== Installing git ===

To install '''git''', download a recent tarball from the [http://www.kernel.org/pub/software/scm/git/ official site]. For example, <tt>cd</tt> to a location with enough disk space, and do:

$ '''wget http://www.kernel.org/pub/software/scm/git/git-1.6.5.tar.gz'''

Unpack the tarball, and make and install it. Here we show how to install it to your ~/bin directory:

$ '''gunzip git-1.6.5.tar.gz'''
$ '''tar xf git-1.6.5.tar'''
$ '''cd git-1.6.5'''
$ '''make'''
$ '''make install'''

The git makefile can be instructed to install '''git''' to <tt>/usr/local/bin</tt> as root for system wide access:

$ '''cp git-1.6.5.tar.gz''' /tmp
$ '''su'''
Password:
# '''cd /usr/local/src/'''
# '''mkdir git'''
# '''cd git'''
# '''cp /tmp/git-1.6.5.tar.gz .'''
# '''gunzip git-1.6.5.tar.gz'''
# '''tar xf git-1.6.5.tar'''
# '''cd git-1.6.5'''
# '''make prefix=/usr/local'''
# '''make install'''

See the '''INSTALL'' instruction at the top of the git src directory for details.

Using '''git''' provides easy access to the binaries used to bring up the codec development environment, and leaves in place the infrastructure to modify and build this environment should you wish to. Any changes to '''git'''-managed source trees are easily observed with the '''git''' tools.

=== Installing the Buildroot Snapshot ===

''Note: The HiFi-2 snapshot is in the process of being made.''

To install the buildroot environment (toolchain and root filesystem), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot'''
$ '''cd buildroot-xtensa-HiFi2-Snapshot'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP''' [56 key strokes]
$ '''git checkout snapshot_2+SMP''' [28 key strokes]

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).

You can examine the tree (git repository) and its history visually using <tt>git gui</tt>.
The git GUI is a faster and more convenient method for checking out the HiFi-2 snapshot. To check out the snapshot_2+SMP branch simply run the command 'git gui' and then pull down the branch->create menu. Next select <>Match Tracking Branch Name and click on ''origin/snapshot_2+SMP''. Finally hit the Create Button.

$ '''git gui''''' [8 key strokes]
[Branch] -> Create... [2 key strokes]
<> Match Tracking Branch Name [1 key stroke]
<> Tracking Branch [1 key stroke]
origin/snapshot_2+SMP [1 key stroke]
[Create] [1 key stroke]
[Reposirory]--> Quit [2 key strokes]

If there are issues installing '''git''', as a last resort, an alternative is ftp (may not always get updated, is currenty our of date, waste disk space, so may be dropped at some point):

http://www.linux-xtensa.org/pub/snapshots/buildroot-xtensa-smp.2-Nov-2009.tar.gz

=== Installing the Linux Kernel Snapshot ===

To install the Linux kernel environment (kernel src, config, and HiFi-2 kernel U-Boot image), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp'''
$ '''cd kernel/xtensa-2.6.29-smp'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
$ '''git checkout snapshot_2+SMP'''

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).
As in the build root case, you can also do it from via git gui using the same proceedure
mantioned above.

Now, assuming we are still in the kernel '''xtensa-2.6.29-smp''' directory
copy the kernel U-Boot Image ('''uImage''') to the tftp directory; Ex:

$ '''cp arch/xtensa/boot/uImage /tftpboot/uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'''

NOTE: On some system, like Fedora Core 9, the tftpboot directory has been moved to /var/lib/tftpboot.
In this case we recomend that you just added a symbolic pointer from /etc to /var/lib/tftpboot:

$ '''su'''
# '''cd /etc'''
# '''/var/lib/tftpboot/ tftpboot'''
# '''ls -ld tftpboot'''
lrwxrwxrwx 1 root root 18 2009-11-23 21:14 tftpboot -> /var/lib/tftpboot/
#

== Setting up a TFTP Server to provide the Linux kernel to U-Boot ==

The TFTP service is part of the xinetd and is installed on Fedora workstations.
You can see that it's installed with the check config command which manages the
/etc/rc.d/init.d startup scripts and with the yum search command:

$ '''chkconfig --list'''
NetworkManager 0:off 1:off 2:off 3:off 4:off 5:off 6:off
NetworkManagerDispatcher 0:off 1:off 2:off 3:off 4:off 5:off 6:off
acpid 0:off 1:off 2:off 3:on 4:on 5:on 6:off
.
.
.
xfs 0:off 1:off 2:on 3:on 4:on 5:on 6:off
xinetd 0:off 1:off 2:off 3:on 4:on 5:on 6:off
ypbind 0:off 1:off 2:off 3:on 4:on 5:on 6:off
yum 0:off 1:off 2:off 3:off 4:off 5:off 6:off

xinetd based services:
amanda: off
auth: off
.
.
.
rsync: off
'''tftp: on''' [NOTE that tftp is enabled]
time: off
time-udp: off
uucp: off
$
$
$
$ '''yum search tftp-server'''
Loading "installonlyn" plugin
Searching Packages:
.
.
.
Reading repository metadata in from local files
.
.
.
'''tftp-server.i386 0.41-1.2.1 installed''' [NOTE that tftp server is installed as part of the inet daemon]
Matched from:
tftp-server
The Trivial File Transfer Protocol (TFTP) is normally used only for
booting diskless workstations. The tftp-server package provides the
server for TFTP, which allows users to transfer files to and from a
remote machine. TFTP provides very little security, and should not be
enabled unless it is expressly needed. The TFTP server is run from
/etc/xinetd.d/tftp, and is disabled by default on Red Hat Linux systems.
[piet@pdelaney_fc5 ~]$

TFTP is not normally enabled, to enable it just edit the file /etc/xinetd.d/tftp
and change the disable field to no:

# default: off
# description: The tftp server serves files using the trivial file transfer \
# protocol. The tftp protocol is often used to boot diskless \
# workstations, download configuration files to network-aware printers, \
# and to start the installation process for some operating systems.
service tftp
{
socket_type = dgram
protocol = udp
wait = yes
user = root
server = /usr/sbin/in.tftpd [NOTE: /var/lib/tftpboot on Fedora Core 9]
server_args = -s /tftpboot
'''disable = no'''
per_source = 11
cps = 100 2
flags = IPv4
}

== Setting up an NFS Server to export the Root Filesystem ==

The LX200 board running Linux needs to mount its root filesystem over NFS.
This filesystem was built using buildroot into a cpio format file,
and left in:

buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2/rootfs.xtensa_test_mmuhifi_c3.cpio

We will also be adding an additional minor changes to make your development environment more comfortable.

Pick a place on your workstation to export your root and unpack the cpio file into that directory.
For example here we will set up an export in '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''':

$ '''cd buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2'''
$ '''WHERE=$PWD'''
$ '''mkdir -p /exports/LINUX_ROOT.HiFi-2'''
$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''cpio -i < $WHERE/rootfs.xtensa_test_mmuhifi_c3.cpio'''

Next add a line to /etc/exports:

/exports *(rw,no_root_squash,sync,no_wdelay)

and restart you nfs services:

$ '''/etc/rc.d/init.d/nfs restart'''
or
$ '''/sbin/chkconfig nfs on'''

The showmount command should show your NFS file system now being exported:

$ '''showmount -e'''
Export list for mypc.foobar.com:
/exports *
$

== Configuring U-Boot to Boot Linux ==

Your LX200 board should have arrived with U-Boot installed in the flash ready to use.
The board has a DIP switch (next to the power on/off switch) that provides the 6 LSBs
of the Ethernet MAC, in switch positions 1 thru 6.

DIP Swithes for MAC: 1 2 3 4 5 6 7 8 ethaddr=00:50:C2:13:6f:0a
Little Endian: 0 1 0 1 0 0 * *
^
|
+------ Enables booting U-Boot from Flash

DIP switch 8 should be shipped in the ON position to enable U-Boot booting from flash.
See Sections 4.2.3 and 4.2.4 of the '''Tensilica Avnet (XT-AV200) Board User's Guide'''
for details. Make sure to select a unique MAC address for you board.

Next, connect a serial interface to a text based terminal emulation program,
set to 38400 bps, no parity, 1 stop bit, no handshaking.
For an example of setting [http://en.wikipedia.org/wiki/Minicom minicom]
for this, see [[minicom_xtboard_setup|here]].

Many users of this board are interested in developing codecs and/or HiFi 2 software and will prefer to just boot linux with the root file system we just described how to export on your NFS server. We will use git now to pull a snapshot of a performance 2.6.29 linux kernel and configure U-Boot to automatically boot it after a power cycle.

U-Boot> '''setenv serverip 192.168.11.55''' [TFTP server IP Address: RTOS-LAB2]
U-Boot> '''setenv nfsroot_server 192.168.11.55''' [Root NFS Servers IP Address: My Workstation]
U-Boot> '''setenv ipaddr 192.168.11.155''' [HOST IP address]
U-Boot> '''setenv bootfile uImage.xtensa-2.6.29-smp.test_mmuhifi_c3''' [File to fetch with TFTP and pass to bootm]
U-Boot> '''setenv root-path /exports/LINUX_ROOT.HiFi-2''' [WARNING: Limit path to < 50 characters]
U-Boot> '''setenv bootargs_using_bootp console=ttyS0,38400 ip=bootp root=nfs coredump_filter=0xff''' [Args passed to Linux while booting with BOOTP proto]
U-boot> '''setenv bootargs console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=${nfsroot_server}:${root-path}''' [Args passed to Linux while booting with DHCP proto]
U-boot> '''setenv bootcmd tftpboot\; bootm''' [Boot Linux after fetching it with TFTP]
U-Boot> '''setenv bootdelay 20''' [Delay 20 seconds before booting automaticaly]
U-Boot> '''setenv autostart yes''' [Boot automatically on power-up/reset]
U-Boot> '''saveenv'''
U-Boot>

'''[REMIND: Update the above procedure, show two or thee approaches (ip, dhcp, bootp)]'''

== Tailoring your system prior to Booting ==

There are a few tweaks that developers have found convenient to add to the the root file-system before booting.
As an initial environment for developing we suggest mounting a /home/default files-system that has number of
files useful for getting started. Find another place to tar in the tar ball with the default users file system.
We chose to include this close to the cpio file with the root file-system. Copy the tar bar to where you are
exporting you root file-system and next to it add the 'default' users file-system:

$ '''cd /export'''
$ '''cp /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.10/binaries/default.tar .'''
$ '''tar xf default.tar'''
$ '''cd default'''
$ '''ls'''
[TO BE ADDED]

Notice a file tar ball called '''saved_files.tar'''. This ia a tar file of files that
developers have found convenient to add and replace on the root file system after
adding a new buildroot file system. Here is a list of the files and a brief
explanation on why it's convenient to add or replace them:

root/.bash_profile [added 'ulimit -c unlimited to allow core dumps to be created]
root/.bashrc
etc/profile [added 'ulimit -c unlimited to allow core dumps to be created]
etc/fstab [Tells the system how to mount extra NFS file systems like /home/default]
etc/init.d/S90local [Mounts /home/default]
etc/resolv.conf [Location of DNS servers when your not using DHCP to boot the kernel]
etc/TZ [Your time zone, currently set to California TZ]
etc/dropbear/dropbear_rsa_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/dropbear/dropbear_dss_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/ssh_config [Typically tailored with things like allowing root logins via ssh]
etc/ssh_host_dsa_key [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_dsa_key.pub [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_key
etc/ssh_host_key.pub
etc/ssh_host_rsa_key
etc/ssh_host_rsa_key.pub
etc/sshd_config [Typically tailored with things like allowing root logins via ssh]
etc/rndc.key
etc/random-seed [Generated during 1st boot]
etc/passwd [Changed default user's shell to bash]
etc/shadow [Changed default and root users login password to 'linux1', need to ssh to the board]
exports/ [The path to where the board can mount extra file systems like /home/default.
fac/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]
fac/vol6/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]

Now lets assume your going to stay with these changes and modify them after taring in these changes.
Here we add the tar ball files to the boards root filesystem.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''tar xf /exports/default/'''

This is a good time to edit a few files on the boards file system
before boot it.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''vi etc/fstab''' [Change fstab entry for /home/default and others to your taste]
$ '''vi etc/init.d/S90local''' [You might want to disable mounting of NFS file systems on the 1st Boot and add this once you try it manually]

== Booting Linux for the 1st Time ==

We should now be ready to boot linux on your LX200. You have exported the root file-system and made the
kernel available to a TFTP server. Now lets start with hitting the reset button on the X200 and it should
auto-boot the kernel:

U-Boot 2009.08 (Nov 15 2009 - 22:03:26)

CPU: Xtensa test_mmuhifi_c3 at 41.6777 MHz
Board: XT-AV200: Avnet board + Xilinx LX200 FPGA + Tensilica bitstream
SysRAM: 96 MB
Flash: 16 MB
In: serial
Out: serial
Err: serial
MAC: 00:50:C2:13:6f:07
IP: 192.168.11.105
open_ethernet
Autobooting in 5 seconds, press <SPACE> to stop
Using open_ethernet device
TFTP from server 192.168.11.55; our IP address is 192.168.11.105
Filename 'uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'.
Load address: 0xd2000000
Loading: #################################################################
###############
done
Bytes transferred = 1161826 (11ba62 hex)
Automatic boot of image at addr 0xD2000000 ...
## Booting kernel from Legacy Image at d2000000 ...
Image Name: Linux-2.6.29-rc7
Image Type: Xtensa Linux Kernel Image (gzip compressed)
Data Size: 1161762 Bytes = 1.1 MB
Load Address: d0001000
Entry Point: d0001000
Verifying Checksum ... OK
Uncompressing Kernel Image ... OK

## Linux Boot Params Starting At Address:0xd5f50000
MEMORY: tag:0x1003, type:0X1000, start:0X0, end:0X6000000
COMMAND_LINE: tag:0x1001, size:188, data:'console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff'
SERIAL_BAUDRATE: tag:0x1004, size:4, baudrate:38400

## Transferring Control to Linux Kernel At Address 0xd0001000 ...

parse_bootparam: Ignoring tag 0x1004
lx60 platform_init(bootparams:d5f50000)
Linux version 2.6.29-rc7 (pdelaney@pdelaney_fc5.hq.tensilica.com) (gcc version 4.2.1) #201 SMP Tue Nov 17 23:49:39 PST 2009
lx60 platform_setup(cmdline[0]:'console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff')
smp_init_cpus: Core Count = 3
smp_init_cpus: Core Id = 9320
On node 0 totalpages: 24576
free_area_init_node: node 0, pgdat d0196540, node_mem_map d01fa000
Normal zone: 216 pages used for memmap
Normal zone: 24360 pages, LIFO batch:3
smp_prepare_boot_cpu:
Built 1 zonelists in Zone order, mobility grouping on. Total pages: 24360
Kernel command line: console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff
trap_init 0
PID hash table entries: 512 (order: 9, 2048 bytes)
time_init: Platform Calibrating CPU frequency
time_init: ccount_per_jiffy:416777 [41.67 MHz], nsec_per_ccount:23
Console: colour dummy device 80x25
console [ttyS0] enabled
Dentry cache hash table entries: 16384 (order: 4, 65536 bytes)
Inode-cache hash table entries: 8192 (order: 3, 32768 bytes)
Memory: 95196k/98304k available (1229k kernel code, 3040k reserved, 28k data, 72k init 0k highmem)
Calibrating delay loop... 41.26 BogoMIPS (lpj=206336)
Mount-cache hash table entries: 512
cpu 1 fffd
secondary_trap_init 1
Calibrating delay loop... 41.67 BogoMIPS (lpj=208384)
secondary_irq_init: set cached_irq_mask and enable interrupts))
secondary_time_init()
secondary_irq_enable(intrnum:6): cpu:1, INTENABLE:7c
secondary_irq_enable(intrnum:0): cpu:1, INTENABLE:7d
cpu 2 fff9
secondary_trap_init 2
Calibrating delay loop... 41.57 BogoMIPS (lpj=207872)
secondary_irq_init: set cached_irq_mask and enable interrupts))
secondary_time_init()
secondary_irq_enable(intrnum:6): cpu:2, INTENABLE:7c
secondary_irq_enable(intrnum:0): cpu:2, INTENABLE:7d
Brought up 3 CPUs
smp_cpus_done:
net_namespace: 304 bytes
NET: Registered protocol family 16
lx60_init()
bio: create slab <bio-0> at 0
NET: Registered protocol family 2
IP route cache hash table entries: 1024 (order: 0, 4096 bytes)
TCP established hash table entries: 4096 (order: 3, 32768 bytes)
TCP bind hash table entries: 4096 (order: 3, 32768 bytes)
TCP: Hash tables configured (established 4096 bind 4096)
TCP reno registered
NET: Registered protocol family 1
msgmni has been set to 186
alg: No test for md5 (md5-generic)
alg: No test for des (des-generic)
alg: No test for des3_ede (des3_ede-generic)
alg: No test for stdrng (krng)
io scheduler noop registered (default)
Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled
serial8250: ttyS0 at MMIO 0x0 (irq = 3) is a 16550A
oeth_probe: {
oeth_setup: Open Ethernet Core Version 1.0.1
: oeth_setup: Found id1:2000, id2:5c30 at phy_id:3.
: Hardware MAC Address: 00:50:c2:13:6f:0f
eth0 (): not using net_device_ops yet
oeth_probe: }
mice: PS/2 mouse device common for all mice
TCP cubic registered
NET: Registered protocol family 17
RPC: Registered udp transport module.
RPC: Registered tcp transport module.
oeth_open: Ready to process packets now on dev->name:'eth0', dev:d597d800;
IP-Config: Complete:
device=eth0, addr=192.168.11.105, mask=255.255.255.0, gw=192.168.11.1,
host="HiFi-2 Demo", domain=, nis-domain=(none),
bootserver=192.168.11.55, rootserver=192.168.11.55, rootpath=
Looking up port of RPC 100003/2 on 192.168.11.55
Looking up port of RPC 100005/1 on 192.168.11.55
VFS: Mounted root (nfs filesystem) on device 0:11.
Freeing unused kernel memory: 72k freed
Starting portmap: done
Initializing random number generator... done.
Starting network...
ip: RTNETLINK answers: File exists
Starting sshd: OK
Starting NFS statd: done
Starting NFS services: done
Starting NFS daemon: done
Starting NFS mountd: done
Starting domain name daemon: namedwarning: `named' uses 32-bit capabilities (legacy support in use)
failed
Fri Nov 20 17:10:37 2009
Mounting Other NFS Filesystems

Welcome to your custom Xtensa HiFi-2 Codec Developemnt System
hifi login: '''root'''
Password: '''linux1'''

== Tailoring your system prior to developing your codec ==

To make your experience more pleasant we suggest you tailor your environment.
Here are some of the changes that we have found helpful:

1. Add a root password to that you can login with ssh.
2. Run rdate with an ntp server on booting.
3. Add NFS mounts to /etc/fstab for your code and buildroot code.
4. Copy in previous ssh server encryption keys to /etc/dropbear to speed up your initial boot.
5. Mount a 'default' user home directory with:
a. Linux Test Suite pre-patch to test the system
b. Audio test example files
c. Copies of Mplayer and its Plug-ins from Buildroot modified slightly to make installation easy.
d. Misc audio test programs.

[TO BE DONE - Where to get 'default' user home directory tar ball and 1st boot patch]

== Compiling the Mplayer Plugins and linking them with MPEG-1 Audio Layer 3 (MP3) and MPEG-4 AAC Codecs ==

Mplayer is provided as an example environment for developing and testing Codecs and HiFi 2 software. There
are two ways to build Mplayer and the plug-in modules that use the codecs. The buildroot
tree (pulled with git) has a copy of mplayer and the plugins that can be built in the
snapshot via 'make menuconfig'. This is a good environment to use once codecs are
developed and debugged.

To facilitate development the mplayer packages can be copied to your NFS mounted development
environment. From there you can just configure mplayer to compile on the board and debug
mplayer and your codecs with gdb locally.

In the default user home directory we have a directory /home/default/buildroot_mplayer_stuff
with a copy of three of the mplayer packages:

[root@hifi buildroot_mplayer_stuff]# '''ls -l'''
drwxr-xr-x 34 root root 4096 Nov 10 05:01 MPlayer-1.0rc2/
drwxr-xr-x 4 root root 4096 Nov 10 01:36 mplayer_hifi2_aacplus_v2_plugin/
drwxr-xr-x 3 root root 4096 Nov 10 00:57 mplayer_hifi2_mp3_plugin/

they were simply copied from the buildroot-xtensa-HiFi2-Snapshot.2/package directory.

To get your development environment ready to compile the mplayer plug-ins you need
to configure Mplayer to use the local C compiler and linker:

# '''cd /home/default/buildroot_mplayer_stuff/MPlayer-1.0rc2/'''
# '''CFLAGS="-g3" ./configure'''

This will take about 15 minutes to configure. After that you can build the
plugins or mplayer. If you want to recompile mplayer it's likely best/necessary
to use the same args to .configure as used by buildroot:

.CFLAGS="-g3" ./configure \
--prefix=/usr \
--confdir=/etc/mplayer \
--with-extraincdir=/usr/include \
--with-extralibdir=/lib \
--disable-gui \
--enable-mad \
--enable-fbdev \
--disable-mencoder \
--disable-dvdnav \
--disable-dvdread \
--disable-dvdread-internal \
--disable-libdvdcss-internal \
--disable-big-endian \
--disable-nemesi \
--disable-tv \
--enable-dynamic-plugins

We are currently able to compile most of mplayer on the XL200 but
due to space limitations it's not possible to compile it -O0.

Now, lets focus on compiling linking the plugins. They are a nice
example of compiling a audio application on the LX200.

We modified the Makefile of the codes slightly, and will make it available.
These additions just instruct make how to install the plugins as explained
in the Chapter 7 of the Linux HiFi application note.

For example the mp3 plugin has this addition:

target_install::
-mkdir /etc/mplayer
cp codecs.conf /etc/mplayer
-mkdir /usr/lib/mplayer
cp ad_xa_mp3_dec.so /usr/lib/mplayer/
cp xa_mp3_dec.so /usr/lib/mplayer
chmod 755 /usr/lib/mplayer/ad_xa_mp3_dec.so
chmod 755 /usr/lib/mplayer/xa_mp3_dec.so

It's just providing a codec config file for mplayer at '''/etc/mplayer/codecs.conf''' and
copying the plug-in to '''/usr/lib/mplayer'''. To install the mp3 codec plugin and mplayer
config file just copy your codec that was compiled with '''xcc''' to the directory, compile it,
and install.

# '''cd /fac/vol6/audio/release/bin/l32r_LE5_pic'''
# '''cp xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz /tmp'''
#
# '''cd /home/default/buildroot_mplayer_stuff'''
# '''cd mplayer_hifi2_mp3_plugin'''
# '''cp /tmp/xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz .'''
# '''gunzip xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz'''
# '''tar xf xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tar'''
# '''make'''
# '''make target_install'''

The unpacking of the Tensilica mp3 codec tar ball will install the following files:

xa_mp3_dec/
xa_mp3_dec/README
xa_mp3_dec/include/
xa_mp3_dec/include/mp3_dec/
xa_mp3_dec/include/mp3_dec/xa_mp3_dec_api.h
xa_mp3_dec/include/xa_apicmd_standards.h
xa_mp3_dec/include/xa_error_handler.h
xa_mp3_dec/include/xa_error_standards.h
xa_mp3_dec/include/xa_memory_standards.h
xa_mp3_dec/include/xa_type_def.h
xa_mp3_dec/test/
xa_mp3_dec/test/build/
xa_mp3_dec/test/build/ldscript_stream_data.txt
xa_mp3_dec/test/build/makefile_testbench_sample
xa_mp3_dec/test/build/paramfilesimple.txt
xa_mp3_dec/test/include/
xa_mp3_dec/test/include/id3_tag_decode.h
xa_mp3_dec/test/src/
xa_mp3_dec/test/src/xa_mp3_dec_sample_testbench.c
xa_mp3_dec/test/src/id3_tag_decode.c
xa_mp3_dec/test/src/stream_data.c
xa_mp3_dec/test/src/xa_mp3_dec_error_handler.c
xa_mp3_dec/test/test_inp/
xa_mp3_dec/test/test_inp/compl.mp3
xa_mp3_dec/test/test_inp/hihat.mp3
xa_mp3_dec/test/test_out/
xa_mp3_dec/test/test_out/force_mkdir.txt
xa_mp3_dec/test/test_ref/
xa_mp3_dec/test/test_ref/compl_24bit.wav
xa_mp3_dec/test/test_ref/hihat_16bit.wav
xa_mp3_dec/lib/
xa_mp3_dec/lib/xa_mp3_dec.a
xa_mp3_dec/doc/
xa_mp3_dec/doc/HiFi2-MP3-DecoderProgrammersGuide.pdf

[TO BE DONE - Add missing C file, make clean deletes it!]

The xa_mp3_dec.a archive will be used by the Makefile in
the mplayer_hifi2_mp3_plugin directory to make the mplayer plug-in.
Section 6 of the '''Using Tensilica HiFi 2 Codec on Xtensa Linux with MPlayer'' Application Note
has a detailed description of the encapsulation process used by the plug-ins.

== Compiling Generic GPL Packages ==

For your development you may want to add a few GPL packages that you find helpfull.
This can be done on the LX200 just as you would on a normal workstation, thought
much slower. For example here we configure and build the strace package:

[[Building the Strace Package]]

== Compiling Tie Code with XCC ==

Codecs like MP3 and AAC have been written in C with TIE extensions and can only be compiled with '''xcc'''.
XCC is likely to large to run on the board without virtual memory. There are two approaches to compiling
Linux TIE code with '''xcc'''. The simple approach assumes the host workstation and target code running of the board
are similar enough that the library interfaces defined by the include files are compatable. This is often the
case for standard system calls, libc, and stdio.The proper approach uses a virtual core that we will create
that has built in references to the library and include files on the target code running on the LX200.

=== Simply using Xtensa Tools to compile the TIE code on a workstation ===

Below we illustrate compiling a simple audio test program on a workstation.
We start by referring to the XTENSA tools build by Xplorer, putting '''xcc''' into our search path and set the standard XTENSA_* environement variables.
For example:

setenv XTENSA_CORE test_mmuhifi_c3
setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config
setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin

setenv PATH ${XTENSA_TOOLS}:${PATH}

[piet@fc9desktop Tests] $ '''cd /exports/default/Audio_Tests''' [NOTE: This is being done on a Workstation]
[piet@fc9desktop Audio_Tests]$ '''xt-xcc -g3 -O0 -fPIC -c hifitest.c'''

Next we link the object on the XL200 board and run gdb on the TIE enhanced code:

[root@hifi Audio_Tests]# '''gcc -g hifitest.o -o hifitest'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:4640; Eatting cpu; time:0
cnt:0x0, pid:4640; Eating Tie; time:7
^C
[root@hifi Audio_Tests]# '''gdb ./hifitest''' [NOTE: This is being done on the LX200 board]
GNU gdb 6.6
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "xtensa_test_mmuhifi_c3-linux-uclibc"...
Using host libthread_db library "/lib/libthread_db.so.1".
(gdb) '''break main'''
Breakpoint 1 at 0x400401: file /exports/default/Audio_Tests/hifitest.c, line 20.
(gdb) '''run'''
Starting program: /home/default/Audio_Tests/hifitest

Breakpoint 1, main (argc=1, argv=0x3fb3fab4)
at /exports/default/Audio_Tests/hifitest.c:20
20 time_t time0 = time(NULL);
(gdb) '''step'''
21 time_t time1 = time(NULL);

=== Building Linux Applications Using Tensilica's XCC Compiler ===

Section 4.3 of the latest ''Xtensa OSKit Guide'' (from Tensilica's
RC-2009.0 release) describes how to setup XCC to compile Linux applications.
For details, see the guide.

A summary follows. The XTENSA_TOOLS_ROOT, XTENSA_ROOT, BUILDROOT_DIR, and TARGET_SYSROOT
environment variables must be set according to where things were installed;
values shown here are for illustration only. The CORENAME variable, set correctly
below for this board, reflects
the name of the core as known to open source tools (as opposed to XTENSA_CORE
which is the core name as known to Xtensa Tools; both happen to match here).

$ setenv XTENSA_ROOT /home/someuser/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
$ setenv XTENSA_TOOLS_ROOT /home/someuser/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools
$ setenv TARGET_SYSROOT /exports/LINUX_ROOT.HiFi-2
$ setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12

$ setenv CORENAME test_mmuhifi_c3

$ cd ${BUILDROOT_DIR}
$ ${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install \
--sysroot=./build_xtensa_${CORENAME}/staging_dir \
--linux-gcc=./build_xtensa_${CORENAME}/staging_dir/usr/bin/xtensa_${CORENAME}-linux-gcc

Assuming the above completes successfully, you can now build applications using Xtensa Tools. First set the usual environment variables:

$ setenv XTENSA_CORE default
$ setenv XTENSA_SYSTEM ${XTENSA_ROOT}-linux/config
$ setenv PATH ${XTENSA_TOOLS_ROOT}/bin:${PATH}

And build something:

$ echo '#include <stdio.h>' > hello.c
$ echo 'int main() {printf("Hello!\n");return 0;}' >> hello.c
$ xt-xcc -g hello.c -o hello

Then copy it where the target can see it:

$ cp hello ${TARGET_SYSROOT}/root

And run it on the target:

[root@hifi ~]# /root/hello

Here's a more interesting example that uses Tensilica TIE features.
(This cannot be compiled using GCC.)

$ cd ${TARGET_SYSROOT}/home/default/Audio_Tests
$ xt-xcc -g hifitest.c -o hifitest

In a ssh termulator window on the board you can now run hifitest:

[root@hifi ~]# '''cd /home/default/Audio_Tests/'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:23178; Eatting cpu; time:0 '''<control-C>'''

[root@hifi Audio_Tests]#

Here is the code for the [[hifitest.c]] source file.

For example the /home/default/AUDIO_Tests/hifitest.c
used above in the core cloning example:

#include <stdio.h>
#include <time.h>
#include <xtensa/tie/xt_hifi2.h>

#define INC 1

main(int argc, char **argv)
{
int inc;
int inc2;
register ae_p24x2s p24_cnt;
register ae_p24x2s p24_inc;
register ae_p24x2s p24_pid;
int cnt;
int cnt2;
int pid;
int pid2;
volatile int i, j, k, l;
time_t time0 = time(NULL);
time_t time1 = time(NULL);

restart:
cnt = 0;
cnt2 = 0;
inc = INC;
pid = getpid();
p24_cnt = AE_ZEROP48();
p24_inc = AE_MOVPA24(inc);
p24_pid = AE_MOVPA24(pid);

while (1)
{
int errors = 0;

if ((cnt & 0xffffff) == 0) {
time0 = time1;
time1 = time(NULL);
printf("cnt:0x%x, pid:%d; Eatting cpu; time:%ld\n", cnt, pid, (time1 - time0));
for(i = 0; i<1000; i++) {
for(j = 0; j < 1000; j++) {
for(k = 0; k < 10; k++) {
l++;
}
}
}
time0 = time1;
time1 = time(NULL);
printf("cnt:0x%x, pid:%d; Eating Tie; time:%ld\n", cnt, pid, (time1 - time0));
}
cnt = (cnt + inc) & 0xffffff;
p24_cnt = AE_ADDP24(p24_cnt, p24_inc);
cnt2 = AE_MOVAP24S_L(p24_cnt) & 0xffffff;
pid2 = AE_MOVAP24S_L(p24_pid) & 0xffffff;
inc2 = AE_MOVAP24S_L(p24_inc) & 0xffffff;

if (cnt2 != cnt)
{
swapon("/tmp/cmt2", 0);
printf("Error: cnt2:0x%x != cnt:0x%x\n", cnt2, cnt);
errors++;
}
if (inc2 != inc)
{
swapon("/tmp/inc2", 0);
printf("Error: inc2:%d != inc:%d\n", cnt2, cnt);
errors++;
}
if ( pid2 != pid)
{
swapon("/tmp/pid2", 0);
printf("Error: pid2:%d != pid:%d\n", pid2, pid);
errors++;
}

if (errors) {
printf("for...\n");
for(i=0; i < 0x3FFFF; i++)
j++;
printf("sleep 10\n");
sleep(10);
printf("for...\n");
for(i=0; i < 0x3FFFF; i++)
j++;
printf("restart\n");
goto restart;
}
}
}
$

== Adding your codec to Buildroot ==

Xtensa developers provide detailed instructions on building the root filesystem and the Linux kernel.
* [[Buildroot_Build_Instructions|Instructions for building and booting Linux (buildroot)]].

Building a comprehensive development environment with buildroot can be a chalanging experience and worthy of providing some tips on process.
Here are notes of the configs used for the three menuconfigs in this 2nd snapshot
provided with SMP additions:
$ '''make [[HiFi-2 snapshot_2 SMP Snapshot menuconfig | menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP uclibc-menuconfig | uclibc-menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP busybox-menuconfig | busybox-menuconfig]]'''

[TO BE DONE - making a new tar ball of saved files, building buildroot, ...]

== Known Problems being investigated, suggested that you know about and possibly avoid ==

1. Using NFS mounts with default parameters causes memory congestion. Use these mount options:

'''vers=2,rsize=4096,wsize=4096,hard,nointr,nolock,nolock,timeo=11,retrans=3,noauto'''

this is extremely important to add to your /etc/fstab on the target.

2. Can't swap over NFS yet, memory can get tight and cause application to be killed.
a. Trying procedure documented in U-Boot Manual.

3. Building the C development with X11 doesn't work with buildroot.

4. Though Mplayer plug-in can be compiled, Mplayer can be compiled but still has a few issues:
a. Can't be compiled -O0 due to limited memory while compiling one file,
b. Compiler infrequently crashes and make has to be restarted.
Not seeing this problem with root build on Fedore Core 9.
Perhaps this was caused by debug kernel or LTP using all of the memory.

5. U-boot has flash problems:
a. Sectors marked Read-Only come up Writeable after a reset/reboot.
b. Flashing a large number of sectors (like the kernel) sometimes
results in an Error (Ex: Vcc) and had to be retried.
c. Saw environment variables trashed on reset/reboot once.
It's possible that U-boot in flash could get whacked
and the board will need to be re-flashed. During a week
or two of testing I haven't see environment getting whacked.

6. gdb appears to be crashing on target when debugging
on latest root with uclibc left unstriped and with debug;
core dump sent to maxim.

7. U-Boot seems to hang periodically when loading the kernel with
tftp; appears to be worse when network activity is high.

8. 'top' command only shows all cpu's or cpu0; cpu 1 and 2 missing.

9. Program dore dump require ulimit -c to be set but root uses /bin/sh
which is a link to bash but causes it to skip running the bash
startup scripts. Changing root to /bin/bash seems to mess up
ssh logins.

=Further reading=

Main Xtensa Linux resources are:

* [http://linux-xtensa.org/ Linux/Xtensa Wiki]
* [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions Buildroot Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Kernel_Build_Instructions Kernel Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Setting_up_U-Boot Setting up U-Boot]
* [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List]
* http://git.linux-xtensa.org/cgi-bin/git.cgi GIT Repositories]

=Thanks to=

* piet
* marc
* dan

And the rest of the people in the Linux-Xtensa mailing list, if you cannot go through some of the steps, don't hesitate to ask on the mailing list, there's always somebody willing to help you!

SMP HiFi 2 Development Board

2009-12-01T20:57:06Z

Marc: /* Configuring U-Boot to Boot Linux */ Minicom info moved to separate page

This is the "communitee"" guide for how to use HiFi-2 Codec Development environment on an LX200 FPGA board.
If somethinig doesn't work ir isn't vovered in these guides, please feel free to ask at the [http://lists.linux-xtensa.org/mailman/listinfo Linux//Xtensa Mailing List]]

<div style="margin:0; margin-top:10px; margin-right:10px; border:1px solid #dfdfdf; padding:0 1em 1em 1em; background-color:#ffffcc; align:right; ">
'''NEWS:'''

Some general notes on these instructions:

* They are a work in progress.

* The following was tested on x86 machines running RedHat Fedora Core 5.

* Buildroot build with Fedora Core 9 also seems to be fine; perhaps better than when built on Fedore Core 5.

</div>

== Introduction ==

This document is addressed to someone who received an LX200 board setup by Tensilica
for HiFi2 codec development.

This document goes over the steps needed to set up the LX200 board for codec development.
To summarize:
* Setup the board. It likely comes with U-boot preinstalled, ready to boot a linux kernel.
* Install '''git'''.
* Download buildroot and linux kernel trees, pre-configured and built for HiFi-2 development.
* Setup a TFTP server to provide the linux kernel to U-Boot.
* Setup an NFS server to export a linux root file system.
* Setup the Linux kernel to boot from the root file system provided by the NFS server.
Once the development board is up and running, this document:
* Suggests a possible way to tailor the board for easy codec development.
* Shows how to add the Tensilica provided codec packages to the Mplayer packages used by Buildroot, including building and installing.
* Demonstrates two procedures for compiling, linking, and debugging codecs.

All development is expected to be done on a Linux host. (One can in principle use Windows to
develop target libraries. However, linking and subsequent steps need to be done in Linux.)

== Downloading the Latest HiFI-2 Buildroot and Kernel Snapshots ==

The HiFi-2 development environment is maintained in a source code version control system named 'git'. The '''git''' tools are useful when working with this development environment, though they are not strictly necessary. This document generally assumes the use of '''git''', which provides more opportunities for modifying this environment as needed (e.g. building more optional buildroot packages). But points out alternatives to allow getting up and running without having to set it up.

=== Installing git ===

To install '''git''', download a recent tarball from the [http://www.kernel.org/pub/software/scm/git/ official site]. For example, <tt>cd</tt> to a location with enough disk space, and do:

$ '''wget http://www.kernel.org/pub/software/scm/git/git-1.6.5.tar.gz'''

Unpack the tarball, and make and install it. Here we show how to install it to your ~/bin directory:

$ '''gunzip git-1.6.5.tar.gz'''
$ '''tar xf git-1.6.5.tar'''
$ '''cd git-1.6.5'''
$ '''make'''
$ '''make install'''

The git makefile can be instructed to install '''git''' to <tt>/usr/local/bin</tt> as root for system wide access:

$ '''cp git-1.6.5.tar.gz''' /tmp
$ '''su'''
Password:
# '''cd /usr/local/src/'''
# '''mkdir git'''
# '''cd git'''
# '''cp /tmp/git-1.6.5.tar.gz .'''
# '''gunzip git-1.6.5.tar.gz'''
# '''tar xf git-1.6.5.tar'''
# '''cd git-1.6.5'''
# '''make prefix=/usr/local'''
# '''make install'''

See the '''INSTALL'' instruction at the top of the git src directory for details.

Using '''git''' provides easy access to the binaries used to bring up the codec development environment, and leaves in place the infrastructure to modify and build this environment should you wish to. Any changes to '''git'''-managed source trees are easily observed with the '''git''' tools.

=== Installing the Buildroot Snapshot ===

''Note: The HiFi-2 snapshot is in the process of being made.''

To install the buildroot environment (toolchain and root filesystem), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot'''
$ '''cd buildroot-xtensa-HiFi2-Snapshot'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP''' [56 key strokes]
$ '''git checkout snapshot_2+SMP''' [28 key strokes]

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).

You can examine the tree (git repository) and its history visually using <tt>git gui</tt>.
The git GUI is a faster and more convenient method for checking out the HiFi-2 snapshot. To check out the snapshot_2+SMP branch simply run the command 'git gui' and then pull down the branch->create menu. Next select <>Match Tracking Branch Name and click on ''origin/snapshot_2+SMP''. Finally hit the Create Button.

$ '''git gui''''' [8 key strokes]
[Branch] -> Create... [2 key strokes]
<> Match Tracking Branch Name [1 key stroke]
<> Tracking Branch [1 key stroke]
origin/snapshot_2+SMP [1 key stroke]
[Create] [1 key stroke]
[Reposirory]--> Quit [2 key strokes]

If there are issues installing '''git''', as a last resort, an alternative is ftp (may not always get updated, is currenty our of date, waste disk space, so may be dropped at some point):

http://www.linux-xtensa.org/pub/snapshots/buildroot-xtensa-smp.2-Nov-2009.tar.gz

=== Installing the Linux Kernel Snapshot ===

To install the Linux kernel environment (kernel src, config, and HiFi-2 kernel U-Boot image), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp'''
$ '''cd kernel/xtensa-2.6.29-smp'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
$ '''git checkout snapshot_2+SMP'''

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).
As in the build root case, you can also do it from via git gui using the same proceedure
mantioned above.

Now, assuming we are still in the kernel '''xtensa-2.6.29-smp''' directory
copy the kernel U-Boot Image ('''uImage''') to the tftp directory; Ex:

$ '''cp arch/xtensa/boot/uImage /tftpboot/uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'''

NOTE: On some system, like Fedora Core 9, the tftpboot directory has been moved to /var/lib/tftpboot.
In this case we recomend that you just added a symbolic pointer from /etc to /var/lib/tftpboot:

$ '''su'''
# '''cd /etc'''
# '''/var/lib/tftpboot/ tftpboot'''
# '''ls -ld tftpboot'''
lrwxrwxrwx 1 root root 18 2009-11-23 21:14 tftpboot -> /var/lib/tftpboot/
#

== Setting up a TFTP Server to provide the Linux kernel to U-Boot ==

The TFTP service is part of the xinetd and is installed on Fedora workstations.
You can see that it's installed with the check config command which manages the
/etc/rc.d/init.d startup scripts and with the yum search command:

$ '''chkconfig --list'''
NetworkManager 0:off 1:off 2:off 3:off 4:off 5:off 6:off
NetworkManagerDispatcher 0:off 1:off 2:off 3:off 4:off 5:off 6:off
acpid 0:off 1:off 2:off 3:on 4:on 5:on 6:off
.
.
.
xfs 0:off 1:off 2:on 3:on 4:on 5:on 6:off
xinetd 0:off 1:off 2:off 3:on 4:on 5:on 6:off
ypbind 0:off 1:off 2:off 3:on 4:on 5:on 6:off
yum 0:off 1:off 2:off 3:off 4:off 5:off 6:off

xinetd based services:
amanda: off
auth: off
.
.
.
rsync: off
'''tftp: on''' [NOTE that tftp is enabled]
time: off
time-udp: off
uucp: off
$
$
$
$ '''yum search tftp-server'''
Loading "installonlyn" plugin
Searching Packages:
.
.
.
Reading repository metadata in from local files
.
.
.
'''tftp-server.i386 0.41-1.2.1 installed''' [NOTE that tftp server is installed as part of the inet daemon]
Matched from:
tftp-server
The Trivial File Transfer Protocol (TFTP) is normally used only for
booting diskless workstations. The tftp-server package provides the
server for TFTP, which allows users to transfer files to and from a
remote machine. TFTP provides very little security, and should not be
enabled unless it is expressly needed. The TFTP server is run from
/etc/xinetd.d/tftp, and is disabled by default on Red Hat Linux systems.
[piet@pdelaney_fc5 ~]$

TFTP is not normally enabled, to enable it just edit the file /etc/xinetd.d/tftp
and change the disable field to no:

# default: off
# description: The tftp server serves files using the trivial file transfer \
# protocol. The tftp protocol is often used to boot diskless \
# workstations, download configuration files to network-aware printers, \
# and to start the installation process for some operating systems.
service tftp
{
socket_type = dgram
protocol = udp
wait = yes
user = root
server = /usr/sbin/in.tftpd [NOTE: /var/lib/tftpboot on Fedora Core 9]
server_args = -s /tftpboot
'''disable = no'''
per_source = 11
cps = 100 2
flags = IPv4
}

== Setting up an NFS Server to export the Root Filesystem ==

The LX200 board running Linux needs to mount its root filesystem over NFS.
This filesystem was built using buildroot into a cpio format file,
and left in:

buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2/rootfs.xtensa_test_mmuhifi_c3.cpio

We will also be adding an additional minor changes to make your development environment more comfortable.

Pick a place on your workstation to export your root and unpack the cpio file into that directory.
For example here we will set up an export in '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''':

$ '''cd buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2'''
$ '''WHERE=$PWD'''
$ '''mkdir -p /exports/LINUX_ROOT.HiFi-2'''
$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''cpio -i < $WHERE/rootfs.xtensa_test_mmuhifi_c3.cpio'''

Next add a line to /etc/exports:

/exports *(rw,no_root_squash,sync,no_wdelay)

and restart you nfs services:

$ '''/etc/rc.d/init.d/nfs restart'''
or
$ '''/sbin/chkconfig nfs on'''

The showmount command should show your NFS file system now being exported:

$ '''showmount -e'''
Export list for mypc.foobar.com:
/exports *
$

== Configuring U-Boot to Boot Linux ==

Your LX200 board should have arrived with U-Boot installed in the flash ready to use.
The board has a DIP switch (next to the power on/off switch) that provides the 6 LSBs
of the Ethernet MAC, in switch positions 1 thru 6.

DIP Swithes for MAC: 1 2 3 4 5 6 7 8 ethaddr=00:50:C2:13:6f:0a
Little Endian: 0 1 0 1 0 0 * *
^
|
+------ Enables booting U-Boot from Flash

DIP switch 8 should be shipped in the ON position to enable U-Boot booting from flash.
See Sections 4.2.3 and 4.2.4 of the '''Tensilica Avnet (XT-AV200) Board User's Guide'''
for details. Make sure to select a unique MAC address for you board.

Next, connect a serial interface to a text based terminal emulation program,
set to 38400 bps, no parity, 1 stop bit, no handshaking.
For an example of setting [http://en.wikipedia.org/wiki/Minicom minicom]
for this, see [[minicom_xtboard_setup|here]].

Many users of this board are interested in developing codecs and/or HiFi 2 software and will prefer to just boot linux with the root file system we just described how to export on your NFS server. We will use git now to pull a snapshot of a performance 2.6.29 linux kernel and configure U-Boot to automatically boot it after a power cycle.

U-Boot> '''setenv serverip 192.168.11.55''' [TFTP server IP Address: RTOS-LAB2]
U-Boot> '''setenv nfsroot_server 192.168.11.55''' [Root NFS Servers IP Address: My Workstation]
U-Boot> '''setenv ipaddr 192.168.11.155''' [HOST IP address]
U-Boot> '''setenv bootfile uImage.xtensa-2.6.29-smp.test_mmuhifi_c3''' [File to fetch with TFTP and pass to bootm]
U-Boot> '''setenv root-path /exports/LINUX_ROOT.HiFi-2''' [WARNING: Limit path to < 50 characters]
U-Boot> '''setenv bootargs_using_bootp console=ttyS0,38400 ip=bootp root=nfs coredump_filter=0xff''' [Args passed to Linux while booting with BOOTP proto]
U-boot> '''setenv bootargs console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=${nfsroot_server}:${root-path}''' [Args passed to Linux while booting with DHCP proto]
U-boot> '''setenv bootcmd tftpboot\; bootm''' [Boot Linux after fetching it with TFTP]
U-Boot> '''setenv bootdelay 20''' [Delay 20 seconds before booting automaticaly]
U-Boot> '''setenv autostart yes''' [Boot automatically on power-up/reset]
U-Boot> '''saveenv'''
U-Boot>

'''[REMIND: Update the above procedure, show two or thee approaches (ip, dhcp, bootp)]'''

== Tailoring your system prior to Booting ==

There are a few tweaks that developers have found convenient to add to the the root file-system before booting.
As an initial environment for developing we suggest mounting a /home/default files-system that has number of
files useful for getting started. Find another place to tar in the tar ball with the default users file system.
We chose to include this close to the cpio file with the root file-system. Copy the tar bar to where you are
exporting you root file-system and next to it add the 'default' users file-system:

$ '''cd /export'''
$ '''cp /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.10/binaries/default.tar .'''
$ '''tar xf default.tar'''
$ '''cd default'''
$ '''ls'''
[TO BE ADDED]

Notice a file tar ball called '''saved_files.tar'''. This ia a tar file of files that
developers have found convenient to add and replace on the root file system after
adding a new buildroot file system. Here is a list of the files and a brief
explanation on why it's convenient to add or replace them:

root/.bash_profile [added 'ulimit -c unlimited to allow core dumps to be created]
root/.bashrc
etc/profile [added 'ulimit -c unlimited to allow core dumps to be created]
etc/fstab [Tells the system how to mount extra NFS file systems like /home/default]
etc/init.d/S90local [Mounts /home/default]
etc/resolv.conf [Location of DNS servers when your not using DHCP to boot the kernel]
etc/TZ [Your time zone, currently set to California TZ]
etc/dropbear/dropbear_rsa_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/dropbear/dropbear_dss_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/ssh_config [Typically tailored with things like allowing root logins via ssh]
etc/ssh_host_dsa_key [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_dsa_key.pub [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_key
etc/ssh_host_key.pub
etc/ssh_host_rsa_key
etc/ssh_host_rsa_key.pub
etc/sshd_config [Typically tailored with things like allowing root logins via ssh]
etc/rndc.key
etc/random-seed [Generated during 1st boot]
etc/passwd [Changed default user's shell to bash]
etc/shadow [Changed default and root users login password to 'linux1', need to ssh to the board]
exports/ [The path to where the board can mount extra file systems like /home/default.
fac/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]
fac/vol6/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]

Now lets assume your going to stay with these changes and modify them after taring in these changes.
Here we add the tar ball files to the boards root filesystem.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''tar xf /exports/default/'''

This is a good time to edit a few files on the boards file system
before boot it.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''vi etc/fstab''' [Change fstab entry for /home/default and others to your taste]
$ '''vi etc/init.d/S90local''' [You might want to disable mounting of NFS file systems on the 1st Boot and add this once you try it manually]

== Booting Linux for the 1st Time ==

We should now be ready to boot linux on your LX200. You have exported the root file-system and made the
kernel available to a TFTP server. Now lets start with hitting the reset button on the X200 and it should
auto-boot the kernel:

U-Boot 2009.08 (Nov 15 2009 - 22:03:26)

CPU: Xtensa test_mmuhifi_c3 at 41.6777 MHz
Board: XT-AV200: Avnet board + Xilinx LX200 FPGA + Tensilica bitstream
SysRAM: 96 MB
Flash: 16 MB
In: serial
Out: serial
Err: serial
MAC: 00:50:C2:13:6f:07
IP: 192.168.11.105
open_ethernet
Autobooting in 5 seconds, press <SPACE> to stop
Using open_ethernet device
TFTP from server 192.168.11.55; our IP address is 192.168.11.105
Filename 'uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'.
Load address: 0xd2000000
Loading: #################################################################
###############
done
Bytes transferred = 1161826 (11ba62 hex)
Automatic boot of image at addr 0xD2000000 ...
## Booting kernel from Legacy Image at d2000000 ...
Image Name: Linux-2.6.29-rc7
Image Type: Xtensa Linux Kernel Image (gzip compressed)
Data Size: 1161762 Bytes = 1.1 MB
Load Address: d0001000
Entry Point: d0001000
Verifying Checksum ... OK
Uncompressing Kernel Image ... OK

## Linux Boot Params Starting At Address:0xd5f50000
MEMORY: tag:0x1003, type:0X1000, start:0X0, end:0X6000000
COMMAND_LINE: tag:0x1001, size:188, data:'console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff'
SERIAL_BAUDRATE: tag:0x1004, size:4, baudrate:38400

## Transferring Control to Linux Kernel At Address 0xd0001000 ...

parse_bootparam: Ignoring tag 0x1004
lx60 platform_init(bootparams:d5f50000)
Linux version 2.6.29-rc7 (pdelaney@pdelaney_fc5.hq.tensilica.com) (gcc version 4.2.1) #201 SMP Tue Nov 17 23:49:39 PST 2009
lx60 platform_setup(cmdline[0]:'console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff')
smp_init_cpus: Core Count = 3
smp_init_cpus: Core Id = 9320
On node 0 totalpages: 24576
free_area_init_node: node 0, pgdat d0196540, node_mem_map d01fa000
Normal zone: 216 pages used for memmap
Normal zone: 24360 pages, LIFO batch:3
smp_prepare_boot_cpu:
Built 1 zonelists in Zone order, mobility grouping on. Total pages: 24360
Kernel command line: console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff
trap_init 0
PID hash table entries: 512 (order: 9, 2048 bytes)
time_init: Platform Calibrating CPU frequency
time_init: ccount_per_jiffy:416777 [41.67 MHz], nsec_per_ccount:23
Console: colour dummy device 80x25
console [ttyS0] enabled
Dentry cache hash table entries: 16384 (order: 4, 65536 bytes)
Inode-cache hash table entries: 8192 (order: 3, 32768 bytes)
Memory: 95196k/98304k available (1229k kernel code, 3040k reserved, 28k data, 72k init 0k highmem)
Calibrating delay loop... 41.26 BogoMIPS (lpj=206336)
Mount-cache hash table entries: 512
cpu 1 fffd
secondary_trap_init 1
Calibrating delay loop... 41.67 BogoMIPS (lpj=208384)
secondary_irq_init: set cached_irq_mask and enable interrupts))
secondary_time_init()
secondary_irq_enable(intrnum:6): cpu:1, INTENABLE:7c
secondary_irq_enable(intrnum:0): cpu:1, INTENABLE:7d
cpu 2 fff9
secondary_trap_init 2
Calibrating delay loop... 41.57 BogoMIPS (lpj=207872)
secondary_irq_init: set cached_irq_mask and enable interrupts))
secondary_time_init()
secondary_irq_enable(intrnum:6): cpu:2, INTENABLE:7c
secondary_irq_enable(intrnum:0): cpu:2, INTENABLE:7d
Brought up 3 CPUs
smp_cpus_done:
net_namespace: 304 bytes
NET: Registered protocol family 16
lx60_init()
bio: create slab <bio-0> at 0
NET: Registered protocol family 2
IP route cache hash table entries: 1024 (order: 0, 4096 bytes)
TCP established hash table entries: 4096 (order: 3, 32768 bytes)
TCP bind hash table entries: 4096 (order: 3, 32768 bytes)
TCP: Hash tables configured (established 4096 bind 4096)
TCP reno registered
NET: Registered protocol family 1
msgmni has been set to 186
alg: No test for md5 (md5-generic)
alg: No test for des (des-generic)
alg: No test for des3_ede (des3_ede-generic)
alg: No test for stdrng (krng)
io scheduler noop registered (default)
Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled
serial8250: ttyS0 at MMIO 0x0 (irq = 3) is a 16550A
oeth_probe: {
oeth_setup: Open Ethernet Core Version 1.0.1
: oeth_setup: Found id1:2000, id2:5c30 at phy_id:3.
: Hardware MAC Address: 00:50:c2:13:6f:0f
eth0 (): not using net_device_ops yet
oeth_probe: }
mice: PS/2 mouse device common for all mice
TCP cubic registered
NET: Registered protocol family 17
RPC: Registered udp transport module.
RPC: Registered tcp transport module.
oeth_open: Ready to process packets now on dev->name:'eth0', dev:d597d800;
IP-Config: Complete:
device=eth0, addr=192.168.11.105, mask=255.255.255.0, gw=192.168.11.1,
host="HiFi-2 Demo", domain=, nis-domain=(none),
bootserver=192.168.11.55, rootserver=192.168.11.55, rootpath=
Looking up port of RPC 100003/2 on 192.168.11.55
Looking up port of RPC 100005/1 on 192.168.11.55
VFS: Mounted root (nfs filesystem) on device 0:11.
Freeing unused kernel memory: 72k freed
Starting portmap: done
Initializing random number generator... done.
Starting network...
ip: RTNETLINK answers: File exists
Starting sshd: OK
Starting NFS statd: done
Starting NFS services: done
Starting NFS daemon: done
Starting NFS mountd: done
Starting domain name daemon: namedwarning: `named' uses 32-bit capabilities (legacy support in use)
failed
Fri Nov 20 17:10:37 2009
Mounting Other NFS Filesystems

Welcome to your custom Xtensa HiFi-2 Codec Developemnt System
hifi login: '''root'''
Password: '''linux1'''

== Tailoring your system prior to developing your codec ==

To make your experience more pleasant we suggest you tailor your environment.
Here are some of the changes that we have found helpful:

1. Add a root password to that you can login with ssh.
2. Run rdate with an ntp server on booting.
3. Add NFS mounts to /etc/fstab for your code and buildroot code.
4. Copy in previous ssh server encryption keys to /etc/dropbear to speed up your initial boot.
5. Mount a 'default' user home directory with:
a. Linux Test Suite pre-patch to test the system
b. Audio test example files
c. Copies of Mplayer and its Plug-ins from Buildroot modified slightly to make installation easy.
d. Misc audio test programs.

[TO BE DONE - Where to get 'default' user home directory tar ball and 1st boot patch]

== Compiling the Mplayer Plugins and linking them with MPEG-1 Audio Layer 3 (MP3) and MPEG-4 AAC Codecs ==

Mplayer is provided as an example environment for developing and testing Codecs and HiFi 2 software. There
are two ways to build Mplayer and the plug-in modules that use the codecs. The buildroot
tree (pulled with git) has a copy of mplayer and the plugins that can be built in the
snapshot via 'make menuconfig'. This is a good environment to use once codecs are
developed and debugged.

To facilitate development the mplayer packages can be copied to your NFS mounted development
environment. From there you can just configure mplayer to compile on the board and debug
mplayer and your codecs with gdb locally.

In the default user home directory we have a directory /home/default/buildroot_mplayer_stuff
with a copy of three of the mplayer packages:

[root@hifi buildroot_mplayer_stuff]# '''ls -l'''
drwxr-xr-x 34 root root 4096 Nov 10 05:01 MPlayer-1.0rc2/
drwxr-xr-x 4 root root 4096 Nov 10 01:36 mplayer_hifi2_aacplus_v2_plugin/
drwxr-xr-x 3 root root 4096 Nov 10 00:57 mplayer_hifi2_mp3_plugin/

they were simply copied from the buildroot-xtensa-HiFi2-Snapshot.2/package directory.

To get your development environment ready to compile the mplayer plug-ins you need
to configure Mplayer to use the local C compiler and linker:

# '''cd /home/default/buildroot_mplayer_stuff/MPlayer-1.0rc2/'''
# '''CFLAGS="-g3" ./configure'''

This will take about 15 minutes to configure. After that you can build the
plugins or mplayer. If you want to recompile mplayer it's likely best/necessary
to use the same args to .configure as used by buildroot:

.CFLAGS="-g3" ./configure \
--prefix=/usr \
--confdir=/etc/mplayer \
--with-extraincdir=/usr/include \
--with-extralibdir=/lib \
--disable-gui \
--enable-mad \
--enable-fbdev \
--disable-mencoder \
--disable-dvdnav \
--disable-dvdread \
--disable-dvdread-internal \
--disable-libdvdcss-internal \
--disable-big-endian \
--disable-nemesi \
--disable-tv \
--enable-dynamic-plugins

We are currently able to compile most of mplayer on the XL200 but
due to space limitations it's not possible to compile it -O0.

Now, lets focus on compiling linking the plugins. They are a nice
example of compiling a audio application on the LX200.

We modified the Makefile of the codes slightly, and will make it available.
These additions just instruct make how to install the plugins as explained
in the Chapter 7 of the Linux HiFi application note.

For example the mp3 plugin has this addition:

target_install::
-mkdir /etc/mplayer
cp codecs.conf /etc/mplayer
-mkdir /usr/lib/mplayer
cp ad_xa_mp3_dec.so /usr/lib/mplayer/
cp xa_mp3_dec.so /usr/lib/mplayer
chmod 755 /usr/lib/mplayer/ad_xa_mp3_dec.so
chmod 755 /usr/lib/mplayer/xa_mp3_dec.so

It's just providing a codec config file for mplayer at '''/etc/mplayer/codecs.conf''' and
copying the plug-in to '''/usr/lib/mplayer'''. To install the mp3 codec plugin and mplayer
config file just copy your codec that was compiled with '''xcc''' to the directory, compile it,
and install.

# '''cd /fac/vol6/audio/release/bin/l32r_LE5_pic'''
# '''cp xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz /tmp'''
#
# '''cd /home/default/buildroot_mplayer_stuff'''
# '''cd mplayer_hifi2_mp3_plugin'''
# '''cp /tmp/xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz .'''
# '''gunzip xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz'''
# '''tar xf xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tar'''
# '''make'''
# '''make target_install'''

The unpacking of the Tensilica mp3 codec tar ball will install the following files:

xa_mp3_dec/
xa_mp3_dec/README
xa_mp3_dec/include/
xa_mp3_dec/include/mp3_dec/
xa_mp3_dec/include/mp3_dec/xa_mp3_dec_api.h
xa_mp3_dec/include/xa_apicmd_standards.h
xa_mp3_dec/include/xa_error_handler.h
xa_mp3_dec/include/xa_error_standards.h
xa_mp3_dec/include/xa_memory_standards.h
xa_mp3_dec/include/xa_type_def.h
xa_mp3_dec/test/
xa_mp3_dec/test/build/
xa_mp3_dec/test/build/ldscript_stream_data.txt
xa_mp3_dec/test/build/makefile_testbench_sample
xa_mp3_dec/test/build/paramfilesimple.txt
xa_mp3_dec/test/include/
xa_mp3_dec/test/include/id3_tag_decode.h
xa_mp3_dec/test/src/
xa_mp3_dec/test/src/xa_mp3_dec_sample_testbench.c
xa_mp3_dec/test/src/id3_tag_decode.c
xa_mp3_dec/test/src/stream_data.c
xa_mp3_dec/test/src/xa_mp3_dec_error_handler.c
xa_mp3_dec/test/test_inp/
xa_mp3_dec/test/test_inp/compl.mp3
xa_mp3_dec/test/test_inp/hihat.mp3
xa_mp3_dec/test/test_out/
xa_mp3_dec/test/test_out/force_mkdir.txt
xa_mp3_dec/test/test_ref/
xa_mp3_dec/test/test_ref/compl_24bit.wav
xa_mp3_dec/test/test_ref/hihat_16bit.wav
xa_mp3_dec/lib/
xa_mp3_dec/lib/xa_mp3_dec.a
xa_mp3_dec/doc/
xa_mp3_dec/doc/HiFi2-MP3-DecoderProgrammersGuide.pdf

[TO BE DONE - Add missing C file, make clean deletes it!]

The xa_mp3_dec.a archive will be used by the Makefile in
the mplayer_hifi2_mp3_plugin directory to make the mplayer plug-in.
Section 6 of the '''Using Tensilica HiFi 2 Codec on Xtensa Linux with MPlayer'' Application Note
has a detailed description of the encapsulation process used by the plug-ins.

== Compiling Generic GPL Packages ==

For your development you may want to add a few GPL packages that you find helpfull.
This can be done on the LX200 just as you would on a normal workstation, thought
much slower. For example here we configure and build the strace package:

[[Building the Strace Package]]

== Compiling Tie Code with XCC ==

Codecs like MP3 and AAC have been written in C with TIE extensions and can only be compiled with '''xcc'''.
XCC is likely to large to run on the board without virtual memory. There are two approaches to compiling
Linux TIE code with '''xcc'''. The simple approach assumes the host workstation and target code running of the board
are similar enough that the library interfaces defined by the include files are compatable. This is often the
case for standard system calls, libc, and stdio.The proper approach uses a virtual core that we will create
that has built in references to the library and include files on the target code running on the LX200.

=== Simply using Xtensa Tools to compile the TIE code on a workstation ===

Below we illustrate compiling a simple audio test program on a workstation.
We start by referring to the XTENSA tools build by Xplorer, putting '''xcc''' into our search path and set the standard XTENSA_* environement variables.
For example:

setenv XTENSA_CORE test_mmuhifi_c3
setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config
setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin

setenv PATH ${XTENSA_TOOLS}:${PATH}

[piet@fc9desktop Tests] $ '''cd /exports/default/Audio_Tests''' [NOTE: This is being done on a Workstation]
[piet@fc9desktop Audio_Tests]$ '''xt-xcc -g3 -O0 -fPIC -c hifitest.c'''

Next we link the object on the XL200 board and run gdb on the TIE enhanced code:

[root@hifi Audio_Tests]# '''gcc -g hifitest.o -o hifitest'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:4640; Eatting cpu; time:0
cnt:0x0, pid:4640; Eating Tie; time:7
^C
[root@hifi Audio_Tests]# '''gdb ./hifitest''' [NOTE: This is being done on the LX200 board]
GNU gdb 6.6
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "xtensa_test_mmuhifi_c3-linux-uclibc"...
Using host libthread_db library "/lib/libthread_db.so.1".
(gdb) '''break main'''
Breakpoint 1 at 0x400401: file /exports/default/Audio_Tests/hifitest.c, line 20.
(gdb) '''run'''
Starting program: /home/default/Audio_Tests/hifitest

Breakpoint 1, main (argc=1, argv=0x3fb3fab4)
at /exports/default/Audio_Tests/hifitest.c:20
20 time_t time0 = time(NULL);
(gdb) '''step'''
21 time_t time1 = time(NULL);

=== The Proper Approach of Building TIE code for Linux Targets ===

In section 4.3 of the '''Xtensa OSKit Guide''' there is a detailed description
of this intense procedure of building target binaries. As the founding father
of Java, Jim Gosling,
once wrote, '''"Not for Pregnant Woman or men with weak hearts"'''. This proceedure
depends on a number of packages to be right, like versions of Xprorer and '''gcc'''.
When it works it's much faster than compiling on the target.

A summary of the procedure is available from the --help message of the
install script that set up a cloned core.

[piet@fc9desktop test_mmuhifi_c3]$ '''${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install --help'''

Usage:
<fullpath>/xt-xcc-linux-install --sysroot=<target_sysroot>
[--clone-core=<corename>]
[--clone-root=<rootdir>]
[--clone-registry=<registrydir>]
[--c-include=<dir>]
[--cxx-include=<dir>]
[--lib-include=<dir>]
[--linux-gcc=<path_to_target_gcc>]
[--help]

--sysroot=<target_sysroot>
Specify the target sysroot directory, the root of a tree containing
target header files and libraries for use by the compiler. Although
this can be the target filesystem as it appears on the host (for
targets supporting native development), it is typically a different
but similarly structured tree (for cross-development). Xtensa Tools
look for target headers in <target_sysroot>/usr/include, and for
target libraries in <target_sysroot>/lib and <target_sysroot>/usr/lib.
There is no default and this directory must be specified.

[--c-include=<dir>]
Specify an additional directory for the default C header search path.

[--cxx-include=<dir>]
Specify an additional directory for the default C++ header search path.

[--lib-include=<dir>]
Specify an extra dir. for the default library+startfile search path.

[--linux-gcc=<path_to_target_gcc>]
Specify the path to a host GCC targeting the Xtensa Linux system,
which this script invokes to obtain additional lists of include
directories for C headers, C++ headers, and libraries.
This is often a convenient shorthand to specifying multiple
--c-include , --cxx-include, and --lib-include options.

[--clone-core=<corename>]
Name of the clone core to install. If omitted, the default is
the original core name specified in the Xtensa Processor
Generator with '-linux' appended to the name.

[--clone-root=<rootdir>]
Specify the directory where the clone core package will be
installed. If omitted, the default is a path derived by replacing
the leaf directory of the original core package, <xtensa_root>,
with the name of the clone core.

[--clone-registry=<registrydir>]
Specify the Xtensa core registry in which to register the new
clone core name. If omitted, the default core registry is
used, located in Xtensa Tools at <xtensa_tools_root>/config.

[--help]
Display this message and exit without installing anything.

This installer clones its containing Xtensa core package (using symlinks),
and modifies the clone to make XCC build applications that run on Linux.
For this to work, XCC must select this clone core name, and use the default
Xtensa Linker Support Package (that is, avoid the -mlsp parameter).

The installer registers the new clone core in the specified Xtensa core
registry. The clone core can be selected using either the XTENSA_CORE
environment variable or the --xtensa-core=<corename> parameter to run
xt-xcc (the XCC C/C++ compiler) and other Xtensa Tools.

[piet@fc9desktop test_mmuhifi_c3]$

Below illustrates using this '''core cloning''' procedure:

$ '''setenv XTENSA_CORE test_mmuhifi_c3'''
$ '''setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3'''
$ '''setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config'''
$ '''setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin'''

$ '''setenv PATH ${XTENSA_TOOLS}:${PATH}'''

$ '''setenv TARGET_SYSROOT /exports/LINUX_ROOT.HiFi-2'''
$ '''setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12'''

$ '''${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install \'''
'''--sysroot=${BUILDROOT_DIR}/build_xtensa_${XTENSA_CORE}/staging_dir \'''
'''--clone-core=test_mmuhifi_c3-linux-clone \'''
'''--linux-gcc=${BUILDROOT_DIR}/build_xtensa_${XTENSA_CORE}/staging_dir/usr/bin/xtensa_test_mmuhifi_c3-linux-gcc''' [NOTE: Maxim used this for some reason on the C++ problem]

The [[Normal Core Cloning Proceedure Output]] will have details on how to change your environment variables to
use the new cloned core:

************************************************************
* Installation Complete.
************************************************************
To build Linux applications using XCC, set the XTENSA_CORE environment
variable to "default" and XTENSA_SYSTEM to
"/home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3-linux-clone/config".

Alternatively, set XTENSA_CORE to "test_mmuhifi_c3-linux-clone" and XTENSA_SYSTEM
to "/home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/config"
(or leave XTENSA_SYSTEM unset if that is the default registry).

Next, we follow the suggested change of environment variables in a new termulator window with
a fresh environemnt:

$ '''setenv XTENSA_CORE test_mmuhifi_c3-linux-clone'''
$ '''setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/config'''
$ '''setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin'''
$ '''setenv PATH ${XTENSA_TOOLS}:${PATH}'''

$ '''cd /exports/default/Audio_Tests'''
$ '''xt-xcc -c hifitest.c -o hifitest''' [NOTE: This file has embedded TIE code in it; it can only be compiled with '''xcc'''

In a ssh termulator window on the board you can now run hifitest

[root@hifi ~]# '''cd /home/default/Audio_Tests/'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:23178; Eatting cpu; time:0 '''<control-C>'''

[root@hifi Audio_Tests]#

The simple procedure should work as long as you keep your tie code in files without
significant system include files. For example the /home/default/AUDIO_Tests/hifitest.c
used above in the core cloning example:

#include <stdio.h>
#include <time.h>
#include <xtensa/tie/xt_hifi2.h>

#define INC 1

main(int argc, char **argv)
{
int inc;
int inc2;
register ae_p24x2s p24_cnt;
register ae_p24x2s p24_inc;
register ae_p24x2s p24_pid;
int cnt;
int cnt2;
int pid;
int pid2;
volatile int i, j, k, l;
time_t time0 = time(NULL);
time_t time1 = time(NULL);

restart:
cnt = 0;
cnt2 = 0;
inc = INC;
pid = getpid();
p24_cnt = AE_ZEROP48();
p24_inc = AE_MOVPA24(inc);
p24_pid = AE_MOVPA24(pid);

while (1)
{
int errors = 0;

if ((cnt & 0xffffff) == 0) {
time0 = time1;
time1 = time(NULL);
printf("cnt:0x%x, pid:%d; Eatting cpu; time:%ld\n", cnt, pid, (time1 - time0));
for(i = 0; i<1000; i++) {
for(j = 0; j < 1000; j++) {
for(k = 0; k < 10; k++) {
l++;
}
}
}
time0 = time1;
time1 = time(NULL);
printf("cnt:0x%x, pid:%d; Eating Tie; time:%ld\n", cnt, pid, (time1 - time0));
}
cnt = (cnt + inc) & 0xffffff;
p24_cnt = AE_ADDP24(p24_cnt, p24_inc);
cnt2 = AE_MOVAP24S_L(p24_cnt) & 0xffffff;
pid2 = AE_MOVAP24S_L(p24_pid) & 0xffffff;
inc2 = AE_MOVAP24S_L(p24_inc) & 0xffffff;

if (cnt2 != cnt)
{
swapon("/tmp/cmt2", 0);
printf("Error: cnt2:0x%x != cnt:0x%x\n", cnt2, cnt);
errors++;
}
if (inc2 != inc)
{
swapon("/tmp/inc2", 0);
printf("Error: inc2:%d != inc:%d\n", cnt2, cnt);
errors++;
}
if ( pid2 != pid)
{
swapon("/tmp/pid2", 0);
printf("Error: pid2:%d != pid:%d\n", pid2, pid);
errors++;
}

if (errors) {
printf("for...\n");
for(i=0; i < 0x3FFFF; i++)
j++;
printf("sleep 10\n");
sleep(10);
printf("for...\n");
for(i=0; i < 0x3FFFF; i++)
j++;
printf("restart\n");
goto restart;
}
}
}
$

== Adding your codec to Buildroot ==

Xtensa developers provide detailed instructions on building the root filesystem and the Linux kernel.
* [[Buildroot_Build_Instructions|Instructions for building and booting Linux (buildroot)]].

Building a comprehensive development environment with buildroot can be a chalanging experience and worthy of providing some tips on process.
Here are notes of the configs used for the three menuconfigs in this 2nd snapshot
provided with SMP additions:
$ '''make [[HiFi-2 snapshot_2 SMP Snapshot menuconfig | menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP uclibc-menuconfig | uclibc-menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP busybox-menuconfig | busybox-menuconfig]]'''

[TO BE DONE - making a new tar ball of saved files, building buildroot, ...]

== Known Problems being investigated, suggested that you know about and possibly avoid ==

1. Using NFS mounts with default parameters causes memory congestion. Use these mount options:

'''vers=2,rsize=4096,wsize=4096,hard,nointr,nolock,nolock,timeo=11,retrans=3,noauto'''

this is extremely important to add to your /etc/fstab on the target.

2. Can't swap over NFS yet, memory can get tight and cause application to be killed.
a. Trying procedure documented in U-Boot Manual.

3. Building the C development with X11 doesn't work with buildroot.

4. Though Mplayer plug-in can be compiled, Mplayer can be compiled but still has a few issues:
a. Can't be compiled -O0 due to limited memory while compiling one file,
b. Compiler infrequently crashes and make has to be restarted.
Not seeing this problem with root build on Fedore Core 9.
Perhaps this was caused by debug kernel or LTP using all of the memory.

5. U-boot has flash problems:
a. Sectors marked Read-Only come up Writeable after a reset/reboot.
b. Flashing a large number of sectors (like the kernel) sometimes
results in an Error (Ex: Vcc) and had to be retried.
c. Saw environment variables trashed on reset/reboot once.
It's possible that U-boot in flash could get whacked
and the board will need to be re-flashed. During a week
or two of testing I haven't see environment getting whacked.

6. gdb appears to be crashing on target when debugging
on latest root with uclibc left unstriped and with debug;
core dump sent to maxim.

7. U-Boot seems to hang periodically when loading the kernel with
tftp; appears to be worse when network activity is high.

8. 'top' command only shows all cpu's or cpu0; cpu 1 and 2 missing.

9. Program dore dump require ulimit -c to be set but root uses /bin/sh
which is a link to bash but causes it to skip running the bash
startup scripts. Changing root to /bin/bash seems to mess up
ssh logins.

=Further reading=

Main Xtensa Linux resources are:

* [http://linux-xtensa.org/ Linux/Xtensa Wiki]
* [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions Buildroot Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Kernel_Build_Instructions Kernel Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Setting_up_U-Boot Setting up U-Boot]
* [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List]
* http://git.linux-xtensa.org/cgi-bin/git.cgi GIT Repositories]

=Thanks to=

* piet
* marc
* dan

And the rest of the people in the Linux-Xtensa mailing list, if you cannot go through some of the steps, don't hesitate to ask on the mailing list, there's always somebody willing to help you!

Minicom xtboard setup

2009-12-01T20:36:06Z

Marc: /* Minicom Setup for Tensilica Boards */ Put back link

= Minicom Setup for Tensilica Boards =

For using [http://en.wikipedia.org/wiki/Minicom minicom] as your
terminal emulator, you can save
settings by name and just invoke minicom with that name, for example:

'''minicom myboard'''

which initializes with parameters from /etc/minirc.myboard:

# Machine-generated file - use "minicom -s" to change parameters.
pr port /dev/ttyS0
pu minit
pu mreset
pu mdialpre
pu mconnect
pu mhangup
pu mdialcan
pu hasdcd No
pu rtscts No

The LX200 board expects to communicate at a baud rate of 38400 without parity and with 1 stop bit,
so the minicom '''Comm Parameters''' should be "Current: 38400 8N1" and can be displayed with <Ctrl-A> p:

Welcome to minicom 2.00.0
┌───────────[Comm Parameters]────────────┐
OPTIONS: History Buf│ │
Compiled on Jun 15 2│ Current: 38400 8N1 │
│ │
Press CTRL-A Z for h│ Speed Parity Data │
│ │
│ A: 300 L: None S: 5 │
│ B: 1200 M: Even T: 6 │
│ C: 2400 N: Odd U: 7 │
│ D: 4800 O: Mark V: 8 │
│ E: 9600 P: Space │
│ F: 19200 Stopbits │
│ G: 38400 W: 1 │
│ H: 57600 X: 2 │
│ I: 115200 Q: 8-N-1 │
│ J: 230400 R: 7-E-1 │
│ │
│ │
│ Choice, or <Enter> to exit? │
└────────────────────────────────────────┘

[[Mplayer_Hifi_2_Codec_Development_Board#Configuring_U-Boot_to_Boot_Linux|(Back to U-Boot setup)]]

Minicom xtboard setup

2009-12-01T20:33:13Z

Marc: Put minicom setup info in a separate page

SMP HiFi 2 Development Board

2009-12-01T20:28:40Z

Marc: /* Configuring U-Boot to Boot Linux */ Typo fixes; arp detects few aliases

This is the "communitee"" guide for how to use HiFi-2 Codec Development environment on an LX200 FPGA board.
If somethinig doesn't work ir isn't vovered in these guides, please feel free to ask at the [http://lists.linux-xtensa.org/mailman/listinfo Linux//Xtensa Mailing List]]

<div style="margin:0; margin-top:10px; margin-right:10px; border:1px solid #dfdfdf; padding:0 1em 1em 1em; background-color:#ffffcc; align:right; ">
'''NEWS:'''

Some general notes on these instructions:

* They are a work in progress.

* The following was tested on x86 machines running RedHat Fedora Core 5.

* Buildroot build with Fedora Core 9 also seems to be fine; perhaps better than when built on Fedore Core 5.

</div>

== Introduction ==

This document is addressed to someone who received an LX200 board setup by Tensilica
for HiFi2 codec development.

This document goes over the steps needed to set up the LX200 board for codec development.
To summarize:
* Setup the board. It likely comes with U-boot preinstalled, ready to boot a linux kernel.
* Install '''git'''.
* Download buildroot and linux kernel trees, pre-configured and built for HiFi-2 development.
* Setup a TFTP server to provide the linux kernel to U-Boot.
* Setup an NFS server to export a linux root file system.
* Setup the Linux kernel to boot from the root file system provided by the NFS server.
Once the development board is up and running, this document:
* Suggests a possible way to tailor the board for easy codec development.
* Shows how to add the Tensilica provided codec packages to the Mplayer packages used by Buildroot, including building and installing.
* Demonstrates two procedures for compiling, linking, and debugging codecs.

All development is expected to be done on a Linux host. (One can in principle use Windows to
develop target libraries. However, linking and subsequent steps need to be done in Linux.)

== Downloading the Latest HiFI-2 Buildroot and Kernel Snapshots ==

The HiFi-2 development environment is maintained in a source code version control system named 'git'. The '''git''' tools are useful when working with this development environment, though they are not strictly necessary. This document generally assumes the use of '''git''', which provides more opportunities for modifying this environment as needed (e.g. building more optional buildroot packages). But points out alternatives to allow getting up and running without having to set it up.

=== Installing git ===

To install '''git''', download a recent tarball from the [http://www.kernel.org/pub/software/scm/git/ official site]. For example, <tt>cd</tt> to a location with enough disk space, and do:

$ '''wget http://www.kernel.org/pub/software/scm/git/git-1.6.5.tar.gz'''

Unpack the tarball, and make and install it. Here we show how to install it to your ~/bin directory:

$ '''gunzip git-1.6.5.tar.gz'''
$ '''tar xf git-1.6.5.tar'''
$ '''cd git-1.6.5'''
$ '''make'''
$ '''make install'''

The git makefile can be instructed to install '''git''' to <tt>/usr/local/bin</tt> as root for system wide access:

$ '''cp git-1.6.5.tar.gz''' /tmp
$ '''su'''
Password:
# '''cd /usr/local/src/'''
# '''mkdir git'''
# '''cd git'''
# '''cp /tmp/git-1.6.5.tar.gz .'''
# '''gunzip git-1.6.5.tar.gz'''
# '''tar xf git-1.6.5.tar'''
# '''cd git-1.6.5'''
# '''make prefix=/usr/local'''
# '''make install'''

See the '''INSTALL'' instruction at the top of the git src directory for details.

Using '''git''' provides easy access to the binaries used to bring up the codec development environment, and leaves in place the infrastructure to modify and build this environment should you wish to. Any changes to '''git'''-managed source trees are easily observed with the '''git''' tools.

=== Installing the Buildroot Snapshot ===

''Note: The HiFi-2 snapshot is in the process of being made.''

To install the buildroot environment (toolchain and root filesystem), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot'''
$ '''cd buildroot-xtensa-HiFi2-Snapshot'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP''' [56 key strokes]
$ '''git checkout snapshot_2+SMP''' [28 key strokes]

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).

You can examine the tree (git repository) and its history visually using <tt>git gui</tt>.
The git GUI is a faster and more convenient method for checking out the HiFi-2 snapshot. To check out the snapshot_2+SMP branch simply run the command 'git gui' and then pull down the branch->create menu. Next select <>Match Tracking Branch Name and click on ''origin/snapshot_2+SMP''. Finally hit the Create Button.

$ '''git gui''''' [8 key strokes]
[Branch] -> Create... [2 key strokes]
<> Match Tracking Branch Name [1 key stroke]
<> Tracking Branch [1 key stroke]
origin/snapshot_2+SMP [1 key stroke]
[Create] [1 key stroke]
[Reposirory]--> Quit [2 key strokes]

If there are issues installing '''git''', as a last resort, an alternative is ftp (may not always get updated, is currenty our of date, waste disk space, so may be dropped at some point):

http://www.linux-xtensa.org/pub/snapshots/buildroot-xtensa-smp.2-Nov-2009.tar.gz

=== Installing the Linux Kernel Snapshot ===

To install the Linux kernel environment (kernel src, config, and HiFi-2 kernel U-Boot image), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ '''git clone git://git.linux-xtensa.org/git/kernel/xtensa-2.6.29-smp'''
$ '''cd kernel/xtensa-2.6.29-smp'''
$ '''git branch --track snapshot_2+SMP origin/snapshot_2+SMP'''
$ '''git checkout snapshot_2+SMP'''

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).
As in the build root case, you can also do it from via git gui using the same proceedure
mantioned above.

Now, assuming we are still in the kernel '''xtensa-2.6.29-smp''' directory
copy the kernel U-Boot Image ('''uImage''') to the tftp directory; Ex:

$ '''cp arch/xtensa/boot/uImage /tftpboot/uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'''

NOTE: On some system, like Fedora Core 9, the tftpboot directory has been moved to /var/lib/tftpboot.
In this case we recomend that you just added a symbolic pointer from /etc to /var/lib/tftpboot:

$ '''su'''
# '''cd /etc'''
# '''/var/lib/tftpboot/ tftpboot'''
# '''ls -ld tftpboot'''
lrwxrwxrwx 1 root root 18 2009-11-23 21:14 tftpboot -> /var/lib/tftpboot/
#

== Setting up a TFTP Server to provide the Linux kernel to U-Boot ==

The TFTP service is part of the xinetd and is installed on Fedora workstations.
You can see that it's installed with the check config command which manages the
/etc/rc.d/init.d startup scripts and with the yum search command:

$ '''chkconfig --list'''
NetworkManager 0:off 1:off 2:off 3:off 4:off 5:off 6:off
NetworkManagerDispatcher 0:off 1:off 2:off 3:off 4:off 5:off 6:off
acpid 0:off 1:off 2:off 3:on 4:on 5:on 6:off
.
.
.
xfs 0:off 1:off 2:on 3:on 4:on 5:on 6:off
xinetd 0:off 1:off 2:off 3:on 4:on 5:on 6:off
ypbind 0:off 1:off 2:off 3:on 4:on 5:on 6:off
yum 0:off 1:off 2:off 3:off 4:off 5:off 6:off

xinetd based services:
amanda: off
auth: off
.
.
.
rsync: off
'''tftp: on''' [NOTE that tftp is enabled]
time: off
time-udp: off
uucp: off
$
$
$
$ '''yum search tftp-server'''
Loading "installonlyn" plugin
Searching Packages:
.
.
.
Reading repository metadata in from local files
.
.
.
'''tftp-server.i386 0.41-1.2.1 installed''' [NOTE that tftp server is installed as part of the inet daemon]
Matched from:
tftp-server
The Trivial File Transfer Protocol (TFTP) is normally used only for
booting diskless workstations. The tftp-server package provides the
server for TFTP, which allows users to transfer files to and from a
remote machine. TFTP provides very little security, and should not be
enabled unless it is expressly needed. The TFTP server is run from
/etc/xinetd.d/tftp, and is disabled by default on Red Hat Linux systems.
[piet@pdelaney_fc5 ~]$

TFTP is not normally enabled, to enable it just edit the file /etc/xinetd.d/tftp
and change the disable field to no:

# default: off
# description: The tftp server serves files using the trivial file transfer \
# protocol. The tftp protocol is often used to boot diskless \
# workstations, download configuration files to network-aware printers, \
# and to start the installation process for some operating systems.
service tftp
{
socket_type = dgram
protocol = udp
wait = yes
user = root
server = /usr/sbin/in.tftpd [NOTE: /var/lib/tftpboot on Fedora Core 9]
server_args = -s /tftpboot
'''disable = no'''
per_source = 11
cps = 100 2
flags = IPv4
}

== Setting up an NFS Server to export the Root Filesystem ==

The LX200 board running Linux needs to mount its root filesystem over NFS.
This filesystem was built using buildroot into a cpio format file,
and left in:

buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2/rootfs.xtensa_test_mmuhifi_c3.cpio

We will also be adding an additional minor changes to make your development environment more comfortable.

Pick a place on your workstation to export your root and unpack the cpio file into that directory.
For example here we will set up an export in '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''':

$ '''cd buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2'''
$ '''WHERE=$PWD'''
$ '''mkdir -p /exports/LINUX_ROOT.HiFi-2'''
$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''cpio -i < $WHERE/rootfs.xtensa_test_mmuhifi_c3.cpio'''

Next add a line to /etc/exports:

/exports *(rw,no_root_squash,sync,no_wdelay)

and restart you nfs services:

$ '''/etc/rc.d/init.d/nfs restart'''
or
$ '''/sbin/chkconfig nfs on'''

The showmount command should show your NFS file system now being exported:

$ '''showmount -e'''
Export list for mypc.foobar.com:
/exports *
$

== Configuring U-Boot to Boot Linux ==

Your LX200 board should have arrived with U-Boot installed in the flash ready to use.
The board has a DIP switch (next to the power on/off switch) that provides the 6 LSBs
of the Ethernet MAC, in switch positions 1 thru 6.

DIP Swithes for MAC: 1 2 3 4 5 6 7 8 ethaddr=00:50:C2:13:6f:0a
Little Endian: 0 1 0 1 0 0 * *
^
|
+------ Enables booting U-Boot from Flash

DIP switch 8 should be shipped in the ON position to enable U-Boot booting from flash.
See Sections 4.2.3 and 4.2.4 of the '''Tensilica Avnet (XT-AV200) Board User's Guide'''
for details. Make sure to select a unique MAC address for you board.

Next, connect a serial interface to a text based terminal emulation program,
set to 38400 bps, no parity, 1 stop bit, no handshaking.
For an example of setting [http://en.wikipedia.org/wiki/Minicom minicom]
for this, see [[minicom_xtboard_setup|here]].
For <tt>minicom</tt> you can save
settings by name and just invoke, for example:

'''minicom myboard'''

which initializes with parameters from /etc/minirc.myboard:

# Machine-generated file - use "minicom -s" to change parameters.
pr port /dev/ttyS0
pu minit
pu mreset
pu mdialpre
pu mconnect
pu mhangup
pu mdialcan
pu hasdcd No
pu rtscts No
~
The LX200 board expects to communicate at a baud rate of 38400 without parity and with 1 stop bit,
so the minicom '''Comm Parameters''' should be "Current: 38400 8N1" and can be displayed with <Ctrl-A> p:

Welcome to minicom 2.00.0
┌───────────[Comm Parameters]────────────┐
OPTIONS: History Buf│ │
Compiled on Jun 15 2│ Current: 38400 8N1 │
│ │
Press CTRL-A Z for h│ Speed Parity Data │
│ │
│ A: 300 L: None S: 5 │
│ B: 1200 M: Even T: 6 │
│ C: 2400 N: Odd U: 7 │
│ D: 4800 O: Mark V: 8 │
│ E: 9600 P: Space │
│ F: 19200 Stopbits │
│ G: 38400 W: 1 │
│ H: 57600 X: 2 │
│ I: 115200 Q: 8-N-1 │
│ J: 230400 R: 7-E-1 │
│ │
│ │
│ Choice, or <Enter> to exit? │
└────────────────────────────────────────┘

Many users of this board are interested in developing codecs and/or HiFi 2 software and will prefer to just boot linux with the root file system we just described how to export on you NFS server. We will use git now to pull a snapshot of a performance 2.6.29 linux kernel and configure U-Boot to automatically boot it after a power cycle.

U-Boot> '''setenv serverip 192.168.11.55''' [TFTP server IP Address: RTOS-LAB2]
U-Boot> '''setenv nfsroot_server 192.168.11.55''' [Root NFS Servers IP Address: My Workstation]
U-Boot> '''setenv ipaddr 192.168.11.155''' [HOST IP address]
U-Boot> '''setenv bootfile uImage.xtensa-2.6.29-smp.test_mmuhifi_c3''' [File to fetch with TFTP and pass to bootm]
U-Boot> '''setenv root-path /exports/LINUX_ROOT.HiFi-2''' [WARNING: Limit path to < 50 characters]
U-Boot> '''setenv bootargs_using_bootp console=ttyS0,38400 ip=bootp root=nfs coredump_filter=0xff''' [Args passed to Linux while booting with BOOTP proto]
U-boot> '''setenv bootargs console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=${nfsroot_server}:${root-path}''' [Args passed to Linux while booting with DHCP proto]
U-boot> '''setenv bootcmd tftpboot\; bootm''' [Boot Linux after fetching it with TFTP]
U-Boot> '''setenv bootdelay 20''' [Delay 20 seconds before booting automaticaly]
U-Boot> '''setenv autostart yes''' [Boot automatically on power-up/reset]
U-Boot> '''saveenv'''
U-Boot>

'''[REMIND: Update the above procedure, show two or thee approaches (ip, dhcp, bootp)]'''

== Tailoring your system prior to Booting ==

There are a few tweaks that developers have found convenient to add to the the root file-system before booting.
As an initial environment for developing we suggest mounting a /home/default files-system that has number of
files useful for getting started. Find another place to tar in the tar ball with the default users file system.
We chose to include this close to the cpio file with the root file-system. Copy the tar bar to where you are
exporting you root file-system and next to it add the 'default' users file-system:

$ '''cd /export'''
$ '''cp /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.10/binaries/default.tar .'''
$ '''tar xf default.tar'''
$ '''cd default'''
$ '''ls'''
[TO BE ADDED]

Notice a file tar ball called '''saved_files.tar'''. This ia a tar file of files that
developers have found convenient to add and replace on the root file system after
adding a new buildroot file system. Here is a list of the files and a brief
explanation on why it's convenient to add or replace them:

root/.bash_profile [added 'ulimit -c unlimited to allow core dumps to be created]
root/.bashrc
etc/profile [added 'ulimit -c unlimited to allow core dumps to be created]
etc/fstab [Tells the system how to mount extra NFS file systems like /home/default]
etc/init.d/S90local [Mounts /home/default]
etc/resolv.conf [Location of DNS servers when your not using DHCP to boot the kernel]
etc/TZ [Your time zone, currently set to California TZ]
etc/dropbear/dropbear_rsa_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/dropbear/dropbear_dss_host_key [Old DropBrer keys, useful if you prefer Dropbear of sshd]
etc/ssh_config [Typically tailored with things like allowing root logins via ssh]
etc/ssh_host_dsa_key [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_dsa_key.pub [sshd keys - Takes 30 minutes to generate, saves time on initial boot]
etc/ssh_host_key
etc/ssh_host_key.pub
etc/ssh_host_rsa_key
etc/ssh_host_rsa_key.pub
etc/sshd_config [Typically tailored with things like allowing root logins via ssh]
etc/rndc.key
etc/random-seed [Generated during 1st boot]
etc/passwd [Changed default user's shell to bash]
etc/shadow [Changed default and root users login password to 'linux1', need to ssh to the board]
exports/ [The path to where the board can mount extra file systems like /home/default.
fac/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]
fac/vol6/ [Where we get the HiFi-2 codec from to install and build mplayer plugins]

Now lets assume your going to stay with these changes and modify them after taring in these changes.
Here we add the tar ball files to the boards root filesystem.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''tar xf /exports/default/'''

This is a good time to edit a few files on the boards file system
before boot it.

$ '''cd /exports/LINUX_ROOT.HiFi-2'''
$ '''vi etc/fstab''' [Change fstab entry for /home/default and others to your taste]
$ '''vi etc/init.d/S90local''' [You might want to disable mounting of NFS file systems on the 1st Boot and add this once you try it manually]

== Booting Linux for the 1st Time ==

We should now be ready to boot linux on your LX200. You have exported the root file-system and made the
kernel available to a TFTP server. Now lets start with hitting the reset button on the X200 and it should
auto-boot the kernel:

U-Boot 2009.08 (Nov 15 2009 - 22:03:26)

CPU: Xtensa test_mmuhifi_c3 at 41.6777 MHz
Board: XT-AV200: Avnet board + Xilinx LX200 FPGA + Tensilica bitstream
SysRAM: 96 MB
Flash: 16 MB
In: serial
Out: serial
Err: serial
MAC: 00:50:C2:13:6f:07
IP: 192.168.11.105
open_ethernet
Autobooting in 5 seconds, press <SPACE> to stop
Using open_ethernet device
TFTP from server 192.168.11.55; our IP address is 192.168.11.105
Filename 'uImage.xtensa-2.6.29-smp.test_mmuhifi_c3'.
Load address: 0xd2000000
Loading: #################################################################
###############
done
Bytes transferred = 1161826 (11ba62 hex)
Automatic boot of image at addr 0xD2000000 ...
## Booting kernel from Legacy Image at d2000000 ...
Image Name: Linux-2.6.29-rc7
Image Type: Xtensa Linux Kernel Image (gzip compressed)
Data Size: 1161762 Bytes = 1.1 MB
Load Address: d0001000
Entry Point: d0001000
Verifying Checksum ... OK
Uncompressing Kernel Image ... OK

## Linux Boot Params Starting At Address:0xd5f50000
MEMORY: tag:0x1003, type:0X1000, start:0X0, end:0X6000000
COMMAND_LINE: tag:0x1001, size:188, data:'console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff'
SERIAL_BAUDRATE: tag:0x1004, size:4, baudrate:38400

## Transferring Control to Linux Kernel At Address 0xd0001000 ...

parse_bootparam: Ignoring tag 0x1004
lx60 platform_init(bootparams:d5f50000)
Linux version 2.6.29-rc7 (pdelaney@pdelaney_fc5.hq.tensilica.com) (gcc version 4.2.1) #201 SMP Tue Nov 17 23:49:39 PST 2009
lx60 platform_setup(cmdline[0]:'console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff')
smp_init_cpus: Core Count = 3
smp_init_cpus: Core Id = 9320
On node 0 totalpages: 24576
free_area_init_node: node 0, pgdat d0196540, node_mem_map d01fa000
Normal zone: 216 pages used for memmap
Normal zone: 24360 pages, LIFO batch:3
smp_prepare_boot_cpu:
Built 1 zonelists in Zone order, mobility grouping on. Total pages: 24360
Kernel command line: console=ttyS0,38400 ip=192.168.11.105:192.168.11.55:192.168.11.1:255.255.255.0:"HiFi-2 Demo" root=/dev/nfs rw nfsroot=192.168.11.55:/exports/LINUX_ROOT.HiFi-2 debug coredump_filter=0xff
trap_init 0
PID hash table entries: 512 (order: 9, 2048 bytes)
time_init: Platform Calibrating CPU frequency
time_init: ccount_per_jiffy:416777 [41.67 MHz], nsec_per_ccount:23
Console: colour dummy device 80x25
console [ttyS0] enabled
Dentry cache hash table entries: 16384 (order: 4, 65536 bytes)
Inode-cache hash table entries: 8192 (order: 3, 32768 bytes)
Memory: 95196k/98304k available (1229k kernel code, 3040k reserved, 28k data, 72k init 0k highmem)
Calibrating delay loop... 41.26 BogoMIPS (lpj=206336)
Mount-cache hash table entries: 512
cpu 1 fffd
secondary_trap_init 1
Calibrating delay loop... 41.67 BogoMIPS (lpj=208384)
secondary_irq_init: set cached_irq_mask and enable interrupts))
secondary_time_init()
secondary_irq_enable(intrnum:6): cpu:1, INTENABLE:7c
secondary_irq_enable(intrnum:0): cpu:1, INTENABLE:7d
cpu 2 fff9
secondary_trap_init 2
Calibrating delay loop... 41.57 BogoMIPS (lpj=207872)
secondary_irq_init: set cached_irq_mask and enable interrupts))
secondary_time_init()
secondary_irq_enable(intrnum:6): cpu:2, INTENABLE:7c
secondary_irq_enable(intrnum:0): cpu:2, INTENABLE:7d
Brought up 3 CPUs
smp_cpus_done:
net_namespace: 304 bytes
NET: Registered protocol family 16
lx60_init()
bio: create slab <bio-0> at 0
NET: Registered protocol family 2
IP route cache hash table entries: 1024 (order: 0, 4096 bytes)
TCP established hash table entries: 4096 (order: 3, 32768 bytes)
TCP bind hash table entries: 4096 (order: 3, 32768 bytes)
TCP: Hash tables configured (established 4096 bind 4096)
TCP reno registered
NET: Registered protocol family 1
msgmni has been set to 186
alg: No test for md5 (md5-generic)
alg: No test for des (des-generic)
alg: No test for des3_ede (des3_ede-generic)
alg: No test for stdrng (krng)
io scheduler noop registered (default)
Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled
serial8250: ttyS0 at MMIO 0x0 (irq = 3) is a 16550A
oeth_probe: {
oeth_setup: Open Ethernet Core Version 1.0.1
: oeth_setup: Found id1:2000, id2:5c30 at phy_id:3.
: Hardware MAC Address: 00:50:c2:13:6f:0f
eth0 (): not using net_device_ops yet
oeth_probe: }
mice: PS/2 mouse device common for all mice
TCP cubic registered
NET: Registered protocol family 17
RPC: Registered udp transport module.
RPC: Registered tcp transport module.
oeth_open: Ready to process packets now on dev->name:'eth0', dev:d597d800;
IP-Config: Complete:
device=eth0, addr=192.168.11.105, mask=255.255.255.0, gw=192.168.11.1,
host="HiFi-2 Demo", domain=, nis-domain=(none),
bootserver=192.168.11.55, rootserver=192.168.11.55, rootpath=
Looking up port of RPC 100003/2 on 192.168.11.55
Looking up port of RPC 100005/1 on 192.168.11.55
VFS: Mounted root (nfs filesystem) on device 0:11.
Freeing unused kernel memory: 72k freed
Starting portmap: done
Initializing random number generator... done.
Starting network...
ip: RTNETLINK answers: File exists
Starting sshd: OK
Starting NFS statd: done
Starting NFS services: done
Starting NFS daemon: done
Starting NFS mountd: done
Starting domain name daemon: namedwarning: `named' uses 32-bit capabilities (legacy support in use)
failed
Fri Nov 20 17:10:37 2009
Mounting Other NFS Filesystems

Welcome to your custom Xtensa HiFi-2 Codec Developemnt System
hifi login: '''root'''
Password: '''linux1'''

== Tailoring your system prior to developing your codec ==

To make your experience more pleasant we suggest you tailor your environment.
Here are some of the changes that we have found helpful:

1. Add a root password to that you can login with ssh.
2. Run rdate with an ntp server on booting.
3. Add NFS mounts to /etc/fstab for your code and buildroot code.
4. Copy in previous ssh server encryption keys to /etc/dropbear to speed up your initial boot.
5. Mount a 'default' user home directory with:
a. Linux Test Suite pre-patch to test the system
b. Audio test example files
c. Copies of Mplayer and its Plug-ins from Buildroot modified slightly to make installation easy.
d. Misc audio test programs.

[TO BE DONE - Where to get 'default' user home directory tar ball and 1st boot patch]

== Compiling the Mplayer Plugins and linking them with MPEG-1 Audio Layer 3 (MP3) and MPEG-4 AAC Codecs ==

Mplayer is provided as an example environment for developing and testing Codecs and HiFi 2 software. There
are two ways to build Mplayer and the plug-in modules that use the codecs. The buildroot
tree (pulled with git) has a copy of mplayer and the plugins that can be built in the
snapshot via 'make menuconfig'. This is a good environment to use once codecs are
developed and debugged.

To facilitate development the mplayer packages can be copied to your NFS mounted development
environment. From there you can just configure mplayer to compile on the board and debug
mplayer and your codecs with gdb locally.

In the default user home directory we have a directory /home/default/buildroot_mplayer_stuff
with a copy of three of the mplayer packages:

[root@hifi buildroot_mplayer_stuff]# '''ls -l'''
drwxr-xr-x 34 root root 4096 Nov 10 05:01 MPlayer-1.0rc2/
drwxr-xr-x 4 root root 4096 Nov 10 01:36 mplayer_hifi2_aacplus_v2_plugin/
drwxr-xr-x 3 root root 4096 Nov 10 00:57 mplayer_hifi2_mp3_plugin/

they were simply copied from the buildroot-xtensa-HiFi2-Snapshot.2/package directory.

To get your development environment ready to compile the mplayer plug-ins you need
to configure Mplayer to use the local C compiler and linker:

# '''cd /home/default/buildroot_mplayer_stuff/MPlayer-1.0rc2/'''
# '''CFLAGS="-g3" ./configure'''

This will take about 15 minutes to configure. After that you can build the
plugins or mplayer. If you want to recompile mplayer it's likely best/necessary
to use the same args to .configure as used by buildroot:

.CFLAGS="-g3" ./configure \
--prefix=/usr \
--confdir=/etc/mplayer \
--with-extraincdir=/usr/include \
--with-extralibdir=/lib \
--disable-gui \
--enable-mad \
--enable-fbdev \
--disable-mencoder \
--disable-dvdnav \
--disable-dvdread \
--disable-dvdread-internal \
--disable-libdvdcss-internal \
--disable-big-endian \
--disable-nemesi \
--disable-tv \
--enable-dynamic-plugins

We are currently able to compile most of mplayer on the XL200 but
due to space limitations it's not possible to compile it -O0.

Now, lets focus on compiling linking the plugins. They are a nice
example of compiling a audio application on the LX200.

We modified the Makefile of the codes slightly, and will make it available.
These additions just instruct make how to install the plugins as explained
in the Chapter 7 of the Linux HiFi application note.

For example the mp3 plugin has this addition:

target_install::
-mkdir /etc/mplayer
cp codecs.conf /etc/mplayer
-mkdir /usr/lib/mplayer
cp ad_xa_mp3_dec.so /usr/lib/mplayer/
cp xa_mp3_dec.so /usr/lib/mplayer
chmod 755 /usr/lib/mplayer/ad_xa_mp3_dec.so
chmod 755 /usr/lib/mplayer/xa_mp3_dec.so

It's just providing a codec config file for mplayer at '''/etc/mplayer/codecs.conf''' and
copying the plug-in to '''/usr/lib/mplayer'''. To install the mp3 codec plugin and mplayer
config file just copy your codec that was compiled with '''xcc''' to the directory, compile it,
and install.

# '''cd /fac/vol6/audio/release/bin/l32r_LE5_pic'''
# '''cp xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz /tmp'''
#
# '''cd /home/default/buildroot_mplayer_stuff'''
# '''cd mplayer_hifi2_mp3_plugin'''
# '''cp /tmp/xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz .'''
# '''gunzip xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz'''
# '''tar xf xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tar'''
# '''make'''
# '''make target_install'''

The unpacking of the Tensilica mp3 codec tar ball will install the following files:

xa_mp3_dec/
xa_mp3_dec/README
xa_mp3_dec/include/
xa_mp3_dec/include/mp3_dec/
xa_mp3_dec/include/mp3_dec/xa_mp3_dec_api.h
xa_mp3_dec/include/xa_apicmd_standards.h
xa_mp3_dec/include/xa_error_handler.h
xa_mp3_dec/include/xa_error_standards.h
xa_mp3_dec/include/xa_memory_standards.h
xa_mp3_dec/include/xa_type_def.h
xa_mp3_dec/test/
xa_mp3_dec/test/build/
xa_mp3_dec/test/build/ldscript_stream_data.txt
xa_mp3_dec/test/build/makefile_testbench_sample
xa_mp3_dec/test/build/paramfilesimple.txt
xa_mp3_dec/test/include/
xa_mp3_dec/test/include/id3_tag_decode.h
xa_mp3_dec/test/src/
xa_mp3_dec/test/src/xa_mp3_dec_sample_testbench.c
xa_mp3_dec/test/src/id3_tag_decode.c
xa_mp3_dec/test/src/stream_data.c
xa_mp3_dec/test/src/xa_mp3_dec_error_handler.c
xa_mp3_dec/test/test_inp/
xa_mp3_dec/test/test_inp/compl.mp3
xa_mp3_dec/test/test_inp/hihat.mp3
xa_mp3_dec/test/test_out/
xa_mp3_dec/test/test_out/force_mkdir.txt
xa_mp3_dec/test/test_ref/
xa_mp3_dec/test/test_ref/compl_24bit.wav
xa_mp3_dec/test/test_ref/hihat_16bit.wav
xa_mp3_dec/lib/
xa_mp3_dec/lib/xa_mp3_dec.a
xa_mp3_dec/doc/
xa_mp3_dec/doc/HiFi2-MP3-DecoderProgrammersGuide.pdf

[TO BE DONE - Add missing C file, make clean deletes it!]

The xa_mp3_dec.a archive will be used by the Makefile in
the mplayer_hifi2_mp3_plugin directory to make the mplayer plug-in.
Section 6 of the '''Using Tensilica HiFi 2 Codec on Xtensa Linux with MPlayer'' Application Note
has a detailed description of the encapsulation process used by the plug-ins.

== Compiling Generic GPL Packages ==

For your development you may want to add a few GPL packages that you find helpfull.
This can be done on the LX200 just as you would on a normal workstation, thought
much slower. For example here we configure and build the strace package:

[[Building the Strace Package]]

== Compiling Tie Code with XCC ==

Codecs like MP3 and AAC have been written in C with TIE extensions and can only be compiled with '''xcc'''.
XCC is likely to large to run on the board without virtual memory. There are two approaches to compiling
Linux TIE code with '''xcc'''. The simple approach assumes the host workstation and target code running of the board
are similar enough that the library interfaces defined by the include files are compatable. This is often the
case for standard system calls, libc, and stdio.The proper approach uses a virtual core that we will create
that has built in references to the library and include files on the target code running on the LX200.

=== Simply using Xtensa Tools to compile the TIE code on a workstation ===

Below we illustrate compiling a simple audio test program on a workstation.
We start by referring to the XTENSA tools build by Xplorer, putting '''xcc''' into our search path and set the standard XTENSA_* environement variables.
For example:

setenv XTENSA_CORE test_mmuhifi_c3
setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3
setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config
setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin

setenv PATH ${XTENSA_TOOLS}:${PATH}

[piet@fc9desktop Tests] $ '''cd /exports/default/Audio_Tests''' [NOTE: This is being done on a Workstation]
[piet@fc9desktop Audio_Tests]$ '''xt-xcc -g3 -O0 -fPIC -c hifitest.c'''

Next we link the object on the XL200 board and run gdb on the TIE enhanced code:

[root@hifi Audio_Tests]# '''gcc -g hifitest.o -o hifitest'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:4640; Eatting cpu; time:0
cnt:0x0, pid:4640; Eating Tie; time:7
^C
[root@hifi Audio_Tests]# '''gdb ./hifitest''' [NOTE: This is being done on the LX200 board]
GNU gdb 6.6
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "xtensa_test_mmuhifi_c3-linux-uclibc"...
Using host libthread_db library "/lib/libthread_db.so.1".
(gdb) '''break main'''
Breakpoint 1 at 0x400401: file /exports/default/Audio_Tests/hifitest.c, line 20.
(gdb) '''run'''
Starting program: /home/default/Audio_Tests/hifitest

Breakpoint 1, main (argc=1, argv=0x3fb3fab4)
at /exports/default/Audio_Tests/hifitest.c:20
20 time_t time0 = time(NULL);
(gdb) '''step'''
21 time_t time1 = time(NULL);

=== The Proper Approach of Building TIE code for Linux Targets ===

In section 4.3 of the '''Xtensa OSKit Guide''' there is a detailed description
of this intense procedure of building target binaries. As the founding father
of Java, Jim Gosling,
once wrote, '''"Not for Pregnant Woman or men with weak hearts"'''. This proceedure
depends on a number of packages to be right, like versions of Xprorer and '''gcc'''.
When it works it's much faster than compiling on the target.

A summary of the procedure is available from the --help message of the
install script that set up a cloned core.

[piet@fc9desktop test_mmuhifi_c3]$ '''${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install --help'''

Usage:
<fullpath>/xt-xcc-linux-install --sysroot=<target_sysroot>
[--clone-core=<corename>]
[--clone-root=<rootdir>]
[--clone-registry=<registrydir>]
[--c-include=<dir>]
[--cxx-include=<dir>]
[--lib-include=<dir>]
[--linux-gcc=<path_to_target_gcc>]
[--help]

--sysroot=<target_sysroot>
Specify the target sysroot directory, the root of a tree containing
target header files and libraries for use by the compiler. Although
this can be the target filesystem as it appears on the host (for
targets supporting native development), it is typically a different
but similarly structured tree (for cross-development). Xtensa Tools
look for target headers in <target_sysroot>/usr/include, and for
target libraries in <target_sysroot>/lib and <target_sysroot>/usr/lib.
There is no default and this directory must be specified.

[--c-include=<dir>]
Specify an additional directory for the default C header search path.

[--cxx-include=<dir>]
Specify an additional directory for the default C++ header search path.

[--lib-include=<dir>]
Specify an extra dir. for the default library+startfile search path.

[--linux-gcc=<path_to_target_gcc>]
Specify the path to a host GCC targeting the Xtensa Linux system,
which this script invokes to obtain additional lists of include
directories for C headers, C++ headers, and libraries.
This is often a convenient shorthand to specifying multiple
--c-include , --cxx-include, and --lib-include options.

[--clone-core=<corename>]
Name of the clone core to install. If omitted, the default is
the original core name specified in the Xtensa Processor
Generator with '-linux' appended to the name.

[--clone-root=<rootdir>]
Specify the directory where the clone core package will be
installed. If omitted, the default is a path derived by replacing
the leaf directory of the original core package, <xtensa_root>,
with the name of the clone core.

[--clone-registry=<registrydir>]
Specify the Xtensa core registry in which to register the new
clone core name. If omitted, the default core registry is
used, located in Xtensa Tools at <xtensa_tools_root>/config.

[--help]
Display this message and exit without installing anything.

This installer clones its containing Xtensa core package (using symlinks),
and modifies the clone to make XCC build applications that run on Linux.
For this to work, XCC must select this clone core name, and use the default
Xtensa Linker Support Package (that is, avoid the -mlsp parameter).

The installer registers the new clone core in the specified Xtensa core
registry. The clone core can be selected using either the XTENSA_CORE
environment variable or the --xtensa-core=<corename> parameter to run
xt-xcc (the XCC C/C++ compiler) and other Xtensa Tools.

[piet@fc9desktop test_mmuhifi_c3]$

Below illustrates using this '''core cloning''' procedure:

$ '''setenv XTENSA_CORE test_mmuhifi_c3'''
$ '''setenv XTENSA_ROOT /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3'''
$ '''setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3/config'''
$ '''setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin'''

$ '''setenv PATH ${XTENSA_TOOLS}:${PATH}'''

$ '''setenv TARGET_SYSROOT /exports/LINUX_ROOT.HiFi-2'''
$ '''setenv BUILDROOT_DIR /export/src/HiFi-2_DemoBoard/buildroot-xtensa-HiFi2-Snapshot.12'''

$ '''${XTENSA_ROOT}/xtensa-elf/src/linux/bin/xt-xcc-linux-install \'''
'''--sysroot=${BUILDROOT_DIR}/build_xtensa_${XTENSA_CORE}/staging_dir \'''
'''--clone-core=test_mmuhifi_c3-linux-clone \'''
'''--linux-gcc=${BUILDROOT_DIR}/build_xtensa_${XTENSA_CORE}/staging_dir/usr/bin/xtensa_test_mmuhifi_c3-linux-gcc''' [NOTE: Maxim used this for some reason on the C++ problem]

The [[Normal Core Cloning Proceedure Output]] will have details on how to change your environment variables to
use the new cloned core:

************************************************************
* Installation Complete.
************************************************************
To build Linux applications using XCC, set the XTENSA_CORE environment
variable to "default" and XTENSA_SYSTEM to
"/home/pdelaney/Xplorer/XtDevTools/install/builds/RC-2009.0-linux/test_mmuhifi_c3-linux-clone/config".

Alternatively, set XTENSA_CORE to "test_mmuhifi_c3-linux-clone" and XTENSA_SYSTEM
to "/home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/config"
(or leave XTENSA_SYSTEM unset if that is the default registry).

Next, we follow the suggested change of environment variables in a new termulator window with
a fresh environemnt:

$ '''setenv XTENSA_CORE test_mmuhifi_c3-linux-clone'''
$ '''setenv XTENSA_SYSTEM /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/config'''
$ '''setenv XTENSA_TOOLS /home/pdelaney/Xplorer/XtDevTools/install/tools/RC-2009.0-linux/XtensaTools/bin'''
$ '''setenv PATH ${XTENSA_TOOLS}:${PATH}'''

$ '''cd /exports/default/Audio_Tests'''
$ '''xt-xcc -c hifitest.c -o hifitest''' [NOTE: This file has embedded TIE code in it; it can only be compiled with '''xcc'''

In a ssh termulator window on the board you can now run hifitest

[root@hifi ~]# '''cd /home/default/Audio_Tests/'''
[root@hifi Audio_Tests]# '''./hifitest'''
cnt:0x0, pid:23178; Eatting cpu; time:0 '''<control-C>'''

[root@hifi Audio_Tests]#

The simple procedure should work as long as you keep your tie code in files without
significant system include files. For example the /home/default/AUDIO_Tests/hifitest.c
used above in the core cloning example:

#include <stdio.h>
#include <time.h>
#include <xtensa/tie/xt_hifi2.h>

#define INC 1

main(int argc, char **argv)
{
int inc;
int inc2;
register ae_p24x2s p24_cnt;
register ae_p24x2s p24_inc;
register ae_p24x2s p24_pid;
int cnt;
int cnt2;
int pid;
int pid2;
volatile int i, j, k, l;
time_t time0 = time(NULL);
time_t time1 = time(NULL);

restart:
cnt = 0;
cnt2 = 0;
inc = INC;
pid = getpid();
p24_cnt = AE_ZEROP48();
p24_inc = AE_MOVPA24(inc);
p24_pid = AE_MOVPA24(pid);

while (1)
{
int errors = 0;

if ((cnt & 0xffffff) == 0) {
time0 = time1;
time1 = time(NULL);
printf("cnt:0x%x, pid:%d; Eatting cpu; time:%ld\n", cnt, pid, (time1 - time0));
for(i = 0; i<1000; i++) {
for(j = 0; j < 1000; j++) {
for(k = 0; k < 10; k++) {
l++;
}
}
}
time0 = time1;
time1 = time(NULL);
printf("cnt:0x%x, pid:%d; Eating Tie; time:%ld\n", cnt, pid, (time1 - time0));
}
cnt = (cnt + inc) & 0xffffff;
p24_cnt = AE_ADDP24(p24_cnt, p24_inc);
cnt2 = AE_MOVAP24S_L(p24_cnt) & 0xffffff;
pid2 = AE_MOVAP24S_L(p24_pid) & 0xffffff;
inc2 = AE_MOVAP24S_L(p24_inc) & 0xffffff;

if (cnt2 != cnt)
{
swapon("/tmp/cmt2", 0);
printf("Error: cnt2:0x%x != cnt:0x%x\n", cnt2, cnt);
errors++;
}
if (inc2 != inc)
{
swapon("/tmp/inc2", 0);
printf("Error: inc2:%d != inc:%d\n", cnt2, cnt);
errors++;
}
if ( pid2 != pid)
{
swapon("/tmp/pid2", 0);
printf("Error: pid2:%d != pid:%d\n", pid2, pid);
errors++;
}

if (errors) {
printf("for...\n");
for(i=0; i < 0x3FFFF; i++)
j++;
printf("sleep 10\n");
sleep(10);
printf("for...\n");
for(i=0; i < 0x3FFFF; i++)
j++;
printf("restart\n");
goto restart;
}
}
}
$

== Adding your codec to Buildroot ==

Xtensa developers provide detailed instructions on building the root filesystem and the Linux kernel.
* [[Buildroot_Build_Instructions|Instructions for building and booting Linux (buildroot)]].

Building a comprehensive development environment with buildroot can be a chalanging experience and worthy of providing some tips on process.
Here are notes of the configs used for the three menuconfigs in this 2nd snapshot
provided with SMP additions:
$ '''make [[HiFi-2 snapshot_2 SMP Snapshot menuconfig | menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP uclibc-menuconfig | uclibc-menuconfig]]'''
$ '''make [[HiFi-2 snapshot_2 SMP busybox-menuconfig | busybox-menuconfig]]'''

[TO BE DONE - making a new tar ball of saved files, building buildroot, ...]

== Known Problems being investigated, suggested that you know about and possibly avoid ==

1. Using NFS mounts with default parameters causes memory congestion. Use these mount options:

'''vers=2,rsize=4096,wsize=4096,hard,nointr,nolock,nolock,timeo=11,retrans=3,noauto'''

this is extremely important to add to your /etc/fstab on the target.

2. Can't swap over NFS yet, memory can get tight and cause application to be killed.
a. Trying procedure documented in U-Boot Manual.

3. Building the C development with X11 doesn't work with buildroot.

4. Though Mplayer plug-in can be compiled, Mplayer can be compiled but still has a few issues:
a. Can't be compiled -O0 due to limited memory while compiling one file,
b. Compiler infrequently crashes and make has to be restarted.
Not seeing this problem with root build on Fedore Core 9.
Perhaps this was caused by debug kernel or LTP using all of the memory.

5. U-boot has flash problems:
a. Sectors marked Read-Only come up Writeable after a reset/reboot.
b. Flashing a large number of sectors (like the kernel) sometimes
results in an Error (Ex: Vcc) and had to be retried.
c. Saw environment variables trashed on reset/reboot once.
It's possible that U-boot in flash could get whacked
and the board will need to be re-flashed. During a week
or two of testing I haven't see environment getting whacked.

6. gdb appears to be crashing on target when debugging
on latest root with uclibc left unstriped and with debug;
core dump sent to maxim.

7. U-Boot seems to hang periodically when loading the kernel with
tftp; appears to be worse when network activity is high.

8. 'top' command only shows all cpu's or cpu0; cpu 1 and 2 missing.

9. Program dore dump require ulimit -c to be set but root uses /bin/sh
which is a link to bash but causes it to skip running the bash
startup scripts. Changing root to /bin/bash seems to mess up
ssh logins.

=Further reading=

Main Xtensa Linux resources are:

* [http://linux-xtensa.org/ Linux/Xtensa Wiki]
* [http://wiki.linux-xtensa.org/index.php/Buildroot_Build_Instructions Buildroot Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Kernel_Build_Instructions Kernel Build Instructions]
* [http://wiki.linux-xtensa.org/index.php/Setting_up_U-Boot Setting up U-Boot]
* [http://lists.linux-xtensa.org/mailman/listinfo Linux/Xtensa Mailing List]
* http://git.linux-xtensa.org/cgi-bin/git.cgi GIT Repositories]

=Thanks to=

* piet
* marc
* dan

And the rest of the people in the Linux-Xtensa mailing list, if you cannot go through some of the steps, don't hesitate to ask on the mailing list, there's always somebody willing to help you!

SMP HiFi 2 Development Board

2009-11-13T16:43:49Z

Marc: Rewording

These instructions explain how to use HiFi-2 Codec Development environment on an LX200 FPGA board.

Some general notes on these instructions:

* They are a work in progress.

* The following was tested on x86 machines running RedHat Fedora Core 5.

== Introduction ==

This document is addressed to someone who received an LX200 board setup by Tensilica
for HiFi2 codec development.

This document goes over the steps needed to set up the LX200 board for codec development.
To summarize:
* Setup the board. It likely comes with U-boot preinstalled, ready to boot a linux kernel.
* Install '''git'''.
* Download buildroot and linux kernel trees, pre-configured and built for HiFi-2 development.
* Setup a TFTP server to provide the linux kernel to U-Boot.
* Setup an NFS server to export a linux root file system.
* Setup the Linux kernel to boot from the root file system provided by the NFS server.
Once the development board is up and running, this document:
* Suggests a possible way to tailor the board for easy codec development.
* Shows how to add the Tensilica provided codec packages to the Mplayer packages used by Buildroot, including building and installing.
* Demonstrates two procedures for compiling, linking, and debugging codecs.

All development is expected to be done on a Linux host. (One can in principle use Windows to
develop target libraries. However, linking and subsequent steps need to be done in Linux.)

== Downloading the Latest HiFI-2 Buildroot and Kernel Snapshots ==

The HiFi-2 development environment is maintained in a source code version control system named 'git'. The '''git''' tools are useful when working with this development environment, though they are not strictly necessary. This document generally assumes the use of '''git''', which provides more opportunities for modifying this environment as needed (e.g. building more optional buildroot packages). But points out alternatives to allow getting up and running without having to set it up.

=== Installing git ===

To install '''git''', download a recent tarball from the [http://www.kernel.org/pub/software/scm/git/ official site]. For example, <tt>cd</tt> to a location with enough disk space, and do:

$ wget http://www.kernel.org/pub/software/scm/git/git-1.6.5.tar.gz

Unpack the tarball, and make and install it. Note: the install step may need to be run as root.

$ gunzip git-1.6.5.tar.gz
$ tar xf git-1.6.5.tar
$ cd git-1.6.5
$ make
$ make install

This usually installs '''git''' to <tt>/usr/local/bin</tt> or <tt>$HOME/bin</tt>.

Using '''git''' provides easy access to the binaries used to bring up the codec development environment, and leaves in place the infrastructure to modify and build this environment should you wish to. Any changes to '''git'''-managed source trees are easily observed with the '''git''' tools.

=== Installing the Buildroot Snapshot ===

''Note: The HiFi-2 snapshot is in the process of being made.''

To install the buildroot environment (toolchain and root filesystem), <tt>cd</tt> to a location with a few GB of available disk space, and do:

$ git clone git://git.linux-xtensa.org/git/buildroot/buildroot-xtensa-HiFi2-Snapshot
$ cd buildroot-xtensa-HiFi2-Snapshot
$ git branch --track snapshot_2+SMP origin/snapshot_2+SMP
$ git checkout snapshot_2+SMP

The last two lines checkout the latest branch (preconfigured for the 3-core HiFi2 on the LX200).

You can examine the tree (git repository) and its history visually using <tt>git gui</tt>.

'''''No need to give two ways of doing the same thing? Delete this paragraph?'''''
The git GUI is also convenient for checking out the HiFi-2 snapshot and provides a comfortable way for viewing the state of the git repository. To check out the snapshot_2+SMP branch simply run the command 'git gui' and then pull down the branch->create menu. Next put ''snapshot_2+SMP'' into the Name block, select Tracking Branch in the Starting Revision section, and select the origin/snapshot_2+SMP branch. Finally hit the ''Create'' button. This will create your tracking branch which can be easy kept in sync with our git repository.

If there are issues installing '''git''', as a last resort, an alternative is ftp (may not always get updated, so may be dropped at some point):

http://www.linux-xtensa.org/pub/snapshots/buildroot-xtensa-smp.2-Nov-2009.tar.gz

=== Installing the Linux Kernel Snapshot ===

[TO BE DONE, including adding a snapshot_2+SMP branch]

== Setting up a TFTP Server to provide the Linux kernel to U-Boot ==

[TO BE DONE - Condider installing Kernel in FLASH to avoid need for TFTP]

== Setting up an NFS Server to export the Root Filesystem ==

The LX200 board running Linux needs to mount its root filesystem over NFS.
This filesystem was built using buildroot into a cpio format file,
and left in:

buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2/rootfs.xtensa_test_mmuhifi_c3.cpio

We will also be adding an additional minor changes to make your development environment more comfortable.

Pick a place on your workstation to export your root and unpack the cpio file into that directory.
For example here we will set up an export in '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''':

$ cd buildroot-xtensa-HiFi2-Snapshot/buildroot-xtensa-smp/binaries/HiFi-2
$ WHERE=$PWD
$ mkdir -p '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp'''
$ cd '''/exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp'''
$ cpio -i < $WHERE/rootfs.xtensa_test_mmuhifi_c3.cpio

Next add a line to /etc/exports:

/exports *(rw,no_root_squash,sync,no_wdelay)

and restart you nfs services:

$ /etc/rc.d/init.d/nfs restart
or
$ /sbin/chkconfig nfs on

The showmount command should show your NFS file system now being exported:

$ showmount -e
Export list for mypc.foobar.com:
/exports *
$

== Configuring U-Boot to Boot Linux ==

Your LX200 board should have arrived with U-Boot installed in the flash ready to use. Just connect a serial interface to a text based terminal emulation program like [http://en.wikipedia.org/wiki/Minicom minicom]. We usually just type:

'''minicom xtboard'''

the boards expect to communicate at with a baud rate of 38400.

Most users of this board are interested in developing codecs on and will prefer to just boot linux with the root file system we just described how to export on you NFS server. We will use git now to pull a snapshot of a performace 2.6.29 linux kerenel and configure U-Boot to automatically boot it after a power cycle.

U-Boot> '''setenv serverip 192.168.11.78''' [TFTP server IP Address: RTOS-LAB2]
U-Boot> '''setenv nfsroot_server 192.168.11.55''' [Root NFS Servers IP Address: My Workstation]
U-Boot> '''setenv ipaddr 192.168.11.155''' [HOST IP address]
U-Boot> '''setenv bootfile uImage.xtensa-2.6.29-smp.test_mmuhifi_c3''' [File to fetch with TFTP and pass to bootm]
U-Boot> '''setenv root-path /exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp''' [WARNING: Limit path to < 50 characters]
U-Boot> '''setenv bootargs_using_bootp=console=ttyS0,38400 ip=bootp root=nfs coredump_filter=0xff''' [Args passed to Linux while booting with BOOTP proto]
U-boot> '''setenv bootargs console=ttyS0,38400 ip=dhcp root=/dev/nfs rw nfsroot=${nfsroot_server}:${root-path}''' [Args passed to Linux while booting with DHCP proto]
U-boot> '''setenv bootcmd tftpboot\; bootm''' [Boot Linux after fetching it with TFTP]
U-Boot> '''setenv bootdelay=20''' [Delay 20 seconds before booting automaticaly]
U-Boot> '''setenv autostart yes''' [Boot automatically on power-up/reset]
U-Boot> '''saveenv'''
U-Boot>

[REMIND: '''Shorten /exports/LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp to /exports/LINUX_ROOT.HiFi-2_DemoBoard'''] [Name to long for the kernel]

== Tailoring your system prior to developing your codec ==

To make your experience more pleasant we suggest you tailor you environment.
Here are some of the changes that we have found helpful:

1. Add a root password to that you can login with ssh.
2. Run rdate with an ntp server on booting.
3. Add NFS mounts to /etc/fstab for your code and buildroot code.
4. Copy in previous ssh server encryption keys to /etc/dropbear to speed up your initial boot.
5. Mount a 'default' user home directory with:
a. Linux Test Suite pre-patch to test the system
b. Audio test example files
c. Copies of Mplayer and its Plug-ins from Buildroot modified slightly to make installation easy.
d. Misc audio test programs.

[TO BE DONE - Where to get 'default' user home directory tar ball and 1st boot patch]

== Compiling your codec and linking it with Mplayer ==

Mplayer is provided as an example environment for developing and testing Codecs. There
are two ways to build Mplayer and the plug-in modules that use the codecs. The buildroot
tree (pulled with git) has a copy of mplayer and the plugins that can be built in the
snapshot via 'make menuconfig'. This is a good environment to use once codecs are
developed and debugged.

To facilitate development the mplayer packages can be copied to your NFS mounted development
environment. From there you can just configure mplayer to compile on the board and debug
mplayer and your codecs with gdb locally.

In the default user home directory we have a directory /home/default/buildroot_mplayer_stuff
with a copy of three of the mplayer packages.

[root@hifi buildroot_mplayer_stuff]# ls -l
drwxr-xr-x 34 root root 4096 Nov 10 05:01 MPlayer-1.0rc2/
drwxr-xr-x 4 root root 4096 Nov 10 01:36 mplayer_hifi2_aacplus_v2_plugin/
drwxr-xr-x 3 root root 4096 Nov 10 00:57 mplayer_hifi2_mp3_plugin/

they were simply copied from the buildroot-xtensa-HiFi2-Snapshot.2/package directory.

To get your development environment ready to compile the mplayer plug-ins you need
to configure Mplayer to use the local C compiler and linker:

# cd /home/default/buildroot_mplayer_stuff/MPlayer-1.0rc2/
# CFLAGS="-O0 -g3" ./configure

This will take about 15 minutes to configure. After that you can build the
plugins or mplayer. If you want to recompile mplayer it's likely best/necessary
to use the same args to .configure as used by buildroot:

.CFLAGS="-O0 -g3" ./configure \
--prefix=/usr \
--confdir=/etc/mplayer \
--with-extraincdir=/usr/include \
--with-extralibdir=/lib \
--disable-gui \
--enable-mad \
--enable-fbdev \
--disable-mencoder \
--disable-dvdnav \
--disable-dvdread \
--disable-dvdread-internal \
--disable-libdvdcss-internal \
--disable-big-endian \
--disable-nemesi \
--disable-tv \
--enable-dynamic-plugins

Let's focus on the plugins as they are closest to the goal of developing codecs.
We modified the Makefile of the codes slightly, and hope to check this in
to buildroot. These additions just instruct make how to install the plugins.
For example the mp3 plugin has this addition:

target_install::
-mkdir /etc/mplayer
cp codecs.conf /etc/mplayer
-mkdir /usr/lib/mplayer
cp ad_xa_mp3_dec.so /usr/lib/mplayer/
cp xa_mp3_dec.so /usr/lib/mplayer
chmod 755 /usr/lib/mplayer/ad_xa_mp3_dec.so
chmod 755 /usr/lib/mplayer/xa_mp3_dec.so

It's just providing a codec config file for mplayer at '''/etc/mplayer/codecs.conf''' and
copying the plug-in to '''/usr/lib/mplayer'''. To install the mp3 codec plugin and mplayer
config file just copy your codec that was compiled with Xcc to the directory, compile it,
and install.

# cd /fac/vol6/audio/release/bin/l32r_LE5_pic
# cp xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz /tmp
#
# cd /home/default/buildroot_mplayer_stuff
# cd mplayer_hifi2_mp3_plugin
# cp /tmp/xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz .
# gunzip xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tgz
# tar xf xa_hifi2_l32r_LE5_pic_mp3_dec_lib_3_1_api_1_15_lib.tar
# make
# make target_install

The unpacking of the Tensilica mp3 code tar ball will install the following files:

xa_mp3_dec/
xa_mp3_dec/README
xa_mp3_dec/include/
xa_mp3_dec/include/mp3_dec/
xa_mp3_dec/include/mp3_dec/xa_mp3_dec_api.h
xa_mp3_dec/include/xa_apicmd_standards.h
xa_mp3_dec/include/xa_error_handler.h
xa_mp3_dec/include/xa_error_standards.h
xa_mp3_dec/include/xa_memory_standards.h
xa_mp3_dec/include/xa_type_def.h
xa_mp3_dec/test/
xa_mp3_dec/test/build/
xa_mp3_dec/test/build/ldscript_stream_data.txt
xa_mp3_dec/test/build/makefile_testbench_sample
xa_mp3_dec/test/build/paramfilesimple.txt
xa_mp3_dec/test/include/
xa_mp3_dec/test/include/id3_tag_decode.h
xa_mp3_dec/test/src/
xa_mp3_dec/test/src/xa_mp3_dec_sample_testbench.c
xa_mp3_dec/test/src/id3_tag_decode.c
xa_mp3_dec/test/src/stream_data.c
xa_mp3_dec/test/src/xa_mp3_dec_error_handler.c
xa_mp3_dec/test/test_inp/
xa_mp3_dec/test/test_inp/compl.mp3
xa_mp3_dec/test/test_inp/hihat.mp3
xa_mp3_dec/test/test_out/
xa_mp3_dec/test/test_out/force_mkdir.txt
xa_mp3_dec/test/test_ref/
xa_mp3_dec/test/test_ref/compl_24bit.wav
xa_mp3_dec/test/test_ref/hihat_16bit.wav
xa_mp3_dec/lib/
xa_mp3_dec/lib/xa_mp3_dec.a
xa_mp3_dec/doc/
xa_mp3_dec/doc/HiFi2-MP3-DecoderProgrammersGuide.pdf

[TO BE DONE - Add missing C file, make clean deletes it!]

The xa_mp3_dec.a archive will be used by the Makefile in
the mplayer_hifi2_mp3_plugin directory to make the mplayer plug-in.
Section 6 of the '''Using Tensilica HiFi 2 Codec on Xtensa Linux with MPlayer'' Application Note
has a detailed description of the encapsulation process used by the plug-ins.

== Adding your codec to Buildroot ==
[TO BE DONE]

== Known Problems being investigated, suggested that you know about and possibly avoid ==

1. Playing raw audio .wav files eats a lot of memory and can congest the system.
a. Using NFS over TCP helps with access time, perhaps an ethernet driver bug.
2. Can't swap over NFS yet, memory can get tight and cause application to be killed.
a. Try proceedure documented in U-Boot Manual.
3. Compressed files seem to be un-accessable over NFS.
4. Building the C development doesn't work with X11.
5. Though Mplayer plug-in can be compiled, Mplayer still has a few issues.
a. Can't be compiled -O0
b. Compiler infrequently crashes and make has to be restarted.

KnownIssues

2009-10-14T14:49:14Z

Marc: Typo/consistency fixes

= Known Kernel Issues and Limitations =

This page contains recommendations, notes, limitations, and requirements for the development of software on systems using Xtensa processors running Linux.

Eventually all these should be duly reported and tracked in
the [http://bugs.linux-xtensa.org Mantis bug tracker].
For the time being, here are some of the main known issues (this is by no means an exhaustive list!).

== 128 MB RAM Limit ==

Kernel highmem support has not yet been implemented, 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.

== 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/Transswitch/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/Transswitch/a2000_src/a2000_src/Linux_atlanta/ctlm-cpe/drivers/ctlmeth/

Evaluation Platforms

2009-09-19T20:35:59Z

Marc: Remove for now.

[[image:board.jpg|right]]
= Evaluation and Prototyping Platforms =

The following boards and simulators can be used for evaluation and prototyping purposes. Evaluation platforms generally fall into one of the following categories:
* instruction set simulators,
* emulation systems that use FPGAs to implement any Xtensa or Diamond core (within the capacity of the FPGAs), and
* boards that integrate a specific configured Xtensa or Diamond core(s) into an ASIC.
Field programmable gate arrays (FPGA) contain programmable logic that can be re-configured to emulate complex logic. Although slower than the dedicated circuitry of an ASIC (application specific integrated circuit), their re-configurability and practically zero NRE make them very useful for prototyping (for example, trying multiple Xtensa processor variants or configurations) or small volume applications.

== Instruction Set Simulator ==

Instruction Set Simulators (ISS) mimic the behavior of processors by simulating instructions, memory interface, and other I/O components. This allows developers to run and test their software long before real hardware becomes available. Functional simulators provide the best performance, whereas cycle-accurate simulators provide timing accuracy compatible to that of real hardware. The latter simulate the processor pipeline and external components synchronized to a virtual clock. Although this overhead reduces their performance, it can provide vital information to improve the implementation of algorithms.

=== Tensilica ISS ===

[http://www.tensilica.com/ Tensilica] offers a commercial functional simulator (TurboXim) and cycle-accurate simulator for the Xtensa processor architecture, as part of their standard software development tools. (You may be able to try a free limited time evaluation copy of this toolset.) Tensilica also offers XTMP and XTSC for modeling systems of one or multiple processors alongside custom functional or cycle-accurate software models for other components. Please visit [http://www.tensilica.com/ Tensilica's] website for further information.

The standalone simulator (xt-iss), for example, simply takes an ELF file as its argument and starts simulating instructions from the reset vector. The option <code>--turbo</code> invokes the (much faster) functional simulator TurboXim.

xt-iss ''[--turbo]'' Image.elf

== Emulation Platforms and Systems ==

=== Avnet Virtex-4 LX60 and LX200 ===

[http://www.em.avnet.com Avnet] offers the following development platforms for the Xilinx Virtex-4 LX FPGA that can emulate various
Xtensa processor configurations. The [http://www.em.avnet.com/tensilica1 LX60] is based on the Xilinx 4VLX60 and comes
with a 10/100 Ethernet PHY, DDR memory, flash memory, serial port, and 2 x 16 character LCD panel. The MAC controller, however, needs to be implemented inside the FPGA. MAC controllers are available from different vendors. [http://opencores.org OpenCores], for example, provides a free Ethernet controller supported by Linux and other operating systems. The [http://www.em.avnet.com/tensilica2 LX200] is based on the Xilinx XC4VLX200 and can emulate more complex processor configurations and extensions (for example the [http://www.tensilica.com/products/hifi_audio.htm HiFi 2 Audio Engine]) and provides the same components as the LX60 except for the LCD panel.

[http://www.tensilica.com Tensilica] provides a bitstream that describes the configuration data to emulate the Diamond Standard DC232L processor (Rev.B) on the LX60 FPGA. Tensilica refers to this board and bitstream combination as the XTAV60 board. It also includes support for the OpenCores Ethernet MAC. For further information, please, contact [http://www.tensilica.com/company/contact_us.htm Tensilica] directly.

=== Eve ZeBu ===

[http://www.eve-team.com Eve] offers an emulation and verification system that can be used to emulate Xtensa processors. Similar to FPGA boards, the ZeBu system emulates the processor, but has a higher capacity to emulate larger processor configurations and additional peripherals. It also provides direct access to signals for debugging and verification.

See the [[Linux on ZeBu]] page or contact [http://www.eve-team.com Eve] directly to request additional information.

== ASIC Evaluation Platforms ==

=== Stretch S55DVKxx and S56DVKxx ===

[http://www.stretchinc.com Stretch] provides software-configurable processors based on the Xtensa architecture. The S5000 processor supports Linux, and at 300MHz, it runs 5-10 times faster than FPGA based emulation platforms. The S55DVKxx and S56DVKxx development platforms provide 10/100/1000 Ethernet, serial, PCI (only S56DVKxx), and other interfaces.

The Stretch platforms come with RedBoot as the bootloader. It can download and boot the kernel over network using TFTP or from flash. Make sure that RedBoot is configured with a valid Ethernet address or set to DHCP to obtain a valid address. The following commands load the kernel image ''zImage.redboot'' and boot the kernel:

RedBoot> load -r -b 0xd0200000 -h 192.168.1.5 zImage.redboot
RedBoot> exec 0xd0200000

Note that RedBoot requires that the tftp host is in the same subnet as the board.

Repository Access

2009-07-26T20:34:47Z

Marc: /* Accessing Linux kernel sources */ Mention 2.6.29-smp tree

= Access to GIT Repositories =

The <tt>linux-xtensa.org</tt> site hosts a number of GIT repositories.
They provide access to the latest sources for their respective projects.
Alternatively, one can download
[[Buildroot_Snapshots|snapshot releases]] which
are updated much less frequently.

The following sections describe how to access these source repositories.

== Accessing buildroot sources ==

Buildroot is used to build the toolchain and root filesystem.
The following downloads a copy of the entire GIT repository:

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

Those with write access to the repository should use the <tt>git+ssh</tt> method instead, like this:

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

Commits to this tree are automatically posted to the
[http://lists.linux-xtensa.org/mailman/listinfo/buildroot-xtensa-commits buildroot-xtensa-commits list].

== Accessing Linux kernel sources ==

There are normally multiple Linux kernel trees to choose from.
At the time of writing, the <tt>xtensa-2.6.24</tt> tree is the lastest "official" tree.
This tree is based on the released 2.6.24 kernel from <tt>kernel.org</tt>.
However, most of the activity currently is in an unofficial <tt>2.6.29-smp</tt> tree.

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

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

This creates and populates the ''<dir>'' directory. If ''<dir>'' is omitted, it defaults to <tt>xtensa-2.6.24</tt> (the last non-extension part of the cloned path).
Those with write access to the repository should use the <tt>git+ssh</tt> method instead, like this:

$ git clone git+ssh://git.linux-xtensa.org/git/kernel/xtensa-2.6.24 <dir>

Commits to this tree are automatically posted to the
[http://lists.linux-xtensa.org/mailman/listinfo/linux-xtensa-devel-commits linux-xtensa-devel-commits list].

== Accessing U-Boot bootloader sources ==

A preliminary version of U-Boot for the Xtensa architecture is available.
The following downloads a copy of the entire GIT repository:

$ git clone git://git.linux-xtensa.org/git/u-boot/u-boot-xtensa.git u-boot

Those with write access to the repository should use the <tt>git+ssh</tt> method instead, like this:

$ git clone git+ssh://git.linux-xtensa.org/git/u-boot/u-boot-xtensa.git u-boot

'' '''PLEASE NOTE:''' These paths are likely to change when the port becomes official.''

Commits to this tree are not yet automatically posted to any list.

== Write Access ==

Only a small number of core developers have write access to these
repositories. To submit changes, you are encouraged to submit patches to
the [http://lists.linux-xtensa.org/mailman/listinfo/linux-xtensa linux-xtensa mailing list].
Contributors are expected to consistently provide
good patches, and have a certain level of involvement and commitment
to the relevant project, before being considered for write access.

LTP Results

2009-05-20T23:44:03Z

Marc: Include link to more accurate LTP results HTML page

= LTP Test Results =

One of the more common ways of testing the Linux kernel is to use the [http://ltp.sourceforge.net/ Linux Test Project (LTP)] testsuite. LTP contains many different tests and testsuites, a number of which are often not applicable in a given environment or test setup.

Running LTP in a system constructed using [[Buildroot_Build_Instructions| buildroot]] typically involves the following steps:

* When configuring buildroot (using e.g. <tt>make menuconfig</tt>), under '''Package Selection for the target''', unselect '''Hide applications that are provided by busybox''', select '''<tt>bash</tt>''', and select '''<tt>ltp-testsuite</tt>'''. Under later versions of LTP that can generate HTML, also go deeper in '''Interpreter languages / Scripting''' and select '''<tt>microperl</tt>'''. Then make buildroot as usual. On the target, the LTP testsuite ends up in <tt>/root/ltp-full-</tt>''<VERSION>''.
* LTP is generally much too big (~150 to 350 MB) to put in a root filesystem that is linked into the kernel (such as initramfs). So you'll generally need to put your root filesystem somewhere else, such as [[Buildroot_Build_Instructions#Mounting_the_Root_Filesystem_Over_NFS| mounting over NFS]].
* Run LTP. This can be as simple as: <tt>cd /root/ltp-full-20070228 ; ./runltp</tt> although you'll typically want to pass <tt>runltp</tt> a few options to specify output files, tests to run, etc.

In some older or bleeding-edge/unstable environments, some tests may crash the kernel or just hang. You may need to comment out these tests from the relevant test series under <tt>/runtest/</tt>, or simply not request that test when running LTP, to complete running the tests.

== Results for the second snapshot (of July 2008) ==

Here are some [http://www.linux-xtensa.org/ltp/20090514c.html unofficial LTP results run on May 14, 2009] (and a [http://www.linux-xtensa.org/ltp/20090514c3.html more accurate report] from a patched copy of LTP's genhtml)
for the Linux for Xtensa [http://www.linux-xtensa.org/download.html snapshot] of July 11, 2008.

The version of LTP used by buildroot, as of that snapshot, is 20070228. However, that version does not generate HTML output. This test run was made using LTP version 20090430 instead, to get HTML formatted results. A number of buildroot files were updated to support this version of LTP (see below).

LTP version 20090430 runs a few more tests by default relative to version 20070228. Many of these new tests require a much larger set of packages installed on the target than the bare minimum root filesystem one gets by default following [[Buildroot_Build_Instructions| buildroot build instructions]]. Some of these tests are even specific to the x86 architecture. Thus, instead of running LTP with a default set of tests, LTP was run with a specific set that excludes most of the new ones (but includes <tt>timer</tt>).

Also note that a number of kernel bugs were fixed since that snapshot, as reflected in various kernel git trees on linux-xtensa.org . Three of these caused the kernel to crash or hang, and were commented out to obtain these test results: <tt>mm01</tt> in <tt>runtest/mm</tt>, <tt>sem01</tt> in <tt>runtest/ipc</tt>, and <tt>hackbench01</tt> in <tt>runtest/sched</tt>.

Here is how LTP was invoked for this run:

cd /root/ltp-full-20090430
time ./runltp -l 20090514c.log -g 20090514c.html -o 20090514c.out -f syscalls,fs,fsx,mm,ipc,sched,math,nptl,pty,timers

You may also be interested to note that due to certain bugs in LTP itself, LTP HTML output erroneously reports certain tests as passing when they are not (regardless of architecture). Careful reading of the Test-Output column (in the absence of a clear PASS line therein) usually indicates the actual result.

=== Buildroot patches for LTP 20090430 ===

* Remove <tt>package/ltp-testsuite/ltp-testsuite-sh-is-not-C-code.patch</tt>
* Edit <tt>package/ltp-testsuite/ltp-testsuite.mk</tt>:

6c6,7
< LTP_TESTSUITE_VERSION:=20070228
---
> LTP_TESTSUITE_VERSION:=20090430
> #LTP_TESTSUITE_VERSION:=20070228
17a19
> ltp-testsuite-newer.patch \

* Edit <tt>package/ltp-testsuite/ltp-testsuite.patch</tt>:

40,41c40,41
< @@ -20,7 +20,7 @@
< LDLIBS += -L../../../../lib -lltp
---
> @@ -23,7 +23,7 @@
> %_64: CFLAGS += -D_FILE_OFFSET_BITS=64
44,45c44,45
< -TARGETS = $(patsubst %.c,%,$(SRCS))
< +TARGETS =#$(patsubst %.c,%,$(SRCS))
---
> -TARGETS += $(patsubst %.c,%,$(SRCS))
> +TARGETS +=#$(patsubst %.c,%,$(SRCS))
52c52
< @@ -85,9 +85,7 @@
---
> @@ -90,9 +90,7 @@
63c63
< @@ -96,10 +94,6 @@
---
> @@ -101,10 +99,6 @@

* Add <tt>package/ltp-testsuite/ltp-testsuite-newer.patch</tt> (this disables a number of tests that don't build because they rely on recent system calls that did not exist in uClibc as of the July 2008 snapshot):

diff -ur ltp-full-20090430/testcases/kernel/syscalls/remap_file_pages/Makefile ltp-full-20090430-patched/testcases/kernel/syscalls/remap_file_pages/Makefile
--- ltp-full-20090430/testcases/kernel/syscalls/remap_file_pages/Makefile 2009-05-12 10:44:15.000000000 -0700
+++ ltp-full-20090430-patched/testcases/kernel/syscalls/remap_file_pages/Makefile 2009-05-12 10:40:28.000000000 -0700
@@ -20,7 +20,7 @@
LDLIBS += -L../../../../lib -lltp

SRCS = $(wildcard *.c)
-TARGETS = $(patsubst %.c,%,$(SRCS))
+TARGETS = #$(patsubst %.c,%,$(SRCS))

all: $(TARGETS)

diff -ur ltp-full-20090430/testcases/kernel/syscalls/signalfd/Makefile ltp-full-20090430-patched/testcases/kernel/syscalls/signalfd/Makefile
--- ltp-full-20090430/testcases/kernel/syscalls/signalfd/Makefile 2008-11-11 00:31:27.000000000 -0800
+++ ltp-full-20090430-patched/testcases/kernel/syscalls/signalfd/Makefile 2009-05-12 10:55:16.000000000 -0700
@@ -19,7 +19,7 @@
LDLIBS += -L../../../../lib -lltp

SRCS = $(wildcard *.c)
-TARGETS = $(patsubst %.c,%,$(SRCS))
+TARGETS = #$(patsubst %.c,%,$(SRCS))

all: $(TARGETS)

diff -ur ltp-full-20090430/testcases/kernel/syscalls/signalfd4/Makefile ltp-full-20090430-patched/testcases/kernel/syscalls/signalfd4/Makefile
--- ltp-full-20090430/testcases/kernel/syscalls/signalfd4/Makefile 2009-01-16 02:07:55.000000000 -0800
+++ ltp-full-20090430-patched/testcases/kernel/syscalls/signalfd4/Makefile 2009-05-12 10:55:54.000000000 -0700
@@ -20,7 +20,7 @@
LDLIBS += -L../../../../lib -lltp

SRCS = $(wildcard *.c)
-TARGETS = $(patsubst %.c,%,$(SRCS))
+TARGETS = #$(patsubst %.c,%,$(SRCS))

all: $(TARGETS)

diff -ur ltp-full-20090430/testcases/kernel/syscalls/splice/Makefile ltp-full-20090430-patched/testcases/kernel/syscalls/splice/Makefile
--- ltp-full-20090430/testcases/kernel/syscalls/splice/Makefile 2009-05-12 11:12:23.000000000 -0700
+++ ltp-full-20090430-patched/testcases/kernel/syscalls/splice/Makefile 2009-05-12 11:15:27.000000000 -0700
@@ -20,7 +20,7 @@
LDLIBS += -L../../../../lib -lltp

SRCS = $(wildcard *.c)
-TARGETS = $(patsubst %.c,%,$(SRCS))
+TARGETS = #$(patsubst %.c,%,$(SRCS))

all: $(TARGETS)

Only in ltp-full-20090430/testcases/kernel/syscalls/splice: splice01
diff -ur ltp-full-20090430/testcases/kernel/syscalls/tee/Makefile ltp-full-20090430-patched/testcases/kernel/syscalls/tee/Makefile
--- ltp-full-20090430/testcases/kernel/syscalls/tee/Makefile 2009-05-12 11:12:52.000000000 -0700
+++ ltp-full-20090430-patched/testcases/kernel/syscalls/tee/Makefile 2009-05-12 11:12:46.000000000 -0700
@@ -20,7 +20,7 @@
LDLIBS += -L../../../../lib -lltp

SRCS = $(wildcard *.c)
-TARGETS = $(patsubst %.c,%,$(SRCS))
+TARGETS = #$(patsubst %.c,%,$(SRCS))

all: $(TARGETS)

diff -ur ltp-full-20090430/testcases/kernel/syscalls/vmsplice/Makefile ltp-full-20090430-patched/testcases/kernel/syscalls/vmsplice/Makefile
--- ltp-full-20090430/testcases/kernel/syscalls/vmsplice/Makefile 2009-05-12 11:13:17.000000000 -0700
+++ ltp-full-20090430-patched/testcases/kernel/syscalls/vmsplice/Makefile 2009-05-12 11:13:09.000000000 -0700
@@ -21,7 +21,7 @@
LDLIBS += -L../../../../lib -lltp

SRCS = $(wildcard *.c)
-TARGETS = $(patsubst %.c,%,$(SRCS))
+TARGETS = #$(patsubst %.c,%,$(SRCS))

all: $(TARGETS)

diff -ur ltp-full-20090430/testcases/network/lib6/Makefile ltp-full-20090430-patched/testcases/network/lib6/Makefile
--- ltp-full-20090430/testcases/network/lib6/Makefile 2009-01-22 01:26:10.000000000 -0800
+++ ltp-full-20090430-patched/testcases/network/lib6/Makefile 2009-05-12 11:45:19.000000000 -0700
@@ -24,8 +24,8 @@
LOADLIBES+= -L../../../lib runcc.a -lltp -lpthread

SRCS=$(wildcard *.c)
-TARGETS= asapi_01 asapi_02 asapi_03 asapi_04 asapi_05 asapi_06 asapi_07 \
- getaddrinfo_01 in6_01 in6_02
+TARGETS= asapi_01 asapi_02 asapi_03 asapi_07 \
+ in6_02

all: $(TARGETS)

LTP Results

2009-05-19T23:21:54Z

Marc: Add preliminary LTP test results for the July 2008 snapshot

= LTP Test Results =

One of the more common ways of testing the Linux kernel is to use the [http://ltp.sourceforge.net/ Linux Test Project (LTP)] testsuite. LTP contains many different tests and testsuites, a number of which are often not applicable in a given environment or test setup.

Running LTP in a system constructed using [[Buildroot_Build_Instructions| buildroot]] typically involves the following steps:

* When configuring buildroot (using e.g. <tt>make menuconfig</tt>), under '''Package Selection for the target''', unselect '''Hide applications that are provided by busybox''', select '''<tt>bash</tt>''', and select '''<tt>ltp-testsuite</tt>'''. Under later versions of LTP that can generate HTML, also go deeper in '''Interpreter languages / Scripting''' and select '''<tt>microperl</tt>'''. Then make buildroot as usual. On the target, the LTP testsuite ends up in <tt>/root/ltp-full-</tt>''<VERSION>''.
* LTP is generally much too big (~150 to 350 MB) to put in a root filesystem that is linked into the kernel (such as initramfs). So you'll generally need to put your root filesystem somewhere else, such as [[Buildroot_Build_Instructions#Mounting_the_Root_Filesystem_Over_NFS| mounting over NFS]].
* Run LTP. This can be as simple as: <tt>cd /root/ltp-full-20070228 ; ./runltp</tt> although you'll typically want to pass <tt>runltp</tt> a few options to specify output files, tests to run, etc.

In some older or bleeding-edge/unstable environments, some tests may crash the kernel or just hang. You may need to comment out these tests from the relevant test series under <tt>/runtest/</tt>, or simply not request that test when running LTP, to complete running the tests.

== Results for the second snapshot (of July 2008) ==

Here are some [http://www.linux-xtensa.org/ltp/20090514c.html unofficial LTP results run on May 14, 2009]
for the Linux for Xtensa [http://www.linux-xtensa.org/download.html snapshot] of July 11, 2008.

The version of LTP used by buildroot, as of that snapshot, is 20070228. However, that version does not generate HTML output. This test run was made using LTP version 20090430 instead, to get HTML formatted results. A number of buildroot files were updated to support this version of LTP (see below).

LTP version 20090430 runs a few more tests by default relative to version 20070228. Many of these new tests require a much larger set of packages installed on the target than the bare minimum root filesystem one gets by default following [[Buildroot_Build_Instructions| buildroot build instructions]]. Some of these tests are even specific to the x86 architecture. Thus, instead of running LTP with a default set of tests, LTP was run with a specific set that excludes most of the new ones (but includes <tt>timer</tt>).

Also note that a number of kernel bugs were fixed since that snapshot, as reflected in various kernel git trees on linux-xtensa.org . Three of these caused the kernel to crash or hang, and were commented out to obtain these test results: <tt>mm01</tt> in <tt>runtest/mm</tt>, <tt>sem01</tt> in <tt>runtest/ipc</tt>, and <tt>hackbench01</tt> in <tt>runtest/sched</tt>.

Here is how LTP was invoked for this run:

cd /root/ltp-full-20090430
time ./runltp -l 20090514c.log -g 20090514c.html -o 20090514c.out -f syscalls,fs,fsx,mm,ipc,sched,math,nptl,pty,timers

You may also be interested to note that due to certain bugs in LTP itself, LTP HTML output erroneously reports certain tests as passing when they are not (regardless of architecture). Careful reading of the Test-Output column (in the absence of a clear PASS line therein) usually indicates the actual result.

=== Buildroot patches for LTP 20090430 ===

* Remove <tt>package/ltp-testsuite/ltp-testsuite-sh-is-not-C-code.patch</tt>
* Edit <tt>package/ltp-testsuite/ltp-testsuite.mk</tt>:

6c6,7
< LTP_TESTSUITE_VERSION:=20070228
---
> LTP_TESTSUITE_VERSION:=20090430
> #LTP_TESTSUITE_VERSION:=20070228
17a19
> ltp-testsuite-newer.patch \

* Edit <tt>package/ltp-testsuite/ltp-testsuite.patch</tt>:

40,41c40,41
< @@ -20,7 +20,7 @@
< LDLIBS += -L../../../../lib -lltp
---
> @@ -23,7 +23,7 @@
> %_64: CFLAGS += -D_FILE_OFFSET_BITS=64
44,45c44,45
< -TARGETS = $(patsubst %.c,%,$(SRCS))
< +TARGETS =#$(patsubst %.c,%,$(SRCS))
---
> -TARGETS += $(patsubst %.c,%,$(SRCS))
> +TARGETS +=#$(patsubst %.c,%,$(SRCS))
52c52
< @@ -85,9 +85,7 @@
---
> @@ -90,9 +90,7 @@
63c63
< @@ -96,10 +94,6 @@
---
> @@ -101,10 +99,6 @@
68c68
< -#define MAX_SWAPFILES 32
---
> -#define MAX_SWAPFILES 32

* Add <tt>package/ltp-testsuite/ltp-testsuite-newer.patch</tt> (this disables a number of tests that don't build because they rely on recent system calls that did not exist in uClibc as of the July 2008 snapshot):

diff -ur ltp-full-20090430/testcases/kernel/syscalls/remap_file_pages/Makefile ltp-full-20090430-patched/testcases/kernel/syscalls/remap_file_pages/Makefile
--- ltp-full-20090430/testcases/kernel/syscalls/remap_file_pages/Makefile 2009-05-12 10:44:15.000000000 -0700
+++ ltp-full-20090430-patched/testcases/kernel/syscalls/remap_file_pages/Makefile 2009-05-12 10:40:28.000000000 -0700
@@ -20,7 +20,7 @@
LDLIBS += -L../../../../lib -lltp

SRCS = $(wildcard *.c)
-TARGETS = $(patsubst %.c,%,$(SRCS))
+TARGETS = #$(patsubst %.c,%,$(SRCS))

all: $(TARGETS)

diff -ur ltp-full-20090430/testcases/kernel/syscalls/signalfd/Makefile ltp-full-20090430-patched/testcases/kernel/syscalls/signalfd/Makefile
--- ltp-full-20090430/testcases/kernel/syscalls/signalfd/Makefile 2008-11-11 00:31:27.000000000 -0800
+++ ltp-full-20090430-patched/testcases/kernel/syscalls/signalfd/Makefile 2009-05-12 10:55:16.000000000 -0700
@@ -19,7 +19,7 @@
LDLIBS += -L../../../../lib -lltp

SRCS = $(wildcard *.c)
-TARGETS = $(patsubst %.c,%,$(SRCS))
+TARGETS = #$(patsubst %.c,%,$(SRCS))

all: $(TARGETS)

diff -ur ltp-full-20090430/testcases/kernel/syscalls/signalfd4/Makefile ltp-full-20090430-patched/testcases/kernel/syscalls/signalfd4/Makefile
--- ltp-full-20090430/testcases/kernel/syscalls/signalfd4/Makefile 2009-01-16 02:07:55.000000000 -0800
+++ ltp-full-20090430-patched/testcases/kernel/syscalls/signalfd4/Makefile 2009-05-12 10:55:54.000000000 -0700
@@ -20,7 +20,7 @@
LDLIBS += -L../../../../lib -lltp

SRCS = $(wildcard *.c)
-TARGETS = $(patsubst %.c,%,$(SRCS))
+TARGETS = #$(patsubst %.c,%,$(SRCS))

all: $(TARGETS)

diff -ur ltp-full-20090430/testcases/kernel/syscalls/splice/Makefile ltp-full-20090430-patched/testcases/kernel/syscalls/splice/Makefile
--- ltp-full-20090430/testcases/kernel/syscalls/splice/Makefile 2009-05-12 11:12:23.000000000 -0700
+++ ltp-full-20090430-patched/testcases/kernel/syscalls/splice/Makefile 2009-05-12 11:15:27.000000000 -0700
@@ -20,7 +20,7 @@
LDLIBS += -L../../../../lib -lltp

SRCS = $(wildcard *.c)
-TARGETS = $(patsubst %.c,%,$(SRCS))
+TARGETS = #$(patsubst %.c,%,$(SRCS))

all: $(TARGETS)

Only in ltp-full-20090430/testcases/kernel/syscalls/splice: splice01
diff -ur ltp-full-20090430/testcases/kernel/syscalls/tee/Makefile ltp-full-20090430-patched/testcases/kernel/syscalls/tee/Makefile
--- ltp-full-20090430/testcases/kernel/syscalls/tee/Makefile 2009-05-12 11:12:52.000000000 -0700
+++ ltp-full-20090430-patched/testcases/kernel/syscalls/tee/Makefile 2009-05-12 11:12:46.000000000 -0700
@@ -20,7 +20,7 @@
LDLIBS += -L../../../../lib -lltp

SRCS = $(wildcard *.c)
-TARGETS = $(patsubst %.c,%,$(SRCS))
+TARGETS = #$(patsubst %.c,%,$(SRCS))

all: $(TARGETS)

diff -ur ltp-full-20090430/testcases/kernel/syscalls/vmsplice/Makefile ltp-full-20090430-patched/testcases/kernel/syscalls/vmsplice/Makefile
--- ltp-full-20090430/testcases/kernel/syscalls/vmsplice/Makefile 2009-05-12 11:13:17.000000000 -0700
+++ ltp-full-20090430-patched/testcases/kernel/syscalls/vmsplice/Makefile 2009-05-12 11:13:09.000000000 -0700
@@ -21,7 +21,7 @@
LDLIBS += -L../../../../lib -lltp

SRCS = $(wildcard *.c)
-TARGETS = $(patsubst %.c,%,$(SRCS))
+TARGETS = #$(patsubst %.c,%,$(SRCS))

all: $(TARGETS)

diff -ur ltp-full-20090430/testcases/network/lib6/Makefile ltp-full-20090430-patched/testcases/network/lib6/Makefile
--- ltp-full-20090430/testcases/network/lib6/Makefile 2009-01-22 01:26:10.000000000 -0800
+++ ltp-full-20090430-patched/testcases/network/lib6/Makefile 2009-05-12 11:45:19.000000000 -0700
@@ -24,8 +24,8 @@
LOADLIBES+= -L../../../lib runcc.a -lltp -lpthread

SRCS=$(wildcard *.c)
-TARGETS= asapi_01 asapi_02 asapi_03 asapi_04 asapi_05 asapi_06 asapi_07 \
- getaddrinfo_01 in6_01 in6_02
+TARGETS= asapi_01 asapi_02 asapi_03 asapi_07 \
+ in6_02

all: $(TARGETS)

Buildroot Snapshots

2009-05-19T22:23:17Z

Marc: Add link to LTP test results page.

= Stable Snapshots of Buildroot and the Linux kernel =

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

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

Unofficial LTP test results are available in the [[LTP_Results| LTP Test Results]] page.

{| border=1 style="text-align:center" cellpadding=4 cellspacing=0
|+ '''List of GIT Commit Points for Each Snapshot'''
|-
! rowspan="2" | Snapshot
! colspan="2" | Linux Kernel
! colspan="2" | Buildroot
! rowspan="2" | Comments
|-
! GIT Tree !! Commit !! GIT Tree !! Commit
|-
| linux-xtensa-20080123.tar.gz || xtensa-2.6.24 || 50f17d5ba5d2 || buildroot-xtensa || dd6f0d70fb1f
| First snapshot
|-
| linux-xtensa-20080711.tar.gz || xtensa-2.6.24 || ce5325b68b14 || buildroot-xtensa || 16f39dfdde4b
| Second snapshot
|-
|}

Instructions for building and booting Linux

2009-05-12T05:41:29Z

Marc: /* Mounting the Root Filesystem Over NFS */ Slight clarifications

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 the Linux kernel ==

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

For most users, just execute the following:

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

where <tt><workdir></tt> is the path to an empty directory on a disk with
at least 4 GB available space. You end up with the following file structure,
which is assumed by the rest of this document:

<workdir>/
/buildroot
/linux

If you happen to have write access to either repository, or want more details,
see the [http://wiki.linux-xtensa.org/index.php/Repository_Access repository access] page.

== Install any required processor specific overlay ==

This step is required if you are targeting a custom Xtensa processor.
If you use a Diamond 232L Standard Core, you can skip this step.

To configure buildroot and the kernel to use a custom Xtensa processor
configuration, you need to overlay a set of files customized for your
processor configuration onto toolchain sources (gcc, binutils, gdb, etc)
and the Linux kernel. This process has been automated using a script
located in the buildroot source tree.
For usage information, you can invoke it without arguments:

$ cd <workdir>
$ ./buildroot/target/xtensa/xt-buildroot-overlay-install

which displays a help message similar to the following:

xt-buildroot-overlay-install version 1.3
Usage: xt-buildroot-overlay-install <parameters> [<options>]
Where <parameters> are:
-t file.tgz Specify path to the Xtensa Linux overlay tarball, typically
<xtensa_root>/src/xtensa-config-overlay.tar.gz
-b dir Path to the base of the buildroot source tree, in which
package specific overlay tarballs get installed.
-k dir Path to the base of the Linux kernel source tree, in which
the Linux kernel specific overlay gets installed.
-c config_name Name for the Xtensa processor configuration as it will be
known to the open source community. Must be a lowercase
identifier, starting with a letter, consisting of letters
and numbers and underscores, not ending with underscore
and not containing consecutive underscores. For examples:
dc232b , dc232b_be , mmubasele , fsf , s5000 .
-l long_name Long name for the Xtensa processor configuration, human-
readable with spaces etc allowed (must be quoted).
For example: 'Diamond 232L Standard Core Rev.B (LE)'
Try to keep it within approximately 40 characters.
And <options> are:
-f If package specific overlay tarballs already exist in
the destination source tree, overwrite them without asking.
--help Show this usage message.

Note that the Xtensa Linux overlay tarball MUST be obtained from an Xtensa
core package built using release RB-2008.3 or later.

Here is an example invocation of the overlay installation script:

$ ./buildroot/target/xtensa/xt-buildroot-overlay-install -t blinkcore-config-overlay.tar.gz \
-b ./buildroot -k ./linux -c superzip -l "ChipCorp SuperZIP Blink Accelerator Core"

The script extracts some relevant information from the overlay tarball,
presents it along with relevant parameters to the user, and prompts
for confirmation before proceeding.

The chosen processor name (-c option) must be unique among known Xtensa processors.
It is also probably wise to avoid names confusingly similar to other (non-Xtensa) processors.
If you expect at some point to contribute support for your custom processor to the
open-source community, this name will likely be long-lived.
(One way to contribute support for a custom processor might be to submit the overlay tarball
or files to the linux-xtensa.org maintainers.)

In the steps below, buildroot and the Linux kernel must be configured
(in their respective <code>''make menuconfig''</code> steps) to select
the <code>''custom''</code> Xtensa processor option.
This presents an extra configuration menu entry where you must provide
the name of the Xtensa processor. Set it to the same name
as was specified in the <code>-c</code> option above.

== Build a toolchain and root filesystem using buildroot ==

'''Note:''' for more details on generic buildroot topics not covered in this simple how-to,
see [http://buildroot.uclibc.org/ buildroot.uclibc.org].

=== Configure buildroot ===

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

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

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

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

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

=== Build buildroot ===

Just type:

$ make

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

Wait patiently for the build to complete. This builds an entire toolchain
as well as some basic packages, and constructs a root filesystem.
It might build many more packages if you selected them earlier with menuconfig.

==== If Something Goes Wrong ====

Perhaps you missed some step above and the build fails. Or you're just switching to a different processor configuration, or making some change with unknown dependencies. Either way, you'll probably need to fix the error and/or make the change, and redo the whole build. The above <tt>make</tt> command usually works fine if you
just added a package using menuconfig, but otherwise does not check many dependencies, so it will usually NOT rebuild things that depend on whatever you have fixed or changed. Here's one way to retry the make from scratch without having to wipe out the <tt>buildroot</tt> directory tree completely and start again from the git cloning.

$ rm -rf *build_xtensa* binaries
$ make

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

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

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

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

=== Configure the kernel ===

The kernel build is a two-step process: configure the kernel, and build it.
First, before we can do anything with the kernel, set your PATH to
point to the toolchain built using buildroot.

$ export PATH="''<workdir>''/buildroot/build_xtensa_''<cname>''/staging_dir/usr/bin:$PATH"

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

Now setup a destination for kernel builds.
We usually like to have the build directory separate from
the source directory, so we use 'O=</destination/path>' in
kernel make commands. If you'll be routinely building multiple
configurations of the Linux kernel, it's good to have some
naming conventions for the build directory. For example,
to experiment with multiple target platforms but only one
processor configuration, we include just the platform name here:

$ mkdir build-xtav60

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

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

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

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

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

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

Under '''General setup''',
make sure the '''Initial RAM filesystem and RAM disk (initramfs/initrd) support'''
entry is enabled. Underneath that, edit '''Initramfs source file(s)''',
and enter the path to the cpio formatted root filesystem
generated by buildroot:

''<workdir>''/buildroot/binaries/uclibc/rootfs.xtensa_''<cname>''.cpio.gz

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

Under '''Processor type and features''',
make sure the '''Xtensa Processor Configuration''' is correct and matches
the processor configuration name you used to build the toolchain with buildroot
(for example, ''dc232b'' for Diamond 232L Rev.B).
The kernel build selects a toolchain and processor variant specific headers
based on this selection.
If the desired processor configuration does not appear explicitly in the list,
simply select '''Custom Xtensa processor configuration''' and enter the
processor configuration name (all lowercase) into the next menu parameter,
'''Xtensa Processor Custom Variant Name'''.

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

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

Exit menuconfig, saving your configuration changes.

Backup your configuration outside the build directory. For example:

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

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

=== Build the kernel ===

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

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

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

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

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

In this example, it is assumed that the machine hosting the
Xtensa Tools has access to the <workdir> directory tree.

=== Install and setup the Xtensa OCD Daemon ===

Setup and connect your JTAG probe, etc.

=== Connect a terminal server ===

At 38400 bps 8N1 no flow control to the XTAV60 serial port.

=== Optionally, setup networking ===

This step is optional.

Setup the board's MAC address using dipswitches
(see XTAV60 or XTAV200 board docs as appropriate)
and connect the board to a network that has a
DHCP server that will respond to that MAC address.
If you don't do this step, you'll simply not have network
access, and the boot process will take a minute or so longer
while the kernel times out waiting for a BOOTP response.
You can edit the kernel configuration and rebuild the kernel
to avoid using bootp (in particular, remove "ip=bootp" from
the kernel cmdline).

=== Download and run the kernel ===

Reset the board (see board documentation).

Using Xtensa Tools, invoke:

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

(xt-gdb) target remote <ocdhost>:20000 0
(xt-gdb) reset
(xt-gdb) load
(xt-gdb) set $pc = &_ResetVector
(xt-gdb) symbol-file <workdir>/build-xtav60/vmlinux
(xt-gdb) c

where <ocdhost> is the IP address or DNS name of the machine
running the Xtensa OCD daemon. The Linux kernel should
start booting as soon as 'c' (continue) is executed.

You should eventually get a login prompt.
Just login as root (no password).

Try various Linux commands. Look at <tt>/bin</tt>,
<tt>/sbin</tt>, <tt>/usr/bin</tt>, etc to see what's available.

Note: no need to setup an NFS or TFTP server. The filesystem
is contained within the kernel image. You may be able to mount
other filesystems over NFS though, if you wish, after booting.

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

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

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 the
XTAV60 board, except that when initially configuring the kernel,
start from the ISS platform template instead:

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

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

Also, when running menuconfig:

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

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

Continue configuring and building the kernel as usual.

=== Run the Kernel on ISS ===

Using Xtensa Tools, invoke:

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

(xt-gdb) target sim --turbo
(xt-gdb) symbol-file <workdir>/build-iss/vmlinux
(xt-gdb) run

Wait patiently while Linux boots ... (maybe a minute)

Login as root (no password).

Note: Input via ISS is cooked, so everything typed gets echoed.
Also, time as reported by the kernel does not progress
according to true wall-clock time: it currently depends on
a simulated processor clock, which advances at various speeds
according to load.

Instructions for building and booting Linux

2009-05-12T05:24:16Z

Marc: /* Build and run a Linux kernel... */ Add instructions for mounting root over NFS

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 the Linux kernel ==

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

For most users, just execute the following:

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

where <tt><workdir></tt> is the path to an empty directory on a disk with
at least 4 GB available space. You end up with the following file structure,
which is assumed by the rest of this document:

<workdir>/
/buildroot
/linux

If you happen to have write access to either repository, or want more details,
see the [http://wiki.linux-xtensa.org/index.php/Repository_Access repository access] page.

== Install any required processor specific overlay ==

This step is required if you are targeting a custom Xtensa processor.
If you use a Diamond 232L Standard Core, you can skip this step.

To configure buildroot and the kernel to use a custom Xtensa processor
configuration, you need to overlay a set of files customized for your
processor configuration onto toolchain sources (gcc, binutils, gdb, etc)
and the Linux kernel. This process has been automated using a script
located in the buildroot source tree.
For usage information, you can invoke it without arguments:

$ cd <workdir>
$ ./buildroot/target/xtensa/xt-buildroot-overlay-install

which displays a help message similar to the following:

xt-buildroot-overlay-install version 1.3
Usage: xt-buildroot-overlay-install <parameters> [<options>]
Where <parameters> are:
-t file.tgz Specify path to the Xtensa Linux overlay tarball, typically
<xtensa_root>/src/xtensa-config-overlay.tar.gz
-b dir Path to the base of the buildroot source tree, in which
package specific overlay tarballs get installed.
-k dir Path to the base of the Linux kernel source tree, in which
the Linux kernel specific overlay gets installed.
-c config_name Name for the Xtensa processor configuration as it will be
known to the open source community. Must be a lowercase
identifier, starting with a letter, consisting of letters
and numbers and underscores, not ending with underscore
and not containing consecutive underscores. For examples:
dc232b , dc232b_be , mmubasele , fsf , s5000 .
-l long_name Long name for the Xtensa processor configuration, human-
readable with spaces etc allowed (must be quoted).
For example: 'Diamond 232L Standard Core Rev.B (LE)'
Try to keep it within approximately 40 characters.
And <options> are:
-f If package specific overlay tarballs already exist in
the destination source tree, overwrite them without asking.
--help Show this usage message.

Note that the Xtensa Linux overlay tarball MUST be obtained from an Xtensa
core package built using release RB-2008.3 or later.

Here is an example invocation of the overlay installation script:

$ ./buildroot/target/xtensa/xt-buildroot-overlay-install -t blinkcore-config-overlay.tar.gz \
-b ./buildroot -k ./linux -c superzip -l "ChipCorp SuperZIP Blink Accelerator Core"

The script extracts some relevant information from the overlay tarball,
presents it along with relevant parameters to the user, and prompts
for confirmation before proceeding.

The chosen processor name (-c option) must be unique among known Xtensa processors.
It is also probably wise to avoid names confusingly similar to other (non-Xtensa) processors.
If you expect at some point to contribute support for your custom processor to the
open-source community, this name will likely be long-lived.
(One way to contribute support for a custom processor might be to submit the overlay tarball
or files to the linux-xtensa.org maintainers.)

In the steps below, buildroot and the Linux kernel must be configured
(in their respective <code>''make menuconfig''</code> steps) to select
the <code>''custom''</code> Xtensa processor option.
This presents an extra configuration menu entry where you must provide
the name of the Xtensa processor. Set it to the same name
as was specified in the <code>-c</code> option above.

== Build a toolchain and root filesystem using buildroot ==

'''Note:''' for more details on generic buildroot topics not covered in this simple how-to,
see [http://buildroot.uclibc.org/ buildroot.uclibc.org].

=== Configure buildroot ===

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

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

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

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

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

=== Build buildroot ===

Just type:

$ make

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

Wait patiently for the build to complete. This builds an entire toolchain
as well as some basic packages, and constructs a root filesystem.
It might build many more packages if you selected them earlier with menuconfig.

==== If Something Goes Wrong ====

Perhaps you missed some step above and the build fails. Or you're just switching to a different processor configuration, or making some change with unknown dependencies. Either way, you'll probably need to fix the error and/or make the change, and redo the whole build. The above <tt>make</tt> command usually works fine if you
just added a package using menuconfig, but otherwise does not check many dependencies, so it will usually NOT rebuild things that depend on whatever you have fixed or changed. Here's one way to retry the make from scratch without having to wipe out the <tt>buildroot</tt> directory tree completely and start again from the git cloning.

$ rm -rf *build_xtensa* binaries
$ make

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

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

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

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

=== Configure the kernel ===

The kernel build is a two-step process: configure the kernel, and build it.
First, before we can do anything with the kernel, set your PATH to
point to the toolchain built using buildroot.

$ export PATH="''<workdir>''/buildroot/build_xtensa_''<cname>''/staging_dir/usr/bin:$PATH"

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

Now setup a destination for kernel builds.
We usually like to have the build directory separate from
the source directory, so we use 'O=</destination/path>' in
kernel make commands. If you'll be routinely building multiple
configurations of the Linux kernel, it's good to have some
naming conventions for the build directory. For example,
to experiment with multiple target platforms but only one
processor configuration, we include just the platform name here:

$ mkdir build-xtav60

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

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

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

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

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

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

Under '''General setup''',
make sure the '''Initial RAM filesystem and RAM disk (initramfs/initrd) support'''
entry is enabled. Underneath that, edit '''Initramfs source file(s)''',
and enter the path to the cpio formatted root filesystem
generated by buildroot:

''<workdir>''/buildroot/binaries/uclibc/rootfs.xtensa_''<cname>''.cpio.gz

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

Under '''Processor type and features''',
make sure the '''Xtensa Processor Configuration''' is correct and matches
the processor configuration name you used to build the toolchain with buildroot
(for example, ''dc232b'' for Diamond 232L Rev.B).
The kernel build selects a toolchain and processor variant specific headers
based on this selection.
If the desired processor configuration does not appear explicitly in the list,
simply select '''Custom Xtensa processor configuration''' and enter the
processor configuration name (all lowercase) into the next menu parameter,
'''Xtensa Processor Custom Variant Name'''.

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

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

Exit menuconfig, saving your configuration changes.

Backup your configuration outside the build directory. For example:

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

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

=== Build the kernel ===

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

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

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

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

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

In this example, it is assumed that the machine hosting the
Xtensa Tools has access to the <workdir> directory tree.

=== Install and setup the Xtensa OCD Daemon ===

Setup and connect your JTAG probe, etc.

=== Connect a terminal server ===

At 38400 bps 8N1 no flow control to the XTAV60 serial port.

=== Optionally, setup networking ===

This step is optional.

Setup the board's MAC address using dipswitches
(see XTAV60 or XTAV200 board docs as appropriate)
and connect the board to a network that has a
DHCP server that will respond to that MAC address.
If you don't do this step, you'll simply not have network
access, and the boot process will take a minute or so longer
while the kernel times out waiting for a BOOTP response.
You can edit the kernel configuration and rebuild the kernel
to avoid using bootp (in particular, remove "ip=bootp" from
the kernel cmdline).

=== Download and run the kernel ===

Reset the board (see board documentation).

Using Xtensa Tools, invoke:

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

(xt-gdb) target remote <ocdhost>:20000 0
(xt-gdb) reset
(xt-gdb) load
(xt-gdb) set $pc = &_ResetVector
(xt-gdb) symbol-file <workdir>/build-xtav60/vmlinux
(xt-gdb) c

where <ocdhost> is the IP address or DNS name of the machine
running the Xtensa OCD daemon. The Linux kernel should
start booting as soon as 'c' (continue) is executed.

You should eventually get a login prompt.
Just login as root (no password).

Try various Linux commands. Look at <tt>/bin</tt>,
<tt>/sbin</tt>, <tt>/usr/bin</tt>, etc to see what's available.

Note: no need to setup an NFS or TFTP server. The filesystem
is contained within the kernel image. You may be able to mount
other filesystems over NFS though, if you wish, after booting.

=== 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 it easier to access files (e.g. generated on the target)
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)

* 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=''<serverip>'':''<exportpath>''

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

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 the
XTAV60 board, except that when initially configuring the kernel,
start from the ISS platform template instead:

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

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

Also, when running menuconfig:

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

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

Continue configuring and building the kernel as usual.

=== Run the Kernel on ISS ===

Using Xtensa Tools, invoke:

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

(xt-gdb) target sim --turbo
(xt-gdb) symbol-file <workdir>/build-iss/vmlinux
(xt-gdb) run

Wait patiently while Linux boots ... (maybe a minute)

Login as root (no password).

Note: Input via ISS is cooked, so everything typed gets echoed.
Also, time as reported by the kernel does not progress
according to true wall-clock time: it currently depends on
a simulated processor clock, which advances at various speeds
according to load.

KnownIssues

2008-12-09T22:10:38Z

Marc: /* Kernel loadable modules using FLIX with L32R */ Mention the OSKit guide for info about XCC for Linux.

KnownIssues

2008-12-09T22:02:32Z

Marc: Moved hardware contents to another page

Supported Processor Configurations

2008-12-09T22:01:53Z

Marc: Move hardware related issues to this page

= Hardware System Limitations =

This page contains recommendations, notes, limitations, and requirements for the development of hardware systems using Xtensa processors running Linux.

= Recommendations =

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

2008-12-09T21:57:46Z

Marc: Move hardware design info to a separate page

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

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

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

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

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

|-
|}

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

KnownIssues

2008-12-09T21:53:59Z

Marc: Gather other system info pages, and add info about kernel modules with FLIX and L32R

= Known Kernel Issues and Limitations =

== Hardware System Limitations ==

This section contains recommendations, notes, limitations, and requirements for the development of hardware systems using Xtensa processors running Linux.

'''Recommendations'''

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.

Please contact Tensilica support if 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.

== Software Limitations ==

This section contains recommendations, notes, limitations, and requirements for the development of software on systems using Xtensa processors running Linux.

Eventually all these should be duly reported and tracked in
the [http://bugs.linux-xtensa.org Mantis bug tracker].
For the time being, here are some of the main known issues (this is by no means an exhaustive list!).

=== 128 MB RAM Limit ===

Kernel highmem support has not yet been implemented, 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.

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

Main Page

2008-12-09T21:22:17Z

Marc: /* <big>Welcome to the Linux/Xtensa Wiki</big> */ Add known issues page

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

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

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

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

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

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

|-
|}

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

Main Page

2008-12-09T21:15:08Z

Marc: /* <big>Welcome to the Linux/Xtensa Wiki</big> */ Moved ISS to evaluation platforms page

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

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

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

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

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

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

|-
|}

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

Evaluation Platforms

2008-12-09T21:13:53Z

Marc: ISS is really another evaluation platform, so move it here, and adjust intro text a bit

[[image:board.jpg|right]]
= Evaluation and Prototyping Platforms =

The following boards and simulators can be used for evaluation and prototyping purposes. Evaluation platforms generally fall into one of the following categories:
* instruction set simulators,
* emulation systems that use FPGAs to implement any Xtensa or Diamond core (within the capacity of the FPGAs), and
* boards that integrate a specific configured Xtensa or Diamond core(s) into an ASIC.
Field programmable gate arrays (FPGA) contain programmable logic that can be re-configured to emulate complex logic. Although slower than the dedicated circuitry of an ASIC (application specific integrated circuit), their re-configurability and practically zero NRE make them very useful for prototyping (for example, trying multiple Xtensa processor variants or configurations) or small volume applications.

== Instruction Set Simulator ==

Instruction Set Simulators (ISS) mimic the behavior of processors by simulating instructions, memory interface, and other I/O components. This allows developers to run and test their software long before real hardware becomes available. Functional simulators provide the best performance, whereas cycle-accurate simulators provide timing accuracy compatible to that of real hardware. The latter simulate the processor pipeline and external components synchronized to a virtual clock. Although this overhead reduces their performance, it can provide vital information to improve the implementation of algorithms.

=== Tensilica ISS ===

[http://www.tensilica.com/ Tensilica] offers a commercial functional simulator (TurboXim) and cycle-accurate simulator for the Xtensa processor architecture, as part of their standard software development tools. (You may be able to try a free limited time evaluation copy of this toolset.) Tensilica also offers XTMP and XTSC for modeling systems of one or multiple processors alongside custom functional or cycle-accurate software models for other components. Please visit [http://www.tensilica.com/ Tensilica's] website for further information.

The standalone simulator (xt-iss), for example, simply takes an ELF file as its argument and starts simulating instructions from the reset vector. The option <code>--turbo</code> invokes the (much faster) functional simulator TurboXim.

xt-iss ''[--turbo]'' Image.elf

== Emulation Platforms and Systems ==

=== Avnet Virtex-4 LX60 and LX200 ===

[http://www.em.avnet.com Avnet] offers the following development platforms for the Xilinx Virtex-4 LX FPGA that can emulate various
Xtensa processor configurations. The [http://www.em.avnet.com/tensilica1 LX60] is based on the Xilinx 4VLX60 and comes
with a 10/100 Ethernet PHY, DDR memory, flash memory, serial port, and 2 x 16 character LCD panel. The MAC controller, however, needs to be implemented inside the FPGA. MAC controllers are available from different vendors. [http://opencores.org OpenCores], for example, provides a free Ethernet controller supported by Linux and other operating systems. The [http://www.em.avnet.com/tensilica2 LX200] is based on the Xilinx XC4VLX200 and can emulate more complex processor configurations and extensions (for example the [http://www.tensilica.com/products/hifi_audio.htm HiFi 2 Audio Engine]) and provides the same components as the LX60 except for the LCD panel.

[http://www.tensilica.com Tensilica] provides a bitstream that describes the configuration data to emulate the Diamond Standard DC232L processor (Rev.B) on the LX60 FPGA. Tensilica refers to this board and bitstream combination as the XTAV60 board. It also includes support for the OpenCores Ethernet MAC. For further information, please, contact [http://www.tensilica.com/company/contact_us.htm Tensilica] directly.

=== Eve ZeBu ===

[http://www.eve-team.com Eve] offers an emulation and verification system that can be used to emulate Xtensa processors. Similar to FPGA boards, the ZeBu system emulates the processor, but has a higher capacity to emulate larger processor configurations and additional peripherals. It also provides direct access to signals for debugging and verification.

See the [[Linux on ZeBu]] page or contact [http://www.eve-team.com Eve] directly to request additional information.

== ASIC Evaluation Platforms ==

=== Stretch S55DVKxx and S56DVKxx ===

[http://www.stretchinc.com Stretch] provides software-configurable processors based on the Xtensa architecture. The S5000 processor supports Linux, and at 300MHz, it runs 5-10 times faster than FPGA based emulation platforms. The S55DVKxx and S56DVKxx development platforms provide 10/100/1000 Ethernet, serial, PCI (only S56DVKxx), and other interfaces.

The Stretch platforms come with RedBoot as the bootloader. It can download and boot the kernel over network using TFTP or from flash. Make sure that RedBoot is configured with a valid Ethernet address or set to DHCP to obtain a valid address. The following commands load the kernel image ''zImage.redboot'' and boot the kernel:

RedBoot> load -r -b 0xd0200000 -h 192.168.1.5 zImage.redboot
RedBoot> exec 0xd0200000

Note that RedBoot requires that the tftp host is in the same subnet as the board.

Supported Processors

2008-12-09T20:40:45Z

Marc: /* 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 232L processor 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>include/asm-xtensa/variant-''config''</code>). Adding support to the kernel
for a custom configured Xtensa processor generally involves copying the appropriate
configuration files into the appropriate variant directory.
See [[Buildroot_Build_Instructions#Install_any_required_processor_specific_overlay|Buildroot Overlay Installation]] for an automated method of installing these files in both toolchain and kernel sources.

== 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''. The following list shows processors currently supported by the kernel.

{| border=1 cellspacing=0 cellpadding=3
|+ Supported processors in the Linux kernel
|- style="background:#f8f8f8;"
! Name !! Byte order !! Notes
|-
| Custom-configured Xtensa || little or big endian || Vendor specific, requires overlay
|-
| Diamond 232L || little or big endian || Rev.A and Rev.B
|-
| 'FSF' || big endian || Only for verification
|-
| Stretch S5000 || little endian || For the S56xx platform
|}

Supported Processors

2008-12-09T20:37:58Z

Marc: Reorganize, remove obsolete MontaVista specific verbiage, clarify a bit more.

== 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 232L processor 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.

In the Linux kernel for example, all configuration files are located inside the Xtensa include directory in the kernel sources (<code>include/asm-xtensa/variant-''config''</code>). Adding support to the kernel
for a custom configured Xtensa processor generally involves copying the appropriate
configuration files into the appropriate variant directory.
See [[Buildroot_Build_Instructions#Install_any_required_processor_specific_overlay|Buildroot Overlay Installation]] for an automated method of installing these files in both toolchain and kernel sources.

== 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''. The following list shows processors currently supported by the kernel.

{| border=1 cellspacing=0 cellpadding=3
|+ Supported processors in the Linux kernel
|- style="background:#f8f8f8;"
! Name !! Byte order !! Notes
|-
| Custom-configured Xtensa || little or big endian || Vendor specific, requires overlay
|-
| Diamond 232L || little or big endian || Rev.A and Rev.B
|-
| 'FSF' || big endian || Only for verification
|-
| Stretch S5000 || little endian || For the S56xx platform
|}