vsf_template_usart.h File Reference

#include "./vsf_template_hal_driver.h"
#include "hal/arch/vsf_arch.h"

Go to the source code of this file.

Data Structures
struct	vsf_usart_isr_t
	USART interrupt configuration structure Contains all necessary information for configuring USART interrupts. More...
struct	vsf_usart_cfg_t
	USART configuration structure Contains all parameters needed to initialize and configure a USART instance. More...
struct	vsf_usart_status_t
	USART status information structure Contains the current status of USART operations and FIFO thresholds. More...
struct	vsf_usart_capability_t
	USART capability structure Defines the hardware capabilities and limitations of the USART interface. More...
struct	vsf_usart_op_t
	USART operation interface structure Contains function pointers for all USART operations. More...
struct	vsf_usart_t
	USART instance structure Used for USART Multi Class support. More...

Macros
#define	VSF_USART_CFG_MULTI_CLASS   ENABLED
	Enable multi-class support by default for maximum availability.
#define	VSF_USART_CFG_PREFIX   vsf
	Define USART hardware mask if count is defined. If VSF_HW_USART_COUNT is defined, this macro will generate the corresponding mask.
#define	VSF_USART_CFG_FUNCTION_RENAME   ENABLED
	Disable VSF_USART_CFG_FUNCTION_RENAME to use the original function names (e.g., vsf_usart_init()) without prefix.
#define	VSF_USART_CFG_REIMPLEMENT_TYPE_MODE   DISABLED
	In the specific hardware driver, we can enable VSF_USART_CFG_REIMPLEMENT_TYPE_MODE to redefine vsf_usart_mode_t as needed.
#define	VSF_USART_CFG_REIMPLEMENT_TYPE_IRQ_MASK   DISABLED
	In the specific hardware driver, we can enable VSF_USART_CFG_REIMPLEMENT_TYPE_IRQ_MASK to redefine vsf_usart_irq_mask_t as needed.
#define	VSF_USART_CFG_REIMPLEMENT_TYPE_STATUS   DISABLED
	In the specific hardware driver, we can enable VSF_USART_CFG_REIMPLEMENT_TYPE_STATUS to redefine struct vsf_usart_status_t.
#define	VSF_USART_CFG_REIMPLEMENT_TYPE_CTRL   DISABLED
	In the specific hardware driver, we can enable VSF_USART_CFG_REIMPLEMENT_TYPE_CTRL to redefine vsf_usart_ctrl_t as needed.
#define	VSF_USART_CFG_REIMPLEMENT_MODE_TO_DATA_BITS    DISABLED
	In the specific hardware driver, we can enable VSF_USART_CFG_REIMPLEMENT_MODE_TO_DATA_BITS to re-implement the function vsf_usart_mode_to_data_bits().
#define	VSF_USART_CFG_REIMPLEMENT_TYPE_CFG   DISABLED
	Redefine struct vsf_usart_cfg_t. The vsf_usart_isr_handler_t type also needs to be redefined. For compatibility, members should not be deleted when struct vsf_usart_cfg_t redefining.
#define	VSF_USART_CFG_REIMPLEMENT_TYPE_CAPABILITY   DISABLED
	Redefine struct vsf_usart_capability_t. For compatibility, members should not be deleted when struct vsf_usart_capability_t redefining.
#define	VSF_USART_CFG_REIMPLEMENT_TYPE_STATUS   DISABLED
	In the specific hardware driver, we can enable VSF_USART_CFG_REIMPLEMENT_TYPE_STATUS to redefine struct vsf_usart_status_t.
#define	VSF_USART_CFG_INHERIT_HAL_CAPABILITY   ENABLED
	In the specific hardware driver, we can enable VSF_USART_CFG_INHERIT_HAL_CAPABILITY to inherit capability from hal.
#define	VSF_USART_APIS(__prefix_name)
	USART API template, used to generate USART type, specific prefix function declarations, etc.
#define	VSF_USART_ADDITIONAL_APIS(__prefix_name)

Typedefs
typedef enum vsf_usart_mode_t	vsf_usart_mode_t
	Predefined VSF USART modes that can be reimplemented in specific HAL drivers. Even if the hardware doesn't support these modes, the following modes must be kept. If the hardware supports more modes, e.g. more parity modes, more databits, more stopbits, more FIFO threshold size, we can implement it in the hardware driver.
typedef enum vsf_usart_irq_mask_t	vsf_usart_irq_mask_t
	USART interrupt mask definitions These interrupts provide status and event notifications for USART operations.
typedef struct vsf_usart_t	vsf_usart_t
	USART instance structure forward declaration.
typedef void	vsf_usart_isr_handler_t(void *target_ptr, vsf_usart_t *usart_ptr, vsf_usart_irq_mask_t irq_mask)
	USART interrupt handler function type declaration.
typedef struct vsf_usart_isr_t	vsf_usart_isr_t
	USART interrupt configuration structure Contains all necessary information for configuring USART interrupts.
