cfn_hal_qspi.h File Reference

Quad-SPI (QSPI / OSPI) HAL API. More...

#include "cfn_hal.h"
#include "cfn_hal_base.h"
#include "cfn_hal_gpio.h"
#include "cfn_hal_types.h"

Go to the source code of this file.

Data Structures
struct	cfn_hal_qspi_cmd_t
	QSPI command configuration. More...
struct	cfn_hal_qspi_config_t
	QSPI configuration structure. More...
struct	cfn_hal_qspi_phy_t
	QSPI hardware physical mapping. More...
struct	cfn_hal_qspi_api_s
	QSPI Virtual Method Table (VMT). More...

Typedefs
typedef struct cfn_hal_qspi_s	cfn_hal_qspi_t
typedef struct cfn_hal_qspi_api_s	cfn_hal_qspi_api_t
typedef void(*	cfn_hal_qspi_callback_t) (cfn_hal_qspi_t *driver, uint32_t event_mask, uint32_t error_mask, void *user_arg)
	QSPI callback signature.

Enumerations
enum	cfn_hal_qspi_event_t { CFN_HAL_QSPI_EVENT_NONE = 0 , CFN_HAL_QSPI_EVENT_TX_COMPLETE = CFN_HAL_BIT(0) , CFN_HAL_QSPI_EVENT_RX_READY = CFN_HAL_BIT(1) , CFN_HAL_QSPI_EVENT_CMD_DONE = CFN_HAL_BIT(2) }
	QSPI nominal event flags. More...
enum	cfn_hal_qspi_error_t { CFN_HAL_QSPI_ERROR_NONE = 0 , CFN_HAL_QSPI_ERROR_TIMEOUT = CFN_HAL_BIT(0) , CFN_HAL_QSPI_ERROR_GENERAL = CFN_HAL_BIT(1) }
	QSPI exception error flags. More...
enum	cfn_hal_qspi_bus_width_t { CFN_HAL_QSPI_BUS_WIDTH_NONE = 0 , CFN_HAL_QSPI_BUS_WIDTH_SINGLE = 1 , CFN_HAL_QSPI_BUS_WIDTH_DUAL = 2 , CFN_HAL_QSPI_BUS_WIDTH_QUAD = 3 }
	QSPI bus width modes. More...

Functions
	CFN_HAL_VMT_CHECK (struct cfn_hal_qspi_api_s)
	CFN_HAL_CREATE_DRIVER_TYPE (qspi, cfn_hal_qspi_config_t, cfn_hal_qspi_api_t, cfn_hal_qspi_phy_t, cfn_hal_qspi_callback_t)
CFN_HAL_INLINE void	cfn_hal_qspi_populate (cfn_hal_qspi_t *driver, uint32_t peripheral_id, struct cfn_hal_clock_s *clock, void *dependency, const cfn_hal_qspi_api_t *api, const cfn_hal_qspi_phy_t *phy, const cfn_hal_qspi_config_t *config, cfn_hal_qspi_callback_t callback, void *user_arg)
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_config_validate (const cfn_hal_qspi_t *driver, const cfn_hal_qspi_config_t *config)
	Validates the QSPI configuration.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_init (cfn_hal_qspi_t *driver)
	Initializes the QSPI driver.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_deinit (cfn_hal_qspi_t *driver)
	Deinitializes the QSPI driver.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_config_set (cfn_hal_qspi_t *driver, const cfn_hal_qspi_config_t *config)
	Sets the QSPI configuration.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_config_get (cfn_hal_qspi_t *driver, cfn_hal_qspi_config_t *config)
	Gets the current QSPI configuration.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_callback_register (cfn_hal_qspi_t *driver, const cfn_hal_qspi_callback_t callback, void *user_arg)
	Registers a callback for QSPI events and errors.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_power_state_set (cfn_hal_qspi_t *driver, cfn_hal_power_state_t state)
	Sets the QSPI power state.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_event_enable (cfn_hal_qspi_t *driver, uint32_t event_mask)
	Enables one or more QSPI nominal events.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_event_disable (cfn_hal_qspi_t *driver, uint32_t event_mask)
	Disables one or more QSPI nominal events.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_event_get (cfn_hal_qspi_t *driver, uint32_t *event_mask)
	Retrieves the current QSPI nominal event status.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_error_enable (cfn_hal_qspi_t *driver, uint32_t error_mask)
	Enables one or more QSPI exception errors.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_error_disable (cfn_hal_qspi_t *driver, uint32_t error_mask)
	Disables one or more QSPI exception errors.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_error_get (cfn_hal_qspi_t *driver, uint32_t *error_mask)
	Retrieves the current QSPI exception error status.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_command (cfn_hal_qspi_t *driver, const cfn_hal_qspi_cmd_t *cmd, uint32_t timeout)
	Sends a command sequence to the memory device.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_transmit (cfn_hal_qspi_t *driver, const uint8_t *data, uint32_t timeout)
	Transmits data following a command phase.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_receive (cfn_hal_qspi_t *driver, uint8_t *data, uint32_t timeout)
	Receives data following a command phase.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_memory_mapped_enable (cfn_hal_qspi_t *driver, const cfn_hal_qspi_cmd_t *cmd)
	Enables memory-mapped mode for direct CPU access.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_qspi_autopolling_enable (cfn_hal_qspi_t *driver, const cfn_hal_qspi_cmd_t *cmd, uint32_t match, uint32_t mask, uint32_t timeout)
	Configures autonomous polling of a memory status register.
