XC-1A Development Board Tutorial

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

The program below illuminates an LED on an XC-1A.

#include <xs1.h>

out port bled = XS1_PORT_4C;

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

Copy and paste the code into your project, and then choose FileSave () to save your changes to file.

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

out port bled = XS1_PORT_4C;

declares an output port named bled, which refers to the 4-bit port 4C. On the XC-1A, the I/O pins of port 4C are connected to the LEDs positioned next to the four press-buttons (collectively referred to as button-LEDs) that contain green diodes.

Show image of port map...

Ports must be declared as global variables. The optional out qualifier allows the compiler to check for correct usage, thereby helping to reduce programming errors.

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

bled <: 0b0001;

causes the value specified to the right of <: to be output to the port specified to its left (led). The port then drives LED next to button A high and the other LEDs low, causing the LED to illuminate green and the other LEDs to remain off.

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

To build and run your project, follow these steps:

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

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

#include <xs1.h>

#define FLASH_PERIOD 20000000

out port bled = XS1_PORT_4C;

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

Copy and paste the code into your project, and then choose FileSave () to save your changes to file.

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

timer tmr;

declares a variable named tmr, and allocates an available hardware timer. Each core on the G4 device 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 tmr‘s 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 projects. To complete this part of the tutorial, follow these steps:

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

The program below inputs from one of two timers in a loop.

#include <xs1.h>
#define BIT_RATE 115200
#define BIT_TIME XS1_TIMER_HZ / BIT_RATE
out port TXD = XS1_PORT_1H;

int main(){
  return 0;
}

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 project using this code.

Show reminder...

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

The program below flashes a single CLOCKLED.

#include <platform.h>
#define PERIOD 20000000

out port cled0 = PORT_CLOCKLED_0;
out port cled1 = PORT_CLOCKLED_1;
out port cled2 = PORT_CLOCKLED_2;
out port cled3 = PORT_CLOCKLED_3;
out port cledG = PORT_CLOCKLED_SELG;
out port cledR = PORT_CLOCKLED_SELR;

void flashLED (out port led, int period);

int main (void) {
  par {
    on stdcore [0]: { cledG <: 1;
                        flashLED (cled0 , PERIOD);
                    }
    on stdcore [1]: flashLED (cled1, PERIOD);
    on stdcore [2]: flashLED (cled2, PERIOD);
    on stdcore [3]: flashLED (cled3, PERIOD);
  }
  return 0;
}

void flashLED (out port led, int period){
}

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

The schematic for the 12 clock-LEDs is shown below; the location of the ports are shown in the XC-1A Hardware Manual.

The LED anodes are connected to four 8-bit ports: PORT_CLOCKLED_0 on XCore 0, PORT_CLOCKLED_1 on XCore 1, PORT_CLOCKLED_3 on XCore 3 and PORT_CLOCKLED_4 on XCore 4. The LED cathodes are connected to two 1-bit ports on XCore 0: PORT_CLOCKLED_SELG (green) and PORT_CLOCKLED_SELR (red). This means that two pins must be driven to illuminate a clock-LED.

The par statement provides a simple way to create concurrent threads that 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.

The program creates four concurrent threads, each running an instance of a function flashLED.

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

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

The program below flashes a single CLOCKLED.

#include <platform.h>
#define PERIOD 20000000

out port cled0 = PORT_CLOCKLED_0;
out port cled1 = PORT_CLOCKLED_1;
out port cled2 = PORT_CLOCKLED_2;
out port cled3 = PORT_CLOCKLED_3;
out port cledG = PORT_CLOCKLED_SELG;
out port cledR = PORT_CLOCKLED_SELR;

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 neighbor */
  }
}

int main (void) {
  chan c0, c1, c2, c3;
  par {
    on stdcore [0]: { cledG <: 1;
                      tokenFlash (c0, c1, cled0, PERIOD, 1);
                    }
    on stdcore [1]: tokenFlash (c1, c2, cled1, PERIOD, 0);
    // other cores
  }
  return 0;
}

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

An XC channel provides a synchronous, bidirectional link between two threads. It consists of two channel ends, which two threads can use to interact on demand using the XC input and output statements.

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

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 main function constructs the token ring. 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 four 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.

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

A select statement is used to respond to one of a set of inputs, depending on which becomes ready first. If more than one 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.

void buttonListener ( chanend left ,
                      chanend right ,
                      in port button ,
                      out port g,
                      out port r) {
  int token ;
  int isGreen = 1;
  g <: 1;
  while (1)
    select {
      case left :> token :
      /* pass token on */
        right <: token ;
      break ;
      case button when pinsneq (0xf):> void :
        /* change color *
        ...
      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.

To finish this part of the tutorial, complete the following tasks which build on the program from the previous section: