| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
SPI master driver
Serial peripheral interface (SPI/SPIM)

Multi-instance SPI master driver. More...

## Modules
| SPI/SPIM peripheral driver configuration

## Data Structures
struct | nrf_drv_spi_t
| SPI master driver instance data structure. More...
struct | nrf_drv_spi_config_t
| SPI master driver instance configuration structure. More...
struct | nrf_drv_spi_xfer_desc_t
| Single transfer descriptor structure. More...
struct | nrf_drv_spi_evt_t

## Macros
#define | SPI0_INSTANCE_INDEX 0
#define | SPI1_INSTANCE_INDEX SPI0_INSTANCE_INDEX+SPI0_ENABLED
#define | SPI2_INSTANCE_INDEX SPI1_INSTANCE_INDEX+SPI1_ENABLED
#define | NRF_DRV_SPI_INSTANCE(id)
| Macro for creating an SPI master driver instance. More...
#define | NRF_DRV_SPI_PIN_NOT_USED 0xFF
| This value can be provided instead of a pin number for signals MOSI, MISO, and Slave Select to specify that the given signal is not used and therefore does not need to be connected to a pin.
#define | NRF_DRV_SPI_DEFAULT_CONFIG
| SPI master instance default configuration. More...
#define | NRF_DRV_SPI_FLAG_TX_POSTINC (1UL << 0)
#define | NRF_DRV_SPI_FLAG_RX_POSTINC (1UL << 1)
#define | NRF_DRV_SPI_FLAG_NO_XFER_EVT_HANDLER (1UL << 2)
#define | NRF_DRV_SPI_FLAG_HOLD_XFER (1UL << 3)
#define | NRF_DRV_SPI_FLAG_REPEATED_XFER (1UL << 4)
#define | NRF_DRV_SPI_SINGLE_XFER(p_tx, tx_len, p_rx, rx_len)
| Macro for setting up single transfer descriptor. More...
#define | NRF_DRV_SPI_XFER_TRX(p_tx_buf, tx_length, p_rx_buf, rx_length) NRF_DRV_SPI_SINGLE_XFER(p_tx_buf, tx_length, p_rx_buf, rx_length)
| Macro for setting duplex TX RX transfer.
#define | NRF_DRV_SPI_XFER_TX(p_buf, length) NRF_DRV_SPI_SINGLE_XFER(p_buf, length, NULL, 0)
| Macro for setting TX transfer.
#define | NRF_DRV_SPI_XFER_RX(p_buf, length) NRF_DRV_SPI_SINGLE_XFER(NULL, 0, p_buf, length)
| Macro for setting RX transfer.

## Typedefs
typedef void(* | nrf_drv_spi_handler_t )(nrf_drv_spi_evt_t const *p_event)
| SPI master driver event handler type.

## Enumerations
enum | nrf_drv_spi_frequency_t { NRF_DRV_SPI_FREQ_125K = NRF_SPI_FREQ_125K, NRF_DRV_SPI_FREQ_250K = NRF_SPI_FREQ_250K, NRF_DRV_SPI_FREQ_500K = NRF_SPI_FREQ_500K, NRF_DRV_SPI_FREQ_1M = NRF_SPI_FREQ_1M, NRF_DRV_SPI_FREQ_2M = NRF_SPI_FREQ_2M, NRF_DRV_SPI_FREQ_4M = NRF_SPI_FREQ_4M, NRF_DRV_SPI_FREQ_8M = NRF_SPI_FREQ_8M }
| SPI data rates. More...
enum | nrf_drv_spi_mode_t { NRF_DRV_SPI_MODE_0 = NRF_SPI_MODE_0, NRF_DRV_SPI_MODE_1 = NRF_SPI_MODE_1, NRF_DRV_SPI_MODE_2 = NRF_SPI_MODE_2, NRF_DRV_SPI_MODE_3 = NRF_SPI_MODE_3 }
| SPI modes. More...
enum | nrf_drv_spi_bit_order_t { NRF_DRV_SPI_BIT_ORDER_MSB_FIRST = NRF_SPI_BIT_ORDER_MSB_FIRST, NRF_DRV_SPI_BIT_ORDER_LSB_FIRST = NRF_SPI_BIT_ORDER_LSB_FIRST }
| SPI bit orders. More...
enum | nrf_drv_spi_evt_type_t { NRF_DRV_SPI_EVENT_DONE }
| SPI master driver event types, passed to the handler routine provided during initialization. More...