cfn_hal_error_code_t	cfn_hal_qspi_construct (cfn_hal_qspi_t *driver, const cfn_hal_qspi_config_t *config, const cfn_hal_qspi_phy_t *phy, struct cfn_hal_clock_s *clock, void *dependency, cfn_hal_qspi_callback_t callback, void *user_arg)
cfn_hal_error_code_t	cfn_hal_qspi_destruct (cfn_hal_qspi_t *driver)

Detailed Description

Quad-SPI (QSPI / OSPI) HAL API.

Copyright (c) 2026 Hisham Moussa Daou https://www.whileone.me

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Typedef Documentation

cfn_hal_qspi_api_t

typedef struct cfn_hal_qspi_api_s cfn_hal_qspi_api_t

cfn_hal_qspi_callback_t

typedef void(* cfn_hal_qspi_callback_t) (cfn_hal_qspi_t *driver, uint32_t event_mask, uint32_t error_mask, void *user_arg)

QSPI callback signature.

Parameters

driver	Pointer to the QSPI driver instance.
event_mask	Mask of triggered nominal events.
error_mask	Mask of triggered exception errors.
user_arg	User-defined argument passed during registration.

cfn_hal_qspi_t

typedef struct cfn_hal_qspi_s cfn_hal_qspi_t

Enumeration Type Documentation

cfn_hal_qspi_bus_width_t

enum cfn_hal_qspi_bus_width_t

QSPI bus width modes.

Enumerator
CFN_HAL_QSPI_BUS_WIDTH_NONE
CFN_HAL_QSPI_BUS_WIDTH_SINGLE
CFN_HAL_QSPI_BUS_WIDTH_DUAL
CFN_HAL_QSPI_BUS_WIDTH_QUAD

cfn_hal_qspi_error_t

enum cfn_hal_qspi_error_t

QSPI exception error flags.

Enumerator
CFN_HAL_QSPI_ERROR_NONE
CFN_HAL_QSPI_ERROR_TIMEOUT	Peripheral or memory timeout
CFN_HAL_QSPI_ERROR_GENERAL	General hardware error

cfn_hal_qspi_event_t

enum cfn_hal_qspi_event_t

QSPI nominal event flags.

Enumerator
CFN_HAL_QSPI_EVENT_NONE
CFN_HAL_QSPI_EVENT_TX_COMPLETE	Data transmission finished
CFN_HAL_QSPI_EVENT_RX_READY	Data reception finished
CFN_HAL_QSPI_EVENT_CMD_DONE	Command phase complete

Function Documentation

CFN_HAL_CREATE_DRIVER_TYPE()

CFN_HAL_CREATE_DRIVER_TYPE	(	qspi	,
		cfn_hal_qspi_config_t	,
		cfn_hal_qspi_api_t	,
		cfn_hal_qspi_phy_t	,
		cfn_hal_qspi_callback_t
	)

cfn_hal_qspi_autopolling_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_autopolling_enable	(	cfn_hal_qspi_t *	driver,
		const cfn_hal_qspi_cmd_t *	cmd,
		uint32_t	match,
		uint32_t	mask,
		uint32_t	timeout
	)

Configures autonomous polling of a memory status register.

Parameters

driver	Pointer to the QSPI driver instance.
cmd	Pointer to the status register read command.
match	Value to wait for in the status register.
mask	Mask to apply to the read value before comparison.
timeout	Timeout duration in milliseconds.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_callback_register()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_callback_register	(	cfn_hal_qspi_t *	driver,
		const cfn_hal_qspi_callback_t	callback,
		void *	user_arg
	)

Registers a callback for QSPI events and errors.

Parameters

driver	Pointer to the QSPI driver instance.
callback	The callback function to register.
user_arg	User-defined argument passed to the callback.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_command()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_command	(	cfn_hal_qspi_t *	driver,
		const cfn_hal_qspi_cmd_t *	cmd,
		uint32_t	timeout
	)

Sends a command sequence to the memory device.

Parameters

driver	Pointer to the QSPI driver instance.
cmd	Pointer to the command configuration structure.
timeout	Timeout duration in milliseconds.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_config_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_config_get	(	cfn_hal_qspi_t *	driver,
		cfn_hal_qspi_config_t *	config
	)

Gets the current QSPI configuration.

Parameters

