vsf_template_usart.h

Go to the documentation of this file.

/*****************************************************************************
 *   Copyright(C)2009-2022 by VSF Team                                       *
 *                                                                           *
 *  Licensed under the Apache License, Version 2.0 (the "License");          *
 *  you may not use this file except in compliance with the License.         *
 *  You may obtain a copy of the License at                                  *
 *                                                                           *
 *     http://www.apache.org/licenses/LICENSE-2.0                            *
 *                                                                           *
 *  Unless required by applicable law or agreed to in writing, software      *
 *  distributed under the License is distributed on an "AS IS" BASIS,        *
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
 *  See the License for the specific language governing permissions and      *
 *  limitations under the License.                                           *
 *                                                                           *
 ****************************************************************************/
 
#ifndef __VSF_TEMPLATE_USART_H__
#define __VSF_TEMPLATE_USART_H__
 
/*============================ INCLUDES ======================================*/
 
#include "./vsf_template_hal_driver.h"
#include "hal/arch/vsf_arch.h"
 
#ifdef __cplusplus
extern "C" {
#endif
/*============================ MACROS ========================================*/
 
// multi-class support enabled by default for maximum availability.
#ifndef VSF_USART_CFG_MULTI_CLASS
#   define VSF_USART_CFG_MULTI_CLASS                ENABLED
#endif
 
#if defined(VSF_HW_USART_COUNT) && !defined(VSF_HW_USART_MASK)
#   define VSF_HW_USART_MASK                        VSF_HAL_COUNT_TO_MASK(VSF_HW_USART_COUNT)
#endif
 
#if defined(VSF_HW_USART_MASK) && !defined(VSF_HW_USART_COUNT)
#   define VSF_HW_USART_COUNT                       VSF_HAL_MASK_TO_COUNT(VSF_HW_USART_MASK)
#endif
 
#ifndef VSF_USART_CFG_PREFIX
#   if VSF_USART_CFG_MULTI_CLASS == ENABLED
#       define VSF_USART_CFG_PREFIX                 vsf
#   elif defined(VSF_HW_USART_COUNT) && (VSF_HW_USART_COUNT != 0)
#       define VSF_USART_CFG_PREFIX                 vsf_hw
#   else
#       define VSF_USART_CFG_PREFIX                 vsf
#   endif
#endif
 
#ifndef VSF_USART_CFG_FUNCTION_RENAME
#   define VSF_USART_CFG_FUNCTION_RENAME            ENABLED
#endif
 
#ifndef VSF_USART_CFG_REIMPLEMENT_TYPE_MODE
#   define VSF_USART_CFG_REIMPLEMENT_TYPE_MODE      DISABLED
#endif
 
#ifndef VSF_USART_CFG_REIMPLEMENT_TYPE_IRQ_MASK
#   define VSF_USART_CFG_REIMPLEMENT_TYPE_IRQ_MASK  DISABLED
#endif
 
#ifndef VSF_USART_CFG_REIMPLEMENT_TYPE_STATUS
#   define VSF_USART_CFG_REIMPLEMENT_TYPE_STATUS    DISABLED
#endif
 
#ifndef VSF_USART_CFG_REIMPLEMENT_TYPE_CMD
#   define VSF_USART_CFG_REIMPLEMENT_TYPE_CMD       DISABLED
#endif
 
#ifndef VSF_USART_CFG_REIMPLEMENT_MODE_TO_DATA_BITS
#   define VSF_USART_CFG_REIMPLEMENT_MODE_TO_DATA_BITS      \
                                                    DISABLED
#endif
 
#if VSF_USART_CFG_REIMPLEMENT_TYPE_CFG == DISABLED
#    define VSF_USART_CFG_REIMPLEMENT_TYPE_CFG DISABLED
#endif
 
#if VSF_USART_CFG_REIMPLEMENT_TYPE_CAPABILITY == DISABLED
#    define VSF_USART_CFG_REIMPLEMENT_TYPE_CAPABILITY DISABLED
#endif
 
#ifndef VSF_USART_CFG_INHERT_HAL_CAPABILITY
#   define VSF_USART_CFG_INHERT_HAL_CAPABILITY      ENABLED
#endif
 
#ifndef VSF_USART_CFG_REQUEST_API
#   define VSF_USART_CFG_REQUEST_API                ENABLED
#endif
 
#ifndef VSF_USART_CFG_FIFO_API
#   define VSF_USART_CFG_FIFO_API                   ENABLED
#endif
 
/*============================ MACROFIED FUNCTIONS ===========================*/
 
#define __VSF_USART_BASE_APIS(__prefix_name) \
    __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)
 
