QSPI driver

Quad Serial Peripheral Interface (QSPI) peripheral driver. More...

Modules
	QSPI peripheral driver configuration

Data Structures
struct	nrfx_qspi_config_t
	QSPI driver instance configuration structure. More...
struct	nrfx_qspi_evt_ext_erase_t
	QSPI driver erase event data. More...
struct	nrfx_qspi_evt_ext_xfer_t
	QSPI driver transfer event data. More...
struct	nrfx_qspi_evt_ext_t
	QSPI driver extended event structure. More...

Macros
#define	NRFX_QSPI_DEFAULT_CONFIG(_pin_sck, _pin_csn, _pin_io0, _pin_io1, _pin_io2, _pin_io3)
	QSPI instance default configuration.
#define	NRFX_QSPI_DEFAULT_CINSTR(opc, len)
	QSPI custom instruction helper with the default configuration.

Typedefs
typedef void(*	nrfx_qspi_handler_t) (nrfx_qspi_evt_t event, void *p_context)
	QSPI driver event handler type.

Enumerations
enum	nrfx_qspi_evt_t { NRFX_QSPI_EVENT_DONE }
	QSPI master driver event types, passed to the handler routine provided during initialization. More...
enum	nrfx_qspi_evt_ext_type_t {   NRFX_QSPI_EVENT_NONE ,   NRFX_QSPI_EVENT_WRITE_DONE ,   NRFX_QSPI_EVENT_READ_DONE ,   NRFX_QSPI_EVENT_ERASE_DONE }
	QSPI master driver extended event types, obtained using nrfx_qspi_event_extended_get() function. More...

Functions
nrfx_err_t	nrfx_qspi_init (nrfx_qspi_config_t const *p_config, nrfx_qspi_handler_t handler, void *p_context)
	Function for initializing the QSPI driver instance.
nrfx_err_t	nrfx_qspi_reconfigure (nrfx_qspi_config_t const *p_config)
	Function for reconfiguring the QSPI driver instance.
void	nrfx_qspi_uninit (void)
	Function for uninitializing the QSPI driver instance.
nrfx_err_t	nrfx_qspi_activate (bool wait)
	Function for activating the QSPI driver instance.
nrfx_err_t	nrfx_qspi_deactivate (void)
	Function for deactivating the QSPI driver instance.
bool	nrfx_qspi_init_check (void)
	Function for checking if the QSPI driver is initialized.
nrfx_err_t	nrfx_qspi_read (void *p_rx_buffer, size_t rx_buffer_length, uint32_t src_address)
	Function for reading data from the QSPI memory.
nrfx_err_t	nrfx_qspi_write (void const *p_tx_buffer, size_t tx_buffer_length, uint32_t dst_address)
	Function for writing data to QSPI memory.
nrfx_err_t	nrfx_qspi_erase (nrf_qspi_erase_len_t length, uint32_t start_address)
	Function for starting erasing of one memory block - 4KB, 64KB, or the whole chip.
nrfx_err_t	nrfx_qspi_chip_erase (void)
	Function for starting an erase operation of the whole chip.
nrfx_qspi_evt_ext_t const *	nrfx_qspi_event_extended_get (void)
	Function for getting the extended event associated with finished operation.
bool	nrfx_qspi_xfer_buffered_check (void)
	Function for checking whether any write or read data transfer is buffered.
nrfx_err_t	nrfx_qspi_mem_busy_check (void)
	Function for getting the current driver status and status byte of memory device with testing WIP (write in progress) bit.
void	nrfx_qspi_timeout_signal (void)
	Function for signaling premature operation timeout.
nrfx_err_t	nrfx_qspi_cinstr_xfer (nrf_qspi_cinstr_conf_t const *p_config, void const *p_tx_buffer, void *p_rx_buffer)
	Function for sending operation code, sending data, and receiving data from the memory device.
