Search Results for: xta

XScope performance figures

Data transferred from the xCORE device to the debug adapter is lossless,
but data transferred from the debug adapter to your host PC may be
lossy, depending on the speed of your PC.

Transfer rates between the xCORE Tile and XTAG-2

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
.

XScope performance figures for xConnect Link with 5-cycle interbit gap

Probe function

Latency (core cycles)

Max calls/sec

xscope_probe_data_pred

15 (always)

666,000

xscope_probe

20 (with no contention)

999,000

xscope_probe_cpu

27 (with no contention)

666,000

xscope_probe_data

22 (with no contention)

666,000

xscope_probe_cpu_data

28 (with no contention)

555,000

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.

Transfer rates between the XTAG-2 and Host PC

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.

Use xTIMEcomposer and xSCOPE to trace data in real-time

Use xTIMEcomposer and xSCOPE to trace data in real-time

xTIMEcomposer and the xSCOPE library let you instrument your program
with probes that collect application data in real-time. This
data can be sent over an XTAG-2 debug adapter to xTIMEcomposer
for real-time display or written to a file for
offline analysis.

xSCOPE connectivity
/files/images/14796/10/xscope-configuration.png

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
configure the probes to output trace data over your adapter’s UART interface
instead

. Note that
the UART interface is supported on a single tile only and offers significantly
reduced performance.

XN File Configuration

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.

Instrument a program

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.

Program that traces 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.

Supported probe types

Probe Type

Data Type

Scope View

Example

XSCOPE_CONTINUOUS

XSCOPE_UINT

Line graph. May

Voltage levels of a motor

 

XSCOPE_INT

be interpolated

controller

 

XSCOPE_FLOAT

   

XSCOPE_DISCRETE

XSCOPE_INT

Horizontal lines

Buffer levels of audio CODEC

XSCOPE_STATEMACHINE

XSCOPE_UINT

State machine

Progression of protocol

XSCOPE_STARTSTOP

XSCOPE_NONE

Start/stop bars

Recorded function entry

 

XSCOPE_UINT

 

and exit, with

 

XSCOPE_INT

 

optional label value

 

XSCOPE_FLOAT

   

Configure and run a program with tracing enabled

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.

Analyze data offline

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

Offline Scope view

/files/images/14796/10/m-scope-view.png

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 (Continuous points button) .

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

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

Analyze data in real-time

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.

Real-Time Scope view

/files/images/14796/10/xscope_real_time.png

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

There are three capture-modes: continous, single capture or stopped.
The default mode on start-up is for the system to capture and
display continuously. The label associated with the capture controls
shows the current state of the xSCOPE system.

Capture controls

/files/images/14796/10/run_controls.png

Stop Display

  • Stops the screen panel from triggering and capturing, no more updates
    will be applied to the screen whilst this mode is set. The mode can be
    used to inspect the captured data. The mouse can be used to change
    signal and time base scales and offsets as described below to inspect
    the signals in detail. When stopped, you can zoom in on the time
    base and view the signal in more detail: the displayed signals are
    subsampled when the timebase is large, and zooming in on the timebase
    will reveal all data.

Single Capture

  • Selest single shot mode to capture one screen of
    data and return to the stopped state. If a trigger is enabled (see
    Trigger Controls
    ) the system will
    wait for this trigger condition to be met before updating the screen
    and returning to the stopped state.

Continuous Capture

  • Select free running mode to update the screen as frequently as possible.
    If triggers are enabled, the screen will update only when the trigger
    is met.

Signal Control

The signal controls are available for each registered probe on the coloured
label displayed in the left panel (see
the figure below)

Signal Controls

/files/images/14796/10/signallabel-wide.png

Enable / Disable Signal

  • Toggle the visibility of the signal by double clicking on the name.

Signal Samples/Div

  • Change the Samples per Division of this probe with the mouse buttons;
    this affects the vertical scale of the signal.

Signal Screen Offset

  • Change the vertical Offset of this probe with the mouse buttons;
    this affects the vertical position of the signal.

Signal Trigger

  • The signal can be used as a trigger (see
    Trigger Controls
    ) by clicking in
    trigger box to the left of the probe label. Only one signal can be
    used for triggering.

Trigger Control

A trigger can be used to restrict the system so that data is only captured
when a condition is met. By default all triggers are disabled, causing data
to be captured unconditionally. To enable triggering, a trigger must be
selected by clicking on the box to the left of the probe label.

When triggering is enabled, a cross appears on the screen showing the
trigger level (relative to the signal on which the trigger is selected) and
the trigger offset on the timebase. The center of the cross is the time
and value where the trigger happens/happened; to the left of this are
the signals that lead up to the trigger; to the right are the signals after
the trigger.

The trigger level and offset can be set directly by clicking in the right-hand
pane. Changes only take effect if the scope is not stopped, and either
running continuously, or set for a single trigger.

Trigger Controls

/files/images/14796/10/trigger_controls.png

Always

  • Disables the trigger and captures data unconditionally.

Rising

  • Trigger on a rising edge of the signal. This is the default mode when
    selecting a signal to be used for triggering.

Falling

  • Trigger on a falling edge of the signal.

The value label associated with the enabled trigger shows the current
trigger value set for the signal. This can be changed by using the mouse buttons.

Timebase Control

The timebase controls are used to set the time range for the signal capture
window, allowing you to scale and shift the horizontal axis.

Timebase Controls

/files/images/14796/10/timebase.png

Time Window

  • The current size to the time window. Scales all signals in time and
    affects the time per division.

Time per Division

  • The time units per division. Scales all signals in time and
    affects the time window.

Time Window Offset

  • The position of the trigger in the time window. Shifts all signals
    left and right. Note that the trigger may not be visible, and could
    be to the left or right of the time window. The signals can be
    shifted right only a limited value.

Screen Control

Several commands are available that operate on all signals.

Screen Controls

/files/images/14796/10/screen_controls.png

Auto Range Signals

  • Automatically arranges all current signals to fit on the screen.
    The signals are measured for a short while, and each signal scaled
    and offset to fit the screen. All signals are displayed across each other.

Separate Signals

  • Similar to Auto Range, but all signals are scaled to fit in a
    small part of the screen. All signals are offset so that they
    are visible separately.

Persistant Display

  • Disabled.

Save Data

  • Saves the current scope view to a PNG file in a user-defined location.

Trace using the UART interface

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.

Documentation

Use xTIMEcomposer to time a program

The xCORE Timing Analyzer lets you determine the time taken to execute
code on your target platform. Due to the deterministic nature of the
xCORE architecture, the tools can measure the shortest and longest time
required to execute a section of code. When combined with user-specified
requirements, the tools can determine at compile-time whether all
timing-critical sections of code are guaranteed to execute within their
deadlines.