typedef struct vsf_usart_cfg_t	vsf_usart_cfg_t
	USART configuration structure Contains all parameters needed to initialize and configure a USART instance.
typedef enum vsf_usart_ctrl_t	vsf_usart_ctrl_t
	USART control commands Defines the available control operations for USART instances.
typedef struct vsf_usart_status_t	vsf_usart_status_t
	USART status information structure Contains the current status of USART operations and FIFO thresholds.
typedef struct vsf_usart_capability_t	vsf_usart_capability_t
	USART capability structure Defines the hardware capabilities and limitations of the USART interface.
typedef struct vsf_usart_op_t	vsf_usart_op_t
	USART operation interface structure Contains function pointers for all USART operations.

Enumerations
enum	vsf_usart_mode_t {   VSF_USART_NO_PARITY = (0x0ul << 0) ,   VSF_USART_EVEN_PARITY = (0x1ul << 0) ,   VSF_USART_ODD_PARITY = (0x2ul << 0) ,   VSF_USART_FORCE_0_PARITY = (0x3ul << 0) ,   VSF_USART_FORCE_1_PARITY = (0x4ul << 0) ,   VSF_USART_1_STOPBIT = (0x0ul << 3) ,   VSF_USART_1_5_STOPBIT = (0x1ul << 3) ,   VSF_USART_0_5_STOPBIT = (0x2ul << 3) ,   VSF_USART_2_STOPBIT = (0x3ul << 3) ,   VSF_USART_5_BIT_LENGTH = (0x0ul << 5) ,   VSF_USART_6_BIT_LENGTH = (0x1ul << 5) ,   VSF_USART_7_BIT_LENGTH = (0x2ul << 5) ,   VSF_USART_8_BIT_LENGTH = (0x3ul << 5) ,   VSF_USART_9_BIT_LENGTH = (0x4ul << 5) ,   VSF_USART_10_BIT_LENGTH = (0x5ul << 5) ,   VSF_USART_NO_HWCONTROL = (0x0ul << 8) ,   VSF_USART_RTS_HWCONTROL = (0x1ul << 8) ,   VSF_USART_CTS_HWCONTROL = (0x2ul << 8) ,   VSF_USART_RTS_CTS_HWCONTROL = (0x3ul << 8) ,   VSF_USART_TX_ENABLE = (0x0ul << 9) ,   VSF_USART_TX_DISABLE = (0x1ul << 9) ,   VSF_USART_RX_ENABLE = (0x0ul << 10) ,   VSF_USART_RX_DISABLE = (0x1ul << 10) ,   VSF_USART_SYNC_CLOCK_ENABLE = (0x0ul << 11) ,   VSF_USART_SYNC_CLOCK_DISABLE = (0x1ul << 11) ,   VSF_USART_HALF_DUPLEX_DISABLE = (0x0ul << 14) ,   VSF_USART_HALF_DUPLEX_ENABLE = (0x1ul << 14) ,   VSF_USART_TX_FIFO_THRESHOLD_EMPTY = (0x0ul << 15) ,   VSF_USART_TX_FIFO_THRESHOLD_HALF_EMPTY = (0x1ul << 15) ,   VSF_USART_TX_FIFO_THRESHOLD_NOT_FULL = (0x2ul << 15) ,   VSF_USART_RX_FIFO_THRESHOLD_NOT_EMPTY = (0x0ul << 17) ,   VSF_USART_RX_FIFO_THRESHOLD_HALF_FULL = (0x1ul << 17) ,   VSF_USART_RX_FIFO_THRESHOLD_FULL = (0x2ul << 17) }
	Predefined VSF USART modes that can be reimplemented in specific HAL drivers. Even if the hardware doesn't support these modes, the following modes must be kept. If the hardware supports more modes, e.g. more parity modes, more databits, more stopbits, more FIFO threshold size, we can implement it in the hardware driver. More...
enum	{   VSF_USART_PARITY_MASK ,   VSF_USART_STOPBIT_MASK ,   VSF_USART_BIT_LENGTH_MASK ,   VSF_USART_TX_FIFO_THRESHOLD_MASK ,   VSF_USART_RX_FIFO_THRESHOLD_MASK ,   VSF_USART_HWCONTROL_MASK ,   VSF_USART_TX_MASK ,   VSF_USART_RX_MASK ,   VSF_USART_SYNC_CLOCK_MASK ,   VSF_USART_HALF_DUPLEX_MASK ,   VSF_USART_MODE_ALL_BITS_MASK }
enum	vsf_usart_irq_mask_t {   VSF_USART_IRQ_MASK_TX_CPL = (0x1ul << 0) ,   VSF_USART_IRQ_MASK_RX_CPL = (0x1ul << 1) ,   VSF_USART_IRQ_MASK_TX = (0x1ul << 2) ,   VSF_USART_IRQ_MASK_RX = (0x1ul << 3) ,   VSF_USART_IRQ_MASK_RX_TIMEOUT = (0x1ul << 4) ,   VSF_USART_IRQ_MASK_CTS = (0x1ul << 5) ,   VSF_USART_IRQ_MASK_FRAME_ERR = (0x1ul << 6) ,   VSF_USART_IRQ_MASK_PARITY_ERR = (0x1ul << 7) ,   VSF_USART_IRQ_MASK_BREAK_ERR = (0x1ul << 8) ,   VSF_USART_IRQ_MASK_OVERFLOW_ERR = (0x1ul << 9) }
	USART interrupt mask definitions These interrupts provide status and event notifications for USART operations. More...
