| Kinetis SDK API Reference Manual 1.0.0-beta Freescale Semiconductor, Inc.

- Introduction
- Related Pages
- API Usage

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures
DSPI Master Driver
Serial Peripheral Interface (DSPI)

The section describes the programming interface of the DSPI master mode Peripheral driver. More...

## Data Structures
struct | dspi_device_t
| Data structure containing information about a device on the SPI bus. More...
struct | dspi_master_state_t
| Runtime state structure for the DSPI master driver. More...
struct | dspi_master_user_config_t
| The user configuration structure for the DSPI master driver. More...

## Init and shutdown
dspi_status_t | dspi_master_init (uint32_t instance, dspi_master_state_t *dspiState, const dspi_master_user_config_t *userConfig, uint32_t *calculatedBaudRate)
| Initialize a DSPI instance for master mode operation. More...
void | dspi_master_shutdown (dspi_master_state_t *dspiState)
| Shuts down a DSPI instance. More...
void | dspi_master_configure_modified_transfer_format (dspi_master_state_t *dspiState, bool enableOrDisable, dspi_master_sample_point_t samplePnt)
| Configures the DSPI modified transfer format in master mode. More...

## Bus configuration
dspi_status_t | dspi_master_configure_bus (dspi_master_state_t *dspiState, const dspi_device_t *device, uint32_t *calculatedBaudRate)
| Configures the DSPI port physical parameters to access a device on the bus. More...

## Blocking transfers
dspi_status_t | dspi_master_transfer (dspi_master_state_t *dspiState, const dspi_device_t *restrict device, const uint8_t *sendBuffer, uint8_t *receiveBuffer, size_t transferByteCount, uint32_t timeout)
| Performs a blocking SPI master mode transfer. More...

## Non-blocking transfers
dspi_status_t | dspi_master_transfer_async (dspi_master_state_t *dspiState, const dspi_device_t *restrict device, const uint8_t *sendBuffer, uint8_t *receiveBuffer, size_t transferByteCount)
| Performs a non-blocking SPI master mode transfer. More...
dspi_status_t | dspi_master_get_transfer_status (dspi_master_state_t *dspiState, uint32_t *framesTransferred)
| Returns whether the previous transfer is finished. More...
dspi_status_t | dspi_master_abort_transfer (dspi_master_state_t *dspiState)
| Terminates an asynchronous transfer early. More...

### DSPI Master Driver

# Overview

The DSPI master mode peripheral driver transfers data to and from external devices on the DSPI bus in master mode. It supports transferring buffers of data with a single function call.

# Run-time state structs

The DSPI master driver uses a run-time state struct dspi_master_state_t to track of the ongoing data transfer. The struct holds data that the DSPI master peripheral driver uses to communicate between the transfer function and the interrupt handler. The interrupt handler also uses this information to keep track of its progress. The user is only responsible to pass the memory for this run-time state structure and the DSPI master driver will fill out the members.

# User config structs

The DSPI master driver uses instances of the user configuration structure dspi_master_user_config_t for the DSPI master driver. For this reason, the user can configure the most common settings of the DSPI peripheral with a single function call.

# Device structs

The DSPI master driver uses instances of the dspi_device_t structure to represent the SPI bus configuration required to communicate to an external device that is connected to the bus.The device struct can be passed to the data transfer functions, and the bus will be reconfigured before the transfer is started. Alternatively, the user can configure the SPI bus for a device manually. For instance, if there is only one device connected to the bus, the user might configure it only once.

# Initialization

To initialize the DSPI master driver, call the dspi_master_init() function and and pass the instance number of the DSPI peripheral, the user config of type dspi_master_user_config_t , a pointer to the variable for retrieving the calculated baud rate (this can be a NULL), and memory allocation for the run-time state structure used by the master driver to keep track of data transfers. For example, to use DSPI1, pass a value of 1 to the init function. This is an example for the other parameters.Example code to initialize and configure the driver:
/* Set up and init the master */
dspi_master_state_t dspiMasterState;
uint32_t calculatedBaudRate;
/* configure the members of the user config */
dspi_master_user_config_t userConfig;
userConfig.isChipSelectContinuous = false;
userConfig.isSckContinuous = false;
userConfig.pcsPolarity = kDspiPcs_ActiveLow;
userConfig.whichCtar = kDspiCtar0;
userConfig.whichPcs = kDspiPcs1;
/* init the DSPI module */
dspi_master_init(masterInstance, &dspiMasterState, &userConfig, &calculatedBaudRate);
// Define bus configuration.
dspi_device_t spiDevice;
spiDevice.dataBusConfig.bitsPerFrame = 16;
spiDevice.dataBusConfig.clkPhase = kDspiClockPhase_FirstEdge;
spiDevice.dataBusConfig.clkPolarity = kDspiClockPolarity_ActiveHigh;
spiDevice.dataBusConfig.direction = kDspiMsbFirst;
spiDevice.bitsPerSec = 500000;
/* configure the SPI bus */
dspi_master_configure_bus(&dspiMasterState, &spiDevice, &calculatedBaudRate);

