cfn_hal_spi.h File Reference

Serial Peripheral Interface (SPI) 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_spi_phy_t
	SPI hardware physical mapping. More...
struct	cfn_hal_spi_config_t
	SPI configuration structure. More...
struct	cfn_hal_spi_transaction_t
	SPI transaction configuration. More...
struct	cfn_hal_spi_device_t
	SPI Device addressing association. More...
struct	cfn_hal_spi_api_s
	SPI Virtual Method Table (VMT). More...

Typedefs
typedef struct cfn_hal_spi_s	cfn_hal_spi_t
typedef struct cfn_hal_spi_api_s	cfn_hal_spi_api_t
typedef void(*	cfn_hal_spi_callback_t) (cfn_hal_spi_t *driver, uint32_t event_mask, uint32_t error_mask, uint8_t *data, size_t nbr_of_bytes, void *user_arg)
	SPI callback signature.

Enumerations
enum	cfn_hal_spi_event_t { CFN_HAL_SPI_EVENT_NONE = 0 , CFN_HAL_SPI_EVENT_TX_COMPLETE = CFN_HAL_BIT(0) , CFN_HAL_SPI_EVENT_RX_READY = CFN_HAL_BIT(1) }
	SPI nominal event flags. More...
enum	cfn_hal_spi_error_t {   CFN_HAL_SPI_ERROR_NONE = 0 , CFN_HAL_SPI_ERROR_FRAMING = CFN_HAL_BIT(0) , CFN_HAL_SPI_ERROR_OVERRUN = CFN_HAL_BIT(1) , CFN_HAL_SPI_ERROR_CRC = CFN_HAL_BIT(2) ,   CFN_HAL_SPI_ERROR_GENERAL = CFN_HAL_BIT(3) }
	SPI exception error flags. More...
enum	cfn_hal_spi_config_format_t {   CFN_HAL_SPI_CONFIG_FMT_POL0_PHA0 , CFN_HAL_SPI_CONFIG_FMT_POL0_PHA1 , CFN_HAL_SPI_CONFIG_FMT_POL1_PHA0 , CFN_HAL_SPI_CONFIG_FMT_POL1_PHA1 ,   CFN_HAL_SPI_CONFIG_FMT_MAX }
	SPI clock phase and polarity formats. More...
enum	cfn_hal_spi_config_cs_mode_t { CFN_HAL_SPI_CONFIG_CS_USER_CONTROLLED , CFN_HAL_SPI_CONFIG_CS_HAL_CONTROLLED , CFN_HAL_SPI_CONFIG_CS_HW_CONTROLLED , CFN_HAL_SPI_CONFIG_CS_MAX }
	SPI Chip Select (CS) management modes. More...

Functions
	CFN_HAL_VMT_CHECK (struct cfn_hal_spi_api_s)
	CFN_HAL_CREATE_DRIVER_TYPE (spi, cfn_hal_spi_config_t, cfn_hal_spi_api_t, cfn_hal_spi_phy_t, cfn_hal_spi_callback_t)
CFN_HAL_INLINE void	cfn_hal_spi_populate (cfn_hal_spi_t *driver, uint32_t peripheral_id, struct cfn_hal_clock_s *clock, void *dependency, const cfn_hal_spi_api_t *api, const cfn_hal_spi_phy_t *phy, const cfn_hal_spi_config_t *config, cfn_hal_spi_callback_t callback, void *user_arg)
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_config_validate (const cfn_hal_spi_t *driver, const cfn_hal_spi_config_t *config)
	Validates the SPI configuration.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_init (cfn_hal_spi_t *driver)
	Initializes the SPI driver.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_deinit (cfn_hal_spi_t *driver)
	Deinitializes the SPI driver.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_config_set (cfn_hal_spi_t *driver, const cfn_hal_spi_config_t *config)
	Sets the SPI configuration.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_config_get (cfn_hal_spi_t *driver, cfn_hal_spi_config_t *config)
	Gets the current SPI configuration.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_callback_register (cfn_hal_spi_t *driver, const cfn_hal_spi_callback_t callback, void *user_arg)
	Registers a callback for SPI events and errors.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_power_state_set (cfn_hal_spi_t *driver, cfn_hal_power_state_t state)
	Sets the SPI power state.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_event_enable (cfn_hal_spi_t *driver, uint32_t event_mask)
	Enables one or more SPI nominal events.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_event_disable (cfn_hal_spi_t *driver, uint32_t event_mask)
	Disables one or more SPI nominal events.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_event_get (cfn_hal_spi_t *driver, uint32_t *event_mask)
	Retrieves the current SPI nominal event status.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_error_enable (cfn_hal_spi_t *driver, uint32_t error_mask)
	Enables one or more SPI exception errors.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_error_disable (cfn_hal_spi_t *driver, uint32_t error_mask)
	Disables one or more SPI exception errors.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_error_get (cfn_hal_spi_t *driver, uint32_t *error_mask)
	Retrieves the current SPI exception error status.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_xfr_irq (cfn_hal_spi_t *driver, const cfn_hal_spi_transaction_t *xfr)
	Starts an SPI transaction using interrupts (non-blocking).
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_xfr_irq_abort (cfn_hal_spi_t *driver)
	Aborts an ongoing non-blocking SPI transaction.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_xfr_polling (cfn_hal_spi_t *driver, const cfn_hal_spi_transaction_t *xfr, uint32_t timeout)
	Executes an SPI transaction using polling (blocking).
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_spi_xfr_dma (cfn_hal_spi_t *driver, const cfn_hal_spi_transaction_t *xfr)
	Starts an SPI transaction using DMA (non-blocking).
