Wrapper around the nRF52 QSPI peripheral. More...

#include <nrfcxx/periph.hpp>

Data Structures
struct	configuration_type
	Configuration parameters for QSPI peripheral. More...

Public Types
using	mutex_type = mutex_irq< QSPI_IRQn >
	An RAII type for mutex access to state that must be protected from QSPI interrupts.

using	offset_type = unsigned int
	Unsigned type specifying flash memory addresses.

using	size_type = unsigned int
	Unsigned type holding size of transfers.

using	ssize_type = int
	Signed type holding transfer sizes or error codes.

Public Member Functions
	QSPI (const configuration_type &configuration)
	Construct a new QSPI interface. More...

const configuration_type &	configuration () const
	Reference the QSPI configuration provided on construction.

uint8_t	latest_sr () const
	Return the most recent cached flash device status register value. More...

int	read_sr () const
	Read the current device status register value. More...

bool	is_qspi_available () const
	Determine whether the QSPI peripheral is available for new commands. More...

bool	is_write_complete (int sr) const
	Test a status register value for completion of all write activities. More...

bool	is_powerdown () const
	Returns the peripheral flag value indicating whether the device is in deep power-down mode. More...

bool	is_ready () const
	Returns the isolated peripheral flag value indicating whether the device is ready to receive new tasks or mode transisions. More...

ssize_t	read (offset_type addr, void *dest, size_type count)
	Read data from the device at a specified address. More...

ssize_t	write (offset_type addr, const void *src, size_type count)
	Write data to the device at a specified address. More...

int	erase (uint8_t type, offset_type addr=-1)
	Initiate an erase of a single flash storage item. More...

unsigned int	jedec_id () const
	Return the JEDEC ID cached on the first activation of the instance. More...

bool	is_activated () const
	Test whether this instance is already activated.

bool	is_owner () const
	Test whether this instance has control of the QSPI peripheral.

int	claim ()
	Attempt to claim use of the QSPI peripheral. More...

int	release ()
	Release the QSPI peripheral if held by this instance. More...

int	activate ()
	Activate the QSPI peripheral to interact with this device. More...

int	deactivate ()
	Deactivate the QSPI peripheral. More...

Static Public Member Functions
static constexpr unsigned int	convert_us_dpmdur (unsigned int dur_us)
	Convert a duration expressed in microseconds to the units of the DPMDUR register. More...

static QSPI *	owner ()
	Get a pointer to the instance that owns the QSPI peripheral.

Static Public Attributes
static constexpr uint8_t	SR_WIP = 0x01
	Bit flag for status register write-in-progress bit.

static constexpr uint8_t	SR_WEL = 0x02
	Bit flag for status register write-enable-latch bit.

static constexpr uint8_t	SR_BP0 = 0x04
	Bit flag for status register protected area block bit 0.

static constexpr uint8_t	SR_BP1 = 0x08
	Bit flag for status register protected area block bit 1.

static constexpr uint8_t	SR_BP2 = 0x10
	Bit flag for status register protected area block bit 2.

static constexpr uint8_t	SR_BP3 = 0x20
	Bit flag for status register protected area block bit 3.

static constexpr uint8_t	SR_QE = 0x40
	Bit flag for status register quad-enabled bit.

static constexpr uint8_t	SR_SWRD = 0x80
	Bit flag for status register write protect bit. More...

static constexpr auto	ERASE_4_KB = static_cast<uint8_t>(QSPI_ERASE_LEN_LEN_4KB) << QSPI_ERASE_LEN_LEN_Pos
	Flag value denoting intent to erase a single 4 KiBy sector. More...

static constexpr auto	ERASE_64_KB = static_cast<uint8_t>(QSPI_ERASE_LEN_LEN_64KB) << QSPI_ERASE_LEN_LEN_Pos
	Flag value denoting intent to erase a single 64 KiBy block. More...

static constexpr auto	ERASE_CHIP = static_cast<uint8_t>(QSPI_ERASE_LEN_LEN_All) << QSPI_ERASE_LEN_LEN_Pos
	Flag value denoting intent to erase the entire chip. More...

Detailed Description

Wrapper around the nRF52 QSPI peripheral.

There is only one QSPI peripheral, but it may be associated with multiple flash devices each of which is controlled through an instance of this class. At most one instance may be in use (claimed) at any time.