nrfx_err_t	nrfx_qspi_cinstr_quick_send (uint8_t opcode, nrf_qspi_cinstr_len_t length, void const *p_tx_buffer)
	Function for sending operation code and data to the memory device with simpler configuration.
nrfx_err_t	nrfx_qspi_lfm_start (nrf_qspi_cinstr_conf_t const *p_config)
	Function for starting the custom instruction long frame mode.
nrfx_err_t	nrfx_qspi_lfm_xfer (void const *p_tx_buffer, void *p_rx_buffer, size_t transfer_length, bool finalize)
	Function for sending and receiving data in the custom instruction long frame mode.
nrfx_err_t	nrfx_qspi_xip_encrypt (nrf_qspi_encryption_t const *p_config)
	Function for setting the XIP encryption.
nrfx_err_t	nrfx_qspi_dma_encrypt (nrf_qspi_encryption_t const *p_config)
	Function for setting the EasyDMA encryption.

Detailed Description

Quad Serial Peripheral Interface (QSPI) peripheral driver.

Macro Definition Documentation

NRFX_QSPI_DEFAULT_CINSTR

#define NRFX_QSPI_DEFAULT_CINSTR	(		opc,
			len
	)

Value:

{ \
 .opcode = (opc), \
 .length = (len), \
 .io2_level = false, \
 .io3_level = false, \
 .wipwait = false, \
 .wren = false \
}

QSPI custom instruction helper with the default configuration.

NRFX_QSPI_DEFAULT_CONFIG

#define NRFX_QSPI_DEFAULT_CONFIG	(		_pin_sck,
			_pin_csn,
			_pin_io0,
			_pin_io1,
			_pin_io2,
			_pin_io3
	)

Value:

{ \
 .xip_offset = 0, \
 .pins = { \
 .sck_pin = _pin_sck, \
 .csn_pin = _pin_csn, \
 .io0_pin = _pin_io0, \
 .io1_pin = _pin_io1, \
 .io2_pin = _pin_io2, \
 .io3_pin = _pin_io3 \
 }, \
 .prot_if = { \
 .readoc = NRF_QSPI_READOC_FASTREAD, \
 .writeoc = NRF_QSPI_WRITEOC_PP, \
 .addrmode = NRF_QSPI_ADDRMODE_24BIT, \
 .dpmconfig = false, \
 }, \
 .phy_if = { \
 .sck_delay = 0x05, \
 .dpmen = false, \
 .spi_mode = NRF_QSPI_MODE_0, \
 .sck_freq = NRF_QSPI_FREQ_DIV16, \
 }, \
 .timeout = 500, \
 .irq_priority = (uint8_t)NRFX_QSPI_DEFAULT_CONFIG_IRQ_PRIORITY, \
}

QSPI instance default configuration.

This configuration sets up QSPI with the following options:

• no offset for address in the external memory for Execute in Place operation
• single data line
• FAST_READ opcode for reading
• PP opcode for writing
• 24 bit addressing mode
• Deep Power-down disabled
• clock frequency: 2 MHz for nRF52 Series, 6 MHz for nRF53 Series
• SCK delay 5 clock ticks
• 500 milliseconds operation timeout
• mode 0 (data captured on the clock rising edge and transmitted on a falling edge. Clock base level is '0')

Parameters

[in]	_pin_sck	Pin for clock signal.
[in]	_pin_csn	Pin for chip select signal.
[in]	_pin_io0	Pin 0 for I/O data.
[in]	_pin_io1	Pin 1 for I/O data.
[in]	_pin_io2	Pin 2 for I/O data.
[in]	_pin_io3	Pin 3 for I/O data.

Enumeration Type Documentation

nrfx_qspi_evt_ext_type_t

enum nrfx_qspi_evt_ext_type_t

QSPI master driver extended event types, obtained using nrfx_qspi_event_extended_get() function.

Enumerator
NRFX_QSPI_EVENT_NONE	No event occurence.
NRFX_QSPI_EVENT_WRITE_DONE	Write done.
NRFX_QSPI_EVENT_READ_DONE	Read done.
NRFX_QSPI_EVENT_ERASE_DONE	Erase done.