enum	{   VSF_USART_IRQ_MASK_RX_IDLE = VSF_USART_IRQ_MASK_RX_TIMEOUT ,   VSF_USART_IRQ_MASK_TX_FIFO_THRESHOLD = VSF_USART_IRQ_MASK_TX ,   VSF_USART_IRQ_MASK_RX_FIFO_THRESHOLD = VSF_USART_IRQ_MASK_RX ,   VSF_USART_IRQ_MASK_ERR ,   VSF_USART_IRQ_ALL_BITS_MASK }
	USART interrupts and control flags. More...
enum	vsf_usart_ctrl_t {   VSF_USART_CTRL_SEND_BREAK = (0x01ul << 0) ,   VSF_USART_CTRL_SET_BREAK = (0x01ul << 1) ,   VSF_USART_CTRL_CLEAR_BREAK = (0x01ul << 2) }
	USART control commands Defines the available control operations for USART instances. More...

Functions
vsf_err_t	vsf_usart_init (vsf_usart_t *usart_ptr, vsf_usart_cfg_t *cfg_ptr)
	Initialize a USART instance.
void	vsf_usart_fini (vsf_usart_t *usart_ptr)
	Finalize a USART instance.
fsm_rt_t	vsf_usart_enable (vsf_usart_t *usart_ptr)
	Enable a USART instance.
fsm_rt_t	vsf_usart_disable (vsf_usart_t *usart_ptr)
	Disable a USART instance.
void	vsf_usart_irq_enable (vsf_usart_t *usart_ptr, vsf_usart_irq_mask_t irq_mask)
	Enable interrupt masks of USART instance.
void	vsf_usart_irq_disable (vsf_usart_t *usart_ptr, vsf_usart_irq_mask_t irq_mask)
	Disable interrupt masks of USART instance.
vsf_usart_status_t	vsf_usart_status (vsf_usart_t *usart_ptr)
	Get the status of USART instance.
vsf_usart_capability_t	vsf_usart_capability (vsf_usart_t *usart_ptr)
	Get the capability of USART instance.
uint_fast32_t	vsf_usart_rxfifo_get_data_count (vsf_usart_t *usart_ptr)
	Get the number of data currently received in the USART receive FIFO.
uint_fast32_t	vsf_usart_rxfifo_read (vsf_usart_t *usart_ptr, void *buffer_ptr, uint_fast32_t count)
	Try to read the maximum length of data from the USART receive FIFO.
uint_fast32_t	vsf_usart_txfifo_get_free_count (vsf_usart_t *usart_ptr)
	Get the maximum number of data that can be sent through the USART send FIFO.
uint_fast32_t	vsf_usart_txfifo_write (vsf_usart_t *usart_ptr, void *buffer_ptr, uint_fast32_t count)
	Try to write the maximum length of data to the USART send FIFO.
vsf_err_t	vsf_usart_request_rx (vsf_usart_t *usart_ptr, void *buffer_ptr, uint_fast32_t count)
	Request a DMA receive operation through the USART.
vsf_err_t	vsf_usart_request_tx (vsf_usart_t *usart_ptr, void *buffer_ptr, uint_fast32_t count)
	Request a DMA transmit operation through the USART.
vsf_err_t	vsf_usart_cancel_rx (vsf_usart_t *usart_ptr)
	Cancel an ongoing USART receive operation.
vsf_err_t	vsf_usart_cancel_tx (vsf_usart_t *usart_ptr)
	Cancel an ongoing USART transmit operation.
int_fast32_t	vsf_usart_get_rx_count (vsf_usart_t *usart_ptr)
	Get the number of bytes received in the current or last USART operation.
int_fast32_t	vsf_usart_get_tx_count (vsf_usart_t *usart_ptr)
	Get the number of bytes transmitted in the current or last USART operation.
vsf_err_t	vsf_usart_ctrl (vsf_usart_t *usart_ptr, vsf_usart_ctrl_t ctrl, void *param)
	Execute a control command on the USART instance.

Macro Definition Documentation

VSF_USART_CFG_MULTI_CLASS

#define VSF_USART_CFG_MULTI_CLASS   ENABLED

Enable multi-class support by default for maximum availability.

VSF_USART_CFG_PREFIX

#define VSF_USART_CFG_PREFIX   vsf