Launch the timing analyzer

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 (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.

Time a section of code

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 (xta endpoint marker) in the editor
    margin and choose Set from endpoint. xTIMEcomposer displays a green dot
    in the top-right quarter of the marker (xta from icon) .
  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 (xta to icon) .

    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 (xta 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 (xta 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 Routes view displays a structural representation of the route.
Each time you analyze a route, an entry is added to the top panel. Click
on a route to view it in the bottom panel. It is represented using the
following nodes:

  • A source-level function (xta function icon) .
  • A list of nodes that are executed in sequence (xta sequence icon) .
  • A set of nodes that are executed conditionally (xta conditional icon) .
  • A loop consisting of a sequence of nodes in which the last node can branch back to the first node (xta loop icon) .
  • A block containing a straight-line sequence of instructions (xta block icon) .
  • A single machine instruction (xta instruction icon) .

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
/files/images/14793/6/m-xta-structure-layout.png

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.

Specify timing requirements

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 (xta not set icon) .
  • A timing requirement is specified and met (xta pass icon) .
  • A timing requirement is specified and met, subject to all I/O instructions being ready to execute (xta pass io icon) .
  • A timing requirement is specified and not met (xta fail icon) .

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.

Add program execution information

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

By default, the timing analyzer assumes that a route always follows
branches that take the longest time to execute. If you know that this is
not the case, for example through inspection during simulation or a
formal analysis of your program, you can refine the parameters used by
the analyzer. Refinements you can make include:

  • Specifying an absolute execution time for a function call

    Right-click on a function node and choose Set function time to open a
    dialog box. Enter a time and click OK.

  • Specifying an absolute time for a path

    Select a path by holding down Ctrl (Windows, Linux) or &cloverleaf;
    (Mac) and clicking on two instruction nodes, then right-click and
    choose Set path time to open a dialog box. Enter a time and click
    OK.

  • Specifying the number of times a node is executed

    By default, the analyzer assumes that the number of times a node is
    executed is the multiplication of each loop count in its scope. To
    change the iteration count to be an absolute value, right-click on a
    node and choose Set loop scope to open a dialog box. Select
    Make scope absolute and click OK.

  • Specifying the number of times a conditional is executed in a loop

    By default, the analyzer assumes that a conditional node always
    follows the path that takes the longest time to execute. To specify
    the number of times a conditional target is executed, right-click on
    the target node and choose Set loop path iterations to open a
    dialog box. Enter the number of iterations and click OK.

Validate timing requirements during compilation

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 (xta script button) .
    Script Options dialog box

    /files/images/14793/6/m-xta-script-options.png

  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.

Documentation

XCC Pragma Directives

xTimeComposer supports the following pragmas.

  • #pragma unsafe arrays

    (XC Only) This pragma disables the generation of run-time safety checks that
    prevent indexing an invalid array element within the scope of the
    next do, while or for statement in the current function;
    outside of a function the pragma applies to the next function
    definition.

  • #pragma loop unroll (n)

    (XC only) This pragma controls the number of times the next do, while
    or for loop in the current function is unrolled. n specifies
    the number of iterations to unroll, and unrolling is performed only
    at optimization level 01 and higher. Omitting the n
    parameter causes the compiler to try and fully unroll the loop.
    Outside of a function the pragma is ignored. The compiler produces a
    warning if unable to perform the unrolling.

  • #pragma stackfunction n

    This pragma allocates n words (ints) of stack space for the
    next function declaration in the current translation unit.

  • #pragma stackcalls n

    (XC only) This pragma allocates n words (ints) of stack space for any
    function called in the next statement. If the next statement does not
    contain a function call then the pragma is ignored; the next statement
    may appear in another function.

  • #pragma ordered

    (XC only) This pragma controls the compilation of the next select
    statement. This select statement is compiled in a way such that if
    multiple events are ready when the select starts, cases earlier in
    the select statement are selected in preference to ones later on.

  • #pragma select handler

    (XC only) This pragma indicates that the next function declaration is a select
    handler. A select handler can be used in a select case, as shown in
    the example below.

    #pragma select handler
    void f(chanend c, int &token, int &data);
    
    ...
    select {
      case f(c, token, data):
        ...
        break;
    }
    ...
    

    The effect is to enable an event on the resource that is the first
    argument to the function. If the event is taken, the body of the
    select handler is executed before the body of the case.

    The first argument of the select handler must have transmissive type
    and the return type must be void.

    If the resource has associated state, such as a condition, then the
    select will not alter any of that state before waiting for events.

  • #pragma fallthrough

    (XC only) This pragma indicates that the following switch case is expected to
    fallthrough to the next switch case without a break or return
    statement. This will suppress any warnings/errors from the compiler
    due to the fallthrough.

  • #pragma xta label "name"

    This pragma provides a label that can be used to specify timing
    constraints.

  • #pragma xta endpoint "name"

    (XC only) This pragma specifies an endpoint. It may appear before an input or
    output statement.

  • #pragma xta call "name"

    (XC only) This pragma defines a label for a (function) call point. Use to
    specify a particular called instance of a function. For example, if a
    function contains a loop, the iterations for this loop can be set to a
    different value depending on which call point the function was called from.

  • #pragma xta command "command"

    (XC only) This pragma allows XTA commands to be embedded into source code.
    All commands are run every time the binary is loaded into the XTA. Commands are
    executed in the order they occur in the file, but the order between commands in
    different source files is not defined.

  • #pragma xta loop (integer)

    (XC only) This pragma applies the given loop XTA iterations to the loop containing the pragma.

XCC Command-Line Manual

XCC is the front-end to the xCORE C, C++ and XC compilers. Typical usage results in preprocessing,
compilation, assembly, linking, and mapping code and data onto tiles. Some options allow
this process to be stopped at intermediate stages and other options are passed to one stage of
processing. Most options have negative forms (for example, -fno-option). A space between an
option and its argument is permitted.

Build settings for an application are defined in the application Makefile. Double click the Makefile in the Project Explorer to open it in the Makefile Editor.

Overall Options

The four possible stages of compilation are preprocessing,
compilation proper, assembly and linking/mapping. The first three
stages are applied to an individual source file, producing an
object file. Linking and mapping combine the object files and an XN
file into a single executable XE file, which contains the code and
data segments for each tile.

  • source-file

    The suffix of a source file determines how it is handled by
    default.

File extensions recognized by XCC and their meaning

Extension

Type of File

Preprocessed by XCC

.xc

XC source code

Y

.c

C source code

Y

.cpp

CPP source code (for compatability, the extensions cc, cp, c++, C and cxx are also recognized)

Y

.S

Assembly code

Y

.xta

xCORE Timing Analyzer script

N

.xn

xCORE Network Description

N

.xi

XC source code

N

.i

C source code

N

.ii

C++ source code

N

.s

Assembly code

N

other

Object file .o be given to the linker

N

  • -xlanguage

    Specifies the language for the following input files. This option
    applies to all following input files until the next -x option.
    Supported values for language are:

    • xc
    • c
    • c++
    • assembler
    • assembler-with-cpp
    • xn
    • xta
    • none (turn off language specification)

  • -std=standard

    Specifies the language variant for the following input C or C++
    file. Supported values for standard are:

    c89

    ISO C89

    gnu89

    ISO C89 with GNU extensions

    c99

    ISO C99

    gnu99

    ISO C99 with GNU extensions (default for C programs)

    c++98

    ISO C++ (1998)

    gnu++98

    ISO C++ (1998) with GNU extensions (default for C++ programs)

  • -fsubword-select

    In XC, allows selecting on channel inputs where the size of
    the desstination variable is less than 32 bits.

    This is default for targets based on XS1-L devices. It is not
    default for targets based on XS1-G devices. For further details,
    see Channel Communication
    .

  • -target=platform

    Specifies the 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
    .

  • -foverlay

    Enable support for memory overlays. Functions marked as overlay roots are
    placed in external memory and are loaded on demand at runtime. The option
    should be passed when compiling and linking. An overlay runtime should be
    supplied in the application.

  • -foverlay=flash

    Enable support for memory overlays linking in the flash overlay runtime.
    Overlays are only enabled on tiles which boot from flash.

  • -foverlay=syscall

    Enable support for memory overlays linking in the syscall overlay runtime.
    Overlay are enabled on all tiles. Overlays are loaded from a host machine
    using a system call.

  • -fxscope

    Enable support for xSCOPE tracing. The XN file of the target must
    contain an xSCOPE link. The option should be passed when compiling and linking.

  • -funroll-loops

    Unroll loops with small iteration counts.
    This is enabled at -O2 and above.

  • -finline-functions

    Integrate simple functions into their callers.
    This is enabled at -O2 and above and also at -Os.

  • -pass-exit-codes

    Returns the numerically highest error code produced by any phase of
    compilation. (By default XCC returns 1 if any phase of the compiler
    returns non-success, otherwise it returns 0.)

  • -c

    Compiles or assembles the source files, producing an object file
    for each source file, but does not link/map. By default the object
    filename is formed by replacing the source file suffix with .o
    (for example, a.c produces a.o).

  • -S

    Stops after compilation proper, producing an assembly code file for
    each nonassembly input file specified. By default the assembly
    filename is formed by replacing the source file suffix with .s.

    Input files not requiring compilation are ignored.

  • -E

    Preprocesses the source files only, outputting the preprocessed
    source to stdout.

    Input files not requiring preprocessing are ignored.

  • -ofile

    Places output in file.

    If -o is not specified, the executable file is placed in
    a.xe, the object file for source.suffix in source.o,
    its assembly code file in source.s, and all preprocessed
    C/C++/XC source on standard output.

  • -v

    Prints (on standard error) the commands executed at each stage of
    compilation. Also prints the version number of XCC, the
    preprocessor and the compiler proper.

  • -###

    The same as -v except that the commands are not executed and
    all command arguments are quoted.

  • --help

    Prints a description of the supported command line options. If the
    -v option is also specified, --help is also passed to the
    subprocesses invoked by XCC.

  • --version

    Displays the version number and copyrights.

Warning Options

Many specific warnings can be controlled with options beginning
-W. Each of the following options has a negative form beginning
-Wno- to turn off warnings.

  • -fsyntax-only

    Checks the code for syntax errors only, then exits.

  • -w

    Turns off all warning messages.

  • -Wbidirectional-buffered-port

    Warns about the use of buffered ports not qualified with either in or out.
    This warning is enabled by default.

  • -Wchar-subscripts

    Warns if an array subscript has type char.

  • -Wcomment

    Warns if a comment-start sequence /* appears in a /*
    comment, or if a backslash-newline appears in a // comment.
    This is default.

  • -Wimplicit-int

    Warns if a declaration does not specify a type. In C also warns
    about function declarations with no return type.

  • -Wmain

    Warns if the type of main is not a function with external linkage
    returning int. In XC also warns if main does not take zero
    arguments. In C also warns if main does not take either zero or
    two arguments of appropriate type.

  • -Wmissing-braces

    Warns if an aggregate or union initializer is not fully bracketed.

  • -Wparentheses

    Warns if parentheses are omitted when there is an assignment in a
    context where a truth value is expected or if operators are nested
    whose precedence people often find confusing.

  • -Wreturn-type

    Warns if a function is defined with a return type that defaults to
    int or if a return statement returns no value in a function
    whose return type is not void.

  • -Wswitch-default

    Warns if a switch statement does not have a default case.

  • -Wswitch-fallthrough

    (XC only) Warns if a case in a switch statement with at least one
    statement can have control fall through to the following case.

  • -Wtiming

    Warns if timing constraints are not satisfied. This is default.

  • -Wtiming-syntax

    Warns about invalid syntax in timing scripts. This is default.

  • -Wunused-function

    Warns if a static function is declared but not defined or a
    non-inline static function is unused.

  • -Wunused-parameter

    Warns if a function parameter is unused except for its
    declaration.

  • -Wunused-variable

    Warns if a local variable or non-constant static variable is unused
    except for its declaration.

  • -Wunused

    Same as -Wunused-function, -Wunused-variable and
    -Wno-unused-parameter.

  • -Wall

    Turns on all of the above -W options.

The following -W... options are not implied by -Wall.

  • -Wextra

    -W

    Prints extra warning messages for the following:

    • A function can return either with or without a value (C, C++
      only).
    • An expression statement or left-hand side of a comma expression
      contains no side effects. This warning can be suppressed by casting
      the unused expression to void (C, C++ only).
    • An unsigned value is compared against zero with < or <=.
    • Storage-class specifiers like static are not the first
      things in a declaration (C, C++ only).
    • A comparison such as x<=y<=z appears (XC only).
    • The return type of a function has a redundant qualifier such as
      const.
    • Warns about unused arguments if -Wall or -Wunused is
      also specified.
    • A comparison between signed and unsigned values could produce an
      incorrect result when the signed value is converted to unsigned.
      (Not warned if -Wno-sign-compare is also specified.)
    • An aggregate has an initializer that does not initialize all
      members.
    • An initialized field without side effects is overridden when
      using designated initializers (C, C++ only).
    • A function parameter is declared without a type specifier in
      K&R-style functions (C, C++ only).
    • An empty body occurs in an if or else statement (C, C++
      only).
    • A pointer is compared against integer zero with <, <=,
      >, or >=. (C, C++ only).
    • An enumerator and a non-enumerator both appear in a conditional
      expression. (C++ only).
    • A non-static reference or non-static const enumerator and a
      non-enumerator both appear in a conditional expression (C++ only).
    • Ambiguous virtual bases (C++ only).
    • Subscripting an array which has been declared register (C++
      only).
    • Taking the address of a variable which has been declared
      register (C++ only).
    • A base class is not initialized in a derived class’ copy
      constructor (C++ only).
  • -Wconversion

    Warns if a negative integer constant expression is implicitly
    converted to an unsigned type.

  • -Wdiv-by-zero

    Warns about compile-time integer division by zero. This is
    default.

  • -Wfloat-equal

    Warns if floating point values are used in equality comparisons.

  • -Wlarger-than-len

    Warns if an object of larger than len bytes is defined.

  • -Wpadded

    Warns if a structure contains padding. (It may be possible to
    rearrange the fields of the structure to reduce padding and thus
    make the structure smaller.)

  • -Wreinterpret-alignment

    Warns when a reinterpret cast moves to a larger alignment.

  • -Wshadow

    Warns if a local variable shadows another local variable, parameter
    or global variable or if a built-in function is shadowed.

  • -Wsign-compare

    Warns if a comparison between signed and unsigned values could
    produce an incorrect result when the signed value is converted to
    unsigned.

  • -Wsystem-headers

    Prints warning messages for constructs found in system header
    files. This is not default. See Directory Options
    .

  • -Wundef

    Warns if an undefined macro is used in a #if directive.

  • -Werror

    Treat all warnings as errors.

  • -Werror=option

    Turns a warning message into an error. The option should be one of
    the warning options to the compiler that can be prefixed with
    -W.

    By default, the flag -Werror=timing-syntax is set. Turning this
    warning into an error implies that timing warnings (-Wtiming)
    are also errors and vice versa.

Debugging Options

  • -g

    Produces debugging information.

  • -fxta-info

    Produces timing information for use with XTA. This is default.

  • -fresource-checks

    Produces code in the executable that traps if a resource allocation
    fails. This causes resource errors to be detected as early as
    possible.

  • -save-temps

    Saves the intermediate files. These files are placed in the current
    directory and named based on the source file.

  • -fverbose-asm

    Produces extra compilation information as comments in intermediate
    assembly files.

  • -dumpmachine

    Prints the target machine and exit.

  • -dumpversion

    Prints the compiler version and exit.

  • -print-multi-lib

    Prints the mapping from multilib directory names to compiler
    switches that enable them. The directory name is seperated from the
    switches by ‘;‘, and each switch starts with a ‘@‘ instead
    of the ‘-‘, without spaces between multiple switches.

  • -print-targets

    Prints the target platforms supported by the compiler. The target
    names correspond to strings accepted by the -target option.

Optimization Options

Turning on optimization makes the compiler attempt to improve
performance and/or code size at the expense of compilation time and
the ability to debug the program.

  • -O0

    Do not optimize. This is the default.

  • -O

    -O1

    Optimize. Attempts to reduce execution time and code size without
    performing any optimizations that take a large amount of
    compilation time.

  • -O2

    Optimize more. None of these optimizations involve a space-speed
    tradeoff.

  • -O3

    Optimize even more. These optimizations may involve a space-speed
    tradeoff; high performance is preferred to small code size.

  • -Os

    Optimize for the smallest code size possible.

  • -fschedule

    Attempt to reorder instructions to increase performance. This is
    not default at any optimization level.

Preprocessor Options

The following options control the preprocessor.

  • -E

    Preprocesses only, then exit.

  • -Dname

    Predefines name as a macro with definition 1.

  • -Dname=definition

    Tokenizes and preprocesses the contents of definition as if it
    appeared in a #define directive.

  • -Uname

    Removes any previous definition of name.

    -D and -U options are processed in the order given on the
    command line.

  • -MD

    Outputs to a file a rule suitable for make describing the
    dependencies of the source file. The default name of the dependency
    file is determined based on whether the -o option is specified.
    If -o is specified, the filename is the basename of the
    argument to -o with the suffix .d. If -o is not
    specified, the filename is the basename of the input file with the
    suffix .d. The name of the file may be overriden with -MF.

  • -MMD

    The same as -MD expect that dependencies on system headers are
    ignored.

  • -MF file

    Specifies the file to write dependency information to.

  • -MP

    Emits phony targets for each dependency of the source file. Each
    phony target depends on nothing. These dummy rules work around
    errors make gives if header files are removed without updating
    the Makefile to match.

  • -MT file

    Specifies the target of the rule emitted by dependency
    generation.

Linker And Mapper Options

The following options control the linker/mapper.

  • -llibrary

    Searches the library library when linking. The linker searches and
    processes libraries and object files in the order specified. The
    actual library name searched for is liblibrary.a.

    The directories searched include any specified with -L.

    Libraries are archive files whose members are object files. The
    linker scans the archive for its members which define symbols that
    have so far been referenced but not defined.

  • -nostartfiles

    Do not link with the system startup files.

  • -nodefaultlibs

    Do not link with the system libraries.

  • -nostdlib

    Do not link with the system startup files or system libraries.

  • -s

    Removes all symbol table and relocation information from the
    executable.

  • -default-clkblk clk

    Use clk as the default clock block. The clock block may be
    specified by its name in <xs1.h> or by its resource
    number.

    The startup code turns on the default clock block, configures it to
    be clocked off the reference clock with no divide and puts it into
    a running state. Ports declared in XC are initially attached to the
    default clock block. If this option is unspecified, the default
    clock block is set to XS1_CLKBLK_REF.

  • -Wm,option

    Passes option as an option to the linker/mapper. If option
    contains commas, it is split into multiple options at the commas.

    To view the full set of advanced mapper options, type
    xmap --help.

  • -Xmapper option

    Passes option as an option to the linker/mapper. To pass an option
    that takes an argument use -Xmapper twice.

  • -report

    Prints a summary of resource usage.

Directory Options

The following options specify directories to search for header
files and libraries.

  • -Idir

    Adds dir to the list of directories to be searched for header
    files.

  • -isystemdir

    Searches dir for header files after all directories specified by
    -I. Marks it as a system directory.

    The compiler suppresses warnings for header files in system
    directories.

  • -iquotedir

    Searches dir only for header files requested with
    #include "file" (not with #include <file>)
    before all directories specified by -I and before the system
    directories.

  • -Ldir

    Adds dir to the list of directories to be searched for by
    -l.

Environment Variables Affecting XCC

The following environment variables affect the operation of XCC.
Multiple paths are separated by an OS-specific path separator
(‘;‘ for Windows, ‘:‘ for Mac and Linux).

  • XCC_INCLUDE_PATH

    A list of directories to be searched as if specified with -I,
    but after any paths given with -I options on the command line.

  • XCC_XC_INCLUDE_PATH

    XCC_C_INCLUDE_PATH

    XCC_CPLUS_INCLUDE_PATH

    XCC_ASSEMBLER_INCLUDE_PATH

    Each of these environment variables applies only when preprocessing
    files of the named language. The variables specify lists of
    directories to be searched as if specified with -isystem, but
    after any paths given with -isystem options on the command
    line.

  • XCC_LIBRARY_PATH

    A list of directories to be searched as if specified with -L,
    but after any paths given with -L on the command line.

  • XCC_DEVICE_PATH

    A list of directories to be searched for device configuration
    files.

  • XCC_EXEC_PREFIX

    If set, subprograms executed by the compiler are prefixed with the
    value of this environment variable. No directory seperated is added
    when the prefix is combined with the name of a subprogram. The
    prefix is not applied when executing the assembler or the mapper.

  • XCC_DEFAULT_TARGET

    The default target platform, to be located as if specified with
    -target=. The default target platform is used if no target is
    specified with -target= and no XN file is passed.

Board Support Provided by <platform.h>

During compilation of a program, the compiler generates a temporary
header file named platform.h that contains variable and macro
definitions, as defined by the target XN file, which includes:

  • Declarations of variables of type tileref (see Declaration
    ).
  • Macro definitions of port names (see Port
    ).

Debug with printf in real-time

The xCORE debugger lets you suspend execution of a program in order to analyze its internal state.
However, if your program contains timing-critical behavior, for example due to it implementing a real-time
communication protocol, the act of suspending the program may cause other system components to fail,
preventing further debugging.

An alternative approach to debugging is to add trace statements to your program that are
used to observe its internal behavior at run-time (sometimes referred to as printf debugging). By printing the
results of intermediate calculations, you can quickly isolate where errors occur in your program.

In a traditional debugging environment, outputting data using a standard such as JTAG
results in interrupts that block core execution, slowing your program down considerably.
xTIMEcomposer lets you redirect the standard streams stdout and stderr to an XTAG-2
debug adapter, where the data is buffered until it can be output to the host.

In this configuration, calls to output routines such as printf complete as soon
as the data has been output on an xConnect Link, minimizing the effect on the program’s
timing characteristics. This allows debugging statements to be added to many timing-critical
code sections and viewed in a console during execution. In the case of a program crash,
all remaining contents in the XTAG-2 buffer is forwarded to the PC, ensuring important
information is not lost.

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 your adapter’s UART interface instead
.
Note that the UART interface offers significantly reduced performance.

Redirect stdout and stderr to the XTAG-2

The program below redirects standard output to the XTAG-2.

#include <stdio.h>
#include <xscope.h>

port receive;
port transmit;

int process(int);

void xscope_user_init(void) {
  xscope_register(0);
  xscope_config_io(XSCOPE_IO_BASIC);
}

int main() {

  while (1) {
    int dataIn, dataOut;

    receive :> dataIn;
    dataOut = process(dataIn);

    /* Debug Information */
    if (dataOut < 0)
      printf("%d %d", dataIn, dataOut);

    transmit <: dataOut;
  }
}

In the constructor xscope_user_init, the call to xscope_register
initializes the XTAG-2 interface, and the call to xscope_config_io
redirects the streams stdout and stderr to this interface.

The main program inputs data from a port, performs a computation
on it and outputs the result to another port. It uses the standard output
function printf to log instances where the computed result is less
than zero.

You can use the C standard I/O functions on any core at the same
time. This usage results in a single channel end being allocated
on each tile on which data is output.

You can timestamp the output data by calling xscope_config_io with the option XSCOPE_IO_TIMED.
This causes the output timestamp to be displayed with the data in the console.
Note that this also reduces the amount of data that can be buffered at any time.

Run a program with XTAG-2 output enabled

To redirect standard output to the XTAG-2 and display
it in the console,
you must build and run your program with the XScope
instrumentation library. To build and run your program,
follow these steps:

  1. Open the Makefile for your project.
  2. Locate the XCC_MAP_FLAGS_config variable for your build
    configuration, for example XCC_MAP_FLAGS_Release.
  3. Add the option -fxscope.
  4. If you are developing using the XDE, create a Run Configuration for your target device
    .
    In the XScope tab, select Offline mode. Click Run to save and run the configuration.

    The XDE loads your program, displaying data received from the XTAG-2 in the console.

  5. If you are developing using the command-line tools, pass the option --xscope to
    XRUN, for example:

    xrun –xscope myprog.xe

    XRUN loads your program and remains attached to the XTAG-2 adapter, displaying
    data received from it in the terminal. XRUN terminates when the program performs a call to exit.

Output using the UART interface

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(0);
  xscope_config_uart(uart_tx);
  xscope_config_io(XSCOPE_IO_BASIC);
}