nrfx_qspi_evt_t

enum nrfx_qspi_evt_t

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

Enumerator
NRFX_QSPI_EVENT_DONE	Transfer done.

Function Documentation

nrfx_qspi_activate()

nrfx_err_t nrfx_qspi_activate

(

bool

wait

)

Function for activating the QSPI driver instance.

Parameters

[in]

wait

True if activation is to be in blocking mode, false otherwise.

Return values

NRFX_SUCCESS	The driver instance has been activated.
NRFX_ERROR_ALREADY	The driver is already activated.
NRFX_ERROR_TIMEOUT	External memory is busy, or there are connection issues.

nrfx_qspi_chip_erase()

nrfx_err_t nrfx_qspi_chip_erase

(

void

)

Function for starting an erase operation of the whole chip.

Note

Refer to the note for nrfx_qspi_read.

Return values

NRFX_SUCCESS	The operation was successful (blocking mode) or commissioned (handler mode).
NRFX_ERROR_BUSY	The driver currently is handling another operation.
NRFX_ERROR_TIMEOUT	The external memory is busy, or there are connection issues.

nrfx_qspi_cinstr_quick_send()

nrfx_err_t nrfx_qspi_cinstr_quick_send	(	uint8_t	opcode,
		nrf_qspi_cinstr_len_t	length,
		void const *	p_tx_buffer
	)

Function for sending operation code and data to the memory device with simpler configuration.

Note

Refer to the note for nrfx_qspi_read.

Use this function to transfer configuration data to memory and to receive data from memory. This function is a synchronous function and should be used only if necessary.

Parameters

[in]	opcode	Operation code. Sending first.
[in]	length	Length of the data to send and opcode. See nrf_qspi_cinstr_len_t.
[in]	p_tx_buffer	Pointer to input data array.

Return values

NRFX_SUCCESS	The operation was successful.
NRFX_ERROR_BUSY	The driver currently handles another operation.
NRFX_ERROR_TIMEOUT	The external memory is busy, or there are connection issues.

nrfx_qspi_cinstr_xfer()

nrfx_err_t nrfx_qspi_cinstr_xfer	(	nrf_qspi_cinstr_conf_t const *	p_config,
		void const *	p_tx_buffer,
		void *	p_rx_buffer
	)

Function for sending operation code, sending data, and receiving data from the memory device.

Note

Refer to the note for nrfx_qspi_read.

Use this function to transfer configuration data to memory and to receive data from memory. Pointers can be addresses from flash memory. This function is a synchronous function and should be used only if necessary.

Note

Please note that the NRFX_QSPI_DEFAULT_CINSTR macro provides default values for the io2_level and io3_level fields that cause the IO2 and IO3 lines to be kept low during the custom instruction transfer. Such configuration may not be suitable in certain circumstances and memory devices can interpret such levels of those lines as active WP# and HOLD#/RESET# signals, respectively. Hence, it is safer to use a configuration that will keep the lines high during the transfer.

Parameters

[in]	p_config	Pointer to the structure with opcode and transfer configuration.
[in]	p_tx_buffer	Pointer to the array with data to send. Can be NULL if only opcode is transmitted.
[out]	p_rx_buffer	Pointer to the array for data to receive. Can be NULL if there is nothing to receive.

Return values

NRFX_SUCCESS	The operation was successful.
NRFX_ERROR_TIMEOUT	The external memory is busy, or there are connection issues.
NRFX_ERROR_BUSY	The driver currently handles other operation.

nrfx_qspi_deactivate()

nrfx_err_t nrfx_qspi_deactivate

(

void

)

Function for deactivating the QSPI driver instance.

Note

If a custom instruction long transfer is ongoing when the function is called, the transfer will be interrupted.

Return values

NRFX_SUCCESS	The driver instance has been activated.
NRFX_ERROR_BUSY	The driver is during transaction.