#if VSF_USART_CFG_FIFO_API == ENABLED
#   define __VSF_USART_FIFO_APIS(__prefix_name) \
        __VSF_HAL_TEMPLATE_API(__prefix_name, uint_fast16_t,      usart, rxfifo_get_data_count, VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr) \
        __VSF_HAL_TEMPLATE_API(__prefix_name, uint_fast16_t,      usart, rxfifo_read,           VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr, void *buffer_ptr, uint_fast16_t count) \
        __VSF_HAL_TEMPLATE_API(__prefix_name, uint_fast16_t,      usart, txfifo_get_free_count, VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr) \
        __VSF_HAL_TEMPLATE_API(__prefix_name, uint_fast16_t,      usart, txfifo_write,          VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr, void *buffer_ptr, uint_fast16_t count)
#else
#   define __VSF_USART_FIFO_APIS(__prefix_name)
#endif
 
#if VSF_USART_CFG_REQUEST_API == ENABLED
#   define __VSF_USART_REQUEST_APIS(__prefix_name) \
        __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)
#else
#   define __VSF_USART_REQUEST_APIS(__prefix_name)
#endif
 
#define __VSF_USART_REQUEST_EXTRA_APIS(__prefix_name)                           \
        __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,          usart, cmd,                   VSF_MCONNECT(__prefix_name, _usart_t) *usart_ptr, vsf_usart_cmd_t cmd, void* param)
 
#define VSF_USART_ADDITIONAL_APIS(__prefix_name)                                \
    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_cmd)(usart_ptr,               \
            VSF_USART_CMD_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_cmd)(usart_ptr,               \
            VSF_USART_CMD_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_cmd)(usart_ptr,               \
            VSF_USART_CMD_CLEAR_BREAK, NULL);                                   \
    }
 
#define VSF_USART_APIS(__prefix_name)                                           \
    __VSF_USART_BASE_APIS(__prefix_name)                                        \
    __VSF_USART_FIFO_APIS(__prefix_name)                                        \
    __VSF_USART_REQUEST_APIS(__prefix_name)                                     \
    __VSF_USART_REQUEST_EXTRA_APIS(__prefix_name)
 
/*============================ TYPES =========================================*/
 