To run your program in the XDE, create a Run Configuration for your target device

and select the option Run UART Server.

To run your program using the command-line tools, pass the option --uart to XRUN,
for example:

xrun –uart –xscope myprog.xe

Because the UART interface uses a port instead of an xConnect Link, you can use the C standard I/O
functions on a single tile only.

Assembly Programming Manual

The XMOS assembly language supports the formation of objects in the
Executable and Linkable Format
(ELF)

with DWARF 3
debugging information.
Extensions to the ELF format are documented in the XMOS Application
Binary Interface

.

Lexical Conventions

There are six classes of tokens: symbol names, directives, constants,
operators, instruction mnemonics and other separators. Blanks, tabs,
formfeeds and comments are ignored except as they separate tokens.

Comments

The character # introduces a comment, which terminates with a
newline. Comments do not occur within string literals.

Symbol Names

A symbol name begins with a letter or with one of the characters
.‘, ‘_‘ or ‘$‘, followed by an optional sequence of letters,
digits, periods, underscores and dollar signs. Upper and lower case
letters are different.

Directives

A directive begins with ‘.‘ followed by one or more letters.
Directives instruct the assembler to perform some action (see Directives
).

Constants

A constant is either an integer number, a character constant or a string
literal.

  • A binary integer is 0b or 0B followed by zero or more of the
    digits 01.
  • An octal integer is 0 followed by zero or more of the digits
    01234567.
  • A decimal integer is a non-zero digit followed by zero or more of the
    digits 0123456789.
  • A hexadecimal integer is 0x or 0X followed by one or more of
    the digits and letters 0123456789abcdefABCDEF.
  • A character constant is a sequence of characters surrounded by single
    quotes.
  • A string literal is a sequence of characters surrounded by double
    quotes.