nrfx_qspi_dma_encrypt()

nrfx_err_t nrfx_qspi_dma_encrypt

(

nrf_qspi_encryption_t const *

p_config

)

Function for setting the EasyDMA encryption.

Parameters

[in]

p_config

DMA encryption configuration structure. To disable encryption, pass NULL pointer as argument.

Return values

NRFX_SUCCESS	Operation was successful.
NRFX_ERROR_BUSY	Driver currently handles other operation.

nrfx_qspi_erase()

nrfx_err_t nrfx_qspi_erase	(	nrf_qspi_erase_len_t	length,
		uint32_t	start_address
	)

Function for starting erasing of one memory block - 4KB, 64KB, or the whole chip.

Note

Refer to the note for nrfx_qspi_read.

Write, read, and erase operations check memory device busy state before starting the operation. If the memory is busy, the resulting action depends on the mode in which the erase operation is used:

• blocking mode (without handler) - a delay occurs until the last operation runs or until the operation data is being sent.
• interrupt mode (with handler) - event emission occurs after the last operation and sending of operation data are finished. To manually control operation execution in the memory device, use nrfx_qspi_mem_busy_check after executing the erase function. Remember that an incoming event signalizes only that data was sent to the memory device and the periheral before the erase operation checked if memory was busy.

Parameters

[in]	length	Size of data to erase. See nrf_qspi_erase_len_t.
[in]	start_address	Memory address to start erasing. If chip erase is performed, address field is ommited.

Return values

NRFX_SUCCESS	The operation was successful (blocking mode) or operation was commissioned (handler mode).
NRFX_ERROR_BUSY	The driver currently handles another operation.
NRFX_ERROR_TIMEOUT	The external memory is busy, or there are connection issues.
NRFX_ERROR_INVALID_ADDR	The provided start address is not aligned to a 32-bit word.

nrfx_qspi_event_extended_get()

nrfx_qspi_evt_ext_t const * nrfx_qspi_event_extended_get

(

void

)

Function for getting the extended event associated with finished operation.

Returns

Pointer to the extended event associated with finished operation.

nrfx_qspi_init()

nrfx_err_t nrfx_qspi_init	(	nrfx_qspi_config_t const *	p_config,
		nrfx_qspi_handler_t	handler,
		void *	p_context
	)

Function for initializing the QSPI driver instance.

This function configures the peripheral and its interrupts.

Note

The function does not activate the peripheral instance. The activation is done during the first transfer after initialization or when calling nrfx_qspi_activate function. The activation process starts the internal clocks, and the QSPI peripheral tries to read the status byte to check the busy bit. Reading the status byte is done in a simple poll and wait mechanism. If the busy bit is set, this indicates issues with the external memory device. As a result, transfer functions return NRFX_ERROR_TIMEOUT.

In case of issues:

• Check the connection.
• Make sure that the memory device does not perform other operations like erasing or writing.
• Check if there is a short circuit.

Parameters

[in]	p_config	Pointer to the structure with the initial configuration.
[in]	handler	Event handler provided by the user. If NULL, transfers will be performed in blocking mode.
[in]	p_context	Pointer to context. Use in the interrupt handler.

Warning

On nRF5340, only the dedicated pins with NRF_GPIO_PIN_SEL_PERIPHERAL configuration are supported. See the chapter Pin assignments in the Product Specification.

Return values

NRFX_SUCCESS	Initialization was successful.
NRFX_ERROR_ALREADY	The driver is already initialized.
NRFX_ERROR_INVALID_STATE	The driver is already initialized. Deprecated - use NRFX_ERROR_ALREADY instead.
NRFX_ERROR_INVALID_PARAM	The pin configuration was incorrect.

nrfx_qspi_init_check()

bool nrfx_qspi_init_check

(

void

)

Function for checking if the QSPI driver is initialized.

Return values

true	Driver is already initialized.
false	Driver is not initialized.

nrfx_qspi_lfm_start()

nrfx_err_t nrfx_qspi_lfm_start