#if VSF_USART_CFG_REIMPLEMENT_TYPE_MODE == DISABLED
typedef 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_SYNC_CLOCK_POLARITY_LOW                   = (0x0ul << 12),
    VSF_USART_SYNC_CLOCK_POLARITY_HIGH                  = (0x1ul << 12),
    VSF_USART_SYNC_CLOCK_PHASE_1_EDGE                   = (0x0ul << 13),
    VSF_USART_SYNC_CLOCK_PHASE_2_EDGE                   = (0x1ul << 13),
 
    VSF_USART_HALF_DUPLEX_DISABLE                       = (0x0ul << 14),
    VSF_USART_HALF_DUPLEX_ENABLE                        = (0x1ul << 14),
 
    /*
        // Here are some examples of fifo implementations
 
        // Example A of driver-specific threshold
        VSF_USART_TX_FIFO_THRESHOLD_1_8                 = (0x0ul << 15),    //!< TX FIFO reaches 1/8 of its depth
        VSF_USART_TX_FIFO_THRESHOLD_1_4                 = (0x1ul << 15),    //!< TX FIFO reaches 1/4 of its depth
        VSF_USART_TX_FIFO_THRESHOLD_1_2                 = (0x2ul << 15),    //!< TX FIFO reaches 1/2 of its depth
        VSF_USART_TX_FIFO_THRESHOLD_3_4                 = (0x3ul << 15),    //!< TX FIFO reaches 3/4 of its depth
        VSF_USART_TX_FIFO_THRESHOLD_7_8                 = (0x4ul << 15),    //!< TX FIFO reaches 7/8 of its depth
        VSF_USART_TX_FIFO_THRESHOLD_EMPTY               = (0x5ul << 15),    //!< TX FIFO becoms empty
        VSF_USART_TX_FIFO_THRESHOLD_HALF_EMPTY          = VSF_USART_TX_FIFO_THRESHOLD_1_2,
        VSF_USART_TX_FIFO_THRESHOLD_NOT_FULL            = (0x6ul << 15),
 
        // Example B of driver-specific threshold
        VSF_USART_TX_FIFO_THRESHOLD_1                   = (0x0ul << 15),    //!<  Triggers VSF_USART_IRQ_MASK_TX interrupt when the data in TX FIFO is less than 1
        VSF_USART_TX_FIFO_THRESHOLD_2                   = (0x1ul << 15),    //!<  Triggers VSF_USART_IRQ_MASK_TX interrupt when the data in TX FIFO is less than 2
        VSF_USART_TX_FIFO_THRESHOLD_3                   = (0x2ul << 15),    //!<  Triggers VSF_USART_IRQ_MASK_TX interrupt when the data in TX FIFO is less than 3
        VSF_USART_TX_FIFO_THRESHOLD_4                   = (0x3ul << 15),    //!<  Triggers VSF_USART_IRQ_MASK_TX interrupt when the data in TX FIFO is less than 4
        VSF_USART_TX_FIFO_THRESHOLD_5                   = (0x4ul << 15),    //!<  Triggers VSF_USART_IRQ_MASK_TX interrupt when the data in TX FIFO is less than 5
        VSF_USART_TX_FIFO_THRESHOLD_6                   = (0x5ul << 15),    //!<  Triggers VSF_USART_IRQ_MASK_TX interrupt when the data in TX FIFO is less than 6
        VSF_USART_TX_FIFO_THRESHOLD_7                   = (0x6ul << 15),    //!<  Triggers VSF_USART_IRQ_MASK_TX interrupt when the data in TX FIFO is less than 7
        VSF_USART_TX_FIFO_THRESHOLD_8                   = (0x7ul << 15),    //!<  Triggers VSF_USART_IRQ_MASK_TX interrupt when the data in TX FIFO is less than 8
        VSF_USART_TX_FIFO_THRESHOLD_EMPTY               = VSF_USART_TX_FIFO_THRESHOLD_1,
        VSF_USART_TX_FIFO_THRESHOLD_HALF_EMPTY          = VSF_USART_TX_FIFO_THRESHOLD_4,
        VSF_USART_TX_FIFO_THRESHOLD_NOT_FULL            = VSF_USART_TX_FIFO_THRESHOLD_8,
    */
    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),
 
    /*
        // Here are some examples of fifo implementations
 
        // Example A of driver-specific threshold
        VSF_USART_RX_FIFO_THRESHOLD_1_8                 = (0x0ul << 17),    //!< RX FIFO reaches 1/8 of its depth
        VSF_USART_RX_FIFO_THRESHOLD_1_4                 = (0x1ul << 17),    //!< RX FIFO reaches 1/4 of its depth
        VSF_USART_RX_FIFO_THRESHOLD_1_2                 = (0x2ul << 17),    //!< RX FIFO reaches 1/2 of its depth
        VSF_USART_RX_FIFO_THRESHOLD_3_4                 = (0x3ul << 17),    //!< RX FIFO reaches 3/4 of its depth
        VSF_USART_RX_FIFO_THRESHOLD_7_8                 = (0x4ul << 17),    //!< RX FIFO reaches 7/8 of its depth
        VSF_USART_RX_FIFO_THRESHOLD_NOT_EMPTY   = VSF_USART_RX_FIFO_THRESHOLD_1_8,
        VSF_USART_RX_FIFO_THRESHOLD_HALF_FULL           = VSF_USART_RX_FIFO_THRESHOLD_1_2,
        VSF_USART_RX_FIFO_THRESHOLD_FULL                = (0x5ul << 17),    //!< RX FIFO becomes full
 
        // Example B of driver-specific threshold
        VSF_USART_RX_FIFO_THRESHOLD_1                   = (0x0ul << 17),
        VSF_USART_RX_FIFO_THRESHOLD_2                   = (0x1ul << 17),
        VSF_USART_RX_FIFO_THRESHOLD_3                   = (0x2ul << 17),
        VSF_USART_RX_FIFO_THRESHOLD_4                   = (0x3ul << 17),
        VSF_USART_RX_FIFO_THRESHOLD_5                   = (0x4ul << 17),
        VSF_USART_RX_FIFO_THRESHOLD_6                   = (0x5ul << 17),
        VSF_USART_RX_FIFO_THRESHOLD_7                   = (0x6ul << 17),
        VSF_USART_RX_FIFO_THRESHOLD_8                   = (0x7ul << 17),
        VSF_USART_RX_FIFO_THRESHOLD_NOT_EMPTY           = VSF_USART_RX_FIFO_THRESHOLD_1,
        VSF_USART_RX_FIFO_THRESHOLD_HALF_FULL           = VSF_USART_RX_FIFO_THRESHOLD_4,
        VSF_USART_RX_FIFO_THRESHOLD_FULL                = VSF_USART_RX_FIFO_THRESHOLD_8,
    */
    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),    
 
    /* Optional mode
    VSF_USART_IRDA_ENABLE                               = (0x1ul << 18),
    VSF_USART_IRDA_DISABLE                              = (0x0ul << 18),
    #define VSF_USART_IRDA_ENABLE                       VSF_USART_IRDA_ENABLE
    #define VSF_USART_IRDA_DISABLE                      VSF_USART_IRDA_DISABLE
    #define VSF_USART_IRDA_MASK                         VSF_USART_IRDA_ENABLE | VSF_USART_IRDA_DISABLE
 
    VSF_USART_SMARTCARD_ENABLE                          = (0x1ul << 19),
    VSF_USART_SMARTCARD_DISABLE                         = (0x0ul << 19),
    #define VSF_USART_SMARTCARD_ENABLE                  VSF_USART_SMARTCARD_ENABLE
    #define VSF_USART_SMARTCARD_DISABLE                 VSF_USART_SMARTCARD_DISABLE
    #define VSF_USART_SMARTCARD_MASK                    VSF_USART_SMARTCARDENABLE | VSF_USART_SMARTCARD_DISABLE
 
    // whether the clock pulse corresponding to the last transmitted
    VSF_USART_SYNC_CLOCK_LAST_BIT_ENABLE                = (0x0ul << 20),
    VSF_USART_SYNC_CLOCK_LAST_BIT_DISABLE               = (0x0ul << 20),
    #define VSF_USART_SYNC_CLOCK_LAST_BIT_ENABLE        VSF_USART_SYNC_CLOCK_LAST_BIT_ENABLE
    #define VSF_USART_SYNC_CLOCK_LAST_BIT_DISABLE       VSF_USART_SYNC_CLOCK_LAST_BIT_DISABLE
    #define VSF_USART_SYNC_CLOCK_LAST_BIT_MASK          VSF_USART_SYNC_CLOCK_LAST_BIT_ENABLE | \
                                                        VSF_USART_SYNC_CLOCK_LAST_BIT_DISABLE
 
    // divisor of IRDA clock
    VSF_USART_IRDA_PRESCALER_BIT_OFFSET                 = (21),
    VSF_USART_IRDA_PRESCALER_MASK                       = (0xFul << VSF_USART_IRDA_PRESCALER_BIT_OFFSET),
    #define VSF_USART_IRDA_PRESCALER_BIT_OFFSET         VSF_USART_IRDA_PRESCALER_BIT_OFFSET
    #define VSF_USART_IRDA_PRESCALER_MASK               VSF_USART_IRDA_PRESCALER_MASK
    */
} vsf_usart_mode_t;
#endif
 
