SPI Programming Guide

This section provides information on how to program applications using the SPI master and slave components.

Source code structure

Directory Structure

A typical SPI application will have at least three top level directories. The application will be contained in a directory starting with app_, the spi component source is in the module_spi_master|slave directory and the directory module_xcommon contains files required to build the application.

app_[my_app_name]/
module_spi_master|slave/
module_xcommon/

Of course the application may use other modules which can also be directories at this level. Which modules are compiled into the application is controlled by the USED_MODULES define in the application Makefile.

Key Files

The following header files contain prototypes of all functions required to use use the SPI components. The API is described in SPI API.

Key Files

File	Description
`spi_master.h`	SPI master API header file
`spi_slave.h`	SPI slave API header file

Demo Applications

This tutorial describes the demo applications included in the XMOS SPI package. SPI H/W Development Platforms describes the required hardware setups to run the demos. The source for both demos can be found in the top level directory of the sc_spi component.

A basic knowledge of XC programming is assumed. For information on XMOS programming, you can find reference material about XC programming at the XMOS website.

To write an SPI enabled application for an XMOS device requires several things:

Write a Makefile for our application
Provide an spi_conf.h configuration file
Write the application code that uses the component

This process is described for both demos in the following sections.

app_spi_master_demo

This application uses module_spi_master to read and write data to the SPI slave flash device on the board.

Note: Running this program will overwrite any existing data in the flash.

Makefile

The Makefile is found in the top level directory of the application. It uses the general XMOS makefile in module_xcommon which compiles all the source files in the application and the modules that the application uses. We only have to add a couple of configuration options.

Firstly, this application is for an XK-1 development board so the TARGET variable needs to be set in the Makefile:

# The TARGET variable determines what target system the application is
# compiled for. It either refers to an XN file in the source directories
# or a valid argument for the --target option when compiling.
TARGET = XK-1

Secondly, the application name must be set:

# The APP_NAME variable determines the name of the final .xe file. It should
# not include the .xe postfix. If left blank the name will default to
# the project name
APP_NAME = app_spi_master_demo

Finally, the application will use the SPI master module. We state that the application uses this as follows:

# The USED_MODULES variable lists other module used by the application.
USED_MODULES = module_spi_master

spi_conf.h

The spi_conf.h file is found in the src/ directory of the application. This file contains a series of #defines that configure the SPI component. The possible #defines that can be set are described in Configuration Defines.

If not set, default values in the spi_master header file will be used.

Within this application we set the SPI mode to 3, and the default SPI clock divider to 2 (giving a SPI clock frequency of 25MHz).

// Copyright (c) 2011, XMOS Ltd., All rights reserved
// This software is freely distributable under a derivative of the
// University of Illinois/NCSA Open Source License posted in
// LICENSE.txt and at <http://github.xcore.com/>

#define DEFAULT_SPI_CLOCK_DIV 2

#define SPI_MASTER_MODE 3

The flash chip on the XK-1 board supports SPI modes 0 and 3, and clock frequencies up to 104MHz. The demo can be recompiled and run in either SPI mode, and larger clock dividers.

Top level program structure

To make use of the SPI master module app_spi_master_demo must contain the following line:

#include "spi_master.h"

This application is contained in spi_master_demo.xc. Within this file is the main() function which sets up the SPI interface, and then calls the read_jedec_id(), write_speed_test(), and read_speed_test() functions to test the interface.

The read_jedec_id() function reads the device ID register and checks the returned value is as correct, outputting both the expected and actual values.

The write_speed_test() function writes a page of data to the flash, and then reads it back to ensure it was written correctly. The time taken to write the data is output.

The read_speed_test() function reads 50kB of data from the flash into a buffer. The time taken to complete the read is output.

Running the application

Run xmake within the app_spi_master_demo/ directory, to compile the program
Connect the XK-1 to your PC using an XTAG-2
Run xrun --io bin/app_spi_master_demo.xe to start the demo

app_spi_loopback_demo

This application uses both module_spi_master and module_spi_slave to create a loopback between 2 threads.

Note: Jumpers are required on the board to run this demo, as described in SPI H/W Development Platforms.

Makefile

Firstly, this application is for an XK-1 development board so the TARGET variable needs to be set in the Makefile:

# The TARGET variable determines what target system the application is
# compiled for. It either refers to an XN file in the source directories
# or a valid argument for the --target option when compiling.
TARGET = XK-1

Secondly, the application name must be set:

# The APP_NAME variable determines the name of the final .xe file. It should
# not include the .xe postfix. If left blank the name will default to
# the project name
APP_NAME = app_spi_loopback_demo

Finally, the application will use both the SPI master and slave modules. We state that the application uses them as follows:

# The USED_MODULES variable lists other module used by the application.
USED_MODULES = module_spi_master module_spi_slave

spi_conf.h

If not set, default values in the spi_master and spi_slave header files will be used.

As both master and slave modules can run in all the SPI modes, within this application any mode can be selected. Changing the #define SPI_MODE ensures that both master and slave are run in the same mode as one another.

The maximum frequency sclk supported by the slave module differs for each SPI mode, #define DEFAULT_SPI_CLOCK_DIV sets the highest frequency that will work in any SPI mode. #define SPI_CLOCK_DIV sets the frequency actually used by the application.

// Copyright (c) 2011, XMOS Ltd., All rights reserved
// This software is freely distributable under a derivative of the
// University of Illinois/NCSA Open Source License posted in
// LICENSE.txt and at <http://github.xcore.com/>

#define DEFAULT_SPI_CLOCK_DIV 58 // Maximum frequency suitable for SPI slave in any SPI mode

#define SPI_CLOCK_DIV 2 //DEFAULT_SPI_CLOCK_DIV

#define SPI_MODE 3
// Ensure that master and slave always operate in the same mode
#define SPI_MASTER_MODE SPI_MODE
#define SPI_SLAVE_MODE SPI_MODE

The application comes configured to run in SPI mode 3, with an SPI clock divider of 2 (giving a SPI clock frequency of 25MHz). The demo can be recompiled and run in other SPI modes, with different clock dividers.

Top level program structure

To make use of the SPI master and slave modules app_spi_loopback_demo must contain the following lines:

#include "spi_master.h"
#include "spi_slave.h"

This application is contained in spi_loopback_demo.xc. Within this file is the main() function which starts the SPI master and slave running in parallel threads by calling the functions run_master() and run_slave(). These run functions initialise the interface modules and run the demo a set number of times. The master_demo() function checks that the data returned from the slave is correct. The interfaces are shut down after the final run of the demo.

Running the application

Run xmake within the app_spi_loopback_demo/ directory, to compile the program
Connect the XK-1 to your PC using an XTAG-2
Run xrun --io bin/app_spi_loopback_demo.xe to start the demo