cfn_hal_error_code_t	cfn_hal_spi_construct (cfn_hal_spi_t *driver, const cfn_hal_spi_config_t *config, const cfn_hal_spi_phy_t *phy, struct cfn_hal_clock_s *clock, void *dependency, cfn_hal_spi_callback_t callback, void *user_arg)
cfn_hal_error_code_t	cfn_hal_spi_destruct (cfn_hal_spi_t *driver)

Detailed Description

Serial Peripheral Interface (SPI) 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_spi_api_t

typedef struct cfn_hal_spi_api_s cfn_hal_spi_api_t

cfn_hal_spi_callback_t

typedef void(* cfn_hal_spi_callback_t) (cfn_hal_spi_t *driver, uint32_t event_mask, uint32_t error_mask, uint8_t *data, size_t nbr_of_bytes, void *user_arg)

SPI callback signature.

Parameters

driver	Pointer to the SPI driver instance.
event_mask	Mask of triggered nominal events.
error_mask	Mask of triggered exception errors.
data	Pointer to the transaction buffer (if applicable).
nbr_of_bytes	Number of bytes transferred.
user_arg	User-defined argument passed during registration.

cfn_hal_spi_t

typedef struct cfn_hal_spi_s cfn_hal_spi_t

Enumeration Type Documentation

cfn_hal_spi_config_cs_mode_t

enum cfn_hal_spi_config_cs_mode_t

SPI Chip Select (CS) management modes.

Enumerator
CFN_HAL_SPI_CONFIG_CS_USER_CONTROLLED	CS toggled manually by application
CFN_HAL_SPI_CONFIG_CS_HAL_CONTROLLED	CS toggled by HAL during xfr
CFN_HAL_SPI_CONFIG_CS_HW_CONTROLLED	CS toggled by hardware peripheral
CFN_HAL_SPI_CONFIG_CS_MAX

cfn_hal_spi_config_format_t

enum cfn_hal_spi_config_format_t

SPI clock phase and polarity formats.

Enumerator
CFN_HAL_SPI_CONFIG_FMT_POL0_PHA0	CPOL=0, CPHA=0
CFN_HAL_SPI_CONFIG_FMT_POL0_PHA1	CPOL=0, CPHA=1
CFN_HAL_SPI_CONFIG_FMT_POL1_PHA0	CPOL=1, CPHA=0
CFN_HAL_SPI_CONFIG_FMT_POL1_PHA1	CPOL=1, CPHA=1
CFN_HAL_SPI_CONFIG_FMT_MAX

cfn_hal_spi_error_t

enum cfn_hal_spi_error_t

SPI exception error flags.

Enumerator
CFN_HAL_SPI_ERROR_NONE
CFN_HAL_SPI_ERROR_FRAMING	Frame synchronization error
CFN_HAL_SPI_ERROR_OVERRUN	Rx overrun or Tx underrun
CFN_HAL_SPI_ERROR_CRC	CRC checksum mismatch
CFN_HAL_SPI_ERROR_GENERAL	General hardware error

cfn_hal_spi_event_t

enum cfn_hal_spi_event_t

SPI nominal event flags.

Enumerator
CFN_HAL_SPI_EVENT_NONE
CFN_HAL_SPI_EVENT_TX_COMPLETE	Data transmission finished
CFN_HAL_SPI_EVENT_RX_READY	Data reception finished

Function Documentation

CFN_HAL_CREATE_DRIVER_TYPE()

CFN_HAL_CREATE_DRIVER_TYPE	(	spi	,
		cfn_hal_spi_config_t	,
		cfn_hal_spi_api_t	,
		cfn_hal_spi_phy_t	,
		cfn_hal_spi_callback_t
	)

cfn_hal_spi_callback_register()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_callback_register	(	cfn_hal_spi_t *	driver,
		const cfn_hal_spi_callback_t	callback,
		void *	user_arg
	)

Registers a callback for SPI events and errors.

Parameters

driver	Pointer to the SPI 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_spi_config_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_config_get	(	cfn_hal_spi_t *	driver,
		cfn_hal_spi_config_t *	config
	)