enum {
#ifndef VSF_USART_PARITY_MASK
    VSF_USART_PARITY_MASK               = VSF_USART_NO_PARITY
                                        | VSF_USART_EVEN_PARITY
                                        | VSF_USART_ODD_PARITY
                                        | VSF_USART_FORCE_0_PARITY
                                        | VSF_USART_FORCE_1_PARITY,
#endif
 
#ifndef VSF_USART_STOPBIT_MASK
    VSF_USART_STOPBIT_MASK              = VSF_USART_1_STOPBIT
                                        | VSF_USART_1_5_STOPBIT
                                        | VSF_USART_0_5_STOPBIT
                                        | VSF_USART_2_STOPBIT,
#endif
 
#ifndef VSF_USART_BIT_LENGTH_MASK
    VSF_USART_BIT_LENGTH_MASK           = VSF_USART_5_BIT_LENGTH
                                        | VSF_USART_6_BIT_LENGTH
                                        | VSF_USART_7_BIT_LENGTH
                                        | VSF_USART_8_BIT_LENGTH
                                        | VSF_USART_9_BIT_LENGTH
                                        | VSF_USART_10_BIT_LENGTH,
#endif
 
#ifndef VSF_USART_TX_FIFO_THRESHOLD_MASK
    VSF_USART_TX_FIFO_THRESHOLD_MASK    = VSF_USART_TX_FIFO_THRESHOLD_EMPTY
                                        | VSF_USART_TX_FIFO_THRESHOLD_HALF_EMPTY
                                        | VSF_USART_TX_FIFO_THRESHOLD_NOT_FULL,
#endif
 
#ifndef VSF_USART_RX_FIFO_THRESHOLD_MASK
    VSF_USART_RX_FIFO_THRESHOLD_MASK    = VSF_USART_RX_FIFO_THRESHOLD_NOT_EMPTY
                                        | VSF_USART_RX_FIFO_THRESHOLD_FULL
                                        | VSF_USART_RX_FIFO_THRESHOLD_HALF_FULL,
#endif
 
#ifndef VSF_USART_HWCONTROL_MASK
    VSF_USART_HWCONTROL_MASK            = VSF_USART_NO_HWCONTROL
                                        | VSF_USART_RTS_HWCONTROL
                                        | VSF_USART_CTS_HWCONTROL
                                        | VSF_USART_RTS_CTS_HWCONTROL,
#endif
 
    VSF_USART_TX_MASK                   = VSF_USART_TX_ENABLE
                                        | VSF_USART_TX_DISABLE,
 