(

nrf_qspi_cinstr_conf_t const *

p_config

)

Function for starting the custom instruction long frame mode.

Note

Refer to the note for nrfx_qspi_read.

The long frame mode is a mechanism that allows for arbitrary byte length custom instructions. Use this function to initiate a custom transaction by sending custom instruction opcode. To send and receive data, use nrfx_qspi_lfm_xfer.

Note

Please note that the NRFX_QSPI_DEFAULT_CINSTR macro provides default values for the io2_level and io3_level fields that cause the IO2 and IO3 lines to be kept low during the custom instruction transfer. Such configuration may not be suitable in certain circumstances and memory devices can interpret such levels of those lines as active WP# and HOLD#/RESET# signals, respectively. Hence, it is safer to use a configuration that will keep the lines high during the transfer.

Parameters

[in]

p_config

Pointer to the structure with custom instruction opcode and transfer configuration. Transfer length must be set to NRF_QSPI_CINSTR_LEN_1B.

Return values

NRFX_SUCCESS	Operation was successful.
NRFX_ERROR_BUSY	Driver currently handles other operation.
NRFX_ERROR_TIMEOUT	The external memory is busy, or there are connection issues.

nrfx_qspi_lfm_xfer()

nrfx_err_t nrfx_qspi_lfm_xfer	(	void const *	p_tx_buffer,
		void *	p_rx_buffer,
		size_t	transfer_length,
		bool	finalize
	)

Function for sending and receiving data in the custom instruction long frame mode.

Note

Refer to the note for nrfx_qspi_read.

Both specified buffers must be at least transfer_length bytes in size.

Parameters

[in]	p_tx_buffer	Pointer to the array with data to send. Can be NULL if there is nothing to send.
[out]	p_rx_buffer	Pointer to the array for receiving data. Can be NULL if there is nothing to receive.
[in]	transfer_length	Number of bytes to send and receive.
[in]	finalize	True if custom instruction long frame mode is to be finalized after this transfer.

Return values

NRFX_SUCCESS	Operation was successful.
NRFX_ERROR_TIMEOUT	External memory is busy or there are connection issues. Long frame mode becomes deactivated.

nrfx_qspi_mem_busy_check()

nrfx_err_t nrfx_qspi_mem_busy_check

(

void

)

Function for getting the current driver status and status byte of memory device with testing WIP (write in progress) bit.

Return values

NRFX_SUCCESS	The driver and memory are ready to handle a new operation.
NRFX_ERROR_BUSY	The driver currently is handling another operation.

nrfx_qspi_read()

nrfx_err_t nrfx_qspi_read	(	void *	p_rx_buffer,
		size_t	rx_buffer_length,
		uint32_t	src_address
	)

Function for reading data from the QSPI memory.

Note

If that is the first operation after activation of driver initialization has been triggered, the activation process starts the internal clocks and the QSPI peripheral tries to read the status byte to check the busy bit. Reading the status byte is done in a simple poll and wait mechanism. If the busy bit is set, this indicates that the memory may not be ready yet. As a result, the function returns NRFX_ERROR_TIMEOUT.

Write, read, and erase operations check memory device busy state before starting the operation. If the memory is busy, the resulting action depends on the mode in which the read operation is used:

• blocking mode (without handler) - a delay occurs until the last operation runs and until the operation data is being read.
• interrupt mode (with handler) - event emission occurs after the last operation and reading of data are finished. In interrupt mode read operations can be double-buffered by calling the function again. To utilize double-buffering feature, NRF_QSPI_TASK_READSTART needs to be triggered on NRF_QSPI_EVENT_READY externally (for example by using the PPI/DPPI).

Parameters

[out]	p_rx_buffer	Pointer to the receive buffer.
[in]	rx_buffer_length	Size of the data to read.
[in]	src_address	Address in memory to read from.

Return values