The C escape sequences may be used to specify certain characters.

Sections and Relocations

Named ELF sections are specified using directives (see section, pushsection, popsection
).
In addition, there is a unique
unnamed “absolute” section and a unique unnamed “undefined” section. The
notation {secname X} refers to an “offset X into section secname.”

The values of symbols in the absolute section are unaffected by
relocations. For example, address {absolute 0} is “relocated” to
run-time address 0. The values of symbols in the undefined section are
not set.

The assembler keeps track of the current section. Initially the current
section is set to the text section. Directives can be used to change the
current section. Assembly instructions and directives which allocate
storage are emitted in the current section. For each section, the
assembler maintains a location counter which holds the current offset in
the section. The active location counter refers to the location
counter for the current section.

Symbols

Each symbol has exactly one name; each name in an assembly program
refers to exactly one symbol. A local symbol is any symbol beginning
with the characters “.L”. A local symbol may be discarded by the
linker when no longer required for linking.

Attributes

Each symbol has a value, an associated section and a binding. A
symbol is assigned a value using the set or linkset directives
(see set, linkset
), or through its use in a label (see Labels
).
The default binding of symbols in the undefined
section is global; for all other symbols the default binding is
local.

Labels

A label is a symbol name immediately followed by a colon (:). The
symbol’s value is set to the current value of the active location
counter. The symbol’s section is set to the current section. A symbol
name must not appear in more than one label.