The implementation supports deep power-down mode and 24-bit addressing.

Constructor & Destructor Documentation

◆ QSPI()

nrfcxx::periph::QSPI::QSPI ( const configuration_type & configuration )

Construct a new QSPI interface.

Warning: An attempt to create an instance with an invalid configuration will produce FailsafeCode::API_VIOLATION.; An attempt to create an instance when the QSPI peripheral is associated with another instance will produce FailsafeCode::API_VIOLATION.; The provided configuration must be persistent and unmodified for the lifespan of the instance.

Parameters

configuration how to talk to the device. A reference to the passed object is retained by the constructed instance.

Member Function Documentation

◆ activate()

int nrfcxx::periph::QSPI::activate ( )

Activate the QSPI peripheral to interact with this device.

Activation ensures the device is not in deep powerdown mode, that the device is configured for SR_QE if the peripheral requires quad I/O signals, and that the QSPI STATUS register is current. On the first activation the JEDEC ID is collected.

◆ claim()

int nrfcxx::periph::QSPI::claim ( )

Attempt to claim use of the QSPI peripheral.

This configures the peripheral to support this device, and enables it. It does not activate it.

There is no power consumption penalty for having QSPI configured and enabled, only for having it activated.

Return values

Zero	on success
-EBUSY	if another instance owns the peripheral

◆ convert_us_dpmdur()

static constexpr unsigned int nrfcxx::periph::QSPI::convert_us_dpmdur ( unsigned int dur_us )

inlinestaticconstexpr

Convert a duration expressed in microseconds to the units of the DPMDUR register.

DPMDUR expresses durations in multiples of 256 * 62.5 ns, or 16 us. This function rounds up to nearest integral duration that is not less than the provided value.

Parameters

dur_us the duration of a deep power-down mode transition, in microseconds.

Returns: that same duration in the representation of DPMDUR.

◆ deactivate()

int nrfcxx::periph::QSPI::deactivate ( )

Deactivate the QSPI peripheral.

Deactivation includes putting the controlled device in to deep power-down mode (if supported), and deactivating the QSPI peripheral. The peripheral remains enabled until release() is invoked.

◆ erase()

int nrfcxx::periph::QSPI::erase	(	uint8_t	type,
		offset_type	addr = `-1`
	)

Initiate an erase of a single flash storage item.

Note: Erase takes significant amounts of time, possibly measured in seconds. This call returns as soon as the erase has request has been initiated. Use is_write_complete() to detect when the erase completes.

Parameters

type	one of ERASE_4_KB, ERASE_64_KB, or ERASE_CHIP. Other values are rejected.
addr	an offset within the flash consistent with the value passed to `type`.

Return values

0	on successful initiation
-EINVAL	if this instance doesn't own the peripheral, or `addr` is inconsistent with `type`.
-EBADF	if the instance is not activated..
-EBUSY	if this instance is actively using the peripheral.

◆ is_powerdown()

bool nrfcxx::periph::QSPI::is_powerdown ( ) const

inline

Returns the peripheral flag value indicating whether the device is in deep power-down mode.

Note: The state of this flag is not valid unless the device is currently active.

See also: is_qspi_available()

◆ is_qspi_available()

bool nrfcxx::periph::QSPI::is_qspi_available ( ) const

inline

Determine whether the QSPI peripheral is available for new commands.

This checks that the STATUS.READY field is marked READY, and the STATUS.DPM field is marked Disabled.

◆ is_ready()

bool nrfcxx::periph::QSPI::is_ready ( ) const

inline

Returns the isolated peripheral flag value indicating whether the device is ready to receive new tasks or mode transisions.

See also: is_qspi_available()

◆ is_write_complete()

bool nrfcxx::periph::QSPI::is_write_complete ( int sr ) const

inline

Test a status register value for completion of all write activities.

Although write() is (currently) synchronous, erase() is asynchronous. Use this function to test whether a requested operation has completed.

Parameters

sr	the status register value to check. If the passed value is negative, `false` will be returned, allowing defined behavior when passing the unchecked return value of read_sr().

Returns: true iff sr is a valid status for which SR_WIP and SR_WEL are cleared.

◆ jedec_id()

unsigned int nrfcxx::periph::QSPI::jedec_id ( ) const

inline

Return the JEDEC ID cached on the first activation of the instance.

