How to guides

The following options are used to specify the program images and data
that makes up the binary and its layout. Padding is inserted when
required to ensure that images are aligned on sector boundaries.

• xe-file [size]

  –factory xe-file [size]

  Specifies xe-file as the factory image. If size is specified,
  padding is inserted to make the space between the start of this image
  and the next image at least the specified size. The default unit of
  size is “bytes;” the size can be postfixed with k to specify a
  unit of kilobytes.

  At most one factory image may by specified.

• –upgrade id xe-file [size]

  Specifies xe-file as an upgrade image with version id. Each
  version number must be a unique number greater than 0. If size is
  specified, padding is inserted to make the space between the start of
  this image and the next image at least the specified size. The
  default unit of size is “bytes;” the size can be postfixed with k
  to specify a unit of kilobytes.

  Multiple upgrade images are inserted into the boot partition in the
  order specified on the command line.

  If no factory image is specified, a single upgrade image may be
  specified and written to a file with the option -o.

• –boot-partition-size n

  Specifies the size of the boot partition to be n bytes. If left
  unspecified, the default size used is the total size of the flash
  device. n must be greater than or equal to the minimum size
  required to store the boot loader, factory image and any upgrade
  images.

• –data file

  Specifies the contents of file to be written to the data partition.

• –loader file

  Specifies custom flash loader functions in file
  (see Customize the flash loader
  ).
  The file may be either an object (.o) or archive (.a).

  By default, the xCORE flash loader loads the image with the highest
  version number that validates against its CRC.

• –verbose

  Prints additional information about the program when loaded onto the
  target system.

• –help

  Prints a description of the supported command line options.

• –version

  Displays the version number and copyrights.

The following options are used to specify which flash device the binary
is to be programmed on. The type of flash device used determines the
values for the SPI divider, sector size and memory capacity.

• –list-devices

  -l

  Prints an enumerated list of all JTAG adapters connected to the PC
  and the devices on each JTAG chain, in the form:

  ID        Name        Adapter ID        Devices

  --        ----        ----------        -------

  The adapters are ordered by their serial numbers.

• –id ID

  Specifies the adapter connected to the target hardware.

  XFLASH connects to the target platform and determines the type of
  flash device connected to it.

• –adapter-id ADAPTER-SERIAL-NUMBER

  Specifies the serial number of the adapter connected to the target
  hardware. XFLASH connects to the target hardware and determines the
  type of flash device connected to it.

• –jtag-speed n

  Sets the divider for the JTAG clock to n. The corresponding JTAG
  clock speed is 6/(n+1)MHz. The default value of the divider
  for the JTAG clock is 0, representing 6MHz.

• –spi-spec file

  Enables support for the flash device specified in file
  (see Add support for a new flash device
  ).

• –spi-div n

  Sets the divider for the SPI clock to n, producing an SPI clock
  speed of 100/2nMHz. By default, if no target is specified, the
  divider value is set to 3 (16.7MHz).

• –noinq

  Does not run the device inquisitor program, which checks that images
  are aligned on sector boundaries. If --noinq is omitted XFLASH
  expects to be able to connect to the device via JTAG.

• –disable-boot-link-warn

  Disables a warning emitted when the links between nodes do not allow for
  boot-from-link to work, for example only links lower than link 3 have
  been specified as connected on bootee nodes, whereas the boot rom
  enables links 4-7 (and link 3 if a primary tile).

The following options are used in conjunction with the
AES Module
.

• –key keyfile

  Encrypts the images in the boot partition using the keys in
  keyfile.

• –disable-otp

  Causes the flash loader to disable access to OTP memory after the
  program is booted. This is default if the option --key is used.

• –enable-otp

  Causes the flash loader to enable access to OTP memory after the
  program is booted. This is default unless the option --key is
  used.

By default, XFLASH programs the generated binary file to the target flash device.

• -o file

  Places output in file, disabling programming.

  If the target platform is booted from more than one flash device,
  multiple output files are created, one for each device. The name of each output
  file is file_node, where node is the value of the
  Id attribute
  of the corresponding node.

The following options perform generic read, write and erase operations
on the target flash device. A target XN file must be specified, which
provides ports used to communicate with the SPI device on the hardware
platform.

• –target-file xn-file [node]

  Specifies xn-file as the target platform.

  If xn-file specifies more than one flash device, a value for node
  must be specified. This value must correspond to the
  Id attribute
  of the node connected to the
  target flash device.