# Transfers

The driver supports two different modes for transferring data: blocking and non-blocking (async). The dspi_master_transfer() is the blocking transfer function. The dspi_master_transfer_async() is a non-blocking function.Example of a blocking transfer:
/* Function prototype */
status_t dspi_master_transfer(dspi_master_state_t * dspiState,
const dspi_device_t * restrict device,
const uint8_t * sendBuffer,
uint8_t * receiveBuffer,
uint32_t transferByteCount,
uint32_t timeout);
/* Example function call */
dspi_master_transfer(&dspiMasterState, NULL, s_dspiSourceBuffer[masterInstance], s_dspiSinkBuffer[masterInstance], 32, 1);
Example of a nonb-locking transfer:
/* Function prototype */
status_t dspi_master_transfer_async(dspi_master_state_t * dspiState,
const dspi_device_t * restrict device,
const uint8_t * sendBuffer,
uint8_t * receiveBuffer,
uint32_t transferByteCount);
/* Example function call */
dspi_master_transfer_async(&dspiMasterState, NULL, s_dspiSourceBuffer[masterInstance], s_dspiSinkBuffer[masterInstance], 32);
/* For non-blocking/a-sync transfers, need to check back to get transfer status, for example */
/* Where framesXfer returns the number of frames transferred */
dspi_master_get_transfer_status(&dspiMasterState, &framesXfer);

## Data Structure Documentation

struct dspi_device_t

The user must fill out these members to set up the DSPI master to properly communicate with the SPI device.

### Data Fields
uint32_t | bitsPerSec
| Baud rate in bits per second. More...
dspi_data_format_config_t | dataBusConfig

#### Field Documentation

uint32_t dspi_device_t::bitsPerSec

struct dspi_master_state_t

This struct holds data that is used by the DSPI master peripheral driver to communicate between the transfer function and the interrupt handler. The interrupt handler also uses this information to keep track of its progress. The user must pass the memory for this run-time state structure and the DSPI master driver will fill out the members.

### Data Fields
uint32_t | instance
| DSPI module instance number.
dspi_ctar_selection_t | whichCtar
| Desired Clock and Transfer Attributes Register (CTAR)
uint32_t | bitsPerFrame
| Desired number of bits per frame.
dspi_which_pcs_config_t | whichPcs
| Desired Peripheral Chip Select (pcs)
bool | isChipSelectContinuous
| Option to enable the continuous assertion of chip select between transfers.
uint32_t | dspiSourceClock
| Module source clock.
volatile bool | isTransferInProgress
| True if there is an active transfer. More...
bool | isTransferAsync
| Whether the transfer is asynchronous (needed in IRQ). More...
const uint8_t *restrict | sendBuffer
| The buffer from which transmitted bytes are taken. More...
uint8_t *restrict | receiveBuffer
| The buffer into which received bytes are placed. More...
volatile size_t | remainingSendByteCount
| Number of bytes remaining to send. More...
volatile size_t | remainingReceiveByteCount
| Number of bytes remaining to receive. More...
sync_object_t | irqSync
| Used to wait for ISR to complete its business. More...

#### Field Documentation

volatile bool dspi_master_state_t::isTransferInProgress

bool dspi_master_state_t::isTransferAsync

const uint8_t* restrict dspi_master_state_t::sendBuffer

uint8_t* restrict dspi_master_state_t::receiveBuffer

volatile size_t dspi_master_state_t::remainingSendByteCount

volatile size_t dspi_master_state_t::remainingReceiveByteCount

sync_object_t dspi_master_state_t::irqSync

struct dspi_master_user_config_t

Use an instance of this struct with the dspi_master_init(). This allows the user to configure the most common settings of the DSPI peripheral with a single function call.

### Data Fields
dspi_ctar_selection_t | whichCtar
| Desired Clock and Transfer Attributes Register(CTAR)
bool | isSckContinuous
| Disable or Enable continuous SCK operation.
bool | isChipSelectContinuous
| Option to enable the continuous assertion of chip select between transfers.
dspi_which_pcs_config_t | whichPcs
| Desired Peripheral Chip Select (pcs)
dspi_pcs_polarity_config_t | pcsPolarity
| Peripheral Chip Select (pcs) polarity setting. More...

#### Field Documentation

dspi_pcs_polarity_config_t dspi_master_user_config_t::pcsPolarity

