SPICC26XXDMA.h File Reference

Detailed Description

SPI driver implementation for a CC26XX SPI controller using the UDMA controller.

============================================================================

Driver include

The SPI header file should be included in an application as follows:

#include <ti/drivers/SPI.h>
#include <ti/drivers/spi/SPICC26XXDMA.h>
#include <ti/drivers/dma/UDMACC26XX.h>

Refer to SPI.h for a complete description of APIs.

Note that the user also needs to include the UDMACC26XX.h driver since the SPI uses uDMA in order to improve throughput.

Overview

The general SPI API should be used in application code, i.e. SPI_open() should be used instead of SPICC26XXDMA_open(). The board file will define the device specific config, and casting in the general API will ensure that the correct device specific functions are called. This is also reflected in the example code in Use Cases.

General Behavior

Before using SPI on CC26XX:

• The SPI driver is initialized by calling SPI_init().
• The SPI HW is configured and flags system dependencies (e.g. IOs, power, etc.) by calling SPI_open().
• The SPI driver makes use of DMA in order to optimize throughput. This is handled directly by the SPI driver, so the application should never to make any calls directly to the UDMACC26XX.h driver.

The following is true for slave operation:

• RX overrun IRQ, SPI and UDMA modules are enabled by calling SPI_transfer().
• All received bytes are ignored after SPI_open() is called, until the first SPI_transfer().
• If an RX overrun occur or if SPI_transferCancel() is called, RX overrun IRQ, SPI and UDMA modules are disabled, TX and RX FIFOs are flushed and all bytes are ignored.
• After a successful transfer, RX overrun IRQ and SPI module remains enabled and UDMA module is disabled. SPI_transfer() must be called again before RX FIFO goes full in order to avoid overflow. If the TX buffer is underflowed, zeros will be outputted. It is safe to call another SPI_transfer() from the transfer callback, see Continous Slave Transfer use case below.
• The SPI driver supports partial return, that can be used if the transfer size is unknown. If PARTIAL_RETURN is enabled, the transfer will end when chip select is deasserted. The SPI_Transaction.status and the SPI_Transaction.count will be updated to indicate whether the transfer ended due to a chip select deassertion and how many bytes were transferred. See Slave Mode With Return Partial use case below.

The following apply for master operation:

• SPI and UDMA modules are enabled by calling SPI_transfer().
• If the SPI_transfer() succeeds, SPI module is enabled and UDMA module is disabled.
• If SPI_transferCancel() is called, SPI and UDMA modules are disabled and TX and RX FIFOs are flushed.

After SPI operation has ended:

• Release system dependencies for SPI by calling SPI_close().

The callback function is called in the following context:

• When an error occurs, the callback function is called in a HWI context.
• When no error occurs, the callback function is called in a SWI context.

Warning

The application should avoid transmitting data stored in flash via SPI if the application might switch to the XOSC_HF, the high frequency external oscillator, during this transfer.

Error handling

If an RX overrun occurs during slave operation:

• If a transfer is ongoing, all bytes received up until the error occurs will be returned, with the error signaled in the SPI_Transaction.status field. RX overrun IRQ, SPI and UDMA modules are then disabled, TX and RX FIFOs are flushed and all bytes will be ignored until a new transfer is issued.
• If a transfer is not ongoing, RX overrun IRQ, SPI and UDMA modules are disabled, TX and RX FIFOs are flushed and all bytes will be ignored until a new transfer is issued.

Timeout

Timeout can occur in SPI_MODE_BLOCKING, there's no timeout in SPI_MODE_CALLBACK. When in SPI_MODE_CALLBACK, the transfer must be cancelled by calling SPI_transferCancel().
If a timeout happens in either SPI_SLAVE or SPI_MASTER mode, the receive buffer will contain the bytes received up until the timeout occured. The SPI transaction status will be set to SPI_TRANSFER_FAILED. The SPI transaction count will be set to the number of bytes sent/received before timeout. The remaining bytes will be flushed from the TX FIFO so that the subsequent transfer can be executed correctly.

