#include "hal/driver/driver.h"

Macros
#define	VSF_SPI_CFG_FUNCTION_RENAME DISABLED

Functions
vsf_err_t	vsf_spi_init (vsf_spi_t spi_ptr, vsf_spi_cfg_t cfg_ptr)
	Initialize a SPI instance.

void	vsf_spi_fini (vsf_spi_t *spi_ptr)
	Finalize (deinitialize) a SPI instance.

vsf_err_t	vsf_spi_get_configuration (vsf_spi_t spi_ptr, vsf_spi_cfg_t cfg_ptr)
	Get current configuration of a SPI instance.

fsm_rt_t	vsf_spi_enable (vsf_spi_t *spi_ptr)
	Enable a SPI instance for operation.

fsm_rt_t	vsf_spi_disable (vsf_spi_t *spi_ptr)
	Disable a SPI instance from operation.

void	vsf_spi_irq_enable (vsf_spi_t *spi_ptr, vsf_spi_irq_mask_t irq_mask)
	Enable specific interrupts for a SPI instance.

void	vsf_spi_irq_disable (vsf_spi_t *spi_ptr, vsf_spi_irq_mask_t irq_mask)
	Disable specific interrupts for a SPI instance.

vsf_spi_irq_mask_t	vsf_spi_irq_clear (vsf_spi_t *spi_ptr, vsf_spi_irq_mask_t irq_mask)
	Clear interrupt flags of SPI instance and return previous state.

vsf_spi_status_t	vsf_spi_status (vsf_spi_t *spi_ptr)
	Get the current status of a SPI instance.

vsf_err_t	vsf_spi_cs_active (vsf_spi_t *spi_ptr, uint_fast8_t index)
	Activate (assert) a SPI chip select line.

vsf_err_t	vsf_spi_cs_inactive (vsf_spi_t *spi_ptr, uint_fast8_t index)
	Deactivate (deassert) a SPI chip select line.

void	vsf_spi_fifo_transfer (vsf_spi_t spi_ptr, void out_buffer_ptr, uint_fast32_t out_offset_ptr, void in_buffer_ptr, uint_fast32_t *in_offset_ptr, uint_fast32_t cnt)
	Perform FIFO-based data transfer on a SPI instance.

vsf_err_t	vsf_spi_request_transfer (vsf_spi_t spi_ptr, void out_buffer_ptr, void *in_buffer_ptr, uint_fast32_t count)
	Request a SPI data transfer operation.

vsf_err_t	vsf_spi_cancel_transfer (vsf_spi_t *spi_ptr)
	Cancel an ongoing SPI transfer operation.

void	vsf_spi_get_transferred_count (vsf_spi_t spi_ptr, uint_fast32_t tx_count, uint_fast32_t *rx_count)
	Get the number of data units transferred in the current or last SPI operation.

vsf_spi_capability_t	vsf_spi_capability (vsf_spi_t *spi_ptr)
	Get the capabilities of a SPI instance.

vsf_err_t	vsf_spi_ctrl (vsf_spi_t spi_ptr, vsf_spi_ctrl_t ctrl, void param)
	Execute a control command on the SPI instance.

Macro Definition Documentation

◆ VSF_SPI_CFG_FUNCTION_RENAME

#define VSF_SPI_CFG_FUNCTION_RENAME DISABLED

Function Documentation

◆ vsf_spi_init()

vsf_err_t vsf_spi_init	(	vsf_spi_t *	spi_ptr,
		vsf_spi_cfg_t *	cfg_ptr
	)

Initialize a SPI instance.

Parameters

[in,out]	spi_ptr	Pointer to SPI instance structure vsf_spi_t
[in]	cfg_ptr	Pointer to SPI configuration structure vsf_spi_cfg_t

Returns: vsf_err_t: VSF_ERR_NONE if initialization successful, otherwise returns error code

Note: The configuration includes clock settings, transfer modes, and interrupt handlers; This must be called before any other SPI operations except for vsf_spi_capability()

◆ vsf_spi_fini()

void vsf_spi_fini ( vsf_spi_t * spi_ptr )