• –target platform [node]

  Specifies a target platform. The platform configuration must be
  specified in the file platform.xn, which is searched for in the paths
  specified by the XCC_DEVICE_PATH environment variable
  .

  If xn-file specifies more than one flash device, a value for node
  must be specified. This value must correspond to the
  Id attribute
  of the node connected to the
  target flash device.

• –erase-all

  Erases all memory on the flash device.

• –read-all

  Reads the contents of all memory on the flash device and writes it to
  a file on the host. Must be used with -o.

• –write-all file

  Writes the bytes in file to the flash device.

To load a program into an SPI flash memory device on your development
board, start the command-line tools

and enter the following commands:

1. xflash -l

   XFLASH prints an enumerated list of all JTAG adapters connected to
   your PC and the devices on each JTAG chain, in the form:

   ID        Name        Adapter ID        Devices

   --        ----        ----------        -------

2. xflash –id ID program.xe

   XFLASH generates an image in the xCORE flash format that contains a
   first stage loader and factory image comprising the binary and data
   segments from your compiled program. It then writes this image to
   flash memory using the xCORE device.

   The XN file used to compile your program must define an SPI flash
   device and specify the four ports of the xCORE device to which it is
   connected (see ExternalDevice
   ).

In manufacturing environments, the same program is typically programmed
into multiple flash devices.

To generate an image file in the xCORE flash format, which can be
subsequently programmed into flash devices,
start the command-line tools

and enter the following command:

xflash program.xe -o image-file

XFLASH generates an image comprising a first stage loader and your
program as the factory image, which it writes to the specified file.

xTimeComposer and the libflash library let you manage multiple firmware
upgrades over the life cycle of your product. You can use XFLASH to
create an upgrade image and, from within your program, use libflash to
write this image to the boot partition. Using libflash, updates are
robust against partially complete writes, for example due to power
failure: if the CRC of the upgrade image fails during boot, the previous
image is loaded instead.

Write a program that upgrades itself

#include <platform.h>
#include <flash.h>

#define MAX_PSIZE 256

/* initializers defined in XN file
 * and available via platform.h */

fl_SPIPorts SPI = { PORT_SPI_MISO,
                    PORT_SPI_SS,
                    PORT_SPI_CLK,
                    PORT_SPI_MOSI,
                    XS1_CLKBLK_1 };

int upgrade(chanend c, int usize) {

  /* obtain an upgrade image and write
   * it to flash memory
   * error checking omitted */

  fl_BootImageInfo b;
  int page[MAX_PSIZE];
  int psize;

  fl_connect(SPI);

  psize = fl_getPageSize();
  fl_getFactoryImage(b);
  fl_getNextBootImage(b);

  while(fl_startImageReplace(b, usize))
    ;
  for (int i=0; i page[j];)
    fl_writeImagePage(page);

  fl_endWriteImage();

  fl_disconnect();

      return 0;
}

int main() {
  /* main application - calls upgrade
   * to perform an in-field upgrade */
}

Build and deploy the upgrader

xTIMEcomposer lets you customize the mechanism for choosing which image
is loaded from flash. The example program in C functions that customize the flash loader

determines which image to load based on the value at the start of the data partition.

extern void *readFlashDataPage(unsigned addr);

int   dpVersion;
void *imgAdr;

int init(void) {
  void *ptr = readFlashDataPage(0);
  dpVersion = *(int *)ptr;
}

int checkCandidateImageVersion(int v) {
  return v == dpVersion;
}

void recordCandidateImage(int v, unsigned adr) {
  imgAdr = adr;
  return 1;
}

unsigned reportSelectedImage(void) {
  return imgAdr;
}

The xCORE loader first calls the function init, and then iterates
over each image in the boot partition. For each image, it calls
checkCandidateImageVersion with the image version number and, if
this function returns non-zero and its CRC is validated, it calls
recordCandidateImage with the image version number and address.
Finally, the loader calls reportSelectedImage to obtain the address
of the selected image.

To produce a custom loader, you are required to define the functions
init, checkCandidateImageVersion, recordCandidateImage and
reportSelectedImage.

The loader provides the function readFlashDataPage.

Build the loader

Add additional images

To load a program under control of the debugger, follow these
steps:

1. Select a project in the Project Explorer.
2. Choose RunDebug Configurations.
3. In the left panel, double-click XCore Application. xTIMEcomposer
   creates a new configuration and displays the default settings in
   the right panel.