## Functions
ret_code_t | nrf_drv_spi_init (nrf_drv_spi_t const *const p_instance, nrf_drv_spi_config_t const *p_config, nrf_drv_spi_handler_t handler)
| Function for initializing the SPI master driver instance. More...
void | nrf_drv_spi_uninit (nrf_drv_spi_t const *const p_instance)
| Function for uninitializing the SPI master driver instance. More...
ret_code_t | nrf_drv_spi_transfer (nrf_drv_spi_t const *const p_instance, uint8_t const *p_tx_buffer, uint8_t tx_buffer_length, uint8_t *p_rx_buffer, uint8_t rx_buffer_length)
| Function for starting the SPI data transfer. More...
ret_code_t | nrf_drv_spi_xfer (nrf_drv_spi_t const *const p_instance, nrf_drv_spi_xfer_desc_t const *p_xfer_desc, uint32_t flags)
| Function for starting the SPI data transfer with additional option flags. More...
uint32_t | nrf_drv_spi_start_task_get (nrf_drv_spi_t const *p_instance)
| Function for returning the address of a SPIM start task. More...
uint32_t | nrf_drv_spi_end_event_get (nrf_drv_spi_t const *p_instance)
| Function for returning the address of a END SPIM event. More...

## Detailed Description

Multi-instance SPI master driver.

## Macro Definition Documentation

#define NRF_DRV_SPI_DEFAULT_CONFIG

Value:
{ \
.sck_pin = NRF_DRV_SPI_PIN_NOT_USED, \
.mosi_pin = NRF_DRV_SPI_PIN_NOT_USED, \
.miso_pin = NRF_DRV_SPI_PIN_NOT_USED, \
.ss_pin = NRF_DRV_SPI_PIN_NOT_USED, \
.irq_priority = SPI_DEFAULT_CONFIG_IRQ_PRIORITY, \
.orc = 0xFF, \
.frequency = NRF_DRV_SPI_FREQ_4M, \
.mode = NRF_DRV_SPI_MODE_0, \
.bit_order = NRF_DRV_SPI_BIT_ORDER_MSB_FIRST, \
}

SPI master instance default configuration.

#define NRF_DRV_SPI_FLAG_HOLD_XFER (1UL << 3)

Set up the transfer but do not start it.

#define NRF_DRV_SPI_FLAG_NO_XFER_EVT_HANDLER (1UL << 2)

Interrupt after each transfer is suppressed, and the event handler is not called.

#define NRF_DRV_SPI_FLAG_REPEATED_XFER (1UL << 4)

Flag indicating that the transfer will be executed multiple times.

#define NRF_DRV_SPI_FLAG_RX_POSTINC (1UL << 1)

RX buffer address incremented after transfer.

#define NRF_DRV_SPI_FLAG_TX_POSTINC (1UL << 0)

TX buffer address incremented after transfer.

#define NRF_DRV_SPI_INSTANCE | ( |  | id | ) |

Value:
{ \
.p_registers = NRF_DRV_SPI_PERIPHERAL(id), \
.irq = CONCAT_3(SPI, id, _IRQ), \
.drv_inst_idx = CONCAT_3(SPI, id, _INSTANCE_INDEX), \
.use_easy_dma = CONCAT_3(SPI, id, _USE_EASY_DMA) \
}

Macro for creating an SPI master driver instance.