## Function Documentation

dspi_status_t dspi_master_init | ( | uint32_t | instance,
|  | dspi_master_state_t * | dspiState,
|  | const dspi_master_user_config_t * | userConfig,
|  | uint32_t * | calculatedBaudRate
| ) |  |

This function initializes the run-time state structure to track the ongoing transfers, ungates the clock to the DSPI module, resets the DSPI module, initializes the module to user defined settings and default settings, configures the IRQ state structure, enables the module-level interrupt to the core, and enables the DSPI module. The CTAR parameter is special in that it allows the user to have different SPI devices connected to the same DSPI module instance in addition to different peripheral chip selects. Each CTAR contains the bus attributes associated with that particular SPI device. For most use cases where only one SPI device is connected per DSPI module instance, use CTAR0. This is an example to set up the dspi_master_state_t and the dspi_master_user_config_t parameters and to call the dspi_master_init function by passing in these parameters:

dspi_master_state_t dspiMasterState; <- the user simply allocates memory for this struct
uint32_t calculatedBaudRate;
dspi_master_user_config_t userConfig; <- the user fills out members for this struct
userConfig.isChipSelectContinuous = false;
userConfig.isSckContinuous = false;
userConfig.pcsPolarity = kDspiPcs_ActiveLow;
userConfig.whichCtar = kDspiCtar0;
userConfig.whichPcs = kDspiPcs0;
dspi_master_init(masterInstance, &dspiMasterState, &userConfig, &calculatedBaudRate);

Parameters

  instance | The instance number of the DSPI peripheral.
  dspiState | The pointer to the DSPI master driver state structure. The user must pass the memory for this run-time state structure and the DSPI master driver will fill out the members. This run-time state structure keeps track of the transfer in progress.
  userConfig | The dspi_master_user_config_t user configuration structure. The user must fill out the members of this structure and pass the pointer of this struct into the function.
  calculatedBaudRate | The calculated baud rate passed back to the user to determine if the calculated baud rate is close enough to meet the needs. The value returned may be 0 if the user decides to set the baud rate to 0 in the user configuration struct. The user can later configure the baud rate via the dspi_master_configure_bus function, and hence may not need to configure the baud rate in the dspi_master_init function.

Returns
  An error code or kStatus_DSPI_Success.

void dspi_master_shutdown | ( | dspi_master_state_t * | dspiState | ) |

This function resets the DSPI peripheral, gates its clock, and disables the interrupt to the core.

Parameters

  dspiState | The pointer to the DSPI master driver state structure.

void dspi_master_configure_modified_transfer_format | ( | dspi_master_state_t * | dspiState,
|  | bool | enableOrDisable,
|  | dspi_master_sample_point_t | samplePnt
| ) |  |

This function allows the user to enable or disable (default setting) the modified transfer format. The modified transfer format is supported to allow high-speed communication with peripherals that require longer setup times. The module can sample the incoming data later than halfway through the cycle to give the peripheral more setup time. The data-in sample point can also be configured in this function. Note that the data-in sample point setting is valid only when the CPHA bit in the CTAR is cleared (when the dspi_clock_phase_t is set to kDspiClockPhase_FirstEdge in the dspi_data_format_config_t).

Parameters

  dspiState | The pointer to the DSPI master driver state structure.
  enableOrDisable | Enables (true) or disables(false) the modified transfer (timing) format.
  samplePnt | Selects when the data in (SIN) is sampled, of type dspi_master_sample_point_t. This value selects either 0, 1, or 2 system clocks between the SCK edge and the SIN (data in) sample.

dspi_status_t dspi_master_configure_bus | ( | dspi_master_state_t * | dspiState,
|  | const dspi_device_t * | device,
|  | uint32_t * | calculatedBaudRate
| ) |  |

The term "device" is used to indicate the SPI device for which the DSPI master is communicating. The user has two options to configure the device parameters: either pass in the pointer to the device configuration structure to the desired transfer function (see dspi_master_transfer or dspi_master_transfer_async) or pass it in to the dspi_master_configure_bus function. The user can pass in a device structure to the transfer function which contains the parameters for the bus (the transfer function will then call this function). However, the user has the option to call this function directly especially to get the calculated baud rate, at which point they may pass in NULL for the device struct in the transfer function (assuming they have called this configure bus function first). This is an example to set up the dspi_device_t structure to call the dspi_master_configure_bus function by passing in these parameters:

dspi_device_t spiDevice;
spiDevice.dataBusConfig.bitsPerFrame = 16;
spiDevice.dataBusConfig.clkPhase = kDspiClockPhase_FirstEdge;
spiDevice.dataBusConfig.clkPolarity = kDspiClockPolarity_ActiveHigh;
spiDevice.dataBusConfig.direction = kDspiMsbFirst;
spiDevice.bitsPerSec = 50000;
dspi_master_configure_bus(&dspiMasterState, &spiDevice, &calculatedBaudRate);

