View source for SMP HiFi 2 Development Board

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!