Define USART hardware mask if count is defined. If VSF_HW_USART_COUNT is defined, this macro will generate the corresponding mask.

Define USART hardware count if mask is defined. If VSF_HW_USART_MASK is defined, this macro will calculate the corresponding count.

Macro VSF_USART_CFG_PREFIX can be redefined in application code to specify a prefix for directly calling a specific driver. This allows applications to access different USART implementations through unique function names. For example: #define VSF_USART_CFG_PREFIX vsf_hw vsf_usart_init(&vsf_hw_usart0, &cfg); It will be expanded at compile time to vsf_hw_usart_init(&vsf_hw_usart0, &cfg).

VSF_USART_CFG_FUNCTION_RENAME

#define VSF_USART_CFG_FUNCTION_RENAME   ENABLED

Disable VSF_USART_CFG_FUNCTION_RENAME to use the original function names (e.g., vsf_usart_init()) without prefix.

VSF_USART_CFG_REIMPLEMENT_TYPE_MODE

#define VSF_USART_CFG_REIMPLEMENT_TYPE_MODE   DISABLED

In the specific hardware driver, we can enable VSF_USART_CFG_REIMPLEMENT_TYPE_MODE to redefine vsf_usart_mode_t as needed.

VSF_USART_CFG_REIMPLEMENT_TYPE_IRQ_MASK

#define VSF_USART_CFG_REIMPLEMENT_TYPE_IRQ_MASK   DISABLED

In the specific hardware driver, we can enable VSF_USART_CFG_REIMPLEMENT_TYPE_IRQ_MASK to redefine vsf_usart_irq_mask_t as needed.

VSF_USART_CFG_REIMPLEMENT_TYPE_STATUS [1/2]

#define VSF_USART_CFG_REIMPLEMENT_TYPE_STATUS   DISABLED

In the specific hardware driver, we can enable VSF_USART_CFG_REIMPLEMENT_TYPE_STATUS to redefine struct vsf_usart_status_t.

VSF_USART_CFG_REIMPLEMENT_TYPE_CTRL

#define VSF_USART_CFG_REIMPLEMENT_TYPE_CTRL   DISABLED

In the specific hardware driver, we can enable VSF_USART_CFG_REIMPLEMENT_TYPE_CTRL to redefine vsf_usart_ctrl_t as needed.

VSF_USART_CFG_REIMPLEMENT_MODE_TO_DATA_BITS

#define VSF_USART_CFG_REIMPLEMENT_MODE_TO_DATA_BITS    DISABLED

In the specific hardware driver, we can enable VSF_USART_CFG_REIMPLEMENT_MODE_TO_DATA_BITS to re-implement the function vsf_usart_mode_to_data_bits().

VSF_USART_CFG_REIMPLEMENT_TYPE_CFG

#define VSF_USART_CFG_REIMPLEMENT_TYPE_CFG   DISABLED

Redefine struct vsf_usart_cfg_t. The vsf_usart_isr_handler_t type also needs to be redefined. For compatibility, members should not be deleted when struct vsf_usart_cfg_t redefining.

VSF_USART_CFG_REIMPLEMENT_TYPE_CAPABILITY

#define VSF_USART_CFG_REIMPLEMENT_TYPE_CAPABILITY   DISABLED

Redefine struct vsf_usart_capability_t. For compatibility, members should not be deleted when struct vsf_usart_capability_t redefining.

VSF_USART_CFG_REIMPLEMENT_TYPE_STATUS [2/2]

#define VSF_USART_CFG_REIMPLEMENT_TYPE_STATUS   DISABLED

In the specific hardware driver, we can enable VSF_USART_CFG_REIMPLEMENT_TYPE_STATUS to redefine struct vsf_usart_status_t.

VSF_USART_CFG_INHERIT_HAL_CAPABILITY

#define VSF_USART_CFG_INHERIT_HAL_CAPABILITY   ENABLED

In the specific hardware driver, we can enable VSF_USART_CFG_INHERIT_HAL_CAPABILITY to inherit capability from hal.

VSF_USART_APIS

#define VSF_USART_APIS

(

__prefix_name

)

Value:

    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              usart, init,                  VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr, vsf_usart_cfg_t *cfg_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, void,                   usart, fini,                  VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, fsm_rt_t,               usart, enable,                VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, fsm_rt_t,               usart, disable,               VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_usart_capability_t, usart, capability,            VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, void,                   usart, irq_enable,            VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr, vsf_usart_irq_mask_t irq_mask) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, void,                   usart, irq_disable,           VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr, vsf_usart_irq_mask_t irq_mask) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_usart_status_t,     usart, status,                VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, uint_fast32_t,          usart, rxfifo_get_data_count, VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, uint_fast32_t,          usart, rxfifo_read,           VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr, void *buffer_ptr, uint_fast32_t count) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, uint_fast32_t,          usart, txfifo_get_free_count, VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, uint_fast32_t,          usart, txfifo_write,          VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr, void *buffer_ptr, uint_fast32_t count) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              usart, request_rx,            VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr, void *buffer_ptr, uint_fast32_t count) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              usart, request_tx,            VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr, void *buffer_ptr, uint_fast32_t count) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              usart, cancel_rx,             VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              usart, cancel_tx,             VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, int_fast32_t,           usart, get_rx_count,          VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, int_fast32_t,           usart, get_tx_count,          VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              usart, ctrl,                  VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr, vsf_usart_ctrl_t ctrl, void* param)