This is a standard unsigned integer embedding the JEDEC manufacturer ID in bits 16..23, and a manufacturer-specific device id in bits 0..15.

◆ latest_sr()

uint8_t nrfcxx::periph::QSPI::latest_sr ( ) const

inline

Return the most recent cached flash device status register value.

Note: The value may be not be fresh.

◆ read()

ssize_t nrfcxx::periph::QSPI::read	(	offset_type	addr,
		void *	dest,
		size_type	count
	)

Read data from the device at a specified address.

Parameters

addr	the offset within the flash device from which data will be read.
dest	the RAM location into which data will be stored.
count	the number of bytes to read from the device.

Return values

count	if the read succeeds.
-EINVAL	if this instance doesn't own the peripheral.
-EBADF	if the instance is not activated..
-EBUSY	if this instance is actively using the peripheral.

◆ read_sr()

int nrfcxx::periph::QSPI::read_sr ( ) const

Read the current device status register value.

Return values

non-negative	the device SR value.
-EINVAL	if the instance does not have control of the QSPI peripheral.
-EBUSY	if the instance is not in a state supporting new commands.

◆ release()

int nrfcxx::periph::QSPI::release ( )

Release the QSPI peripheral if held by this instance.

This deactivates and disables the QSPI peripheral, making it available for subsequent claim() attempts.

Return values

Zero	on success
-EINVAL	if this instance doesn't own the peripheral
-EBUSY	if this instance is actively using the peripheral.

◆ write()

ssize_t nrfcxx::periph::QSPI::write	(	offset_type	addr,
		const void *	src,
		size_type	count
	)

Write data to the device at a specified address.

Note: It is the caller's responsibility to ensure that the flash area that will be written is adequately erased.

Warning: At this time this call is synchronous: it will not return until the write has completed, which may take some significant amount of time (roughly 1.5 ms per KiBy at 32 MHz). The call will not return until the device has completed the write (is_write_complete() will succeed).

Parameters

addr	the offset within the flash device at which data will be written.
dest	the RAM location from which data will be transferred.
count	the number of bytes to write to the device.

Return values

count	if the write succeeds.
-EINVAL	if this instance doesn't own the peripheral.
-EBADF	if the instance is not activated..
-EBUSY	if this instance is actively using the peripheral.

Field Documentation

◆ ERASE_4_KB

constexpr auto nrfcxx::periph::QSPI::ERASE_4_KB = static_cast<uint8_t>(QSPI_ERASE_LEN_LEN_4KB) << QSPI_ERASE_LEN_LEN_Pos

staticconstexpr

Flag value denoting intent to erase a single 4 KiBy sector.

Passed to the type argument of erase(). The corresponding addr argument must be aligned to a 4 KiBy boundary.

◆ ERASE_64_KB

constexpr auto nrfcxx::periph::QSPI::ERASE_64_KB = static_cast<uint8_t>(QSPI_ERASE_LEN_LEN_64KB) << QSPI_ERASE_LEN_LEN_Pos

staticconstexpr

Flag value denoting intent to erase a single 64 KiBy block.

Passed to the type argument of erase(). The corresponding addr argument must be aligned to a 64 KiBy boundary.

◆ ERASE_CHIP

constexpr auto nrfcxx::periph::QSPI::ERASE_CHIP = static_cast<uint8_t>(QSPI_ERASE_LEN_LEN_All) << QSPI_ERASE_LEN_LEN_Pos

staticconstexpr

Flag value denoting intent to erase the entire chip.

Passed to the type argument of erase(). The corresponding addr argument must be zero.

◆ SR_SWRD

constexpr uint8_t nrfcxx::periph::QSPI::SR_SWRD = 0x80

staticconstexpr

Bit flag for status register write protect bit.

Don't set this unless you're sure you'll never want to reconfigure the status register again.

The documentation for this class was generated from the following file:

nrfcxx/periph.hpp

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ QSPI()

Member Function Documentation

◆ activate()

◆ claim()

◆ convert_us_dpmdur()

◆ deactivate()

◆ erase()

◆ is_powerdown()

◆ is_qspi_available()

◆ is_ready()

◆ is_write_complete()

◆ jedec_id()

◆ latest_sr()

◆ read()

◆ read_sr()

◆ release()

◆ write()

Field Documentation

◆ ERASE_4_KB

◆ ERASE_64_KB

◆ ERASE_CHIP

◆ SR_SWRD