SMP HiFi 2 Development Board

These instructions explain how to use HiFi-2 Codec Development environment on a LX200 FPGA board.

Some general notes on these instructions:

• They are a work in progress, it's currently being prepared for a Tensilica customer.

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

Introduction

We will be going over the steps needed to set up you LX200 board for codec development. Your board likely comes with U-boot preinstalled on it to boot a linux kernel. You will be downloading a copy of buildroot and a linux kernel that have been pre-configured and built for HiFi-2 development. You will be setting up a TFTP server to provide the linux kernle to U-Boot, setting up a NFS server to export a linux root file system and setting up the Linux kernel to boot from your root file system provided by your NFS file server. Once your running on your development board we will suggest how to taylor your board for easy development of your codecs. We will then show you how how to add the Tensilica provided codec packages to the same Mplayer packages used by Buildroot, and finally, builing and installing them. We will demonstrate two proceedured for compiling codecs with XCC, linking them for you development environment, and then debugging them.

Downloading The latest HiFI-2 Buildroot and Kernel Snapshots

The HiFi-2 development environment is maintain in a source code version control system named 'git' that is likely a good environemt for you to use when working with this development environemt, thought it can be done without it. We will assume you will be using 'git' but will point out allternatives for those not interested in investing the time to set it up. By introducing you to the git environment used to build this environment we leave you the opportunity to modify it for your needs. For example you might want to debug with a graphical gdb GUI like ddd or add a few more packages from buildroot.

Installing git

   The Git source code Version Control System can be easily installed in a few minutes. Start by downloading a recient tar ball to your system from:

        http://www.kernel.org/pub/software/scm/git/

   Then simpley unpack the tar ball, drop into the git src code, and then make and install it.

       $ cp $HOME/Desktop/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
       $ make install

This will usually git to /usr/local/bin or $HOME/bin. It will provide you with easy access to the binariess used to bring up the codec development environment and leave you in place the infrastructure to modify it after you have some experience useing it. All of you changes will be easily seen with the git gui.

Installing the Buildroot Snapshot

 The HiFi-2 snapshot is in the process of being made. Their are two major components, a Linux kernel git reposiory, and a buildroot git repository. We will download both preconfigured for easily running HiFi-2 codecs. Both the kernel and buildroot are available via git and compressed tar balls. With git being arguable preferable as it will allow you to easly see any changes you have made from this reference starting point.

The buildtoot environment can be downloaded with git by using the following command:

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

once git is finished, do a cd to buildroot-xtensa-HiFi2-Snapshot and checkout the latest stuff; which is currently the snapshot_2+SMP branch. This can be done at the command line with:

   $ cd buildroot-xtensa-HiFi2-Snapshot
   $ git branch --track snapshot_2+SMP origin/snapshot_2+SMP
   $ git checkout snapshot_2+SMP

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.

Alternativly you can currently ftp a compress tar ball from our ftp server:

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

but this isn't as clean and may be discontinued.

Installing the Linux Kernel Snapshot

  [TO BE DONE]

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

  [TO BE DONE - Condider installing Kernel in FLASH]

Setting up a NFS Server to export the Root Filesystem

Your buildroot has a cpio file that we will use to build a root file system to export via NFS to your LX200 board. We will also be adding an additional minor changes to make your development environment more comfortable. The cpio file with your root file system was build and left in:

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

Pick a place on your workstation to export you root and unpack the cpio file into that directory. For exmaple 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
   $ cp rootfs.xtensa_test_mmuhifi_c3.cpio /tmp
   $ cd /exports
   $ mkdir LINUX_ROOT.HiFi-2_DemoBoard.buildroot-xtensa-smp
   $ cp /tmp/rootfs.xtensa_test_mmuhifi_c3.cpio
   $ cat rootfs.xtensa_test_mmuhifi_c3.cpio | cpio -i

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 pdelaney_fc5.hq.tensilica.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 minicom. We usually just type:

  minicom xtboard

the boards expect to communicate at with a bauderate 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]

Tayloring your system prior to developing your codec

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

  1. Add a root password to that you can login with ssh.
  2. Run rdate with a 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 it's Plug-ins from Buildroot modified slighly to make instalation 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 a example environment for developing and testing Codecs. There are two ways to build Mplayer and the plug-in modules that use the codes. The buildroot that you pulled with git has a copy of mplayer and the Plugins that can be built in the snapshot via a 'make menuconfig'. This is a good environment to use once your codes are developed and debugged.

To facilitate developemnt the mplayer packages can be copied to you 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-in's 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 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 buildtoot:

       .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 

Lets 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

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 encapsilation process used by the plug-ins.