XC-2 Development Board Tutorial

Before writing any code, you need a project to store your files in. To create a new project containing a single application, follow these steps:

The program below illuminates an LED on an XC-2.

#include <xs1.h>

out port x0ledb = XS1_PORT_1J;

int main () {
  x0ledb <: 1;
  while (1)
    ;
  return 0;
}

To add this code to your application, follow these steps:

Take a look at the application code in the editor. The declaration

out port x0ledb = XS1_PORT_1J;

declares an output port named x0ledb, which refers to the 1-bit port 1J. On the XC-2, the I/O pin of port 1J is connected to the LED next to Button B.

Show image of port map...

XC input and output statements make it easy to express I/O operations on ports. The statement

x0ledb <: 1;

causes the value specified to the right of <: to be output to the port specified to its left (x0ledb). The port then drives the LED high causing the LED to illuminate green.

The empty while loop prevents the program from terminating, which ensures that the LED remains illuminated.

To build and run your application, follow these steps:

The XDE lets you work with multiple applications at the same time. You can group related applications into a single project, making them easy to organize and move around together.

To create a second application in your existing project, follow these steps:

The program below flashes a single LED on an XC-2.

#include <xs1.h>

#define FLASH_PERIOD 20000000

out port x0ledb = XS1_PORT_1J;

int main (void) {
  timer tmr;
  unsigned ledOn = 1;
  unsigned t;
  tmr :> t;
  while (1) {
    x0ledb <: ledOn;
    t += FLASH_PERIOD;
    tmr when timerafter (t) :> void;
    ledOn = !ledOn;
  }
  return 0;
}

To add this code to your application, follow these steps:

Take a look at the application code in the editor. The declaration

timer tmr;

declares a variable named tmr, and allocates an available hardware timer. The L1 provides 10 timers, which can be used to determine when an event happens, or to delay execution until a particular time. Each timer contains a 32-bit counter that is incremented at 100MHz and whose value can be input at any time.

The statement

tmr :> t;

inputs the value of the tmr counter into the variable t. Having recorded the current time, the statement

t += FLASH_PERIOD;

increments this value by the required delay, and the statement

tmr when timerafter(t) :> void;

delays inputting a value until the specified time is reached. The input value is not needed, which is expressed as an input to void.

To build and run your application, follow these steps:

The Run button () can be used to switch between applications. To complete this part of the tutorial, follow these steps:

By default when you build or run an application, the XDE checks whether the source code has changed in any application in your project and rebuilds all applications that have changed. On some systems, the time taken to inspect all folders can produce a noticable increase in the build time.

During development, you can control which applications are included in the build. To disable an application from the build, open the project-level Makefile in the editor and uncheck the application from the build list.

Now that you have two applications in your project, you may wish to rename your project to represent the fact that it is a container for a collection of applications. To complete this part of the tutorial, follow these steps:

The program below serializes a byte of data and transmits its individual bits over a 1-bit port using the UART transmission protocol:

#include <platform.h>

#define BIT_RATE 115200
#define BIT_TIME XS1_TIMER_HZ / BIT_RATE

void txByte(out port TXD, int byte) {
  unsigned time;
  timer t;

  /* input initial time */
  t :> time;

  /* output start bit */
  TXD <: 0;
  time += BIT_TIME;
  t when timerafter(time) :> void;

  /* output data bits */
  for (int i=0; i<8; i++) {
    TXD <: >> byte;
    time += BIT_TIME;
    t when timerafter(time) :> void;
  }

  /* output stop bit */
  TXD <: 1;
  time += BIT_TIME;
  t when timerafter(time) :> void;
}

Before continuing to the next part of this tutorial, create a new application using this code.

Show reminder...

A UART translates data between parallel and serial forms for transmission over a serial link. Each bit of data is driven for a fixed period, during which time the receiver must sample the data. The diagram below shows the transmission of a single byte of data at a rate of 115200 bits/s, which means that each bit is driven for 8.68us.

The function txByte outputs a byte by first outputting a start bit, following by a conditional input on a timer that waits for the bit time to elapse; the data bits and stop bit are output in the same way.

The output statement in the for loop

TXD <: >> byte;

includes the modifier >>, which right-shifts the value of byte by the port width (1 bit) after outputting the least significant port-width bits. This operation is performed in the same instruction as the output, making it more efficient than shifting the value as a separate operation afterwards.

To complete this part of the tutorial, perform the following tasks:

The program below creates four concurrent threads, each running an instance of a function that flashes an LED:

#include <platform.h>

#define FLASH_PERIOD 20000000

on stdcore[0] : out port x0ledB = PORT_LED_0_1;
on stdcore[0] : out port x0ledA = PORT_LED_0_0;
on stdcore[1] : out port x1ledB = PORT_LED_1_1;
on stdcore[1] : out port x1ledA = PORT_LED_1_0;