Power Management

The TI-RTOS power management framework will try to put the device into the most power efficient mode whenever possible. Please see the technical reference manual for further details on each power mode.

The SPICC26XXDMA.h driver is setting a power constraint during transfers to keep the device out of standby. When the transfer has finished, the power constraint is released. The following statements are valid:

• After SPI_open(): the device is still allowed to enter standby.
• In slave mode:
  • During SPI_transfer(): the device cannot enter standby, only idle.
  • After an RX overflow: device is allowed to enter standby.
  • After a successful SPI_transfer(): the device is allowed to enter standby, but SPI module remains enabled.
    • Note: In slave mode, the device might enter standby while a byte is being transferred if SPI_transfer() is not called again after a successful transfer. This could result in corrupt data being transferred.
  • Application thread should typically either issue another transfer after SPI_transfer() completes successfully, or call SPI_transferCancel() to disable the SPI module and thus assuring that no data is received while entering standby.
• In master mode:
  • During SPI_transfer(): the device cannot enter standby, only idle.
  • After SPI_transfer() succeeds: the device can enter standby.
  • If SPI_transferCancel() is called: the device can enter standby.

Note

The external hardware connected to the SPI might have some pull configured on the SPI lines. When the SPI is inactive, this might cause leakage on the IO and the current consumption to increase. The application must configure a pull configuration that alignes with the external hardware. See Ensure low power during inactive periods for code example.

SPI details

Chip Select

This SPI controller supports a hardware chip select pin. Refer to the user manual on how this hardware chip select pin behaves in regards to the SPI frame format.

Chip select type	SPI_MASTER mode	SPI_SLAVE mode
Hardware chip select	No action is needed by the application to select the peripheral.	See the device documentation on it's chip select requirements.
Software chip select	The application is responsible to ensure that correct SPI slave is selected before performing a SPI_transfer().	See the device documentation on it's chip select requirements.

Multiple slaves when operating in master mode

In a scenario where the SPI module is operating in master mode with multiple SPI slaves, the chip select pin can be reallocated at runtime to select the appropiate slave device. See Master Mode With Multiple Slaves use case below. This is only relevant when chip select is a hardware chip select. Otherwise the application can control the chip select pins directly using the PIN driver.

Data Frames

SPI data frames can be any size from 4-bits to 16-bits. If the dataSize in SPI_Params is greater that 8-bits, then the SPICC26XXDMA driver implementation will assume that the SPI_Transaction txBuf and rxBuf point to an array of 16-bit uint16_t elements.

dataSize	buffer element size
4-8 bits	uint8_t
9-16 bits	uint16_t

Bit Rate

When the SPI is configured as SPI slave, the maximum bit rate is 4MHz.

When the SPI is configured as SPI master, the maximum bit rate is 12MHz.

UDMA

Interrupts

The UDMA module generates IRQs on the SPI interrupt vector. This driver automatically installs a UDMA aware Hwi (interrupt) to service the assigned UDMA channels.

Transfer Size Limit

The UDMA contoller only supports data transfers of upto 1024 data frames. A data frame can be 4 to 16 bits in length.

Scratch Buffers

A uint32_t scratch buffer is used to allow SPI_transfers where txBuf or rxBuf are NULL. Rather than requiring txBuf or rxBuf to have a dummy buffer of size of the transfer count, a single UDMA accessible uint32_t scratch buffer is used. When rxBuf is NULL, the UDMA will transfer all the SPI data receives into the scratch buffer as a "bit-bucket". When rxBuf is NULL, the scratch buffer is initialized to defaultTxBufValue so the uDMA will send some known value. Each SPI driver instance uses its own scratch buffer.

Supported Functions