USART API template, used to generate USART type, specific prefix function declarations, etc.

Parameters

[in]

__prefix_name

The prefix used for generating USART functions.

VSF_USART_ADDITIONAL_APIS

#define VSF_USART_ADDITIONAL_APIS

(

__prefix_name

)

Value:

    static inline vsf_err_t VSF_MCONNECT(__prefix_name, _usart_send_break)      \
        (VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr)                      \
    {                                                                           \
        return VSF_MCONNECT(__prefix_name, _usart_ctrl)(usart_ptr,              \
            VSF_USART_CTRL_SEND_BREAK, NULL);                                   \
    }                                                                           \
    static inline vsf_err_t VSF_MCONNECT(__prefix_name, _usart_set_break)       \
        (VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr)                      \
    {                                                                           \
        vsf_usart_capability_t cap =                                            \
            VSF_MCONNECT(__prefix_name, _usart_capability)(usart_ptr);          \
        VSF_HAL_ASSERT(cap.support_set_and_clear_break);                        \
        return VSF_MCONNECT(__prefix_name, _usart_ctrl)(usart_ptr,              \
            VSF_USART_CTRL_SET_BREAK, NULL);                                    \
    }                                                                           \
    static inline vsf_err_t VSF_MCONNECT(__prefix_name, _usart_clear_break)     \
        (VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr)                      \
    {                                                                           \
        vsf_usart_capability_t cap =                                            \
            VSF_MCONNECT(__prefix_name, _usart_capability)(usart_ptr);          \
        VSF_HAL_ASSERT(cap.support_set_and_clear_break);                        \
        return VSF_MCONNECT(__prefix_name, _usart_ctrl)(usart_ptr,              \
            VSF_USART_CTRL_CLEAR_BREAK, NULL);                                  \
    }

Typedef Documentation

vsf_usart_mode_t

typedef enum vsf_usart_mode_t vsf_usart_mode_t

Predefined VSF USART modes that can be reimplemented in specific HAL drivers. Even if the hardware doesn't support these modes, the following modes must be kept. If the hardware supports more modes, e.g. more parity modes, more databits, more stopbits, more FIFO threshold size, we can implement it in the hardware driver.

If more new modes are added to the driver, then the corresponding MASK macros need to be defined to include the values of the new modes. For example:

• Adding new TX FIFO Threshold options requires VSF_USART_TX_FIFO_THRESHOLD_MASK
• Adding new parity check options requires VSF_USART_PARITY_MASK
• Adding new stop bit options requires VSF_USART_STOPBIT_MASK

vsf_usart_irq_mask_t

typedef enum vsf_usart_irq_mask_t vsf_usart_irq_mask_t

USART interrupt mask definitions These interrupts provide status and event notifications for USART operations.

vsf_usart_t

typedef struct vsf_usart_t vsf_usart_t

USART instance structure forward declaration.

vsf_usart_isr_handler_t

typedef void vsf_usart_isr_handler_t(void *target_ptr, vsf_usart_t *usart_ptr, vsf_usart_irq_mask_t irq_mask)

USART interrupt handler function type declaration.

Parameters

[in,out]	target_ptr	User defined target pointer
[in,out]	usart_ptr	USART instance structure pointer
[in]	irq_mask	Interrupt mask indicating which events occurred

Note

This handler is called when configured interrupts occur

Example:

void usart_irq_handler(void *target_ptr, vsf_usart_t *usart_ptr, vsf_usart_irq_mask_t irq_mask)
{
    if (irq_mask & VSF_USART_IRQ_MASK_TX_CPL) {
        // Handle TX complete
    }
    if (irq_mask & VSF_USART_IRQ_MASK_RX_CPL) {
        // Handle RX complete
    }
}

vsf_usart_isr_t

typedef struct vsf_usart_isr_t vsf_usart_isr_t

USART interrupt configuration structure Contains all necessary information for configuring USART interrupts.

vsf_usart_cfg_t

typedef struct vsf_usart_cfg_t vsf_usart_cfg_t

USART configuration structure Contains all parameters needed to initialize and configure a USART instance.

vsf_usart_ctrl_t

typedef enum vsf_usart_ctrl_t vsf_usart_ctrl_t

USART control commands Defines the available control operations for USART instances.

vsf_usart_status_t

typedef struct vsf_usart_status_t vsf_usart_status_t

USART status information structure Contains the current status of USART operations and FIFO thresholds.

