Application Note: Dynamic loading of USB Binaries onto the XTAG2

boardpushyUrban and Civil

Dec 8, 2013 (4 years and 7 months ago)


Application Note:Dynamic loading of USB Binaries
onto the XTAG2
Publication Date:2012/8/2
XMOS © 2012,All Rights Reserved.
Application Note:Dynamic loading of USB Binaries onto the XTAG2 2/7
Table of Contents
1 Dynamic loading of USB Binaries on the XTAG2 3
1.1 Prerequisites:.........................................3
1.2 Getting the USB HID example working...........................3
1.3 Running USB Audio on the XTAG2.............................4
1.3.1 Troubleshooting...................................5
1.3.2 Debug with second XTAG2.............................6
1 Dynamic loading of USB Binaries on the XTAG2
Some notes on getting an XMOS USB Application to dynamically load onto an XTAG2.
First a simple HID example is used,then a proof of concept is given showing how
more complex examples like USB Audio can be run in the same manner
1.1 Prerequisites:
From github:
· Also associated dependencies
For the USB Audio example you will also need the USB L1 Audio source code (as
the port map needs modifying to run on an XTAG2).This must be requested via
your profile on
This note assumes you are running on OS X and comfortable with command line
tools and utilities.There is currently no GUI tool for this flow.
1.2 Getting the USB HID example working
The USB HID example is a good starting point for this as no external inputs are
required and a successful load of the code can immediately be seen on screen.The
link to download this from is given above.
Open the app_example_usb_hid/src/main.xc file and change the USB Phy reset
port to match the XTAG2 port map:
The project can now be built,and then the commands in the dynamic loader
makefile can then be used to generate a suitable header file:
xobjdump --split --strip bin/app_example_usb_hid.xe
od -t x4 image_n0c0.bin | awk'BEGIN{print"int burnData[] = {"} END {print
>"};"} {for(i=2;i<=NF;i++) {print"0x"$i","}}'> app_l1_hid.h
The part of proj_xtag2 that is used is in the run_dynamic_xe directory.There is
already a version of the USB HID library here as a header file so the project can just
be built using xmake or make.
Application Note:Dynamic loading of USB Binaries onto the XTAG2 4/7
To run the example code,an XTAG2 must be connected to the PC and then
runDynamic must be the first program run.Performing anxrun -l or similar will
load the JTAG firmware onto the XTAG2 and it will not be possibly to dynamically
load this HID code.Disconnecting and reconnecting the XTAG2 will reinitialise it
into a state where it can dynamically load code again.
With the XTAG2 connected to the host PC,it should be possible to run the program:
./runDynamic The following output should appear:
Running dynamic USB code...
A few seconds later,the mouse pointer should start jumping around a small (40
pixel) square.This is the effect of the HID device now running on the XTAG2.To
stop it,disconnect the board.
If xrun -l (or other xrun/xgdb command) has been performed prior to running
the HID demo,you will see the following message:
Device is not running USB loader,please reboot...
Could not find/open device
Once you can see the cursor moving around the square,it confirms the basic USB
dynamic loader is working.USB Audio has some additional complexity so this is
explained below.
1.3 Running USB Audio on the XTAG2
The USB Audio code has one main extra requirement over the HID example - it
requires an audio master clock.This must be supplied to the XSYS header on a
suitable pin.Without a master clock,the firmware will enumerate but then stop
working as the firmware is designed to wait for stable clocks.
To act as a useful USB Audio device,it is also necessary to have LR and bit clocks.
The XTAG has fairly limited IOs,but enough are available on the XSYS header to
have a basic 2in/2out USB audio device.
The audio code port map must be modified to suit the XTAG2 available IOs.A
suggested portmap is below:
on stdcore[0]:buffered out port:32 p_i2s_dac[1] = {XS1_PORT_1D};
on stdcore[0]:buffered in port:32 p_i2s_adc[1] = {XS1_PORT_1J};
on stdcore[0]:buffered out port:32 p_lrclk = XS1_PORT_1C;
on stdcore[0]:buffered out port:32 p_bclk = XS1_PORT_1A;
on stdcore[0]:port p_mclk = XS1_PORT_1M;
on stdcore[0]:in port p_for_mclk_count = XS1_PORT_1E;
/* USB Reset port */
on stdcore[0]:out port p_usb_rst = XS1_PORT_1I;
Application Note:Dynamic loading of USB Binaries onto the XTAG2 5/7
SPDIF and MIDI are not supported.
Build the USB Audio code with the modified port map above,then use the process
explanined in the first part of this document to create a header file from the XE.
Change to the runDynamic.c source code and change the included app_l1_hid.h
header to the new file you have created with USB audio.Rebuild the runDynamic
The hardware now needs to be set up - disconnect the XTAG2 from the host,and
connect the MClk to port 1M (pin 15 on the XSYS connector).This should be the
correct MClk value for the default sample frequency set in the USB Audio code in
Once this is done,reconnect the XTAG2 to the host and run the runDynamic
command.Again,do not run xrun,xgdb before the runDynamic command.The
host should now load the firmware onto the XTAG2,and a few seconds later the
USB Audio device should appear in Audio Midi.
1.3.1 Troubleshooting
Debugging any issues requires a second XTAG2 with a suitable header to connect
to the JTAG pins on the board being used for development.In the absence of this,
there are a few things that can be checked.As before,these steps assume you are
using OS X.
Firstly see if the device appears in USB Prober.This utility was included in OS X
10.6 and can be downloaded from Apple for 10.7,but you may need a developer
account.If you have USB Prober,set it to “Refresh Automatically”,then watch as
you run runDyanmic.With an uninitialized XTAG2 connected,you should see an
“XTAG2” line.When you call runDynamic,you should see the XTAG2 line disappear,
then “XMOS USB Audio 2.0” appear.If this only appears briefly before disappearing
again,the device has started to enumerate but then got stuck causing the usb bus
to fail.This is usually because the MClk is not connected or running.
Simiarly,you can view the system logs/var/log/kernel.log.If the last few entries
Aug 1 11:46:13 atuin kernel[0]:USBF:1426106.126 [0xffffff8012f03a00
> ] The IOUSBFamily was not able to enumerate a device.
Aug 1 11:46:14 atuin kernel[0]:USBF:1426106.951 [0xffffff8012f03a00
> ] The IOUSBFamily is having trouble enumerating a USB device that has
> been plugged in.It will keep retrying.(Port 1 of Hub at 0xfd120000
> )
this again implies that enumeration has started but the XCore has stalled the
process.The USB Audio implementation requires a stable MClk to work.Check
the that MClk is running and connected to the correct pin on the XSYS header.
Also check that the value in customdefines.h for the clock multiplier matches the
provided MClk (eg 256 or 512 fs for 44.1/48kHz).
Application Note:Dynamic loading of USB Binaries onto the XTAG2 6/7
Beyond this will require a second JTAG adaptor with a suitable header connected
to allow debug.
1.3.2 Debug with second XTAG2
Debug is possible in the usual manner using a second XTAG2 appropriately con-
nected to the JTAG pins on the header of the device you are trying to debug.The
main caveat is the order of running/loading devices to ensure the board you want
to dynamically load code to does not get initialised with the XTAG2 firmware.To
try and minimize confusion,this will use the following terminology:
· USB board:The XTAG2 board on which you want to run USB functional code
· JTAG board:The XTAG2 board which is being used in the normal manner as a
debug adaptor.
The USB Board will need a header soldering to the JTAG pins on the long side of the
board.These then need connecting to the correct pins on the XSYS header on the
JTAG board.The connections for the XSYS header are given in the XTAG2 hardware
manual,available here:
On the USB board,the pin names are on the screenprint but can be hard to read,
so with the XSYS header to the left working towards the crystal they are in order:
Once this is wired up,start by connecting the USB board to the host.runDynamic
can be called to load the USB Audio firmware onto the USB board.Now connect the
JTAG board to the host and USB board.Open XDE with the USB Audio project code.
You can create a new Debug configuration and then in the Debug tab select “Attach
to running process”.If you then choose “apply” and “Debug”,xgdb will attach to
the firmware running on the USB board.It is now possible to debug it in the usual
You can also use xrun (or run configurations/run) to run firmware on the USB board
via the JTAG board.You may get warnings that the boot mode is not set correctly,
but the device should still execute the code loaded via JTAG.
Application Note:Dynamic loading of USB Binaries onto the XTAG2 7/7
Copyright © 2012,All Rights Reserved.
Xmos the owner or licensee of this design,code,or Information (collectively,the “Information”) and
is providing it to you “AS IS” with no warranty of any kind,express or implied and shall have no liability in
relation to its use.Xmos Ltd.makes no representation that the Information,or any particular implementation
thereof,is or will be free from any claims of infringement and again,shall have no liability in relation to any
such claims.
XMOS and the XMOS logo are registered trademarks of Xmos the United Kingdom and other countries,
and may not be used without written permission.All other trademarks are property of their respective owners.
Where those designations appear in this book,and XMOS was aware of a trademark claim,the designations
have been printed with initial capital letters or in all capitals.