    VSF_USART_RX_MASK                   = VSF_USART_RX_ENABLE
                                        | VSF_USART_RX_DISABLE,
 
    VSF_USART_SYNC_CLOCK_MASK           = VSF_USART_SYNC_CLOCK_ENABLE
                                        | VSF_USART_SYNC_CLOCK_DISABLE,
 
    VSF_USART_HALF_DUPLEX_MASK          = VSF_USART_HALF_DUPLEX_DISABLE
                                        | VSF_USART_HALF_DUPLEX_ENABLE,
 
    VSF_USART_SYNC_CLOCK_POLARITY_MASK  = VSF_USART_SYNC_CLOCK_POLARITY_LOW
                                        | VSF_USART_SYNC_CLOCK_POLARITY_HIGH,
 
    VSF_USART_SYNC_CLOCK_PHASE_MASK     = VSF_USART_SYNC_CLOCK_PHASE_1_EDGE
                                        | VSF_USART_SYNC_CLOCK_PHASE_2_EDGE,
 
 
 
    VSF_USART_MODE_ALL_BITS_MASK        = VSF_USART_PARITY_MASK
                                        | VSF_USART_STOPBIT_MASK
                                        | VSF_USART_BIT_LENGTH_MASK
                                        | VSF_USART_HWCONTROL_MASK
                                        | VSF_USART_TX_FIFO_THRESHOLD_MASK
                                        | VSF_USART_RX_FIFO_THRESHOLD_MASK
                                        | VSF_USART_TX_MASK
                                        | VSF_USART_RX_MASK
                                        | VSF_USART_SYNC_CLOCK_MASK
                                        | VSF_USART_HALF_DUPLEX_MASK
                                        | VSF_USART_SYNC_CLOCK_POLARITY_MASK
                                        | VSF_USART_SYNC_CLOCK_PHASE_MASK
#ifdef VSF_USART_SYNC_CLOCK_LAST_BIT_MASK
                                        | VSF_USART_SYNC_CLOCK_LAST_BIT_MASK
#endif
 
#ifdef VSF_USART_IRDA_PRESCALER_MASK
                                        | VSF_USART_IRDA_PRESCALER_MASK
#endif
#ifdef VSF_USART_IRDA_MASK
                                        | VSF_USART_IRDA_MASK
#endif
 
#ifdef VSF_USART_SMARTCARD_MASK
                                        | VSF_USART_SMARTCARD_MASK
#endif
};
 
#if VSF_USART_CFG_REIMPLEMENT_TYPE_IRQ_MASK == DISABLED
typedef enum vsf_usart_irq_mask_t {
    // request_rx/request_tx complete
    VSF_USART_IRQ_MASK_TX_CPL           = (0x1ul << 0),
    VSF_USART_IRQ_MASK_RX_CPL           = (0x1ul << 1),
 
    // TX/RX reach fifo threshold, threshold on some devices is bound to 1
    VSF_USART_IRQ_MASK_TX               = (0x1ul << 2),
    VSF_USART_IRQ_MASK_RX               = (0x1ul << 3),
    VSF_USART_IRQ_MASK_RX_TIMEOUT       = (0x1ul << 4),
 
    // clear to send interrupt
    VSF_USART_IRQ_MASK_CTS              = (0x1ul << 5),
 
    // Error interrupt
    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),
 
    /*
    VSF_USART_IRQ_MASK_TX_HALF_CPL      = (0x1ul << 10),
    #define VSF_USART_IRQ_MASK_TX_HALF_CPL VSF_USART_IRQ_MASK_TX_HALF_CPL
    VSF_USART_IRQ_MASK_RX_HALF_CPL      = (0x1ul << 11),
    #define VSF_USART_IRQ_MASK_RX_HALF_CPL VSF_USART_IRQ_MASK_RX_HALF_CPL
 
    VSF_USART_IRQ_MASK_CANCEL_TX_CPL    = (0x1ul << 12),
    #define VSF_USART_IRQ_MASK_CANCEL_TX_CPL VSF_USART_IRQ_MASK_CANCEL_TX_CPL
    VSF_USART_IRQ_MASK_CANCEL_RX_CPL    = (0x1ul << 13),
    #define VSF_USART_IRQ_MASK_CANCEL_RX_CPL VSF_USART_IRQ_MASK_CANCEL_RX_CPL
 
    VSF_USART_IRQ_MASK_NOISE_ERR        = (0x1ul << 14),
    #define VSF_USART_IRQ_MASK_NOISE_ERR VSF_USART_IRQ_MASK_NOISE_ERR
    */
} vsf_usart_irq_mask_t;
#endif
 
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,
 
