SMP HiFi 2 Development Board
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 official site. For example, cd 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 /usr/local/bin or $HOME/bin.
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), cd 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 git gui.
Perfer to give this GUI approach to doing the same thing. It's far easier to remember. We want to encourage the user to use git. Lets avoid problem were customers have been reluctant to use git. Git gui requires remembering only 16 key strokes and provieds suggestions on what to do. Command like requires remembering 80 keystrokes and is demanding on memory. Remembering to prefix the tracking branch with origin takes time to get use to. Of course Cut-N-Pasting the command line is faster. The GUI is instructional for getting the user doing this kind of stuff on their own. For example you can read the NEC code or the NEC handbook. I like the handbook because it's more than just the proceedures to follow, it adds context for better memory.
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 BE DONE, including adding a snapshot_2+SMP branch]
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/ftfp
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
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_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 minicom. We usually just type:
minicom xtboard
which initializes with parameters from /etc/minirc.xtboard:
# 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 with 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 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.