| 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 | Enumerations
SPI Master Peripheral Driver
Serial Peripheral Interface (SPI)

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

## Data Structures
struct | spi_user_config_t
| Information about a device on the SPI bus. More...

## Enumerations
enum | _spi_timeouts { kSpiWaitForever = 0xffffffffU }

## Initialization and shutdown
void | spi_master_init (uint32_t instance)
| Initializes an SPI instance for master mode operation. More...
void | spi_master_shutdown (uint32_t instance)
| Shuts down an SPI instance. More...

## Bus configuration
void | spi_master_configure_bus (uint32_t instance, const spi_user_config_t *device)
| Configures the SPI port to access a device on the bus. More...

## Blocking transfers
spi_status_t | spi_master_transfer (uint32_t instance, const spi_user_config_t *restrict device, const uint8_t *restrict sendBuffer, uint8_t *restrict receiveBuffer, size_t transferByteCount, uint32_t timeout)
| Performs a blocking SPI master mode transfer. More...

## Non-blocking transfers
spi_status_t | spi_master_transfer_async (uint32_t instance, const spi_user_config_t *restrict device, const uint8_t *restrict sendBuffer, uint8_t *restrict receiveBuffer, size_t transferByteCount)
| Performs a non-blocking SPI master mode transfer. More...
spi_status_t | spi_master_get_tranfer_status (uint32_t instance, uint32_t *bytesTransferred)
| Returns whether the previous transfer finished. More...
spi_status_t | spi_master_abort_transfer (uint32_t instance)
| Terminates an asynchronous transfer early. More...

### SPI Master Peripheral Driver

# Overview

The SPI master mode peripheral driver transfers data to and from the external devices on the SPI bus in master mode. It provides an easy way to transfer buffers of data with a single function call.

# Device structures

The driver uses instances of the #spi_device_t structure to represent the SPI bus configuration required to communicate the bus connectivity to an external device.The device structures can be passed to the data transfer functions and the bus is reconfigured before the transfer is started. Alternatively, you can manually configure the SPI bus for a device. For example, if there is only one device connected to the bus, you might configure it only once.

# Initialization

To initialize the SPI master driver, call the spi_master_init() function and pass the instance number of the SPI peripheral you want to use. For example, to use the SPI1, pass a value of 1 to the initialization function.This is an example code to initialize and configure the driver:
// Define bus configuration.
spi_device_t device = {
.busFrequencyKHz = 1000,
.polarity = kSpiClockPolarity_ActiveHigh,
.phase = kSpiClockPhase_SecondEdge,
.direction = kSpiMsbFirst
};
// Init driver.
spi_master_init(0);
// Configure bus.
spi_master_configure_bus(0, &device);

# Transfers

The driver supports two different modes to transfer data: blocking and non-blocking. The blocking transfer function is the spi_master_transfer().This is an example of a blocking transfer:
uint8_t sendBuf[] = { 0, 1, 2, 3 };
uint8_t receiveBuf[sizeof(sendBuf)];
spi_master_transfer(0, // SPI0
&device, // Device SPI bus configuration
sendBuf, // Data to send
receiveBuf, // Buffer to hold received data
sizeof(sendBuf), // Number of bytes to transfer
kSpiWaitForever); // No timeout
This is an example of a non-blocking transfer:
uint8_t sendBuf[] = { 0, 1, 2, 3 };
uint8_t receiveBuf[sizeof(sendBuf)];
// Start the transfer.
spi_master_transfer_async(0, // SPI0
&device, // Device SPI bus configuration
sendBuf, // Data to send
receiveBuf, // Buffer to hold received data
sizeof(sendBuf)); // Number of bytes to transfer
// Wait for the transfer to complete.
while (spi_master_get_transfer_status(0, NULL) == kStatus_SPI_Busy)
{
}

## Data Structure Documentation

struct spi_user_config_t

### Data Fields
uint32_t | busFrequencyKHz
spi_clock_polarity_t | polarity
spi_clock_phase_t | phase
spi_shift_direction_t | direction

## Enumeration Type Documentation

enum _spi_timeouts

Enumerator
kSpiWaitForever | Waits forever for a transfer to complete.

## Function Documentation

void spi_master_init | ( | uint32_t | instance | ) |

Parameters

  instance | The instance number of the SPI peripheral.

void spi_master_shutdown | ( | uint32_t | instance | ) |

Resets the SPI peripheral and gates its clock.

Parameters

  instance | The instance number of the SPI peripheral.

void spi_master_configure_bus | ( | uint32_t | instance,
|  | const spi_user_config_t * | device
| ) |  |

Parameters

  instance | The instance number of the SPI peripheral.
  device | Pointer to the device information structure. This structure contains the settings for SPI bus configurations.

spi_status_t spi_master_transfer | ( | uint32_t | instance,
|  | const spi_user_config_t *restrict | device,
|  | const uint8_t *restrict | sendBuffer,
|  | uint8_t *restrict | 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.

Parameters

  instance | The instance number of the SPI peripheral.
  device | Pointer to the device information structure. This structure contains the settings for the SPI bus configuration for this transfer. You may pass NULL for this parameter, in which case the current bus configuration is used unmodified.
  sendBuffer | Buffer of data to send. You may pass NULL for this parameter, in which case bytes with a value of 0 (zero) are sent.
  receiveBuffer | Buffer where 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 is returned.

Return values

  #kStatus_Success | The transfer was successful.
  kStatus_SPI_Busy | Cannot perform another transfer because one is already in progress.
  kStatus_SPI_Timeout | The transfer timed out and was aborted.

spi_status_t spi_master_transfer_async | ( | uint32_t | instance,
|  | const spi_user_config_t *restrict | device,
|  | const uint8_t *restrict | sendBuffer,
|  | uint8_t *restrict | receiveBuffer,
|  | size_t | transferByteCount
| ) |  |

Parameters

  instance | The instance number of the SPI peripheral.
  device | Pointer to the device information structure. This structure contains the settings for the SPI bus configuration for this transfer. You may pass NULL for this parameter, in which case the current bus configuration is used unmodified.
  sendBuffer | Buffer of data to send. You may pass NULL for this parameter, in which case bytes with a value of 0 (zero) will be sent.
  receiveBuffer | Buffer where 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_Success | The transfer was successful.
  kStatus_SPI_Busy | Cannot perform another transfer because one is already in progress.
  kStatus_SPI_Timeout | The transfer timed out and was aborted.

spi_status_t spi_master_get_tranfer_status | ( | uint32_t | instance,
|  | uint32_t * | bytesTransferred
| ) |  |

Parameters

  instance | The instance number of the SPI peripheral.
  bytesTransferred | Pointer to a value that is filled in with the number of bytes that were sent in the active transfer

Return values

  kStatus_Success | The transfer has completed successfully.
  kStatus_SPI_Busy | The transfer is still in progress. bytesTransferred is filled with the number of bytes that have been transferred so far.

spi_status_t spi_master_abort_transfer | ( | uint32_t | instance | ) |

Parameters

  instance | The instance number of the SPI peripheral.

Return values

  #kStatus_Success | The transfer was successful.