4. In the Name text box, enter a name for the configuration.
5. xTIMEcomposer tries to identify the target project and executable for
   you. To select one yourself, click Browse to the right of the
   Project text box and select your project in the
   Project Selection dialog box. Then click Search Project and
   select the executable file in the Program Selection dialog
   box.

   You must have previously compiled your program without any errors
   for the executable to be available for selection.

6. If you have a development board connected to your system, in the
   the Device options panel check the hardware option and
   select your debug adapter from the Adapter list. Alternatively,
   check the simulator option to run your program on the
   simulator.
7. To save the configuration and launch the debugger, click
   Debug. If you are asked whether to open the Debug
   perspective, check Remember my decision and click Yes.

xTIMEcomposer loads your program in the debugger and opens it in the
Debug perspective.

xTIMEcomposer remembers the configuration last used to load your program.
To debug the program later using the same settings, just click the
Debug button () . To use a different
configuration, click the arrow to the right of the Debug button
and select a configuration from the drop-down list.

Once launched, the debugger runs the program until either an
exception is raised or you suspend execution by clicking the
Suspend button () .

Click the Resume button () to continue executing
a suspended program, or use one of the step controls to advance the
core selected in the Debug view incrementally:

• Step Into ()

  Executes a single line of source code
  on the core selected in the Debug view. If the next line of
  code is a function call, the debugger suspends at the first
  statement in the called function. All other cores are resumed.

• Step over ()

  Executes a single line of source
  code on the core selected in the Debug view. All other
  cores are resumed.

• Step return ()

  Steps the core selected in the
  Debug view until the current function returns.
  If the next line of code is a function
  call, the debugger executes the entire function. All other cores
  are resumed.

• Step through ()

  Switches the debugger context
  to the corresponding input core of a channel output
  statement. This is useful for following the path of data as it
  flows between cores. No cores are resumed.

When debugging optimized code, a step operation is not guaranteed
to advance to the next line in the source code, since the compiler
may have reordered instruction execution to improve performance.

Once a program is suspended, you can query the state of each core
and can inspect the values held in registers and memory.

• Examine a core’s call stack

  The Debug view displays a
  list of software tasks, each of
  which can be expanded to show its call stack, as shown in Debug view
  .

  Debug view

  

  In the example above, the tile tile[0] is suspended at a breakpoint in the function
  send_data on line 25 of the file debug.xc.

• Examine Variables

  The Variables view displays
  variables and their values. In the
  Debug view click on any function in a core’s call stack to
  view its variables, as shown in Variables view
  .

  Variables view

  

  To view a global variable, right-click in the Variables view,
  select Add Global Variables from the pop-up menu to open a
  dialog box and select the global variable to add to the view.

  Compiling a program without optimizations guarantees that every
  variable is held in memory for the duration of its scope so that
  its value can always be displayed. If optimizations are enabled, a
  variable may not be available to be examined, resulting in the
  message <value optimized out>.

You can do the following with variables:

• Display a variable’s value in hexadecimal format

  Right-click on a variable to bring up a menu and choose
  FormatHexadecimal. You can also choose binary,
  decimal or normal.
  The normal format is determined by the type of the variable.

• Change a variable’s value

  Click on a value to highlight it, enter a new value and press
  Enter. The table entry is highlighted yellow to indicate its
  value has changed. This allows you to test what happens under
  what-if scenarios.

• Prevent the debugger from reading a variable

  Right-click on a variable and choose Disable from the contextual
  menu. This is useful if the variable’s type is qualified with
  volatile.

  To apply settings to multiple variables at once, press Ctrl
  (Windows, Linux) or &cloverleaf; (Mac) while you click on multiple
  variables, then right-click and select an option from the
  contextual menu.

• Examine Memory

  The Memory view provides a list of memory monitors, each
  representing a section of memory. To open the Memory view, choose
  WindowShow ViewMemory. In the Debug view click on any core to
  view the contents of its memory, as shown in
  Memory view
  .

  Memory view

  

To specify a memory location to view, click the Add button
() to open the Memory Monitor dialog box, enter a
memory location and click OK. You can enter either an absolute
address or a C/XC expression. To view the contents of an array just
enter its name.

To display the memory contents in a different format such as Hex or
ASCII, click the New Renderings tab, select a format and click
Add Renderings. xTIMEcomposer adds new tabs in the panel to the right
of the Memory view, each showing a different interpretation of
the values in memory.

