SPIM driver

group nrfx_spim

Serial Peripheral Interface Master with EasyDMA (SPIM) driver.

Defines

NRFX_SPIM_INSTANCE(id)

Macro for creating an instance of the SPIM driver.

NRFX_SPIM_DEFAULT_CONFIG(_pin_sck, _pin_mosi, _pin_miso, _pin_ss)

SPIM driver default configuration.

This configuration sets up SPIM with the following options:

  • SS pin active low

  • over-run character set to 0xFF

  • clock frequency: 4 MHz

  • mode: 0 (SCK active high, sample on leading edge of the clock signal)

  • MSB shifted out first

  • MISO pull-up disabled

Parameters:

  • _pin_sck – [in] SCK pin.

  • _pin_mosi – [in] MOSI pin.

  • _pin_miso – [in] MISO pin.

  • _pin_ss – [in] Slave select pin.

NRFX_SPIM_FREQUENCY_STATIC_CHECK(id, frequency)

Macro for checking whether specified frequency can be achieved for a given SPIM instance.

Note

This macro uses a compile-time assertion.

Parameters:

  • id – [in] Index of the specified SPIM instance.

  • frequency – [in] Desired frequency value in Hz.

NRFX_SPIM_FLAG_TX_POSTINC

Flag indicating that TX buffer address will be incremented after transfer.

NRFX_SPIM_FLAG_RX_POSTINC

Flag indicating that RX buffer address will be incremented after transfer.

NRFX_SPIM_FLAG_NO_XFER_EVT_HANDLER

Flag indicating that the interrupt after each transfer will be suppressed, and the event handler will not be called.

NRFX_SPIM_FLAG_HOLD_XFER

Flag indicating that the transfer will be set up, but not started.

NRFX_SPIM_FLAG_REPEATED_XFER

Flag indicating that the transfer will be executed multiple times.

NRFX_SPIM_SINGLE_XFER(p_tx, tx_len, p_rx, rx_len)

Macro for setting up single transfer descriptor.

This macro is for internal use only.

NRFX_SPIM_XFER_TRX(p_tx_buf, tx_length, p_rx_buf, rx_length)

Macro for setting the duplex TX RX transfer.

NRFX_SPIM_XFER_TX(p_buf, length)

Macro for setting the TX transfer.

NRFX_SPIM_XFER_RX(p_buf, length)

Macro for setting the RX transfer.

NRFX_SPIM_INST_HANDLER_GET(idx)

Macro returning SPIM interrupt handler.

param[in] idx SPIM index.

Returns:

Interrupt handler.

Typedefs

typedef nrfy_spim_xfer_desc_t nrfx_spim_xfer_desc_t

Single transfer descriptor structure.

typedef void (*nrfx_spim_evt_handler_t)(nrfx_spim_evt_t const *p_event, void *p_context)

SPIM driver event handler type.

Enums

enum nrfx_spim_evt_type_t

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

Values:

enumerator NRFX_SPIM_EVENT_DONE

Transfer done.

Functions

nrfx_err_t nrfx_spim_init(nrfx_spim_t const *p_instance, nrfx_spim_config_t const *p_config, nrfx_spim_evt_handler_t handler, void *p_context)

Function for initializing the SPIM driver instance.

This function configures and enables the specified peripheral.

Warning

On nRF5340, 32 MHz setting for SPIM4 peripheral instance is supported only on the dedicated pins with NRF_GPIO_PIN_SEL_PERIPHERAL configuration. See the chapter Pin assignments in the Product Specification.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

  • p_config – [in] Pointer to the structure with the initial configuration. NULL if configuration is to be skipped and will be done later using nrfx_spim_reconfigure.

  • handler – [in] Event handler provided by the user. If NULL, transfers will be performed in blocking mode.

  • p_context – [in] Context passed to event handler.