#define NRF_DRV_SPI_SINGLE_XFER | ( |  | p_tx,
|  |  | tx_len,
|  |  | p_rx,
|  |  | rx_len
| ) |  |

Value:
{ \
.p_tx_buffer = (uint8_t const *)(p_tx), \
.tx_length = (tx_len), \
.p_rx_buffer = (p_rx), \
.rx_length = (rx_len), \
}

Macro for setting up single transfer descriptor.

This macro is for internal use only.

## Enumeration Type Documentation

enum nrf_drv_spi_bit_order_t

SPI bit orders.

Enumerator
NRF_DRV_SPI_BIT_ORDER_MSB_FIRST | Most significant bit shifted out first.
NRF_DRV_SPI_BIT_ORDER_LSB_FIRST | Least significant bit shifted out first.

enum nrf_drv_spi_evt_type_t

SPI master driver event types, passed to the handler routine provided during initialization.

Enumerator
NRF_DRV_SPI_EVENT_DONE | Transfer done.

enum nrf_drv_spi_frequency_t

SPI data rates.

Enumerator
NRF_DRV_SPI_FREQ_125K | 125 kbps.
NRF_DRV_SPI_FREQ_250K | 250 kbps.
NRF_DRV_SPI_FREQ_500K | 500 kbps.
NRF_DRV_SPI_FREQ_1M | 1 Mbps.
NRF_DRV_SPI_FREQ_2M | 2 Mbps.
NRF_DRV_SPI_FREQ_4M | 4 Mbps.
NRF_DRV_SPI_FREQ_8M | 8 Mbps.

enum nrf_drv_spi_mode_t

SPI modes.

Enumerator
NRF_DRV_SPI_MODE_0 | SCK active high, sample on leading edge of clock.
NRF_DRV_SPI_MODE_1 | SCK active high, sample on trailing edge of clock.
NRF_DRV_SPI_MODE_2 | SCK active low, sample on leading edge of clock.
NRF_DRV_SPI_MODE_3 | SCK active low, sample on trailing edge of clock.

## Function Documentation

uint32_t nrf_drv_spi_end_event_get | ( | nrf_drv_spi_t const * | p_instance | ) |

Function for returning the address of a END SPIM event.

A END event can be used to detect the end of a transfer if the NRF_DRV_SPI_FLAG_NO_XFER_EVT_HANDLER option is used.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

Returns
  END event address.

ret_code_t nrf_drv_spi_init | ( | nrf_drv_spi_t const *const | p_instance,
|  | nrf_drv_spi_config_t const * | p_config,
|  | nrf_drv_spi_handler_t | handler
| ) |  |

Function for initializing the SPI master driver instance.

This function configures and enables the specified peripheral.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | p_config | Pointer to the structure with the initial configuration. If NULL, the default configuration is used.
  | handler | Event handler provided by the user. If NULL, transfers will be performed in blocking mode.

Return values

  NRF_SUCCESS | If initialization was successful.
  NRF_ERROR_INVALID_STATE | If the driver was already initialized.
  NRF_ERROR_BUSY | If some other peripheral with the same instance ID is already in use. This is possible only if PERIPHERAL_RESOURCE_SHARING_ENABLED is set to a value other than zero.

uint32_t nrf_drv_spi_start_task_get | ( | nrf_drv_spi_t const * | p_instance | ) |

Function for returning the address of a SPIM start task.

This function should be used if nrf_drv_spi_xfer was called with the flag NRF_DRV_SPI_FLAG_HOLD_XFER. In that case, the transfer is not started by the driver, but it must be started externally by PPI.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

Returns
  Start task address.

ret_code_t nrf_drv_spi_transfer | ( | nrf_drv_spi_t const *const | p_instance,
|  | uint8_t const * | p_tx_buffer,
|  | uint8_t | tx_buffer_length,
|  | uint8_t * | p_rx_buffer,
|  | uint8_t | rx_buffer_length
| ) |  |

Function for starting the SPI data transfer.