A breakpoint is a marker in the program that instructs the
debugger to interrupt execution so that you can investigate the
state of the program. You can add a breakpoint to any executable
line of code, causing execution to suspend before that line of code
executes.

To add a breakpoint, double-click the marker bar in the left margin
of the code editor next to the line at which you wish to suspend
execution. A blue dot () is displayed to
indicate the presence of the breakpoint. Note that the breakpoint
applies to every core that executes the function.

Breakpoints are also displayed in the Breakpoints view. To open
the Breakpoints view, choose WindowShowViewBreakpoints.
Double-click on a breakpoint to locate the corresponding line in
the source code editor.

Here are some other things can do with breakpoints:

• Set a conditional breakpoint

  Right-click on a breakpoint marker to bring up a contextual menu,
  and choose Breakpoint Properties to display a properties dialog
  box. Click the Common option in the left panel and enter a C/XC
  conditional expression in the Condition text box in the right
  panel. The expression can contain any variables in the scope of the
  breakpoint.

• Set a conditional breakpoint

  Right-click on a breakpoint marker to bring up a contextual menu,
  and choose Breakpoint Properties to display a properties dialog
  box. Click the Common option in the left panel and enter a C/XC
  conditional expression in the Condition text box in the right
  panel. The expression can contain any variables in the scope of the
  breakpoint.

• Set a watchpoint on a global variable

  A watchpoint is a special breakpoint that suspends execution
  whenever the value of an expression changes (without specifying
  where it might happen). Right-click anywhere in the Breakpoints
  view and choose Add Watchpoint C/XC from the contextual menu. Enter
  a C/XC expression in the dialog box, for example a[MAX]. Select
  Write to break when the expression is written, and Read to
  break when the expression is read.

• Disable a breakpoint

  In the Breakpoints view, clear the checkbox next to a
  breakpoint. Enable the checkbox to re-enable the breakpoint.

• Remove a breakpoint

  Double-click on a breakpoint marker in the code editor to remove
  it. Alternatively, right-click a breakpoint in the Breakpoints
  view and select Remove from the contextual menu; to remove all
  breakpoints, select Remove All.

The Disassembly view displays the assembly instructions that
are executed on the target platform. To open the Disassembly
view, choose WindowShow ViewDisassembly.

xTIMEcomposer automatically enables instruction stepping mode whenever
the Disassembly view has focus. Alternatively, click the
Instruction Stepping Mode button
() to enable. Once enabled, click
the Step button () to advance the program by a
single assembly instruction.

To configure the simulator, follow these steps:

1. Select a project in the Project Explorer.
2. Choose RunRun Configurations.
3. In the left panel, double-click XCore Application. xTIMEcomposer
   creates a new configuration and displays the default settings in the
   right panel.
4. In the right panel, in Name, enter a name for the configuration.
5. xTIMEcomposer tries to identify the target project and executable for you.
   To select one yourself, click Browse to the right of the
   Project text box and select your project in the Project
   Selection dialog box. Then click Search Project and select the
   executable file in the Program Selection dialog box.

   You must have previously compiled your program without any errors for
   the executable to be available for selection.

6. Select the simulator option and click the Simulator tab to
   configure additional options, as shown in
   the figure below.
   Simulator configuration options

   

   • To output the processor instruction trace during simulation,
     select Dump simulator trace.

     By default, the instruction trace is displayed in the
     Console. To write the trace to a file instead, select Trace
     to file and enter a filename. The filename must be different
     from all other files in your project.

     The format of the instruction trace is described No Caption
     .

   • To view a summary of the program’s execution once the program
     terminates, select Display statistics. The summary includes
     the instruction count for each logical core, and the number of
     data and control tokens sent through the switches.
   • To limit the number of cycles executed by the simulator, enter a
     value in the Limit cycles to text box. Leave blank if you want
     the program to run from start to finish. This is useful for
     simulating programs with infinite loops.
7. To save and run the configuration, click Run.

xTIMEcomposer loads your executable, displaying any output generated by your
program in the Console.

xTIMEcomposer remembers the configuration last used to run your program. To
run it again using the same configuration, just click the Run button () button. To use a different configuration, click the arrow to
the right of the Run button and select a configuration from the
drop-down list.

The simulator can output signal tracing data to a VCD file which you can
visualize with the xTIMEcomposer waveform viewer.