Return values:

  • NRFX_SUCCESS – Initialization was successful.

  • NRFX_ERROR_INVALID_STATE – The driver was already initialized.

  • NRFX_ERROR_BUSY – Some other peripheral with the same instance ID is already in use. This is possible only if Peripheral Resource Sharing (PRS) module is enabled.

  • NRFX_ERROR_NOT_SUPPORTED – Requested configuration is not supported by the SPIM instance.

  • NRFX_ERROR_INVALID_PARAM – Requested frequency is not available on the specified driver instance or pins.

  • NRFX_ERROR_FORBIDDEN – Software-controlled Slave Select and hardware-controlled Slave Select cannot be active at the same time.

nrfx_err_t nrfx_spim_reconfigure(nrfx_spim_t const *p_instance, nrfx_spim_config_t const *p_config)

Function for reconfiguring the SPIM driver instance.

Note

This function can not be called during transmission.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

  • p_config – [in] Pointer to the structure with the configuration.

Return values:

  • NRFX_SUCCESS – Reconfiguration was successful.

  • NRFX_ERROR_BUSY – The driver is during transfer.

  • NRFX_ERROR_INVALID_STATE – The driver is uninitialized.

  • NRFX_ERROR_NOT_SUPPORTED – Requested configuration is not supported by the SPIM instance.

  • NRFX_ERROR_INVALID_PARAM – Requested frequency is not available on the specified driver instance or pins.

  • NRFX_ERROR_FORBIDDEN – Software-controlled Slave Select and hardware-controlled Slave Select cannot be active at the same time.

void nrfx_spim_uninit(nrfx_spim_t const *p_instance)

Function for uninitializing the SPIM driver instance.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

nrfx_err_t nrfx_spim_xfer(nrfx_spim_t const *p_instance, nrfx_spim_xfer_desc_t const *p_xfer_desc, uint32_t flags)

Function for starting the SPIM data transfer.

Additional options are provided using the flags parameter:

Note

Peripherals using EasyDMA (including SPIM) require the transfer buffers to be placed in the Data RAM region. If this condition is not met, this function will fail with the error code NRFX_ERROR_INVALID_ADDR.

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:

  • NRFX_SUCCESS – The procedure is successful.

  • NRFX_ERROR_BUSY – The driver is not ready for a new transfer.

  • NRFX_ERROR_NOT_SUPPORTED – The provided parameters are not supported.

  • NRFX_ERROR_INVALID_ADDR – The provided buffers are not placed in the Data RAM region.

nrfx_err_t nrfx_spim_xfer_dcx(nrfx_spim_t const *p_instance, nrfx_spim_xfer_desc_t const *p_xfer_desc, uint32_t flags, uint8_t cmd_length)

Function for starting the SPIM data transfer with DCX control.

See nrfx_spim_xfer for description of additional options of transfer provided by the flags parameter.

Note

Peripherals that use EasyDMA (including SPIM) require the transfer buffers to be placed in the Data RAM region. If this condition is not met, this function will fail with the error code NRFX_ERROR_INVALID_ADDR.

Parameters:

  • p_instance – Pointer to the driver instance structure.

  • p_xfer_desc – Pointer to the transfer descriptor.

  • flags – Transfer options (0 for default settings).

  • cmd_length – Length of the command bytes preceding the data bytes. The DCX line will be low during transmission of command bytes and high during transmission of data bytes. Maximum value available for dividing the transmitted bytes into command bytes and data bytes is NRF_SPIM_DCX_CNT_ALL_CMD - 1. The NRF_SPIM_DCX_CNT_ALL_CMD value passed as the cmd_length parameter causes all transmitted bytes to be marked as command bytes.

Return values:

  • NRFX_SUCCESS – The procedure is successful.

  • NRFX_ERROR_BUSY – The driver is not ready for a new transfer.

  • NRFX_ERROR_NOT_SUPPORTED – The provided parameters are not supported.

  • NRFX_ERROR_INVALID_ADDR – The provided buffers are not placed in the Data RAM region.

NRFX_STATIC_INLINE uint32_t nrfx_spim_start_task_address_get(nrfx_spim_t const *p_instance)