Generic API function	API function	Description
SPI_init()	SPICC26XXDMA_init()	Initialize SPI driver
SPI_open()	SPICC26XXDMA_open()	Initialize SPI HW and set system dependencies
SPI_close()	SPICC26XXDMA_close()	Disable SPI and UDMA HW and release system dependencies
SPI_control()	SPICC26XXDMA_control()	Configure an already opened SPI handle
SPI_transfer()	SPICC26XXDMA_transfer()	Start transfer from SPI
SPI_transferCancel()	SPICC26XXDMA_transferCancel()	Cancel ongoing transfer from SPI

Note

All calls should go through the generic API

Unsupported Functionality

The CC26XX SPI driver does not support:

• SPICC26XXDMA_serviceISR()

Use Cases

Basic Slave Mode

Receive 100 bytes over SPI in SPI_MODE_BLOCKING.

SPI_Handle handle;
SPI_Params params;
SPI_Transaction transaction;
uint8_t rxBuf[100];     // Receive buffer

// Init SPI and specify non-default parameters
SPI_Params_init(&params);
params.bitRate     = 1000000;
params.frameFormat = SPI_POL1_PHA1;
params.mode        = SPI_SLAVE;

// Configure the transaction
transaction.count = 100;
transaction.txBuf = NULL;
transaction.rxBuf = rxBuf;

// Open the SPI and perform the transfer
handle = SPI_open(Board_SPI, &params);
SPI_transfer(handle, &transaction);

Slave Mode With Return Partial

This use case will perform a transfer in SPI_MODE_BLOCKING until the wanted amount of bytes is transferred or until chip select is deasserted by the SPI master. This SPI_transfer() call can be used when unknown amount of bytes shall be transferred. Note: The partial return is also possible in SPI_MODE_CALLBACK mode.

SPI_Handle handle;
SPI_Params params;
SPI_Transaction transaction;
uint8_t rxBuf[100];     // Receive buffer

// Init SPI and specify non-default parameters
SPI_Params_init(&params);
params.bitRate     = 1000000;
params.frameFormat = SPI_POL1_PHA1;
params.mode        = SPI_SLAVE;

// Configure the transaction
transaction.count = 100;
transaction.txBuf = NULL;
transaction.rxBuf = rxBuf;

// Open the SPI and initiate the partial read
handle = SPI_open(Board_SPI, &params);

// Enable RETURN_PARTIAL
SPI_control(handle, SPICC26XXDMA_RETURN_PARTIAL_ENABLE, NULL);

// Begin transfer
SPI_transfer(handle, &transaction);

Continous Slave Transfer In SPI_MODE_CALLBACK

This use case will configure the SPI driver to transfer continously in SPI_MODE_CALLBACK, 16 bytes at the time and echoing received data after every 16 bytes.

// Callback function
static void transferCallback(SPI_Handle handle, SPI_Transaction *transaction)
{
    // Start another transfer
    SPI_transfer(handle, transaction);
}

static void taskFxn(UArg a0, UArg a1)
{
    SPI_Handle handle;
    SPI_Params params;
    SPI_Transaction transaction;
    uint8_t buf[16];                  // Receive and transmit buffer

    // Init SPI and specify non-default parameters
    SPI_Params_init(&params);
    params.bitRate             = 1000000;
    params.frameFormat         = SPI_POL1_PHA1;
    params.mode                = SPI_SLAVE;
    params.transferMode        = SPI_MODE_CALLBACK;
    params.transferCallbackFxn = transferCallback;

    // Configure the transaction
    transaction.count = 16;
    transaction.txBuf = buf;
    transaction.rxBuf = buf;

    // Open the SPI and initiate the first transfer
    handle = SPI_open(Board_SPI, &params);
    SPI_transfer(handle, &transaction);

    // Wait forever
    while(true);
}

Basic Master Mode

This use case will configure a SPI master to send the data in txBuf while receiving data to rxBuf in BLOCKING_MODE.

SPI_Handle handle;
SPI_Params params;
SPI_Transaction transaction;
uint8_t txBuf[] = "Hello World";    // Transmit buffer
uint8_t rxBuf[11];                  // Receive buffer