Finalize (deinitialize) a SPI instance.

Parameters

[in,out] spi_ptr Pointer to SPI instance structure vsf_spi_t

Note: This function should be called when the SPI instance is no longer needed; Ensure all transfers are complete before calling this function

◆ vsf_spi_get_configuration()

vsf_err_t vsf_spi_get_configuration	(	vsf_spi_t *	spi_ptr,
		vsf_spi_cfg_t *	cfg_ptr
	)

Get current configuration of a SPI instance.

Parameters

[in]	spi_ptr	Pointer to SPI instance
[out]	cfg_ptr	Pointer to SPI configuration structure to store current settings

Returns: vsf_err_t VSF_ERR_NONE if successful, otherwise an error code

Note: This function retrieves the current configuration of the SPI instance

◆ vsf_spi_enable()

fsm_rt_t vsf_spi_enable ( vsf_spi_t * spi_ptr )

Enable a SPI instance for operation.

Parameters

[in,out] spi_ptr Pointer to SPI instance structure vsf_spi_t

Returns: fsm_rt_t: fsm_rt_cpl if SPI was enabled immediately, fsm_rt_on_going if enabling is in progress

Note: The instance must be initialized before enabling

◆ vsf_spi_disable()

fsm_rt_t vsf_spi_disable ( vsf_spi_t * spi_ptr )

Disable a SPI instance from operation.

Parameters

[in,out] spi_ptr Pointer to SPI instance structure vsf_spi_t

Returns: fsm_rt_t: fsm_rt_cpl if SPI was disabled immediately, fsm_rt_on_going if disabling is in progress

Note: Any ongoing transfers should be completed or cancelled before disabling

◆ vsf_spi_irq_enable()

void vsf_spi_irq_enable	(	vsf_spi_t *	spi_ptr,
		vsf_spi_irq_mask_t	irq_mask
	)

Enable specific interrupts for a SPI instance.

Parameters

[in,out]	spi_ptr	Pointer to SPI instance structure vsf_spi_t
[in]	irq_mask	Interrupt mask(s) to enable from vsf_spi_irq_mask_t

Note: Clear any pending interrupts before enabling new ones; Multiple interrupts can be enabled by OR-ing the masks

◆ vsf_spi_irq_disable()

void vsf_spi_irq_disable	(	vsf_spi_t *	spi_ptr,
		vsf_spi_irq_mask_t	irq_mask
	)

Disable specific interrupts for a SPI instance.

Parameters

[in,out]	spi_ptr	Pointer to SPI instance structure vsf_spi_t
[in]	irq_mask	Interrupt mask(s) to disable from vsf_spi_irq_mask_t

Note: Multiple interrupts can be disabled by OR-ing the masks

◆ vsf_spi_irq_clear()

vsf_spi_irq_mask_t vsf_spi_irq_clear	(	vsf_spi_t *	spi_ptr,
		vsf_spi_irq_mask_t	irq_mask
	)

Clear interrupt flags of SPI instance and return previous state.

Parameters

[in]	spi_ptr	a pointer to structure vsf_spi_t
[in]	irq_mask	one or more values of enum vsf_spi_irq_mask_t to clear

Returns: vsf_spi_irq_mask_t: the interrupt mask state before clearing (0 if no flags were set)

Note: This function attempts to clear the specified interrupt flags if they are set, and returns the state of those flags before clearing. This is useful for polling operations and determining if interrupts occurred. Note that if interrupts are enabled and an interrupt handler is active, the interrupt handler may clear the interrupt flags automatically. In such cases, this function will return 0 even if interrupts occurred.

◆ vsf_spi_status()

vsf_spi_status_t vsf_spi_status ( vsf_spi_t * spi_ptr )

Get the current status of a SPI instance.

Parameters

[in,out] spi_ptr Pointer to SPI instance structure vsf_spi_t

Returns: vsf_spi_status_t: Current status flags of the SPI instance

Note: Status includes busy flag and other peripheral status information

◆ vsf_spi_cs_active()