NRFX_SUCCESS	The operation was successful (blocking mode) or operation was commissioned (handler mode).
NRFX_ERROR_BUSY	The driver currently handles another operation.
NRFX_ERROR_TIMEOUT	The external memory is busy, or there are connection issues.
NRFX_ERROR_INVALID_ADDR	The provided buffer is not placed in the Data RAM region or its address is not aligned to a 32-bit word.

nrfx_qspi_reconfigure()

nrfx_err_t nrfx_qspi_reconfigure

(

nrfx_qspi_config_t const *

p_config

)

Function for reconfiguring the QSPI driver instance.

Parameters

[in]

p_config

Pointer to the structure with the configuration.

Warning

The function deactivates the peripheral instance. The activation is done during the first transfer after reconfiguration or when calling nrfx_qspi_activate function.

Return values

NRFX_SUCCESS	Reconfiguration was successful.
NRFX_ERROR_BUSY	The driver is during transaction.
NRFX_ERROR_TIMEOUT	External memory is busy or there are connection issues.
NRFX_ERROR_INVALID_STATE	The driver is uninitialized.
NRFX_ERROR_INVALID_PARAM	The pin configuration was incorrect.

nrfx_qspi_timeout_signal()

void nrfx_qspi_timeout_signal

(

void

)

Function for signaling premature operation timeout.

The function provides a mechanism that can cause premature timeout when the driver is waiting for the READY event. This allows to use external source of the timeout. If the driver is initialized with a handler, it will not process the event generated for the transfer.

nrfx_qspi_uninit()

void nrfx_qspi_uninit

(

void

)

Function for uninitializing the QSPI driver instance.

Note

If a custom instruction long transfer is ongoing when the function is called, the transfer will be interrupted.

nrfx_qspi_write()

nrfx_err_t nrfx_qspi_write	(	void const *	p_tx_buffer,
		size_t	tx_buffer_length,
		uint32_t	dst_address
	)

Function for writing data to QSPI memory.

Note

Refer to the note for nrfx_qspi_read.

Write, read, and erase operations check memory device busy state before starting the operation. If the memory is busy, the resulting action depends on the mode in which the write operation is used:

• blocking mode (without handler) - a delay occurs until the last operation runs or until the operation data is being sent.
• interrupt mode (with handler) - event emission occurs after the last operation and sending of operation data are finished. To manually control operation execution in the memory device, use nrfx_qspi_mem_busy_check after executing the write function. Remember that an incoming event signalizes only that data was sent to the memory device and the peripheral before the write operation checked if memory was busy. In interrupt mode write operations can be double-buffered by calling the function again. To utilize double-buffering feature, NRF_QSPI_TASK_WRITESTART needs to be triggered on NRF_QSPI_EVENT_READY externally (for example by using the PPI/DPPI).

Parameters

[in]	p_tx_buffer	Pointer to the writing buffer.
[in]	tx_buffer_length	Size of the data to write.
[in]	dst_address	Address in memory to write to.

Return values

NRFX_SUCCESS	The operation was successful (blocking mode) or operation was commissioned (handler mode).
NRFX_ERROR_BUSY	The driver currently handles other operation.
NRFX_ERROR_TIMEOUT	The external memory is busy, or there are connection issues.
NRFX_ERROR_INVALID_ADDR	The provided buffer is not placed in the Data RAM region or its address is not aligned to a 32-bit word.

nrfx_qspi_xfer_buffered_check()

bool nrfx_qspi_xfer_buffered_check

(

void

)

Function for checking whether any write or read data transfer is buffered.

Returns

True if there is a transfer buffered, false otherwise.

nrfx_qspi_xip_encrypt()

nrfx_err_t nrfx_qspi_xip_encrypt

(

nrf_qspi_encryption_t const *

p_config

)

Function for setting the XIP encryption.

Parameters

[in]

p_config

XIP encryption configuration structure. To disable encryption, pass NULL pointer as argument.

Return values

NRFX_SUCCESS	Operation was successful.
NRFX_ERROR_BUSY	Driver currently handles other operation.