Enable signal tracing

View a trace file

View a signal

You can connect any two ports or pins together in your simulation, to
model connections between the pins. To configure a loopback, follow
these steps:

1. Create a simulator Run Configuration
   .
2. Click the Simulator tab to display the simulator configuration
   options.
3. Click the Loopback tab in the Plugins panel and select
   Enable pin connections.
4. In the Pin Connections panel, click Add. An empty loopback
   configuration is displayed. The loopback consists of two sets of
   options that you can configure for two different ports.

   Setting up a loopback connection

   

5. In the drop-down lists for each end of the connection, select a value
   for Tile and Port. If you leave the tile unspecified, the
   list of ports is taken from the project’s XN file and the tile is
   determined automatically. If you specify tile, the list of ports is
   taken from the header file <xs1.h>. To specify that only a subset of the
   pins are connected to the port, change the values for Offset and
   Width.
6. Click Run.

You can connect the simulator to any external plugin that has been
compiled on your host PC using the XMOS simulator plugin interface. To
configure an external plugin, follow these steps:

1. Create a simulator Run Configuration
   .
2. Click the Simulator tab to display the simulator configuration
   options.
3. In the Plugins panel, click the External tab.
4. Click Add to open the plugin configuration dialog.
   

   Setting up an external plugin

   

5. Select the plugin DLL and specify an optional command-line argument
   string.
6. Click Run to save your settings and run your program on the
   simulator with the specified plugins.

The recommended xConnect Link speed for most target hardware is 10ns between
transitions (10MByte/sec). This can be achieved by setting the link
interbit gap to 5 cycles (see Link
). The
latencies and maximum call rates for the probe functions using an xConnect
Link at this speed are given in XScope performance figures for xConnect Link with 5-cycle interbit gap
.

If two subsequent calls are made, the second call may be delayed in line
with the maximum frequency. For example, if xscope_probe_data_pred
is called twice, the second call is delayed by approximately 1.5µ s.

The maximum call rates can be increased by speeding up the link and
reducing the interbit gap (see Link
). A
small interbit gap requires careful layout of the link, since it
increases link frequency.

The UART interface executes at a rate of 2MB/s.

Many PCs are limited to inputting trace data from the XTAG-2 at a rate
of 500,000 trace records/sec or less. If your PC is unable to keep up it
will drop records, reducing the granularity of the trace data. The
XDE Scope view marks the loss of data on the timeline.

To allow the tools to configure the xCONNECT link required for high speed data collection using xscope, the XN file for a board must be modified to expose the connection to the XTAG-2 device. The following information must be added to the links section of an XN file for a board to set up the link used by the target device to communicate with the XTAG-2 and the xscope channel.

<Link Encoding="2wire" Delays="4,4" Flags="XSCOPE">
  <LinkEndpoint NodeId="0" Link="X0LD"/>
  <LinkEndpoint RoutingId="0x8000" Chanend="1"/>
</Link>

Note that when the link is set to 2 wire, the minimum delay is set to 4 and the flags specify that this link is to be used for streaming debug. Setting the delay higher results in the output of packets used by xscope being less frequent. The RoutingId is also important as the value 0x8000 specifies to the tools that this is a special link used for xscope.

When used in a multi-tile system the NodeId of the package which is connected to the XSYS connector must be specified. The tools set up the links with the other tiles but they need to know which specific device has the external link to be connected to the XTAG-2.

The example program in Program that traces input levels to a microphone
uses the xSCOPE
instrumentation functions to trace the input levels to a microphone.

#include <xscope.h>

port micL;
port micR;

void xscope_user_init(void) {
  xscope_register(2,
    XSCOPE_CONTINUOUS, "Microphone Left",  XSCOPE_UINT, "mV",
    XSCOPE_CONTINUOUS, "Microphone Right", XSCOPE_UINT, "mV"
  );
}

int main() {
  while (1) {
    int sample;
    micL :> sample;
    xscope_uint(0, sample);
    micR :> sample;
    xscope_uint(1, sample);
  }
}

The constructor xscope_user_init registers two probes
for tracing the left and right inputs to a microphone. The probes are
defined as continuous, which means xTIMEcomposer can interpolate
values between two subsequent measurements. The probes are
defined to take values of type unsigned int.

In main, the program calls the probe function
xscope_uint each time it samples data from the
microphone. This function creates a trace record and sends it to the PC.