Gets the current SPI configuration.

Parameters

driver	Pointer to the SPI 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_spi_config_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_config_set	(	cfn_hal_spi_t *	driver,
		const cfn_hal_spi_config_t *	config
	)

Sets the SPI configuration.

Parameters

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

Returns

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

cfn_hal_spi_config_validate()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_config_validate	(	const cfn_hal_spi_t *	driver,
		const cfn_hal_spi_config_t *	config
	)

Validates the SPI configuration.

Parameters

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

Returns

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

cfn_hal_spi_construct()

cfn_hal_error_code_t cfn_hal_spi_construct	(	cfn_hal_spi_t *	driver,
		const cfn_hal_spi_config_t *	config,
		const cfn_hal_spi_phy_t *	phy,
		struct cfn_hal_clock_s *	clock,
		void *	dependency,
		cfn_hal_spi_callback_t	callback,
		void *	user_arg
	)

cfn_hal_spi_deinit()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_deinit

(

cfn_hal_spi_t *

driver

)

Deinitializes the SPI driver.

Parameters

driver

Pointer to the SPI driver instance.

Returns

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

cfn_hal_spi_destruct()

cfn_hal_error_code_t cfn_hal_spi_destruct

(

cfn_hal_spi_t *

driver

)

cfn_hal_spi_error_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_error_disable	(	cfn_hal_spi_t *	driver,
		uint32_t	error_mask
	)

Disables one or more SPI exception errors.

Parameters

driver	Pointer to the SPI 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_spi_error_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_error_enable	(	cfn_hal_spi_t *	driver,
		uint32_t	error_mask
	)

Enables one or more SPI exception errors.

Parameters

driver	Pointer to the SPI 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_spi_error_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_error_get	(	cfn_hal_spi_t *	driver,
		uint32_t *	error_mask
	)

Retrieves the current SPI exception error status.

Parameters

driver	Pointer to the SPI 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_spi_event_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_event_disable	(	cfn_hal_spi_t *	driver,
		uint32_t	event_mask
	)

Disables one or more SPI nominal events.

Parameters

driver	Pointer to the SPI 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_spi_event_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_event_enable	(	cfn_hal_spi_t *	driver,
		uint32_t	event_mask
	)

Enables one or more SPI nominal events.

Parameters

driver	Pointer to the SPI 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_spi_event_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_event_get	(	cfn_hal_spi_t *	driver,
		uint32_t *	event_mask
	)

Retrieves the current SPI nominal event status.

Parameters

driver	Pointer to the SPI 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_spi_init()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_init

(

cfn_hal_spi_t *

driver

)

Initializes the SPI driver.

Parameters

driver

Pointer to the SPI driver instance.

Returns

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

cfn_hal_spi_populate()

CFN_HAL_INLINE void cfn_hal_spi_populate	(	cfn_hal_spi_t *	driver,
		uint32_t	peripheral_id,
		struct cfn_hal_clock_s *	clock,
		void *	dependency,
		const cfn_hal_spi_api_t *	api,
		const cfn_hal_spi_phy_t *	phy,
		const cfn_hal_spi_config_t *	config,
		cfn_hal_spi_callback_t	callback,
		void *	user_arg
	)

cfn_hal_spi_power_state_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_power_state_set	(	cfn_hal_spi_t *	driver,
		cfn_hal_power_state_t	state
	)

Sets the SPI power state.

Parameters

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

Returns

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

cfn_hal_spi_xfr_dma()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_xfr_dma	(	cfn_hal_spi_t *	driver,
		const cfn_hal_spi_transaction_t *	xfr
	)

Starts an SPI transaction using DMA (non-blocking).

Parameters

driver	Pointer to the SPI driver instance.
xfr	Pointer to the transaction configuration.

Returns

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

cfn_hal_spi_xfr_irq()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_xfr_irq	(	cfn_hal_spi_t *	driver,
		const cfn_hal_spi_transaction_t *	xfr
	)

Starts an SPI transaction using interrupts (non-blocking).

Parameters

driver	Pointer to the SPI driver instance.
xfr	Pointer to the transaction configuration.

Returns

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

cfn_hal_spi_xfr_irq_abort()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_xfr_irq_abort

(

cfn_hal_spi_t *

driver

)

Aborts an ongoing non-blocking SPI transaction.

Parameters

driver

Pointer to the SPI driver instance.

Returns

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

cfn_hal_spi_xfr_polling()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_spi_xfr_polling	(	cfn_hal_spi_t *	driver,
		const cfn_hal_spi_transaction_t *	xfr,
		uint32_t	timeout
	)

Executes an SPI transaction using polling (blocking).

Parameters

driver	Pointer to the SPI driver instance.
xfr	Pointer to the transaction configuration.
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_spi_api_s

)