vsf_usart_capability_t

typedef struct vsf_usart_capability_t vsf_usart_capability_t

USART capability structure Defines the hardware capabilities and limitations of the USART interface.

vsf_usart_op_t

typedef struct vsf_usart_op_t vsf_usart_op_t

USART operation interface structure Contains function pointers for all USART operations.

Enumeration Type Documentation

vsf_usart_mode_t

enum vsf_usart_mode_t

Predefined VSF USART modes that can be reimplemented in specific HAL drivers. Even if the hardware doesn't support these modes, the following modes must be kept. If the hardware supports more modes, e.g. more parity modes, more databits, more stopbits, more FIFO threshold size, we can implement it in the hardware driver.

If more new modes are added to the driver, then the corresponding MASK macros need to be defined to include the values of the new modes. For example:

• Adding new TX FIFO Threshold options requires VSF_USART_TX_FIFO_THRESHOLD_MASK
• Adding new parity check options requires VSF_USART_PARITY_MASK
• Adding new stop bit options requires VSF_USART_STOPBIT_MASK

Enumerator
VSF_USART_NO_PARITY	USART Parity configuration options. No parity
VSF_USART_EVEN_PARITY	Even parity.
VSF_USART_ODD_PARITY	Odd parity.
VSF_USART_FORCE_0_PARITY	Force 0 parity.
VSF_USART_FORCE_1_PARITY	Force 1 parity.
VSF_USART_1_STOPBIT	USART Stop bit configuration options. 1 stop bit
VSF_USART_1_5_STOPBIT	1.5 stop bits
VSF_USART_0_5_STOPBIT	0.5 stop bit
VSF_USART_2_STOPBIT	2 stop bits
VSF_USART_5_BIT_LENGTH	USART Data bit length configuration options. 5-bit data length
VSF_USART_6_BIT_LENGTH	6-bit data length
VSF_USART_7_BIT_LENGTH	7-bit data length
VSF_USART_8_BIT_LENGTH	8-bit data length
VSF_USART_9_BIT_LENGTH	9-bit data length
VSF_USART_10_BIT_LENGTH	10-bit data length
VSF_USART_NO_HWCONTROL	USART Hardware flow control configuration options. No hardware flow control
VSF_USART_RTS_HWCONTROL	RTS hardware flow control.
VSF_USART_CTS_HWCONTROL	CTS hardware flow control.
VSF_USART_RTS_CTS_HWCONTROL	RTS/CTS hardware flow control.
VSF_USART_TX_ENABLE	USART TX/RX enable/disable options. TX enabled
VSF_USART_TX_DISABLE	TX disabled.
VSF_USART_RX_ENABLE	RX enabled.
VSF_USART_RX_DISABLE	RX disabled.
VSF_USART_SYNC_CLOCK_ENABLE	USART Synchronous clock configuration options. Sync clock enabled
VSF_USART_SYNC_CLOCK_DISABLE	Sync clock disabled.
VSF_USART_HALF_DUPLEX_DISABLE	USART Half-duplex configuration options. Half-duplex disabled
VSF_USART_HALF_DUPLEX_ENABLE	Half-duplex enabled.
VSF_USART_TX_FIFO_THRESHOLD_EMPTY	USART TX FIFO threshold configuration options Note: Some devices may support additional threshold levels. TX FIFO empty
VSF_USART_TX_FIFO_THRESHOLD_HALF_EMPTY	TX FIFO half empty.
VSF_USART_TX_FIFO_THRESHOLD_NOT_FULL	TX FIFO not full.
VSF_USART_RX_FIFO_THRESHOLD_NOT_EMPTY	USART RX FIFO threshold configuration options Note: Some devices may support additional threshold levels. RX FIFO not empty
VSF_USART_RX_FIFO_THRESHOLD_HALF_FULL	RX FIFO half full.
VSF_USART_RX_FIFO_THRESHOLD_FULL	RX FIFO full.

anonymous enum

anonymous enum

Enumerator
VSF_USART_PARITY_MASK
VSF_USART_STOPBIT_MASK
VSF_USART_BIT_LENGTH_MASK
VSF_USART_TX_FIFO_THRESHOLD_MASK
VSF_USART_RX_FIFO_THRESHOLD_MASK
VSF_USART_HWCONTROL_MASK
VSF_USART_TX_MASK
VSF_USART_RX_MASK
VSF_USART_SYNC_CLOCK_MASK
VSF_USART_HALF_DUPLEX_MASK
VSF_USART_MODE_ALL_BITS_MASK

vsf_usart_irq_mask_t

enum vsf_usart_irq_mask_t

USART interrupt mask definitions These interrupts provide status and event notifications for USART operations.