Expressions

An expression specifies an address or value. The result of an expression
must be an absolute number or an offset into a particular section. An
expression is a constant expression if all of its symbols are defined
and it evaluates to a constant. An expression is a simple expression if
it is one of a constant expression, a symbol, or a symbol ± a constant.
An expression may be encoded in the ELF-extended expression section and
its value evaluated by the linker (see set, linkset
);
the encoding scheme is determined by the ABI. The syntax of an
expression is:

expression ::= unary-exp
| expression infix-op unary-exp
| unary-exp ? unary-exp $: unary-exp
| function-exp
unary-exp ::= argument
| prefix-op unary-exp
argument ::= symbol
| constant
| ( expression )
function-exp ::= $overlay_region_ptr ( symbol )
| $overlay_index ( symbol )
| $overlay_physical_addr ( symbol )
| $overlay_virtual_addr ( symbol )
| $overlay_num_bytes ( symbol )
infix-op ::= one of
+ - < > <= >= || << >> * $M $A & /
prefix-op ::= one of
- ~ $D

Symbols are evaluated to {section x} where section is one of a
named section, the absolute section or the undefined section, and x is
a signed 2’s complement 32-bit integer.

Infix operators have the same precedence and behavior as C, and
operators with equal precedence are performed left to right. In
addition, the $M operator has lowest precedence, and the $A
operator has the highest precedence.

