How to guides

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.

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

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.

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

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.

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.

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.

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.

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.

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

To import a project, follow these steps:

1. Choose FileImport.
2. Double-click on the General option, select Existing Projects
   into Workspace and click Next.
3. In the Import dialog box, click Browse (next to the Select
   archive file text box).
4. Select the archive to import and click Open.
5. Click Finish.

To export a project, follow these steps:

1. Choose FileExport.
2. Double-click on the General option, select Archive File and
   click Next.
3. Select the projects you wish to export in the top-left panel. You can
   exclude files by deselecting them in the top-right panel.
4. Enter a name for the archive in the To archive file text box.
5. Click Finish.

To start xTIMEcomposer Studio:

In Windows:

Choose StartProgramsXMOSxTIMEcomposer_12xtimecomposer.

In OS X:

Open a new Finder window, navigate to the Applications folder, open the folder
XMOS_xTIMEcomposer_12 and double-click on the xtimecomposer.app icon.

In Linux:

Open a terminal window, change to the installation directory and enter the following
commands:

source SetEnv

xtimecomposer

Register Your Tools

The xTIMEcomposer command-line tools use a set of environment variables when searching
for header files, libraries and target devices (see Environment Variables Affecting XCC
).
To add the xTIMEcomposer tools to the path and configure the default set of environment variables:

In Windows:

Choose StartProgramsXMOSxTIMEcomposer_12Command Prompt.

In OS X:

Open a Terminal window, change to the installation directory and either open from
the Finder, enter the following command:

SetEnv.command

In Linux:

Open a Terminal window, change to the installation directory and enter the following
command:

source SetEnv

You can now run any of the tools by entering its name and command-line options.
Some of the most common commands are summarized in the following section.

The Quick Start Menu in the xTIMEcomposer Studio Developer Column provides a convenient starting point for all users, including developers who are new to XMOS and experienced users.

Developers with an xCORE development board, can use the page to create new projects for their board or find kit-specific documentation and tutorials. Those who do not have a board you can follow a tool tutorial using the simulator.

New developers can use the Quick Start Menu to link to key documents and information that will help them use xTIMEcomposer Studio. For existing users there are links to documents that explain changes between the latest release and previous versions of the toolchain.

To make the most of the Quick Start Menu select your level of expertise or interest
and then follow the instructions on screen.

To compile a program for your development board, enter the following commands:

1. xcc -print-targets

   XCC displays a list of supported development boards.

2. xcc <file> -target=<board> -o <binary>

   XCC compiles the file, generating an executable binary for your target board.

To load a compiled program onto your development board, enter the following commands:

1. xrun -l

   XRUN 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. xrun –id <n> –io <binary>

   XRUN loads your binary onto the hardware connected to the adapter with the
   specified ID.

   The --io option causes XRUN to remain connected to the adapter, providing
   the standard output stream from your hardware to the terminal.

To compile and debug your program, enter the following commands:

1. xcc <file> -target=<board> -o <binary> -g

   XCC compiles your file with debugging information enabled.

2. xgdb bin.xe

   GDB loads with a prompt.

3. list-devices

   GDB 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

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

4. connect –id <id>

   GDB connects to your target hardware.

5. load

   GDB loads your binary.

6. break main

   GDB adds a breakpoint to the function main.

7. continue

   GDB runs the program until it reaches main.

To run your program on the simulator, enter the following command:

xsim <binary>

To launch the simulator from within the debugger, at the GDB prompt enter the
command:

connect -s

You can then load your program onto the simulator in the same way as if using a
development board.

To install the tools on your PC, follow these steps:

On Windows:

1. Download the Windows installer from:

   http://1m2n3b4v.xmos.com/tools

2. Double-click the installer to run it. Follow the on-screen prompts to install the
   tools on your PC.

On Mac:

1. Download the Macintosh installer from:

   http://1m2n3b4v.xmos.com/tools

2. Double-click the downloaded installer to open it, and then drag the xTIMEcomposer icon
   into your Applications folder.

   The installer copies the files to your hard disk.

3. Unmount the installer.

On Linux:

1. Download the Linux archive from:

   http://1m2n3b4v.xmos.com/tools

2. Uncompress the archive to an installation directory, for example by entering
   the following command:

   tar -xzf archive.tgz -C /home/user

xTIMEcomposer interfaces to development boards over USB. Some boards provide
an integrated debug adapter, and others require an external adapter that connects
to the board via an XSYS connector, as shown in the figure below.

Adapter configurations used with xCORE development boards

xTIMEcomposer supports adapters based on either FTDI or xCORE USB-to-JTAG chips.
Consult your board manual to determine which driver to use.

On Windows:

The JTAG drivers are installed by the tools installer. Plug your xCORE
development board in after an installation to load the drivers.

On Mac:

USB driver support is provided natively on OS X.

On Linux:

USB driver support is provided natively on some versions of Linux. In some cases,
the driver must be enabled (see Enable USB drivers on Linux
).

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.

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.

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.