void flashLED(out port led, int delay);

int main(void) {
  par {
    on stdcore[0]: flashLED(x0ledB, FLASH_PERIOD);
    on stdcore[0]: flashLED(x0ledA, FLASH_PERIOD);
    on stdcore[1]: flashLED(x1ledB, FLASH_PERIOD);
    on stdcore[1]: flashLED(x1ledA, FLASH_PERIOD);
  }
  return 0;
}

Take a look at the application code in the editor.

The header file platform.h provides a declaration of the global variable stdcore, which can be used to specify the placement of port declarations and threads.

The par statement provides a simple way to create concurrent threads that can run independently of one another. The on statement instructs the compiler on which processor each port is connected and each thread is executed.

An``on`` statement may only be used with threads created by main, in which case main may contain only channel declarations, a single par statement and an optional return statement.

To complete this part of the tutorial, perform the following tasks:

Experiment with different period values for each of the threads so that the threads can be seen to be operating independently of one another.

Extend this program to flash the LEDs on both sides of the XS-G4.

Note that the LEDs on processor 3 are in reverse order on the XC-2.

The function below implements a component of the token ring illustrated above, repeatedly inputting a token from its left neighbor, flashing an LED and outputting the token to its right neighbor.

void tokenFlash(chanend left, chanend right,
                out port led, int delay, int isMaster) {
  timer tmr;
  unsigned t;
  if (isMaster)     / * master inserts token into ring */
    right <: 1;
  while (1) {
    int token;
    left :> token;   /* input token from left neighbor */
    led <: 1;
    tmr :> t;
    tmr when timerafter(t+delay) :> void;
    led <: 0;
    right <: token;  /* output token to right neigbor */
  }
}

The first two function parameters are channel ends, the third an LED port and the fourth a Boolean value indicating whether or not the thread executing the function is the designated master. The master inserts a token into the ring.

The xc input and output statements are used to communicate the token between threads. As channels are synchronous, each output operation blocks until a matching input operation is ready, ensuring that precisely one thread has possession of the token at any time.

The function below constructs part of the token ring:

int main(void) {
  chan c0, c1, c2, ...;
  par {
    on stdcore[0]: tokenFlash(c0, c1, x0ledA, PERIOD, 1);
    on stdcore[0]: tokenFlash(c1, c2, x0ledB, PERIOD, 0);
    ...
  }
  return 0;
}

A channel is declared using the keyword chan. The locations of its two channel ends are established through its use in two statements of the par.

A total of eight channels are required to complete this program, each of which must be used in two threads: once as a left argument and once as a right argument to the function tokenFlash.

Complete this program, compile and run it on your XC-2.

As the token cycles around the eight threads, the eight LEDs should each flash in sequence.

A select statement is used to respond to one of a set of inputs, depending on which becomes ready first. If more than one of input becomes ready at the same time, only one is executed.

The function below waits for either a token to be received, in which case it passes it on, or for a button to be pressed, in which case it holds the token when received until the button is pressed again:

void buttonListener(chanend left, chanend right, port button) {
  int token;
  while (1)
    select {
      case left :> token :
        /* pass token on */
        right <: token;
        break;
      case button when pinsneq(0xf):> void :
        /* wait for token, then hold until button is pressed */
        left :> token;
        button when pinsneq(0xf):> void; /* push down */
        button when  pinseq(0xf):> void; /* release */
        right <: token;
        break;
      }
}

The guarded input statement:

case left :> token :

becomes ready when the token arrives, in which case it is input and passed to the next thread. The guard:

case button when pinsneq(0xf):> void :

becomes ready when the value on the pins connected to the port button is not equal to the bit pattern 0xf. This signifies that the button was pressed. The body of this case then waits for the button to be pressed again and released before continuing.

Add the function buttonListener to the token ring from the previous section that responds to either one of the two press-buttons. You can find their ports in the diagram at the end of this tutorial on page sec:portmap.

Compile and run this program on your XC-2.

Verify that the LED stops cycling after a full cycle when one of the buttons is pressed. Pressing the button again causes the next cycle to commence.

Modify the program so that pressing a button changes the cycle direction.

The simplest solution is to add a select` statement to the function ``flashLED that inputs from either its left or right neighbor, and extend buttonListener similarly.

The software can be downloaded as a ZIP file from http://www.xmos.com/xc2/, and imported directly into the XDE as a pre-configured project (for instructions see the Tools User Guide) or uncompressed and built using the provided Makefile.

Open the file test.xc and change the preprocessor value OWN_IP_ADDRESS to an IP address that your network can route.

Compile and run this program on your XC-2.

You should be able to ping and receive a response from the board.

Note that you may need to disable your firewall.

Modify the function demo in the file test.xc so that it flashes one of the green LEDs each time it receives a ping request.