Function for returning the address of a SPIM start task.

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

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

Returns:

Start task address.

NRFX_STATIC_INLINE uint32_t nrfx_spim_end_event_address_get(nrfx_spim_t const *p_instance)

Function for returning the address of a END SPIM event.

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

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

Returns:

END event address.

void nrfx_spim_abort(nrfx_spim_t const *p_instance)

Function for aborting ongoing transfer.

Note

You should call the function if the first transfer has been started with one or more of the following options: NRFX_SPIM_FLAG_NO_XFER_EVT_HANDLER, NRFX_SPIM_FLAG_HOLD_XFER, and NRFX_SPIM_FLAG_REPEATED_XFER. When you do not expect more transfers, use this function so that the driver can put the peripheral into a low power state.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

struct nrfx_spim_t
#include <nrfx_spim.h>

Data structure of the Serial Peripheral Interface Master with EasyDMA (SPIM) driver instance.

Public Members

NRF_SPIM_Type *p_reg

Pointer to a structure with SPIM registers.

uint8_t drv_inst_idx

Index of the driver instance. For internal use only.

struct nrfx_spim_config_t
#include <nrfx_spim.h>

Configuration structure of the SPIM driver instance.

Public Members

uint32_t sck_pin

SCK pin number.

uint32_t mosi_pin

MOSI pin number (optional).

Set to NRF_SPIM_PIN_NOT_CONNECTED if this signal is not needed.

uint32_t miso_pin

MISO pin number (optional).

Set to NRF_SPIM_PIN_NOT_CONNECTED if this signal is not needed.

uint32_t ss_pin

Slave Select pin number (optional).

Set to NRF_SPIM_PIN_NOT_CONNECTED if this signal is not needed.

Note

Unlike the other fields that specify pin numbers, this one cannot be omitted when both GPIO configuration and pin selection are to be skipped but the signal is not controlled by hardware (the driver must then control it as a regular GPIO).

bool ss_active_high

Polarity of the Slave Select pin during transmission.

uint8_t irq_priority

Interrupt priority.

uint8_t orc

Overrun character.

This character is used when all bytes from the TX buffer are sent, but the transfer continues due to RX.

uint32_t frequency

SPIM frequency in Hz.

nrf_spim_mode_t mode

SPIM mode.

nrf_spim_bit_order_t bit_order

SPIM bit order.

nrf_gpio_pin_pull_t miso_pull

MISO pull up configuration.

uint32_t dcx_pin

D/CX pin number (optional).

uint8_t rx_delay

Sample delay for input serial data on MISO.

The value specifies the delay, in number of 64 MHz clock cycles (15.625 ns), from the the sampling edge of SCK (leading edge for CONFIG.CPHA = 0, trailing edge for CONFIG.CPHA = 1) until the input serial data is sampled.

bool use_hw_ss

Indication to use software or hardware controlled Slave Select pin.

uint8_t ss_duration

Slave Select duration before and after transmission.

Minimum duration between the edge of CSN and the edge of SCK. Also, minimum duration of CSN inactivity between transactions. The value is specified in number of 64 MHz clock cycles (15.625 ns). Supported only for hardware-controlled Slave Select.

bool skip_gpio_cfg

Skip GPIO configuration of pins.

When set to true, the driver does not modify any GPIO parameters of the used pins. Those parameters are supposed to be configured externally before the driver is initialized.

bool skip_psel_cfg

Skip pin selection configuration.

When set to true, the driver does not modify pin select registers in the peripheral. Those registers are supposed to be set up externally before the driver is initialized.

Note

When both GPIO configuration and pin selection are to be skipped, the structure fields that specify pins can be omitted, as they are ignored anyway. This does not apply to the ss_pin field, unless it is to be controlled by hardware.

struct nrfx_spim_evt_t
#include <nrfx_spim.h>

SPIM event description with transmission details.

Public Members

nrfx_spim_evt_type_t type

Event type.

nrfx_spim_xfer_desc_t xfer_desc

Transfer details.