For the + and - operators, the set of valid operations and
results is given in the table below.
For the $D operator, the argument must be a symbol; the result is
1 if the symbol is defined and 0 otherwise.

Valid operations for + and - operators

Op

Left Operand

Right Operand

Result

+

{section x}

{absolute y}

{section x+y}

+

{absolute x}

{section y}

{section x+y}

+

{absolute x}

{absolute y}

{absolute x+y}

-

{section x}

{section y}

{absolute x-y}

-

{section x}

{absolute y}

{section x-y}

-

{absolute x}

{absolute y}

{absolute x-y}

The ? operator is used to select between symbols: if the first
operand is non-zero then the result is the second operand, otherwise the
result is the third operand.

The operators $overlay_region_ptr, $overlay_index,
$overlay_physical_addr, $overlay_virtual_addr and $overlay_num_bytes
can be used to query properties of the overlay containing the overlay roots
with the specified overlay key symbol (see Overlay Directives
).
The set of results of these operators is given in
the table below.

Operators for querying properties of overlays.

Operator

Result

$overlay_region_ptr

Virtual address of the overlay region containing the overlay.

$overlay_index

Index of the overlay in the overlay region.

$overlay_physical_addr

Physical address of the overlay.

$overlay_virtual_addr

Virtual (runtime) address of the overlay.

$overlay_num_bytes

Size of the overlay in bytes.

For all other operators, both arguments must be absolute and the result
is absolute. The $M operator returns the maximum of the two operands
and the $A operator returns the value of the first operand aligned
to the second.

Wherever an absolute expression is required, if omitted then {absolute
0} is assumed.

Directives

Directives instruct the assembler to perform some action. The supported
directives are given in this section.

add_to_set

The add_to_set directive adds an expression to a set of expressions
associated with a key symbol. Its syntax is:

add-to-set-directive ::= .add_to_set symbol , expression
| .add_to_set symbol , expression , symbol

An optional predicate symbol may be specified as the 3rd argument. If this
argument is specified the expression will only be added to the set if the
predicate symbol is not eliminated from the linked object.

max_reduce, sum_reduce

The max_reduce directive computes the maximum of the values of the
expressions in a set. The sum_reduce directive computes the sum of the
values of the expressions in a set.

max-reduce-directive ::= .max_reduce symbol , symbol , expression

sum-reduce-directive ::= .sum_reduce symbol , symbol , expression

The first symbol is defined using the value computed by the directive.
The second symbol is the key symbol identifying the set of expressions (see
add_to_set
). The expression specifies the initial
value for the reduction operation.

align

The align directive pads the active location counter section to the
specified storage boundary. Its syntax is:

align-directive ::= .align expression

The expression must be a constant expression; its value must be a power
of 2. This value specifies the alignment required in bytes.

ascii, asciiz

The ascii directive assembles each string into consecutive
addresses. The asciiz directive is the same, except that each string
is followed by a null byte.

ascii-directive ::= .ascii string-list
| .asciiz string-list
string-list ::= string-list , string
| .asciiz string

byte, short, int, long, word

These directives emit, for each expression, a number that at run-time is
the value of that expression. The byte order is determined by the
endianness of the target architecture. The size of numbers emitted with
the word directive is determined by the size of the natural word on the
target architecture. The size of the numbers emitted using the other
directives are determined by the sizes of corresponding types in the
ABI.

value-directive ::= value-size exp-list
value-size ::= .byte
| .short
| .int
| .long
| .word
exp-list ::= exp-list , expression
| expression

file

The file directive has two forms.

file-directive ::= .file string
| .file constant string

When used with one argument, the file directive creates an ELF
symbol table entry with type STT_FILE and the specified string
value. This entry is guaranteed to be the first entry in the symbol
table.

When used with two arguments the file directive adds an entry to the
DWARF 3 .debug_line file names table. The first argument is a unique
positive integer to use as the index of the entry in the table. The
second argument is the name of the file.

loc

The .loc directive adds a row to the DWARF 3
.debug_line line number matrix.

loc-directive ::= constant constant constantopt
| constant constant constant ⟨loc-option⟩*
loc-option ::= basic_block
| prologue_end
| epilogue_begin
| is_stmt constant
| isa constant