Parameters

  dspiState | The pointer to the DSPI master driver state structure.
  device | Pointer to the device information struct. This struct contains the settings for the SPI bus configuration. The device parameters are the desired baud rate (in bits-per-sec), and the data format field which consists of bits-per-frame, clock polarity and phase, and data shift direction.
  calculatedBaudRate | The calculated baud rate passed back to the user to determine if the calculated baud rate is close enough to meet the needs. The baud rate never exceeds the desired baud rate.

Returns
  An error code or kStatus_DSPI_Success.

dspi_status_t dspi_master_transfer | ( | dspi_master_state_t * | dspiState,
|  | const dspi_device_t *restrict | device,
|  | const uint8_t * | sendBuffer,
|  | uint8_t * | receiveBuffer,
|  | size_t | transferByteCount,
|  | uint32_t | timeout
| ) |  |

This function simultaneously sends and receives data on the SPI bus, as SPI is naturally a full-duplex bus. The function does not return until the transfer is complete.

Parameters

  dspiState | The pointer to the DSPI master driver state structure.
  device | Pointer to the device information struct. This struct contains the settings for the SPI bus configuration in this transfer. You may pass NULL for this parameter, in which case the current bus configuration is used unmodified. The device can be configured separately by calling the dspi_master_configure_bus function.
  sendBuffer | The pointer to the data buffer of the data to send. You may pass NULL for this parameter and bytes with a value of 0 (zero) will be sent.
  receiveBuffer | Pointer to the buffer where the received bytes are stored. If you pass NULL for this parameter, the received bytes are ignored.
  transferByteCount | The number of bytes to send and receive.
  timeout | A timeout for the transfer in microseconds. If the transfer takes longer than this amount of time, the transfer is aborted and a kStatus_SPI_Timeout error returned.

Return values

  kStatus_DSPI_Success | The transfer was successful.
  kStatus_DSPI_Busy | Cannot perform another transfer because a transfer is already in progress.
  kStatus_DSPI_Timeout | The transfer timed out and was aborted.

dspi_status_t dspi_master_transfer_async | ( | dspi_master_state_t * | dspiState,
|  | const dspi_device_t *restrict | device,
|  | const uint8_t * | sendBuffer,
|  | uint8_t * | receiveBuffer,
|  | size_t | transferByteCount
| ) |  |

This function returns immediately. The user must check back to check whether the transfer is complete (using the dspi_master_get_transfer_status function). This function simultaneously sends and receives data on the SPI bus, as SPI is naturally a full-duplex bus.

Parameters

  dspiState | The pointer to the DSPI master driver state structure.
  device | Pointer to the device information struct. This struct contains the settings for the SPI bus configuration in this transfer. You may pass NULL for this parameter, in which case the current bus configuration is used unmodified. The device can be configured separately by calling the dspi_master_configure_bus function.
  sendBuffer | The pointer to the data buffer of the data to send. You may pass NULL for this parameter, in which case bytes with a value of 0 (zero) are sent.
  receiveBuffer | Pointer to the buffer where the received bytes are stored. If you pass NULL for this parameter, the received bytes are ignored.
  transferByteCount | The number of bytes to send and receive.

Return values

  kStatus_DSPI_Success | The transfer was successful.
  kStatus_DSPI_Busy | Cannot perform another transfer because a transfer is already in progress.

dspi_status_t dspi_master_get_transfer_status | ( | dspi_master_state_t * | dspiState,
|  | uint32_t * | framesTransferred
| ) |  |

When performing an a-sync transfer, the user can call this function to ascertain the state of the current transfer: in progress (or busy) or complete (success). In addition, if the transfer is still in progress, the user can get the number of words that have been transferred up to now.

Parameters

  dspiState | The pointer to the DSPI master driver state structure
  framesTransferred | Pointer to value that is filled in with the number of frames that have been sent in the active transfer. A frame is defined as the number of bits per frame.

Return values

  kStatus_DSPI_Success | The transfer has completed successfully.
  kStatus_DSPI_Busy | The transfer is still in progress. wordsTransferred will be filled with the number of words that have been transferred so far.

dspi_status_t dspi_master_abort_transfer | ( | dspi_master_state_t * | dspiState | ) |

During an a-sync transfer, the user has the option to terminate the transfer early if the transfer is still in progress.

Parameters

  dspiState | The pointer to the DSPI master driver state structure.

Return values

  kStatus_DSPI_Success | The transfer was successful.
  kStatus_DSPI_NoTransferInProgress | No transfer is currently in progress.