#ifndef VSF_USART_IRQ_MASK_ERR
    VSF_USART_IRQ_MASK_ERR                  = VSF_USART_IRQ_MASK_FRAME_ERR
                                            | VSF_USART_IRQ_MASK_PARITY_ERR
                                            | VSF_USART_IRQ_MASK_BREAK_ERR
                                            | VSF_USART_IRQ_MASK_OVERFLOW_ERR,
#endif
 
#ifndef VSF_USART_IRQ_ALL_BITS_MASK
    VSF_USART_IRQ_ALL_BITS_MASK             = VSF_USART_IRQ_MASK_TX
                                            | VSF_USART_IRQ_MASK_RX
                                            | VSF_USART_IRQ_MASK_RX_TIMEOUT
                                            | VSF_USART_IRQ_MASK_CTS
                                            | VSF_USART_IRQ_MASK_TX_CPL
                                            | VSF_USART_IRQ_MASK_RX_CPL
                                            | VSF_USART_IRQ_MASK_ERR,
#    ifdef VSF_USART_IRQ_MASK_TX_HALF_CPL
                                            | VSF_USART_IRQ_MASK_TX_HALF_CPL
#    endif
#    ifdef VSF_USART_IRQ_MASK_RX_HALF_CPL
                                            | VSF_USART_IRQ_MASK_RX_HALF_CPL
#    endif
#    ifdef VSF_USART_IRQ_MASK_CANCEL_TX_CPL
                                            | VSF_USART_IRQ_MASK_CANCEL_TX_CPL
#    endif
#    ifdef VSF_USART_IRQ_MASK_CANCEL_RX_CPL
                                            | VSF_USART_IRQ_MASK_CANCEL_RX_CPL
#    endif
#endif
};
 
#if VSF_USART_CFG_REIMPLEMENT_TYPE_CFG == DISABLED
typedef struct vsf_usart_t vsf_usart_t;
 
typedef void vsf_usart_isr_handler_t(void *target_ptr,
                                     vsf_usart_t *usart_ptr,
                                     vsf_usart_irq_mask_t irq_mask);
 
typedef struct vsf_usart_isr_t {
    vsf_usart_isr_handler_t *handler_fn;
    void                    *target_ptr;
    vsf_arch_prio_t          prio;
} vsf_usart_isr_t;
 
typedef struct vsf_usart_cfg_t {
    uint32_t mode;
    uint32_t baudrate;
    uint32_t rx_timeout;
    vsf_usart_isr_t isr;
} vsf_usart_cfg_t;
#endif
 
#if VSF_USART_CFG_REIMPLEMENT_TYPE_CMD == DISABLED
typedef enum vsf_usart_cmd_t {
    VSF_USART_CMD_SEND_BREAK    = (0x01ul << 0),
 
    VSF_USART_CMD_SET_BREAK     = (0x01ul << 1),
    VSF_USART_CMD_CLEAR_BREAK   = (0x01ul << 2),
 
    /*
    VSF_USART_CMD_REQUEST_RX_RESUME                     = (0x1ul << 3),
    #define VSF_USART_CMD_REQUEST_RX_RESUME VSF_USART_CMD_REQUEST_RX_RESUME
    VSF_USART_CMD_REQUEST_TX_RESUME                     = (0x1ul << 4),
    #define VSF_USART_CMD_REQUEST_TX_RESUME VSF_USART_CMD_REQUEST_TX_RESUME
 
    VSF_USART_CMD_REQUEST_RX_PAUSE                      = (0x1ul << 5),
    #define VSF_USART_CMD_REQUEST_RX_PAUSE VSF_USART_CMD_REQUEST_RX_PAUSE
    VSF_USART_CMD_REQUEST_TX_PAUSE                      = (0x1ul << 6),
    #define VSF_USART_CMD_REQUEST_TX_PAUSE VSF_USART_CMD_REQUEST_TX_PAUSE
 
    VSF_USART_CMD_HALF_DUPLEX_ENABLE_TRANSMITTER        = (0x1ul << 7),
    #define VSF_USART_CMD_HALF_DUPLEX_ENABLE_TRANSMITTER VSF_USART_CMD_HALF_DUPLEX_ENABLE_TRANSMITTER
 
    VSF_USART_CMD_HALF_DUPLEX_ENABLE_RECEIVER           = (0x1ul << 8),
    #define VSF_USART_CMD_HALF_DUPLEX_ENABLE_RECEIVER VSF_USART_CMD_HALF_DUPLEX_ENABLE_RECEIVER
    */
} vsf_usart_cmd_t;
#endif
 