If an event handler was provided in the nrf_drv_spi_init call, this function returns immediately and the handler is called when the transfer is done. Otherwise, the transfer is performed in blocking mode, which means that this function returns when the transfer is finished.

Note
  Peripherals using EasyDMA (for example, SPIM) require the transfer buffers to be placed in the Data RAM region. If they are not and an SPIM instance is used, this function will fail with the error code NRF_ERROR_INVALID_ADDR.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | p_tx_buffer | Pointer to the transmit buffer. Can be NULL if there is nothing to send.
  | tx_buffer_length | Length of the transmit buffer.
  [in] | p_rx_buffer | Pointer to the receive buffer. Can be NULL if there is nothing to receive.
  | rx_buffer_length | Length of the receive buffer.

Return values

  NRF_SUCCESS | If the operation was successful.
  NRF_ERROR_BUSY | If a previously started transfer has not finished yet.
  NRF_ERROR_INVALID_ADDR | If the provided buffers are not placed in the Data RAM region.

void nrf_drv_spi_uninit | ( | nrf_drv_spi_t const *const | p_instance | ) |

Function for uninitializing the SPI master driver instance.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

ret_code_t nrf_drv_spi_xfer | ( | nrf_drv_spi_t const *const | p_instance,
|  | nrf_drv_spi_xfer_desc_t const * | p_xfer_desc,
|  | uint32_t | flags
| ) |  |

Function for starting the SPI data transfer with additional option flags.

Function enables customizing the transfer by using option flags.

Additional options are provided using the flags parameter:

- NRF_DRV_SPI_FLAG_TX_POSTINC and NRF_DRV_SPI_FLAG_RX_POSTINC: Post-incrementation of buffer addresses. Supported only by SPIM.
- NRF_DRV_SPI_FLAG_HOLD_XFER: Driver is not starting the transfer. Use this flag if the transfer is triggered externally by PPI. Supported only by SPIM. Use nrf_drv_twi_start_task_get to get the address of the start task.
- NRF_DRV_SPI_FLAG_NO_XFER_EVT_HANDLER: No user event handler after transfer completion. This also means no interrupt at the end of the transfer. Supported only by SPIM. If NRF_DRV_SPI_FLAG_NO_XFER_EVT_HANDLER is used, the driver does not set the instance into busy state, so you must ensure that the next transfers are set up when SPIM is not active. nrf_drv_spi_end_event_get function can be used to detect end of transfer. Option can be used together with NRF_DRV_SPI_FLAG_REPEATED_XFER to prepare a sequence of SPI transfers without interruptions.
- NRF_DRV_SPI_FLAG_REPEATED_XFER: Prepare for repeated transfers. You can set up a number of transfers that will be triggered externally (for example by PPI). An example is a TXRX transfer with the options NRF_DRV_SPI_FLAG_RX_POSTINC, NRF_DRV_SPI_FLAG_NO_XFER_EVT_HANDLER, and NRF_DRV_SPI_FLAG_REPEATED_XFER. After the transfer is set up, a set of transfers can be triggered by PPI that will read, for example, the same register of an external component and put it into a RAM buffer without any interrupts. nrf_drv_spi_end_event_get can be used to get the address of the END event, which can be used to count the number of transfers. If NRF_DRV_SPI_FLAG_REPEATED_XFER is used, the driver does not set the instance into busy state, so you must ensure that the next transfers are set up when SPIM is not active. Supported only by SPIM.
  Note
    Function is intended to be used only in non-blocking mode.
  Parameters

    p_instance | Pointer to the driver instance structure.
    p_xfer_desc | Pointer to the transfer descriptor.
    flags | Transfer options (0 for default settings).

  Return values

    NRF_SUCCESS | If the procedure was successful.
    NRF_ERROR_BUSY | If the driver is not ready for a new transfer.
    NRF_ERROR_NOT_SUPPORTED | If the provided parameters are not supported.
    NRF_ERROR_INVALID_ADDR | If the provided buffers are not placed in the Data RAM region.