driver	Pointer to the QSPI driver instance.
config	[out] Pointer to store the configuration.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_config_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_config_set	(	cfn_hal_qspi_t *	driver,
		const cfn_hal_qspi_config_t *	config
	)

Sets the QSPI configuration.

Parameters

driver	Pointer to the QSPI driver instance.
config	Pointer to the configuration structure.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_config_validate()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_config_validate	(	const cfn_hal_qspi_t *	driver,
		const cfn_hal_qspi_config_t *	config
	)

Validates the QSPI configuration.

Parameters

driver	Pointer to the QSPI driver instance.
config	Pointer to the configuration structure.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_construct()

cfn_hal_error_code_t cfn_hal_qspi_construct	(	cfn_hal_qspi_t *	driver,
		const cfn_hal_qspi_config_t *	config,
		const cfn_hal_qspi_phy_t *	phy,
		struct cfn_hal_clock_s *	clock,
		void *	dependency,
		cfn_hal_qspi_callback_t	callback,
		void *	user_arg
	)

cfn_hal_qspi_deinit()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_deinit

(

cfn_hal_qspi_t *

driver

)

Deinitializes the QSPI driver.

Parameters

driver

Pointer to the QSPI driver instance.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_destruct()

cfn_hal_error_code_t cfn_hal_qspi_destruct

(

cfn_hal_qspi_t *

driver

)

cfn_hal_qspi_error_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_error_disable	(	cfn_hal_qspi_t *	driver,
		uint32_t	error_mask
	)

Disables one or more QSPI exception errors.

Parameters

driver	Pointer to the QSPI driver instance.
error_mask	Mask of errors to disable.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_error_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_error_enable	(	cfn_hal_qspi_t *	driver,
		uint32_t	error_mask
	)

Enables one or more QSPI exception errors.

Parameters

driver	Pointer to the QSPI driver instance.
error_mask	Mask of errors to enable.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_error_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_error_get	(	cfn_hal_qspi_t *	driver,
		uint32_t *	error_mask
	)

Retrieves the current QSPI exception error status.

Parameters

driver	Pointer to the QSPI driver instance.
error_mask	[out] Pointer to store the error mask.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_event_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_event_disable	(	cfn_hal_qspi_t *	driver,
		uint32_t	event_mask
	)

Disables one or more QSPI nominal events.

Parameters

driver	Pointer to the QSPI driver instance.
event_mask	Mask of events to disable.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_event_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_event_enable	(	cfn_hal_qspi_t *	driver,
		uint32_t	event_mask
	)

Enables one or more QSPI nominal events.

Parameters

driver	Pointer to the QSPI driver instance.
event_mask	Mask of events to enable.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_event_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_event_get	(	cfn_hal_qspi_t *	driver,
		uint32_t *	event_mask
	)

Retrieves the current QSPI nominal event status.

Parameters

driver	Pointer to the QSPI driver instance.
event_mask	[out] Pointer to store the event mask.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_init()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_init

(

cfn_hal_qspi_t *

driver

)

Initializes the QSPI driver.

Parameters

driver

Pointer to the QSPI driver instance.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_memory_mapped_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_memory_mapped_enable	(	cfn_hal_qspi_t *	driver,
		const cfn_hal_qspi_cmd_t *	cmd
	)

Enables memory-mapped mode for direct CPU access.

Parameters

driver	Pointer to the QSPI driver instance.
cmd	Pointer to the read command configuration.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_populate()

CFN_HAL_INLINE void cfn_hal_qspi_populate	(	cfn_hal_qspi_t *	driver,
		uint32_t	peripheral_id,
		struct cfn_hal_clock_s *	clock,
		void *	dependency,
		const cfn_hal_qspi_api_t *	api,
		const cfn_hal_qspi_phy_t *	phy,
		const cfn_hal_qspi_config_t *	config,
		cfn_hal_qspi_callback_t	callback,
		void *	user_arg
	)

cfn_hal_qspi_power_state_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_power_state_set	(	cfn_hal_qspi_t *	driver,
		cfn_hal_power_state_t	state
	)

Sets the QSPI power state.

Parameters

driver	Pointer to the QSPI driver instance.
state	Target power state.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_receive()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_receive	(	cfn_hal_qspi_t *	driver,
		uint8_t *	data,
		uint32_t	timeout
	)

Receives data following a command phase.

Parameters

driver	Pointer to the QSPI driver instance.
data	[out] Pointer to the buffer where received data will be stored.
timeout	Timeout duration in milliseconds.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_qspi_transmit()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_qspi_transmit	(	cfn_hal_qspi_t *	driver,
		const uint8_t *	data,
		uint32_t	timeout
	)

Transmits data following a command phase.

Parameters

driver	Pointer to the QSPI driver instance.
data	Pointer to the data to be sent.
timeout	Timeout duration in milliseconds.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

CFN_HAL_VMT_CHECK()

CFN_HAL_VMT_CHECK

(

struct cfn_hal_qspi_api_s

)