#if VSF_USART_CFG_REIMPLEMENT_TYPE_STATUS == DISABLED
typedef struct vsf_usart_status_t {
    union {
        inherit(vsf_peripheral_status_t)
        struct {
            uint32_t is_busy         : 1;
            uint32_t is_tx_busy      : 1;
            uint32_t is_rx_busy      : 1;
            // TX FIFO threshold in bytes
            uint32_t tx_fifo_thresh  : 8;
            // RX FIFO threshold in bytes
            uint32_t rx_fifo_thresh  : 8;
        };
    };
} vsf_usart_status_t;
#endif
 
typedef struct vsf_usart_capability_t {
#if VSF_USART_CFG_INHERT_HAL_CAPABILITY == ENABLED
    inherit(vsf_peripheral_capability_t)
#endif
    vsf_usart_irq_mask_t irq_mask;
 
    // baudrate range
    uint32_t max_baudrate;
    uint32_t min_baudrate;
 
    // TX FIFO depth, in data count (frame)
    uint8_t txfifo_depth;
    // RX FIFO depth, in data count (frame)
    uint8_t rxfifo_depth;
 
    uint8_t max_data_bits;
    uint8_t min_data_bits;
 
    uint8_t support_rx_timeout          : 1;
    uint8_t support_send_break          : 1;
    uint8_t support_set_and_clear_break : 1;
} vsf_usart_capability_t;
 
typedef struct vsf_usart_op_t {
#undef __VSF_HAL_TEMPLATE_API
#define __VSF_HAL_TEMPLATE_API VSF_HAL_TEMPLATE_API_FP
 
    VSF_USART_APIS(vsf)
} vsf_usart_op_t;
 
#if VSF_USART_CFG_MULTI_CLASS == ENABLED
struct vsf_usart_t  {
    const vsf_usart_op_t * op;
};
#endif
 
/*============================ PROTOTYPES ====================================*/
 
extern vsf_err_t vsf_usart_init(vsf_usart_t *usart_ptr, vsf_usart_cfg_t *cfg_ptr);
 
extern void vsf_usart_fini(vsf_usart_t *usart_ptr);
 
extern fsm_rt_t vsf_usart_enable(vsf_usart_t *usart_ptr);
 
extern fsm_rt_t vsf_usart_disable(vsf_usart_t *usart_ptr);
 
extern void vsf_usart_irq_enable(vsf_usart_t *usart_ptr, vsf_usart_irq_mask_t irq_mask);
 
extern void vsf_usart_irq_disable(vsf_usart_t *usart_ptr, vsf_usart_irq_mask_t irq_mask);
 
extern vsf_usart_status_t vsf_usart_status(vsf_usart_t *usart_ptr);
 
extern vsf_usart_capability_t vsf_usart_capability(vsf_usart_t *usart_ptr);
 
extern uint_fast16_t vsf_usart_rxfifo_get_data_count(vsf_usart_t *usart_ptr);
 
extern uint_fast16_t vsf_usart_rxfifo_read(vsf_usart_t *usart_ptr, void *buffer_ptr, uint_fast16_t count);
 
extern uint_fast16_t vsf_usart_txfifo_get_free_count(vsf_usart_t *usart_ptr);
 
extern uint_fast16_t vsf_usart_txfifo_write(vsf_usart_t *usart_ptr, void *buffer_ptr, uint_fast16_t count);
 
extern vsf_err_t vsf_usart_request_rx(vsf_usart_t *usart_ptr, void *buffer_ptr, uint_fast32_t count);
 
extern vsf_err_t vsf_usart_request_tx(vsf_usart_t *usart_ptr, void *buffer_ptr, uint_fast32_t count);
 
extern vsf_err_t vsf_usart_cancel_rx(vsf_usart_t *usart_ptr);
 
extern vsf_err_t vsf_usart_cancel_tx(vsf_usart_t *usart_ptr);
 
extern int_fast32_t vsf_usart_get_rx_count(vsf_usart_t *usart_ptr);
 
extern int_fast32_t vsf_usart_get_tx_count(vsf_usart_t *usart_ptr);
 
extern vsf_err_t vsf_usart_cmd(vsf_usart_t *usart_ptr, vsf_usart_cmd_t cmd, void * param);
 
/*============================ INLINE FUNCTIONS ==============================*/
 
#if VSF_USART_CFG_REIMPLEMENT_MODE_TO_DATA_BITS == DISABLED
static inline uint8_t vsf_usart_mode_to_data_bits(vsf_usart_mode_t mode)
{
    switch (mode & VSF_USART_BIT_LENGTH_MASK) {
    case VSF_USART_5_BIT_LENGTH:
        return 5;
    case VSF_USART_6_BIT_LENGTH:
        return 6;
    case VSF_USART_7_BIT_LENGTH:
        return 7;
    case VSF_USART_8_BIT_LENGTH:
        return 8;
    case VSF_USART_9_BIT_LENGTH:
        return 9;
    case VSF_USART_10_BIT_LENGTH:
        return 10;
    default:
        return 0;
    }
}
#endif
 