Enumerator
VSF_USART_IRQ_MASK_TX_CPL	TX complete interrupt.
VSF_USART_IRQ_MASK_RX_CPL	RX complete interrupt.
VSF_USART_IRQ_MASK_TX	TX FIFO threshold interrupt.
VSF_USART_IRQ_MASK_RX	RX FIFO threshold interrupt.
VSF_USART_IRQ_MASK_RX_TIMEOUT	RX timeout interrupt.
VSF_USART_IRQ_MASK_CTS	CTS change interrupt.
VSF_USART_IRQ_MASK_FRAME_ERR	Frame error interrupt.
VSF_USART_IRQ_MASK_PARITY_ERR	Parity error interrupt.
VSF_USART_IRQ_MASK_BREAK_ERR	Break error interrupt.
VSF_USART_IRQ_MASK_OVERFLOW_ERR	Overflow error interrupt.

anonymous enum

anonymous enum

USART interrupts and control flags.

Enumerator
VSF_USART_IRQ_MASK_RX_IDLE	RX idle timeout interrupt mask.
VSF_USART_IRQ_MASK_TX_FIFO_THRESHOLD	TX FIFO threshold interrupt mask.
VSF_USART_IRQ_MASK_RX_FIFO_THRESHOLD	RX FIFO threshold interrupt mask.
VSF_USART_IRQ_MASK_ERR	Combined error interrupt mask.
VSF_USART_IRQ_ALL_BITS_MASK	All supported interrupt mask bits.

vsf_usart_ctrl_t

enum vsf_usart_ctrl_t

USART control commands Defines the available control operations for USART instances.

Enumerator
VSF_USART_CTRL_SEND_BREAK	Send BREAK signal The BREAK signal will be automatically cleared after a number of bit times.
VSF_USART_CTRL_SET_BREAK	Set BREAK signal The BREAK signal will remain until explicitly cleared.
VSF_USART_CTRL_CLEAR_BREAK	Clear BREAK signal Clears a previously set BREAK signal.

Function Documentation

vsf_usart_init()

vsf_err_t vsf_usart_init ( vsf_usart_t *  usart_ptr, vsf_usart_cfg_t *  cfg_ptr  )

extern

Initialize a USART instance.

Parameters

[in]	usart_ptr	Pointer to USART instance
[in]	cfg_ptr	Pointer to USART configuration

Returns

vsf_err_t VSF_ERR_NONE if successful, otherwise an error code

Note

This function must be called before using any other USART functions

calculate baudrate

calculate baudrate

vsf_usart_fini()

void vsf_usart_fini ( vsf_usart_t *  usart_ptr )

extern

Finalize a USART instance.

Parameters

[in]

usart_ptr

a pointer to structure vsf_usart_t

Returns

none

vsf_usart_enable()

fsm_rt_t vsf_usart_enable ( vsf_usart_t *  usart_ptr )

extern

Enable a USART instance.

Parameters

[in]

usart_ptr

a pointer to structure vsf_usart_t

Returns

fsm_rt_t: fsm_rt_cpl if USART was enabled, fsm_rt_on_going if USART is still enabling

don't forget to enable sync clock and peripheral_clk here

vsf_usart_disable()

fsm_rt_t vsf_usart_disable ( vsf_usart_t *  usart_ptr )

extern

Disable a USART instance.

Parameters

[in]

usart_ptr

a pointer to structure vsf_usart_t

Returns

fsm_rt_t: fsm_rt_cpl if USART was disabled, fsm_rt_on_going if USART is still disabling

don't forget to disable sync clock and peripheral_clk here

vsf_usart_irq_enable()

void vsf_usart_irq_enable ( vsf_usart_t *  usart_ptr, vsf_usart_irq_mask_t  irq_mask  )

extern

Enable interrupt masks of USART instance.

Parameters

[in]	usart_ptr	a pointer to structure vsf_usart_t
[in]	irq_mask	one or more values of enum vsf_usart_irq_mask_t

Returns

none

Note

All pending interrupts should be cleared before interrupts are enabled

vsf_usart_irq_disable()

void vsf_usart_irq_disable ( vsf_usart_t *  usart_ptr, vsf_usart_irq_mask_t  irq_mask  )

extern

Disable interrupt masks of USART instance.

Parameters

[in]	usart_ptr	a pointer to structure vsf_usart_t
[in]	irq_mask	one or more values of enum vsf_usart_irq_mask_t

Returns

none

vsf_usart_status()

vsf_usart_status_t vsf_usart_status ( vsf_usart_t *  usart_ptr )

extern

Get the status of USART instance.

Parameters

[in]

usart_ptr

a pointer to structure vsf_usart_t

Returns

vsf_usart_status_t: return all status of current USART

vsf_usart_capability()

vsf_usart_capability_t vsf_usart_capability ( vsf_usart_t *  usart_ptr )

extern

Get the capability of USART instance.

Parameters

[in]

usart_ptr

a pointer to structure vsf_usart_t

Returns

vsf_usart_capability_t: return all capabilities of current USART vsf_usart_capability_t

vsf_usart_rxfifo_get_data_count()