The address register is set to active location counter. The first two
arguments set the file and line registers respectively. The optional
third argument sets the column register. Additional arguments set
further registers in the .debug_line state machine.

basic_block

Sets basic_block to true.

prologue_end

Sets prologue_end to true.

epilogue_begin

Sets epilogue_begin to true.

is_stmt

Sets is_stmt to the specified value, which must be 0 or 1.

isa

Sets isa to the specified value.

weak

The weak directive sets the weak attribute on the specified symbol.

weak-directive ::= .weak symbol

globl, global, extern, locl, local

The globl directive makes the specified symbols visible to other
objects during linking. The extern directive specifies that the
symbol is defined in another object. The locl directive specifies a
symbol has local binding.

visibility ::= .globl
| .extern
| .locl
| .global
| .extern
| .local
vis-directive ::= visibility symbol
| visibility symbol , string

If the optional string is provided, an SHT_TYPEINFO entry is created
in the ELF-extended type section which contains the symbol and an index
into the string table whose entry contains the specified string. (If the
string does not already exist in the string table, it is inserted.) The
meaning of this string is determined by the ABI.

The global and local directives are synonyms for the globl
and locl directives. They are provided for compatibility with other
assemblers.

globalresource

globalresource-directive ::= .globalresource expression , string
| .globalresource expression , string , string

The globalresource directive causes the assembler to add information to the
binary to indicate that there was a global port or clock declaration. The first
argument is the resource ID of the port. The second argument is the name of the
variable. The optional third argument is the tile the port was declared on. For
example:

.globalresource 0x10200, p, tile[0]

specifies that the port p was declared on tile[0] and initialized with the resource ID 0x10200.

typestring

The typestring adds an SHT_TYPEINFO entry in the ELF-extended type
section which contains the symbol and an index into the string table whose entry
contains the specified string. (If the string does not already exist in the
string table, it is inserted.) The meaning of this string is determined by the
ABI.

typestring-directive ::= .typestring symbol , string

ident, core, corerev

Each of these directives creates an ELF note section named
.xmos_note.”

info-directive ::= .ident string
| .core string
| .corerev string

The contents of this section is a (name, type, value) triplet: the name
is xmos; the type is either IDENT, CORE or COREREV; and
the value is the specified string.

section, pushsection, popsection

The section directives change the current ELF section (see Sections and Relocations
).

section-directive ::= sec-or-push name
| sec-or-push name , flags sec-typeopt
| .popsection
sec-or-push ::= .section
| .pushsection
flags ::= string
sec-type ::= type
| type , flag-args
type ::= @progbits
| @nobits
flag-args ::= string

The code following a section or pushsection directive is
assembled and appended to the named section. The optional flags may
contain any combination of the following characters.

a

section is allocatable

c

section is placed in the global constant pool

d

section is placed in the global data region

w

section is writable

x

section is executable

M

section is mergeable

S

section contains zero terminated strings

The optional type argument progbits specifies that the section
contains data; nobits specifies that it does not.

If the M symbol is specified as a flag, a type argument must be
specified and an integer must be provided as a flag-specific argument.
The flag-specific argument represents the entity size of data entries in
the section. For example:

.section .cp.const4, "M", @progbits, 4

Sections with the M flag but not S flag must contain fixed-size
constants, each flag-args bytes long. Sections with both the M and
S flags must contain zero-terminated strings, each character
flag-args bytes long. The linker may remove duplicates within sections
with the same name, entity size and flags.

Each section with the same name must have the same type and flags. The
section directive replaces the current section with the named
section. The pushsection directive pushes the current section onto
the top of a section stack and then replaces the current section with
the named section. The popsection directive replaces the current
section with the section on top of the section stack and then pops this
section from the stack.

text

The text directive changes the current ELF section to the .text
section. The section type and attributes are determined by the ABI.

text-directive ::= .text

set, linkset

A symbol is assigned a value using the set or linkset directive.

set-directive ::= set-type symbol , expression
set-type ::= .set
| .linkset

The set directive defines the named symbol with the value of the
expression. The expression must be either a constant or a symbol: if the
expression is a constant, the symbol is defined in the absolute section;
if the expression is a symbol, the defined symbol inherits its section
information and other attributes from this symbol.

The linkset directive is the same, except that the expression is not
evaluated; instead one or more SHT_EXPR entries are created in the
ELF-extended expression section which together form a tree
representation of the expression.

Any symbol used in the assembly code may be a target of an SHT_EXPR
entry, in which case its value is computed by the linker by evaluating
the expression once values for all other symbols in the expression are
known. This may happen at any incremental link stage; once the value is
known, it is assigned to the symbol as with set and the expression entry
is eliminated from the linked object.

cc_top, cc_bottom

The cc_top and cc_bottom directives are used to mark the
beginning and end of elimination blocks.

cc-top-directive ::= .cc_top name , predicate
| .cc_top name
cc-directive ::= cc-top-directive
| .cc_bottom name
name ::= symbol
predicate ::= symbol

cc_top and cc_bottom directives with the same name refer to the
same elimination block. An elimination block must have precisely one
cc_top directive and one cc_bottom directive. The top and bottom
of an elimination block must be in the same section. The elimination
block consists of the data and labels in this section between the
cc_top and cc_bottom directives. Elimination blocks must be
disjoint; it is illegal for elimination blocks to overlap.

An elimination block is retained in final executable if one of the following
is true:

  • A label inside the elimination block is referenced from a location
    outside an elimination block.
  • A label inside the elimination block is referenced from an elimination
    block which is not eliminated
  • The predicate symbol is defined outside an elimination block or
    is contained in an elimination block which is not eliminated.

If none of these conditions are true the elimination block is removed from
the final executable.

scheduling

The scheduling directive enables or disables instruction scheduling.
When scheduling is enabled, the assembler may reorder instructions to
minimize the number of FNOPs. The default scheduling mode is determined
by the command-line option -fschedule
.

scheduling-directive ::= .scheduling scheduling-mode
scheduling-mode ::= on
| off
| default

issue_mode

The issue_mode directive changes the current issue mode assumed by the
assembler. See Instructions
for details of how the issue mode
affects how instructions are assembled.

issue-mode-directive ::= issue_mode issue-mode
issue-mode ::= single
| dual

syntax

The syntax directive changes the current syntax mode. See
Instructions
for details of how assembly instructions
are specified in each mode.

syntax-directive ::= .syntax syntax
syntax ::= default
| architectural

assert

assert-directive ::= .assert constant , symbol , string

The assert directive requires an assertion to be tested prior to
generating an executable object: the assertion fails if the symbol has a
non-zero value. If the constant is 0, a failure should be reported as a
warning; if the constant is 1, a failure should be reported as an error.
The string is a message for an assembler or linker to emit on failure.

Overlay Directives

The overlay directives control how code and data is partitioned into overlays
that are loaded on demand at runtime.