vsf_err_t vsf_spi_cs_active	(	vsf_spi_t *	spi_ptr,
		uint_fast8_t	index
	)

Activate (assert) a SPI chip select line.

Parameters

[in,out]	spi_ptr	Pointer to SPI instance structure vsf_spi_t
[in]	index	Chip select line index (0 to cs_count-1)

Returns: vsf_err_t: VSF_ERR_NONE if successful, otherwise returns error code

Note: Hardware chip select support must be available if using hardware mode

◆ vsf_spi_cs_inactive()

vsf_err_t vsf_spi_cs_inactive	(	vsf_spi_t *	spi_ptr,
		uint_fast8_t	index
	)

Deactivate (deassert) a SPI chip select line.

Parameters

[in,out]	spi_ptr	Pointer to SPI instance structure vsf_spi_t
[in]	index	Chip select line index (0 to cs_count-1)

Returns: vsf_err_t: VSF_ERR_NONE if successful, otherwise returns error code

Note: Hardware chip select support must be available if using hardware mode

◆ vsf_spi_fifo_transfer()

void vsf_spi_fifo_transfer	(	vsf_spi_t *	spi_ptr,
		void *	out_buffer_ptr,
		uint_fast32_t *	out_offset_ptr,
		void *	in_buffer_ptr,
		uint_fast32_t *	in_offset_ptr,
		uint_fast32_t	count
	)

Perform FIFO-based data transfer on a SPI instance.

Parameters

[in,out]	spi_ptr	Pointer to SPI instance structure vsf_spi_t
[in]	out_buffer_ptr	Pointer to data to transmit (can be NULL for receive-only)
[in,out]	out_offset_ptr	Pointer to transmit buffer offset
[out]	in_buffer_ptr	Pointer to buffer for received data (can be NULL for transmit-only)
[in,out]	in_offset_ptr	Pointer to receive buffer offset
[in]	count	Number of data units to transfer (can be 0 for QSPI operations with only command/address phases)

Note

Data unit size is determined by the configured data size in SPI mode (vsf_spi_mode_t)

Buffer size requirements: 4-8 bits = 1 byte, 9-16 bits = 2 bytes, 17-32 bits = 4 bytes per data unit

In master mode, out_buffer_ptr data is sent through MOSI pin, in_buffer_ptr receives from MISO pin

In slave mode, out_buffer_ptr data is sent through MISO pin, in_buffer_ptr receives from MOSI pin

When using QSPI after configuring with vsf_spi_ctrl(), the count parameter refers to data phase units only

Nullability rules: At least one of out_buffer_ptr or in_buffer_ptr must be non-NULL.

If out_buffer_ptr is NULL (receive-only), out_offset_ptr must be NULL.
If in_buffer_ptr is NULL (transmit-only), in_offset_ptr must be NULL.
If a buffer pointer is non-NULL, its corresponding offset pointer must also be non-NULL.
It is invalid for both out_buffer_ptr and in_buffer_ptr to be NULL simultaneously.

Driver implementers should validate the parameters and use an assertion (e.g., VSF_HAL_ASSERT) to handle invalid arguments.

◆ vsf_spi_request_transfer()

vsf_err_t vsf_spi_request_transfer	(	vsf_spi_t *	spi_ptr,
		void *	out_buffer_ptr,
		void *	in_buffer_ptr,
		uint_fast32_t	count
	)

Request a SPI data transfer operation.

Parameters

[in,out]	spi_ptr	Pointer to SPI instance structure vsf_spi_t
[in]	out_buffer_ptr	Pointer to data to transmit (NULL for receive-only)
[out]	in_buffer_ptr	Pointer to buffer for received data (NULL for transmit-only)
[in]	count	Number of data units to transfer (can be 0 for QSPI operations with only command/address phases)

Returns: vsf_err_t: VSF_ERR_NONE if transfer started successfully, or error code