The table below summarizes the
different types of probes that can be configured.
Only continous probes can be displayed real-time.

Once you have instrumented your program, you must compile and link it
with the xSCOPE library, and run it in either offline or real-time
mode.

To link with the xSCOPE library and run xSCOPE, follow these steps:

1. Open the Makefile for your project.
2. Locate the XCC_FLAGS_config variable for your build
   configuration, for example XCC_FLAGS_Release.
3. Add the option -fxscope.
4. Create a Run Configuration for your target device
   .
5. Click the ** xSCOPE** tab and select Offline Mode to save data to a file for offline analysis,
   or Real-Time Mode to output the data to the real-time viewer.

   • In offline mode, xTIMEcomposer logs trace data until program termination and
     saves the traced data to the file xscope.xmt. To change, enter a
     filename in the Output file text box. To limit the size of the trace file,
     enter a number in the Limit records to text box.
   • In real-time mode, xTIMEcomposer opens the Scope view and displays an
     animated view of the traced data as the program executes.

6. Click Run to save and run the configuration.

Double-click a trace file in Project Explorer to open it in the Scope view,
as shown in the figure below.

The top panel of the Scope view displays a graph
of the data values for each selected probe: the x-axis represents time
(as per the timeline in the bottom panel) and the y-axis represents
the traced data values. The probes are grouped by their assigned units,
and multiple probes with the same unit can be overlaid onto a single
graph.

Moving the cursor over the scope data displays the
current data (y-value) and time (x-value) in the
first two of the four numeric boxes at the top of the window. Left-click
on the view to display a marker as a red line – the associated time is
displayed in the third numeric box. The fourth numeric box displays the
difference between the marker time and the current cursor position.

If the cursor changes to a pointing finger, double-click to
locate the statement in the source code responsible for generating the
trace point.

The bottom panel of this view displays a timeline for each probe:
vertical lines on a probe’s timeline indicate times at which the probe
created a record.

Drag the Buffer Position slider left or right to move through the timeline.
To show more information in the window, increase the value in the Buffer Size field.

Use the Scope view toolbar at the top of the window to perform additional tasks:

To show data points for interpolated continuous signals, click the
Continuous points button () .

To view all data points, click the Zoom Fit
button () .

Load a trace file that is not part of your project, click the
Open button () and browse to the file.

The Scope view can display trace data streamed from hardware in real-time.
The left panel displays the signal information and controls and the right
panel displays the screen view for the signals.

The left panel displays a list of the continous probes registered by the
application (see Instrument a program
). Each
named probe is assigned a color that is used to draw events on the display,
and which is used to identify the probe in the screen panel.

The Scope view is based around a traditional oscilloscope, and data is
captured around a trigger, and then displayed. The capture mode,
display mode, trigger and timebase are all controlled in the left panel.
The right panel has 10 horizontal and vertical divisions, and the scales
are all shown as units per division.

Numeric controls can all be modified by using the mouse: click the left
button to increase the value or the right button to decrease the value. The
scroll wheel can be used if your platform supports it (Mac OS/X,
Linux, and some but not all versions of Windows).

Capture control

Signal Control

Trigger Control

Timebase Control

Screen Control

If you are using a legacy FTDI or XTAG-1 debug adapter, or if the XSYS
connector on your target hardware does not provide an xCONNECT Link, you can
output data over the UART interface provided by your adapter.

To use the UART interface, you must provide the xSCOPE library with a 1-bit
UART TX port that has been initialized with the pin connected to the UART-TX
pin on your debug adapter. An example initialization is shown below.

#include <platform.h>
#include <xscope.h>

port uart_tx = PORT_UART_TX;

void xscope_user_init(void) {
  xscope_register(2,
    XSCOPE_CONTINUOUS, "Microphone Left",  XSCOPE_UINT, "mV",
    XSCOPE_CONTINUOUS, "Microphone Right", XSCOPE_UINT, "mV"
  );
  xscope_config_uart(uart_tx);
}

Because the UART interface uses a port instead of an xCONNECT Link, the
probe functions can be called on a single tile only.

To create a Run Configuration, follow these steps:

1. Select a project in the Project Explorer.
2. Choose RunRun Configurations.
3. In the left panel, double-click XCore Application.

   xTIMEcomposer creates a new configuration and displays the default
   settings in the right panel, as shown in the figure below.

   Run Configuration window

   