uint_fast32_t vsf_usart_rxfifo_get_data_count ( vsf_usart_t *  usart_ptr )

extern

Get the number of data currently received in the USART receive FIFO.

Parameters

[in]

usart_ptr

a pointer to structure vsf_usart_t

Returns

uint_fast32_t: the number of data currently in the USART receive queue

vsf_usart_rxfifo_read()

uint_fast32_t vsf_usart_rxfifo_read ( vsf_usart_t *  usart_ptr, void *  buffer_ptr, uint_fast32_t  count  )

extern

Try to read the maximum length of data from the USART receive FIFO.

Parameters

[in]	usart_ptr	a pointer to structure vsf_usart_t
[in]	buffer_ptr	data buffer
[in]	count	maximum number of reads

Returns

uint_fast32_t: return the actual number of bytes read from the current USART receive FIFO

vsf_usart_txfifo_get_free_count()

uint_fast32_t vsf_usart_txfifo_get_free_count ( vsf_usart_t *  usart_ptr )

extern

Get the maximum number of data that can be sent through the USART send FIFO.

Parameters

[in]

usart_ptr

a pointer to structure vsf_usart_t

Returns

uint_fast32_t: return the maximum number of bytes that can be sent through the current USART send FIFO

vsf_usart_txfifo_write()

uint_fast32_t vsf_usart_txfifo_write ( vsf_usart_t *  usart_ptr, void *  buffer_ptr, uint_fast32_t  count  )

extern

Try to write the maximum length of data to the USART send FIFO.

Parameters

[in]	usart_ptr	a pointer to structure vsf_usart_t
[in]	buffer_ptr	data buffer
[in]	count	maximum number of writes

Returns

uint_fast32_t: return the actual number of bytes written to the current USART send queue

vsf_usart_request_rx()

vsf_err_t vsf_usart_request_rx ( vsf_usart_t *  usart_ptr, void *  buffer_ptr, uint_fast32_t  count  )

extern

Request a DMA receive operation through the USART.

Parameters

[in]	usart_ptr	a pointer to structure vsf_usart_t
[in]	buffer_ptr	Pointer to the receive buffer
[in]	count	Number of bytes to receive

Returns

vsf_err_t: VSF_ERR_NONE if the receive request was successfully started, otherwise returns error code

Note

This is an asynchronous operation

vsf_usart_request_tx()

vsf_err_t vsf_usart_request_tx ( vsf_usart_t *  usart_ptr, void *  buffer_ptr, uint_fast32_t  count  )

extern

Request a DMA transmit operation through the USART.

Parameters

[in]	usart_ptr	a pointer to structure vsf_usart_t
[in]	buffer_ptr	Pointer to the transmit buffer
[in]	count	Number of bytes to transmit

Returns

vsf_err_t: VSF_ERR_NONE if the transmit request was successfully started, otherwise returns error code

Note

This is an asynchronous operation

vsf_usart_cancel_rx()

vsf_err_t vsf_usart_cancel_rx ( vsf_usart_t *  usart_ptr )

extern

Cancel an ongoing USART receive operation.

Parameters

[in]

usart_ptr

a pointer to structure vsf_usart_t

Returns

vsf_err_t: VSF_ERR_NONE if the receive operation was successfully cancelled, otherwise returns error code

vsf_usart_cancel_tx()

vsf_err_t vsf_usart_cancel_tx ( vsf_usart_t *  usart_ptr )

extern

Cancel an ongoing USART transmit operation.

Parameters

[in]

usart_ptr

a pointer to structure vsf_usart_t

Returns

vsf_err_t: VSF_ERR_NONE if the transmit operation was successfully cancelled, otherwise returns error code

vsf_usart_get_rx_count()

int_fast32_t vsf_usart_get_rx_count ( vsf_usart_t *  usart_ptr )

extern

Get the number of bytes received in the current or last USART operation.

Parameters

[in]

usart_ptr

a pointer to structure vsf_usart_t

Returns

int_fast32_t: Number of received bytes, negative value for error

vsf_usart_get_tx_count()

int_fast32_t vsf_usart_get_tx_count ( vsf_usart_t *  usart_ptr )

extern

Get the number of bytes transmitted in the current or last USART operation.

Parameters

[in]

usart_ptr

a pointer to structure vsf_usart_t

Returns

int_fast32_t: Number of transmitted bytes, negative value for error

vsf_usart_ctrl()

vsf_err_t vsf_usart_ctrl ( vsf_usart_t *  usart_ptr, vsf_usart_ctrl_t  ctrl, void *  param  )

extern

Execute a control command on the USART instance.

Parameters

[in]	usart_ptr	a pointer to structure vsf_usart_t
[in]	ctrl	Control command from vsf_usart_ctrl_t enumeration
[in,out]	param	Command-specific parameter (can be NULL depending on command)

Returns

vsf_err_t: VSF_ERR_NONE if control command executed successfully, otherwise returns error code

Note

Available commands and their parameters depend on hardware support