// Init SPI and specify non-default parameters
SPI_Params_init(&params);
params.bitRate     = 1000000;
params.frameFormat = SPI_POL1_PHA1;
params.mode        = SPI_MASTER;

// Configure the transaction
transaction.count = sizeof(txBuf);
transaction.txBuf = txBuf;
transaction.rxBuf = rxBuf;

// Open the SPI and perform the transfer
handle = SPI_open(Board_SPI, &params);
SPI_transfer(handle, &transaction);

Master Mode With Multiple Slaves

This use case will configure a SPI master to send data to one slave and then to another in BLOCKING_MODE. It is assumed that the board file is configured so that the two chip select pins have a default setting of a high output and that the SPICC26XXDMA_HWAttrsV1 used points to one of them since the SPI driver will revert to this default setting when switching the chip select pin.

// From board.c
PIN_Config BoardGpioInitTable[] = {
    Board_CSN_0   | PIN_GPIO_OUTPUT_EN | PIN_GPIO_HIGH   | PIN_PUSHPULL,   // Ensure SPI slave 0 is not selected
    Board_CSN_1   | PIN_GPIO_OUTPUT_EN | PIN_GPIO_HIGH   | PIN_PUSHPULL    // Ensure SPI slave 1 is not selected
}

const SPICC26XXDMA_HWAttrsV1 spiCC26XXDMAHWAttrs[CC2650_SPICOUNT] = {
{   // Use SPI0 module with default chip select on Board_CSN_0
    .baseAddr = SSI0_BASE,
    .intNum = INT_SSI0,
    .intPriority = ~0,
    .swiPriority = 0,
    .defaultTxBufValue = 0,
    .powerMngrId = PERIPH_SSI0,
    .rxChannelIndex = UDMA_CHAN_SSI0_RX,
    .txChannelIndex = UDMA_CHAN_SSI0_TX,
    .mosiPin = Board_SPI0_MOSI,
    .misoPin = Board_SPI0_MISO,
    .clkPin = Board_SPI0_CLK,
    .csnPin = Board_CSN_0
}

// From your_application.c
static void taskFxn(UArg a0, UArg a1)
{
    SPI_Handle handle;
    SPI_Params params;
    SPI_Transaction transaction;
    PIN_Id csnPin1  = PIN_ID(Board_CSN_1);
    uint8_t txBuf[] = "Hello World";    // Transmit buffer

    // Init SPI and specify non-default parameters
    SPI_Params_init(&params);
    params.bitRate     = 1000000;
    params.frameFormat = SPI_POL1_PHA1;
    params.mode        = SPI_MASTER;

    // Configure the transaction
    transaction.count = sizeof(txBuf);
    transaction.txBuf = txBuf;
    transaction.rxBuf = NULL;

    // Open the SPI and perform transfer to the first slave
    handle = SPI_open(Board_SPI, &params);
    SPI_transfer(handle, &transaction);

    // Then switch chip select pin and perform transfer to the second slave
    SPI_control(handle, SPICC26XXDMA_SET_CSN_PIN, &csnPin1);
    SPI_transfer(handle, &transaction);
}

Ensure low power during inactive periods

External hardware connected on the SPI, i.e. SPI host/slave, might have configured a pull on one or more of the SPI lines. Dependent on the hardware, it might conflict with the pull used for the CC26XX SPI. To avoid increased leakage and ensure the lowest possible power consumption when the SPI is inactive, the application must configure a matching pull on the SPI IOs. An example of how this can be done is shown below.

PIN_Handle pinHandle;
SPI_Handle handle;
SPI_Params params;
SPI_Transaction transaction;
uint8_t txBuf[] = "Heartbeat";    // Transmit buffer
uint8_t rxBuf[9];                 // Receive buffer
PIN_Id misoPinId;
uint32_t standbyDurationMs = 100;

// Init SPI and specify non-default parameters
SPI_Params_init(&params);
params.bitRate     = 1000000;
params.frameFormat = SPI_POL1_PHA1;
params.mode        = SPI_MASTER;

// Configure the transaction
transaction.count = sizeof(txBuf);
transaction.txBuf = txBuf;
transaction.rxBuf = rxBuf;

// Open the SPI and perform the transfer
handle = SPI_open(Board_SPI, &params);
// Get pinHandle
pinHandle = ((SPICC26XXDMA_Object *)spiHandle->object)->pinHandle;
// Get miso pin id
misoPinId = ((SPICC26XXDMA_HWAttrsV1 *)spiHandle->hwAttrs)->misoPin;

// Apply low power sleep pull config for MISO
PIN_setConfig(pinHandle, PIN_BM_PULLING, PIN_PULLUP | misoPinId);

// Do forever
while(1) {
  // Transfer data
  SPI_transfer(handle, &transaction);
  // Sleep
  Task_sleep(standbyDurationMs*100);
}

Instrumentation

The SPI driver interface produces log statements if instrumentation is enabled.

Diagnostics Mask	Log details
Diags_USER1	basic SPI operations performed
Diags_USER2	detailed SPI operations performed

---

#include <stdint.h>
#include <ti/drivers/SPI.h>
#include <ti/drivers/pin/PINCC26XX.h>
#include <ti/drivers/dma/UDMACC26XX.h>
#include <ti/drivers/Power.h>
#include <ti/drivers/power/PowerCC26XX.h>
#include <ti/sysbios/knl/Semaphore.h>
#include <ti/sysbios/knl/Swi.h>
#include <ti/sysbios/family/arm/m3/Hwi.h>

Include dependency graph for SPICC26XXDMA.h:

Go to the source code of this file.

Data Structures
struct	SPICC26XXDMA_HWAttrsV1
	SPICC26XXDMA Hardware attributes. More...
struct	SPICC26XXDMA_Object
	SPICC26XXDMA Object. More...

Macros
#define	ti_sysbios_family_arm_m3_Hwi__nolocalnames
#define	SPICC26XXDMA_CMD_RETURN_PARTIAL_ENABLE   SPI_CMD_RESERVED + 0
	Command used by SPI_control to enable partial return. More...
#define	SPICC26XXDMA_CMD_RETURN_PARTIAL_DISABLE   SPI_CMD_RESERVED + 1
	Command used by SPI_control to disable partial return. More...
#define	SPICC26XXDMA_CMD_SET_CSN_PIN   SPI_CMD_RESERVED + 2
	Command used by SPI_control to re-configure chip select pin. More...
#define	SPICC26XXDMA_CMD_SET_CSN_WAKEUP   SPI_CMD_RESERVED + 3
	Command used by SPI_control to re-configure a wakeup pin. More...
#define	SPICC26XXDMA_RETURN_PARTIAL_ENABLE   SPICC26XXDMA_CMD_RETURN_PARTIAL_ENABLE
#define	SPICC26XXDMA_RETURN_PARTIAL_DISABLE   SPICC26XXDMA_CMD_RETURN_PARTIAL_DISABLE
#define	SPICC26XXDMA_SET_CSN_PIN   SPICC26XXDMA_CMD_SET_CSN_PIN
#define	SPICC26XXDMA_SET_CSN_WAKEUP   SPICC26XXDMA_CMD_SET_CSN_WAKEUP

Typedefs
typedef enum SPICC26XXDMA_FrameSize	SPICC26XXDMA_FrameSize
typedef void(*	SPICC26XXDMA_CallbackFxn) (SPI_Handle handle)
typedef struct SPICC26XXDMA_HWAttrsV1	SPICC26XXDMA_HWAttrsV1
	SPICC26XXDMA Hardware attributes. More...
typedef struct SPICC26XXDMA_Object	SPICC26XXDMA_Object
	SPICC26XXDMA Object. More...
typedef struct SPICC26XXDMA_Object *	SPICC26XXDMA_Handle

Enumerations
enum	SPICC26XXDMA_FrameSize {   SPICC26XXDMA_8bit = 0,   SPICC26XXDMA_16bit = 1 }

Variables
const SPI_FxnTable	SPICC26XXDMA_fxnTable

Macro Definition Documentation

#define ti_sysbios_family_arm_m3_Hwi__nolocalnames

#define SPICC26XXDMA_RETURN_PARTIAL_ENABLE   SPICC26XXDMA_CMD_RETURN_PARTIAL_ENABLE

#define SPICC26XXDMA_RETURN_PARTIAL_DISABLE   SPICC26XXDMA_CMD_RETURN_PARTIAL_DISABLE

#define SPICC26XXDMA_SET_CSN_PIN   SPICC26XXDMA_CMD_SET_CSN_PIN

#define SPICC26XXDMA_SET_CSN_WAKEUP   SPICC26XXDMA_CMD_SET_CSN_WAKEUP

Typedef Documentation

typedef enum SPICC26XXDMA_FrameSize SPICC26XXDMA_FrameSize

typedef void(* SPICC26XXDMA_CallbackFxn) (SPI_Handle handle)

typedef struct SPICC26XXDMA_HWAttrsV1 SPICC26XXDMA_HWAttrsV1

SPICC26XXDMA Hardware attributes.

These fields, with the exception of intPriority, are used by driverlib APIs and therefore must be populated by driverlib macro definitions. For CC26xxWare these definitions are found in:

• inc/hw_memmap.h
• inc/hw_ints.h
• driverlib/udma.h

intPriority is the SPI peripheral's interrupt priority, as defined by the underlying OS. It is passed unmodified to the underlying OS's interrupt handler creation code, so you need to refer to the OS documentation for usage. For example, for SYS/BIOS applications, refer to the ti.sysbios.family.arm.m3.Hwi documentation for SYS/BIOS usage of interrupt priorities. If the driver uses the ti.drivers.ports interface instead of making OS calls directly, then the HwiP port handles the interrupt priority in an OS specific way. In the case of the SYS/BIOS port, intPriority is passed unmodified to Hwi_create().

A sample structure is shown below:

const SPICC26XXDMA_HWAttrsV1 spiCC26XXDMAobjects[] = {
    {
        .baseAddr = SSI0_BASE,
        .intNum = INT_SPI0,
        .intPriority = ~0,
        .swiPriority = 0,
        .powerMngrId = PERIPH_SPI0,
        .defaultTxBufValue = 0,
        .rxChannelBitMask = UDMA_CHAN_SPI0_RX,
        .txChannelBitMask = UDMA_CHAN_SPI0_TX,
        .mosiPin = Board_SPI0_MISO,
        .misoPin = Board_SPI0_MOSI,
        .clkPin = Board_SPI0_CLK,
        .csnPin = Board_SPI0_CSN
    },
    {
        .baseAddr = SSI1_BASE,
        .intNum = INT_SPI1,
        .intPriority = ~0,
        .swiPriority = 0,
        .powerMngrId = PERIPH_SPI1,
        .defaultTxBufValue = 0,
        .rxChannelBitMask = UDMA_CHAN_SPI1_RX,
        .txChannelBitMask = UDMA_CHAN_SPI1_TX,
        .mosiPin = Board_SPI1_MISO,
        .misoPin = Board_SPI1_MOSI,
        .clkPin = Board_SPI1_CLK,
        .csnPin = Board_SPI1_CSN
    },
};

typedef struct SPICC26XXDMA_Object SPICC26XXDMA_Object

SPICC26XXDMA Object.

The application must not access any member variables of this structure!

typedef struct SPICC26XXDMA_Object * SPICC26XXDMA_Handle

Enumeration Type Documentation

enum SPICC26XXDMA_FrameSize

Enumerator
SPICC26XXDMA_8bit
SPICC26XXDMA_16bit

Variable Documentation

const SPI_FxnTable SPICC26XXDMA_fxnTable