4. In Name, enter a name for the configuration.
5. xTIMEcomposer tries to identify the target project and executable for you.
   To select one yourself, click Browse to the right of the
   Project text box and select your project in the Project
   Selection dialog box. Then click Search Project and select the
   executable file in the Program Selection dialog box.

   You must have previously compiled your program without any errors for
   the executable to be available for selection.

6. If you have a development board connected to your system, check the
   hardware option and select your debug adapter from the
   Target list. Alternatively, check the simulator option to
   run your program on the XMOS simulator.
7. Click Run.

xTIMEcomposer loads your executable, displaying any output generated by your
program in the Console.

xTIMEcomposer remembers the configuration last used to run your program. To
run it again using the same configuration, just click the Run button () . To use a different configuration, click the arrow to the
right of the Run button and select a configuration from the
drop-down list.

The following options are used to specify an executable to run and,
optionally, an xCORE tile on which to run the program.

• xe-file

  Specifies an XE file to load and run.

• –verbose

  Prints information about the program loaded onto the target devices.

• –help

  Prints a description of the supported command line options.

• –version

  Displays the version number and copyrights.

The following options are used to specify a target hardware platform.

• –list-devices

  -l

  Prints an enumerated list of all JTAG adapters connected to the host
  and the devices on each JTAG chain, in the form:

  ID        Name        Adapter ID        Devices

  --        ----        ----------        -------

  The adapters are ordered by their serial numbers.

• –list-board-info

  -lb

  Displays information about the connected target board.

• –id ID

  Specifies the adapter connected to the target hardware.

• –adapter-id ADAPTER-SERIAL-NUMBER

  Specifies the serial number of the adapter connected to the target
  hardware.

• –jtag-speed n

  Sets the divider for the JTAG clock to n. If unspecified, the default
  value is 0. The maximum value is 70.

  For FTDI-based debug adapters, the JTAG clock speed is set to
  6/(n+1)MHz.

  For XMOS-based debug adapters, the JTAG clock speed is set to
  25/(n+1)MHz.

• –noreset

  Does not reset the XMOS devices on the JTAG scan chain before loading
  the program. This is not default.

The following options are used to enable debugging capabilities.

• –io

  Causes XRUN to remain attached to the JTAG adapter after loading the
  program, enabling system calls with the host. XRUN terminates when
  the program calls exit.

  By default, XRUN disconnects from the JTAG adapter once the program
  is loaded.

• –uart

  Enables a UART server that interfaces with the UART-to-USB converter
  on the XMOS USB-to-JTAG adapters. The converter operates at a rate of
  115200 bits/sec.

  The USB-to-UART converter on XMOS adapter interfaces with two pins on
  the XSYS connector that, on XMOS development boards, are connected to
  ports on an XMOS device. The ports are named in the XN files as
  PORT_UART_TX and PORT_UART_RX.

  This option is not supported for adapters based on FTDI chips.

• –attach

  Attaches to a JTAG adapter (of a running program), enabling system
  calls with the host. XRUN terminates when the program performs a call
  to exit.

  An XE file must be specified with this option.

• –dump-state

  Prints the core, register and stack contents of all xCORE Tiles in JTAG
  scan chain.

The following options are used to enable XScope capabilities.

• –xscope

  Enables an XScope server with the target.

• –xscope-realtime

  Enables an XScope server with the target using a socket connection.

• –xscope-file filename

  Specifies the filename for XScope data collection.

• –xscope-port ip:port

  Specifies the IP address and port for realtime data capture.

• –xscope-limit limit

  Specifies the record limit for XScope data collection.

To load a program under control of the timing analyzer, follow these
steps:

1. Select a project in the Project Explorer.
2. Choose RunTime Configurations.
3. In the left panel, double-click XCore Application. xTIMEcomposer
   creates a new configuration and displays the default settings in the
   right panel.
4. xTIMEcomposer tries to identify the target project and executable for you.
   To select one yourself, click Browse to the right of the
   Project text box and select your project in the Project
   Selection dialog box. Then click Search Project and select the
   executable file in the Program Selection dialog box.

   You must have previously compiled your program without any errors for
   the executable to be available for selection.

5. In the Name text box, enter a name for the configuration.
6. To save the configuration and launch the timing analyzer, click
   Time.

xTIMEcomposer loads your program in the timing analyzer and opens it in the
Timing perspective. In this perspective the editor is read-only, to
ensure the relationship between the binary and source code remains consistent.