Note: This is an asynchronous operation, register for completion interrupts to be notified; Data unit size is determined by the configured data size in SPI mode (vsf_spi_mode_t); Buffer size requirements: 4-8 bits = 1 byte, 9-16 bits = 2 bytes, 17-32 bits = 4 bytes per data unit; If both out_buffer_ptr and in_buffer_ptr are not NULL, data is exchanged in full-duplex mode; In master mode, out_buffer_ptr data is sent through MOSI pin, in_buffer_ptr receives from MISO pin; In slave mode, out_buffer_ptr data is sent through MISO pin, in_buffer_ptr receives from MOSI pin; For QSPI operations after calling vsf_spi_ctrl(), this function will execute all configured phases (command, address, dummy, data). Count parameter refers only to data phase units.; Nullability rules: out_buffer_ptr and in_buffer_ptr must not be both NULL; if a buffer pointer is NULL, its corresponding offset pointer (if any in related APIs) must also be NULL; if a buffer pointer is non-NULL, its corresponding offset pointer must be non-NULL.

◆ vsf_spi_cancel_transfer()

vsf_err_t vsf_spi_cancel_transfer ( vsf_spi_t * spi_ptr )

Cancel an ongoing SPI transfer operation.

Parameters

[in,out] spi_ptr Pointer to SPI instance structure vsf_spi_t

Returns: vsf_err_t: VSF_ERR_NONE if cancellation was successful, or error code

Note: SPI hardware may not be able to cancel immediately if busy

◆ vsf_spi_get_transferred_count()

void vsf_spi_get_transferred_count	(	vsf_spi_t *	spi_ptr,
		uint_fast32_t *	sent_count,
		uint_fast32_t *	received_count
	)

Get the number of data units transferred in the current or last SPI operation.

Parameters

[in,out]	spi_ptr	Pointer to SPI instance structure vsf_spi_t
[out]	sent_count	Pointer to store the number of data units transmitted (can be NULL if not needed)
[out]	received_count	Pointer to store the number of data units received (can be NULL if not needed)

Note: Data unit count is based on the configured data size in SPI mode (vsf_spi_mode_t); Buffer size requirements: 4-8 bits = 1 byte, 9-16 bits = 2 bytes, 17-32 bits = 4 bytes per data unit; For ongoing transfers, returns the current progress; for completed transfers, returns final counts

◆ vsf_spi_capability()

vsf_spi_capability_t vsf_spi_capability ( vsf_spi_t * spi_ptr )

Get the capabilities of a SPI instance.

Parameters

[in,out] spi_ptr Pointer to SPI instance structure vsf_spi_t

Returns: vsf_spi_capability_t: Hardware capabilities of the SPI instance

Note: Capabilities include supported features, modes, and limitations

◆ vsf_spi_ctrl()

vsf_err_t vsf_spi_ctrl	(	vsf_spi_t *	spi_ptr,
		vsf_spi_ctrl_t	ctrl,
		void *	param
	)

Execute a control command on the SPI instance.

Parameters

[in,out]	spi_ptr	Pointer to SPI instance structure vsf_spi_t
[in]	ctrl	Control command from vsf_spi_ctrl_t enumeration
[in]	param	Command-specific parameter (can be NULL depending on command)

Returns: vsf_err_t: VSF_ERR_NONE if command executed successfully, VSF_ERR_NOT_SUPPORT if command is not supported, other error codes defined by vsf_err_t for specific failures

Note: Available commands and their parameters are hardware-dependent; Some commands may not be supported on all hardware platforms

Macros

Functions

Macro Definition Documentation

◆ VSF_SPI_CFG_FUNCTION_RENAME

Function Documentation

◆ vsf_spi_init()

◆ vsf_spi_fini()

◆ vsf_spi_get_configuration()

◆ vsf_spi_enable()

◆ vsf_spi_disable()

◆ vsf_spi_irq_enable()

◆ vsf_spi_irq_disable()

◆ vsf_spi_irq_clear()

◆ vsf_spi_status()

◆ vsf_spi_cs_active()

◆ vsf_spi_cs_inactive()

◆ vsf_spi_fifo_transfer()

◆ vsf_spi_request_transfer()

◆ vsf_spi_cancel_transfer()

◆ vsf_spi_get_transferred_count()

◆ vsf_spi_capability()

◆ vsf_spi_ctrl()