overlay-directive ::= .overlay_reference symbol , symbol
| .overlay_root symbol , symbol
| .overlay_root symbol
| .overlay_subgraph_conflict sym-list
sym-list ::= sym-list , symbol
| symbol
  • The overlay_root directive specifies that the first symbol should be
    treated as an overlay root. The optional second symbols specifies a overlay
    key symbol. If no overlay key symbol is explictly specified the overlay root
    symbol is used as the key symbol. Specifying the same overlay key symbol for
    multiple overlay roots forces the overlay roots into the same overlay.
  • The overlay_reference directive specifies that linker should assume that
    there is a reference from the first symbol to the second symbol when
    it partitions the program into overlays.
  • The overlay_subgraph_conflict directive specifies that linker should not
    place any code or data reachable from one the symbols into an overlay that is
    mapped an overlay region that contains another overlay containing code or data
    reachable from one of the other symbols.

Language Directives

The language directives create entries in the ELF-extended expression
section; the encoding is determined by the ABI.

xc-directive ::= globdir symbol , string
| globdir symbol , symbol , range-args , string
| .globpassesref symbol , symbol , string
| .call symbol , symbol
| .par symbol , symbol , string
range-args ::= expression , expression
globdir ::= .globread
| .globwrite
| .parwrite
| .globpassesref

For each directive, the string is an error message for the assembler or
linker to display on encountering an error attributed to the directive.

call

Both symbols must have function type. This directive sets the property that
the first function may make a call to the second function.

par

Both symbols must have function type. This directive sets the property
that the first function is invoked in parallel with the second function.

globread

The first symbol must have function type and the second directive must
have object type. This directive sets the property that the function may
read the object. When a range is specified, the first expression is the
offset from the start of the variable in bytes of the address which is
read and the second expression is the size of the read in bytes.

globwrite

The first symbol must have function type and the second directive must
have object type. This directive sets the property that the function may
write the object. When a range is specified, the first expression is the
offset from the start of the variable in bytes of the address which is
written and the second expression is the size of the write in bytes.

parwrite

The first symbol must have function type and the second directive must have
object type. This directive set the property that the function is called in
an expression which writes to the object where the order of evalulation of
the write and the function call is undefined. When a range is specified, the
first expression is the offset from the start of the variable in bytes of
the address which is written and the second expression is the size of the
write in bytes.

globpassesref

The first symbol must have function type and the second directive must have
object type. This directive sets the property that the object may be passed
by reference to the function.

XMOS Timing Analyzer Directives

The XMOS Timing Analyzer directives add timing metadata to ELF sections.

xta-directive ::= .xtabranch exp-listopt
| .xtaendpoint string , source-location
| .xtacall string , source-location
| .xtalabel string , source-location
| .xtathreadstart
| .xtathreadstop
| .xtaloop constant
| .xtacommand string , source-location
source-location ::= string , string , constant

The first string of a source location is the compilation directory. The
second string is the path to the file. The path may be specified as
either a relative path from the compilation directory or as an absolute
path. The third argument is the line number.

  • xtabranch specifies a comma-separated list of locations that may
    be branched to from the current location.
  • xtaendpoint marks the current location as an endpoint with the
    specified label.
  • xtacall marks the current location as a function call with the
    specified label.
  • xtalabel marks the current location using the specified label.
  • xtathreadstart apecifies that a thread may be initialized to
    start executing at the current location.
  • xtathreadstop specifies that a thread executing the instruction
    at the current location will not execute any further instructions.
  • xtaloop specifies that the innermost loop containing the current
    location executes the specified number of times.
  • xtacommand specifies an XTA command to be executed when analyzing
    the executable.

uleb128, sleb128

The following directives emit, for each expression in the
comma-separated list of expressions, a value that encodes either an
unsigned or signed DWARF little-endian base 128 number.

leb-directive ::= .uleb128 exp-list
| .sleb128 exp-list

space, skip

The space directive emits a sequence of bytes, specified by the
first expression, each with the fill value specified by the second
expression. Both expressions must be constant expressions.

space-or-skip ::= .space
| .skip
space-directive ::= space-or-skip expression
| space-or-skip expression , expression

The skip directive is a synonym for the space directive. It is
provided for compatibility with other assemblers.

type

The type directive specifies the type of a symbol to be either a
function symbol or an object symbol.

type-directive ::= .type symbol , symbol-type
symbol-type ::= @function
| @object

size

The size directive specifies the size associated with a symbol.

size-directive ::= .size symbol , expression

jmptable, jmptable32

The jmptable and jmptable32 directives generate a table of
unconditional branch instructions. The target of each branch instruction
is the next label in the list. The size of the each branch instruction
is 16 bits for the jmptable directive and 32 bits for the
jmptable32 directive.

jmptable-directive ::= .jmptable jmptable-listopt
| .jmptable32 jmptable-listopt
jmptable-list ::= symbol
| jmptable-list symbol

Each symbol must be a label. A maximum of 32 labels maybe specified. If
the unconditional branch distance does not fit into a 16-bit branch
instruction, a branch is made to a trampoline at the end of the table,
which performs the branch to the target label.

Instructions

Assembly instructions are normally inserted into an ELF text section.
The syntax of an instruction is:

instruction ::= mnemonic instruction-argsopt
instruction-args ::= instruction-args , instruction-arg
| instruction-arg
instruction-arg ::= symbol [ expression ]
| symbol [ expression ] : symbol
| expression

To target the dual issue execution mode of xCORE-200 devices, instructions may
be put in bundles:

separator ::= newline
| ;
instruction-bundle ::= { ⟨separator⟩* bundle-contents ⟨separator⟩* }
bundle-contents ::= instruction ⟨separator⟩+ instruction
| instruction

The current issue mode, as specifed by the issue_mode directive
(see issue_mode
), affects how the assembler assembles
instructions. Initially the current issue mode is single and instruction bundles
cannot be used. If the current issue mode is changed to dual then:

  • Instruction bundles can be specified.
  • 16-bit instructions not in an instruction bundle are implicitly
    placed in an instruction bundle alongside a NOP instruction.
  • The encoding of some operands may change. For example the assembler
    applies a different scaling factor to the immediate operand of relative
    branch instructions to match the different scaling factor that the processor
    uses at runtime when the instruction is executed in dual issue mode.

The order in which instructions are listed in an instruction bundle is not
significant. The assembler may reorder the instructions in the bundle to satisfy
architectural constraints.

The assembly instructions are summarized below using the default assembly
syntax. The architecture manual
documents the architectural
syntax of the instructions. The syntax directive is used to switch the syntax
mode.

The following notation is used:

bitp

one of: 1, 2, 3, 4, 5, 6, 7, 8, 16, 24 and

Scroll to Top