xTIMEcomposer remembers the configuration last used to load your program. To
load XTA the program later using the same settings, just click the
XTA button () . To use a different configuration, click
the arrow to the right of the XTA button and select a configuration
from the drop-down list.

A route consists of the set of all paths through which control can
flow between two points (or endpoints) in a program. Each route has a
best-case time, in which branches always follow the path that takes the
shortest time to execute, and a corresponding worst-case time.

To specify a route and analyze it, follow these steps:

1. Right-click on an endpoint marker () in the editor
   margin and choose Set from endpoint. xTIMEcomposer displays a green dot
   in the top-right quarter of the marker () .
2. Right-click on an endpoint marker and choose Set to endpoint.
   xTIMEcomposer displays a red dot in the bottom-right quarter of the
   marker () .

   You can specify a start point above an end point. You can also
   specify a start point at or below an end point, defining a route
   whose paths flow out and then back into the function. This is typical
   of functions called multiple times or from within a loop.

3. Click the Analyze Endpoints button ()
   in the main toolbar. xTIMEcomposer analyzes all the paths in the specified
   route, displaying a tree-like representation in the lower panel of
   the Routes view and a graph-like representation in the
   Structure tab of the Visualizations view.

   Alternatively, to analyze the time taken to execute a function, just
   click the Analyze Function button () in
   the main toolbar and select a function from the drop-down list.

xTIMEcomposer provides endpoint markers for all statements whose order is
guaranteed to be preserved during compilation. These statements include
I/O operations and function calls.

Visualize a route

The Visualizations view

The Visualizations view provides graphical representations of the
route. The Structure tab represents the route as a line that flows from
left to right, as shown in the example below. The route forks into
multiple paths whenever the code branches, and all paths join at its
end. The best-case timing path is highlighted in green, the worst-case
path in red, and all other paths are colored gray.

Visualizations view

In both the Route view and Structure view, you can hover over a
node to display a summary of its timing properties. Click on a node to
highlight its source code in the editor, or double-click to go to the
line at the start of the node. In the Structure view, double-click
on a function name to expand or collapse it.

A timing requirement specifies how long the paths in a route may take
to execute for the program to behave correctly. In the top panel of the
Routes view, the status of each route is indicated by an icon to the
left of its name:

• No timing requirement is specified () .
• A timing requirement is specified and met () .
• A timing requirement is specified and met, subject to all I/O instructions being ready to execute () .
• A timing requirement is specified and not met () .

To specify a timing requirement, right-click on a route and choose Set
timing requirements. A dialog box opens. Enter the maximum time in
which the paths must execute in either ns, cycles or MHz and click
OK. xTIMEcomposer updates the status of the route.

Under some conditions the timing analyzer is unable to prove timing
without additional information. Examples of common conditions include:

• The route contains an I/O instruction that can pause for an unknown
  length of time.
• The route contains a loop with a data-dependent exit condition.
• A path fails to meet timing, but the path is only executed as a
  result of an error condition and is not therefore timing critical.

In these cases you can provide the timing analyzer additional
information about the execution of your program. Armed with this
additional information, the analyzer may then be able to prove that a
route’s timing requirement is met. Information you can provide includes:

• The number of loop iterations

  Right-click on a loop node and choose Set loop iterations to
  display a dialog box. Enter a maximum loop count and click OK.

• The maximum pause time for an I/O instruction

  Right-click on an instruction node and choose Set instruction
  time to display a dialog box. Enter a value, select a unit of
  time/rate (such as nanoseconds or MHz) and click OK.

• Exclude a path from the route

  Right-click on a node and choose Exclude.

Refine the worst-case analysis

Once you’ve specified the timing requirements for your program,
including any refinements about its execution, you can
generate a script that checks these requirements at compile-time.

To create a script that checks all timing requirements specified in the
Routes view, follow these steps:

1. Click the Generate Script button () .
   Script Options dialog box

   

2. In the Script location text box, enter a filename for the script.
   The filename must have a .xta extension.
3. To change the names of the pragmas added to the source file, modify
   their values in the Pragma name fields.
4. Click OK to save the script and update your source code. xTIMEcomposer
   adds the script to your project and opens it in the editor. It also
   updates your source files with any pragmas required by the script.

The next time you compile your program, the timing requirements are
checked and any failures are reported as compilation errors.
Double-click on a timing error to view the failing requirement in the
script.