Installation instructions#

Download the tools#

The tools and related drivers are provided in a single platform-specific downloadable file. By default, the file will be available from:

In some circumstances you may be instructed to download specific versions of the tools from other locations.

Install the tools#

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

  1. Run the installer. Click “Yes” when asked to allow the installer to make changes to your computer.

  2. The installer GUI will guide you through the installation. For a default installation, click “Next” on every page, then “Install”.

  3. Recommendation: Install a ‘bash’ command line environment and commonly used Linux tools. This is recommended because - for the sake of brevity - all the examples provided in this documentation assume a bash environment.

    One way of installing a basic bash environment on a Windows machine is to install Git for Windows. Follow the standard instructions for installation and, when asked, make the selection as below:

  1. Uncompress the archive to your chosen installation directory. The example below will install to your home directory:

    $ tar -xf archive.tgz -C ~

    In this example, the tools will install to ~/XMOS/XTC/version. This location will henceforth be known as your tools installation location.

  1. Double-click the downloaded installer to open it, and then drag the ‘X’ icon into your Applications folder.

  2. Unmount the installer.

Check your installation#

After installation, check it by following the instructions at Configuring the command-line environment.

Configure the XTAG USB drivers#

The tools interface to development boards over USB via an XTAG adapter. Most development boards require an external XTAG adapter that connects to the board via an XSYS or XSYS2 connector. Some development boards include an integrated XTAG adaptor.


Fig. 1 XTAG adapter configurations used with xCORE development boards#

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

The XTAG drivers for Linux are installed as part of the normal installation process. However, to make them accessible by all users, an additional step requiring root access is needed. This step is likely only required once on a given development machine, or when new XTAG devices are released by XMOS. Change directory to the scripts folder of your tools installation and run the setup script:

$ sudo ./

Reconnect any currently connected XTAG devices for the changes to be applied.

To check that the XTAG devices are available and accessible run the following script in the same directory:

$ ./

As shown, this script should be run as the normal user, not root.

USB driver support is provided natively on OS X.

Using XTAG from within a VM#

If you are using the tools from within a VM, you’ll need to instruct that the XTAGs attached to the host be tunneled through to the guest machine. The USB settings required in Oracle VM VirtualBox Manager are shown below:


“Add” or “Edit” your USB filter details such that they appear as below. It is important that the “Product ID” field is empty.


Check XTAG access#

Configure the environment. Connect a development board to your host machine via an XTAG adaptor as necessary. Ensure that the development board is powered.

Use xrun -l to list the devices available for debugging. The first time you issue this command, it may take several seconds for the XTAG firmware to be downloaded. An example of the expected result is:

$ xrun -l

Available XMOS Devices

  ID    Name                    Adapter ID      Devices
  --    ----                    ----------      -------
  0     XMOS XTAG-3             wfF.G58J        P[0]

If the ‘Devices’ column lists None, it means the XTAG itself cannot gain access to the development board. Check that the development board itself is powered, and that the XSYS/XSYS2 connection is well made.