static inline vsf_err_t vsf_usart_send_break(vsf_usart_t *usart_ptr)
{
    vsf_usart_capability_t cap = vsf_usart_capability(usart_ptr);
    VSF_HAL_ASSERT(cap.support_send_break);
 
    return vsf_usart_cmd(usart_ptr, VSF_USART_CMD_SEND_BREAK, NULL);
}
 
static inline vsf_err_t vsf_usart_set_break(vsf_usart_t *usart_ptr)
{
    vsf_usart_capability_t cap = vsf_usart_capability(usart_ptr);
    VSF_HAL_ASSERT(cap.support_set_and_clear_break);
 
    return vsf_usart_cmd(usart_ptr, VSF_USART_CMD_SET_BREAK, NULL);
}
 
static inline vsf_err_t vsf_usart_clear_break(vsf_usart_t *usart_ptr)
{
    vsf_usart_capability_t cap = vsf_usart_capability(usart_ptr);
    VSF_HAL_ASSERT(cap.support_set_and_clear_break);
 
    return vsf_usart_cmd(usart_ptr, VSF_USART_CMD_CLEAR_BREAK, NULL);
}
 
/*============================ MACROFIED FUNCTIONS ===========================*/
 
#if VSF_USART_CFG_FUNCTION_RENAME == ENABLED
#   define __vsf_usart_t                                 VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_t)
#   define vsf_usart_init(__USART, ...)                  VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_init)                  ((__vsf_usart_t *)(__USART), ##__VA_ARGS__)
#   define vsf_usart_fini(__USART)                       VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_fini)                  ((__vsf_usart_t *)(__USART))
#   define vsf_usart_capability(__USART)                 VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_capability)            ((__vsf_usart_t *)(__USART))
#   define vsf_usart_enable(__USART)                     VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_enable)                ((__vsf_usart_t *)(__USART))
#   define vsf_usart_disable(__USART)                    VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_disable)               ((__vsf_usart_t *)(__USART))
#   define vsf_usart_irq_enable(__USART, ...)            VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_irq_enable)            ((__vsf_usart_t *)(__USART), ##__VA_ARGS__)
#   define vsf_usart_irq_disable(__USART, ...)           VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_irq_disable)           ((__vsf_usart_t *)(__USART), ##__VA_ARGS__)
#   define vsf_usart_status(__USART)                     VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_status)                ((__vsf_usart_t *)(__USART))
#   define vsf_usart_rxfifo_get_data_count(__USART, ...) VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_rxfifo_get_data_count) ((__vsf_usart_t *)(__USART), ##__VA_ARGS__)
#   define vsf_usart_rxfifo_read(__USART, ...)           VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_rxfifo_read)           ((__vsf_usart_t *)(__USART), ##__VA_ARGS__)
#   define vsf_usart_txfifo_get_free_count(__USART, ...) VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_txfifo_get_free_count) ((__vsf_usart_t *)(__USART), ##__VA_ARGS__)
#   define vsf_usart_txfifo_write(__USART, ...)          VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_txfifo_write)          ((__vsf_usart_t *)(__USART), ##__VA_ARGS__)
#   define vsf_usart_request_rx(__USART, ...)            VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_request_rx)            ((__vsf_usart_t *)(__USART), ##__VA_ARGS__)
#   define vsf_usart_request_tx(__USART, ...)            VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_request_tx)            ((__vsf_usart_t *)(__USART), ##__VA_ARGS__)
#   define vsf_usart_cancel_rx(__USART)                  VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_cancel_rx)             ((__vsf_usart_t *)(__USART))
#   define vsf_usart_cancel_tx(__USART)                  VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_cancel_tx)             ((__vsf_usart_t *)(__USART))
#   define vsf_usart_get_rx_count(__USART)               VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_get_rx_count)          ((__vsf_usart_t *)(__USART))
#   define vsf_usart_get_tx_count(__USART)               VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_get_tx_count)          ((__vsf_usart_t *)(__USART))
#   define vsf_usart_send_break(__USART, ...)            VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_send_break)            ((__vsf_usart_t *)(__USART))
#   define vsf_usart_set_break(__USART)                  VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_send_break)            ((__vsf_usart_t *)(__USART))
#   define vsf_usart_clear_break(__USART)                VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_send_break)            ((__vsf_usart_t *)(__USART))
#   define vsf_usart_cmd(__USART, ...)                   VSF_MCONNECT(VSF_USART_CFG_PREFIX, _usart_cmd)                   ((__vsf_usart_t *)(__USART), ##__VA_ARGS__)
#endif
 
/*============================ INCLUDES ======================================*/
 
#ifdef __cplusplus
}
#endif
 
#endif