vsf_template_timer.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_TIMER_H__
#define __VSF_TEMPLATE_TIMER_H__
 
/*============================ INCLUDES ======================================*/
 
#include "./vsf_template_hal_driver.h"
#include "hal/arch/vsf_arch.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*============================ MACROS ========================================*/
 
#ifndef VSF_TIMER_CFG_MULTI_CLASS
#   define VSF_TIMER_CFG_MULTI_CLASS                    ENABLED
#endif
 
#if defined(VSF_HW_TIMER_COUNT) && !defined(VSF_HW_TIMER_MASK)
#   define VSF_HW_TIMER_MASK                            VSF_HAL_COUNT_TO_MASK(VSF_HW_TIMER_COUNT)
#endif
 
#if defined(VSF_HW_TIMER_MASK) && !defined(VSF_HW_TIMER_COUNT)
#   define VSF_HW_TIMER_COUNT                           VSF_HAL_MASK_TO_COUNT(VSF_HW_TIMER_MASK)
#endif
 
#ifndef VSF_TIMER_CFG_PREFIX
#   if VSF_TIMER_CFG_MULTI_CLASS == ENABLED
#       define VSF_TIMER_CFG_PREFIX                     vsf
#   elif defined(VSF_HW_TIMER_COUNT) && (VSF_HW_TIMER_COUNT != 0)
#       define VSF_TIMER_CFG_PREFIX                     vsf_hw
#   else
#       define VSF_TIMER_CFG_PREFIX                     vsf
#   endif
#endif
 
#ifndef VSF_TIMER_CFG_FUNCTION_RENAME
#   define VSF_TIMER_CFG_FUNCTION_RENAME                ENABLED
#endif
 
#ifndef VSF_TIMER_CFG_REIMPLEMENT_TYPE_IRQ_MASK
#   define VSF_TIMER_CFG_REIMPLEMENT_TYPE_IRQ_MASK      DISABLED
#endif
 
#ifndef VSF_TIMER_CFG_REIMPLEMENT_TYPE_CFG
#    define VSF_TIMER_CFG_REIMPLEMENT_TYPE_CFG          DISABLED
#endif
 
#ifndef VSF_TIMER_CFG_REIMPLEMENT_TYPE_CHANNEL_MODE
#   define VSF_TIMER_CFG_REIMPLEMENT_TYPE_CHANNEL_MODE  DISABLED
#endif
 
#ifndef VSF_TIMER_CFG_REIMPLEMENT_TYPE_CHANNEL_CFG
#   define VSF_TIMER_CFG_REIMPLEMENT_TYPE_CHANNEL_CFG   DISABLED
#endif
 
#ifndef VSF_TIMER_CFG_REIMPLEMENT_TYPE_CHANNEL_REQUEST
#   define VSF_TIMER_CFG_REIMPLEMENT_TYPE_CHANNEL_REQUEST   DISABLED
#endif
 
#ifndef VSF_TIMER_CFG_REIMPLEMENT_TYPE_STATUS
#   define VSF_TIMER_CFG_REIMPLEMENT_TYPE_STATUS        DISABLED
#endif
 
#ifndef VSF_TIMER_CFG_REIMPLEMENT_TYPE_CTRL
#   define VSF_TIMER_CFG_REIMPLEMENT_TYPE_CTRL          DISABLED
#endif
 
#ifndef VSF_TIMER_CFG_REIMPLEMENT_TYPE_CHANNEL_CTRL
#   define VSF_TIMER_CFG_REIMPLEMENT_TYPE_CHANNEL_CTRL DISABLED
#endif
 
#ifndef VSF_TIMER_CFG_REIMPLEMENT_TYPE_CAPABILITY
#   define VSF_TIMER_CFG_REIMPLEMENT_TYPE_CAPABILITY   DISABLED
#endif
 
#ifndef VSF_TIMER_CFG_INHERIT_HAL_CAPABILITY
#   define VSF_TIMER_CFG_INHERIT_HAL_CAPABILITY          ENABLED
#endif
 
#ifndef __VSF_TIMER_CFG_SUPPORT_STANDARD_OPTIONAL
#   define __VSF_TIMER_CFG_SUPPORT_STANDARD_OPTIONAL DISABLED
#endif
 
/*============================ MACROFIED FUNCTIONS ===========================*/
 
#define VSF_TIMER_APIS(__prefix_name) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              timer, init,                  VSF_MCONNECT(__prefix_name, _t) *timer_ptr, vsf_timer_cfg_t *cfg_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, void,                   timer, fini,                  VSF_MCONNECT(__prefix_name, _t) *timer_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              timer, get_configuration,     VSF_MCONNECT(__prefix_name, _t) *timer_ptr, vsf_timer_cfg_t *cfg_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, fsm_rt_t,               timer, enable,                VSF_MCONNECT(__prefix_name, _t) *timer_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, fsm_rt_t,               timer, disable,               VSF_MCONNECT(__prefix_name, _t) *timer_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, void,                   timer, irq_enable,            VSF_MCONNECT(__prefix_name, _t) *timer_ptr, vsf_timer_irq_mask_t irq_mask) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, void,                   timer, irq_disable,           VSF_MCONNECT(__prefix_name, _t) *timer_ptr, vsf_timer_irq_mask_t irq_mask) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_timer_irq_mask_t,   timer, irq_clear,             VSF_MCONNECT(__prefix_name, _t) *timer_ptr, vsf_timer_irq_mask_t irq_mask) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_timer_status_t,     timer, status,                VSF_MCONNECT(__prefix_name, _t) *timer_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_timer_capability_t, timer, capability,            VSF_MCONNECT(__prefix_name, _t) *timer_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              timer, set_period,            VSF_MCONNECT(__prefix_name, _t) *timer_ptr, uint32_t period) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, uint32_t,               timer, get_counter,           VSF_MCONNECT(__prefix_name, _t) *timer_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              timer, set_counter,           VSF_MCONNECT(__prefix_name, _t) *timer_ptr, uint32_t value, vsf_timer_set_counter_mode_t mode) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              timer, ctrl,                  VSF_MCONNECT(__prefix_name, _t) *timer_ptr, vsf_timer_ctrl_t ctrl, void* param) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              timer, channel_config,        VSF_MCONNECT(__prefix_name, _t) *timer_ptr, uint8_t channel, vsf_timer_channel_cfg_t *channel_cfg_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              timer, channel_start,         VSF_MCONNECT(__prefix_name, _t) *timer_ptr, uint8_t channel) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              timer, channel_stop,          VSF_MCONNECT(__prefix_name, _t) *timer_ptr, uint8_t channel) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              timer, channel_request_start, VSF_MCONNECT(__prefix_name, _t) *timer_ptr, uint8_t channel, vsf_timer_channel_request_t *request_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              timer, channel_request_stop,  VSF_MCONNECT(__prefix_name, _t) *timer_ptr, uint8_t channel) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              timer, channel_ctrl,          VSF_MCONNECT(__prefix_name, _t) *timer_ptr, uint8_t channel, vsf_timer_channel_ctrl_t ctrl, void* param)
 
/*============================ TYPES =========================================*/
 
#if VSF_TIMER_CFG_REIMPLEMENT_TYPE_CHANNEL_MODE == DISABLED
typedef enum vsf_timer_channel_mode_t {
    // channel mode : different timer channel may support different mode
    // Base Mode : The timer channel will be used as a base timer
    VSF_TIMER_CHANNEL_MODE_BASE             = (0x00 << 0),
 
#if __VSF_TIMER_CFG_SUPPORT_STANDARD_OPTIONAL
    // \~english Some timer may support more mode like PWM, Output Compare etc.
    // \~chinese 有些定时器可能支持更多的模式，如 PWM、输出比较等。
 
    // \~english PWM(Pulse Width Modulation) Mode : The timer channel will be used as a
    // PWM output, all channels's period should be the same
    // \~chinese PWM（脉宽调制）模式：定时器通道将用作 PWM 输出，所有通道的周期应该相同
    VSF_TIMER_CHANNEL_MODE_PWM              = (0x01 << 0),
#   define VSF_TIMER_CHANNEL_MODE_PWM  VSF_TIMER_CHANNEL_MODE_PWM
 
    // \~english Output Compare Mode: The timer channel will be used as a output compare,
    //           different channels can have different period (change pin level in interrupt)
    //           PWM mode can be seen as a special case of output compare mode, that is all
    //           channels have the same period.
    // \~chinese 输出比较模式：定时器通道将用作输出比较，不同通道可以有不同的周期（在中断中改变引脚电平）。
    //           PWM 模式可以看作是输出比较模式的一种特殊情况，即所有通道的周期相同。
    VSF_TIMER_CHANNEL_MODE_OUTPUT_COMPARE   = (0x02 << 0),
#   define VSF_TIMER_CHANNEL_MODE_OUTPUT_COMPARE  VSF_TIMER_CHANNEL_MODE_OUTPUT_COMPARE
 
    // \~english Input Capture Mode : The timer channel will be used as a input capture
    // \~chinese 输入捕获模式：定时器通道将用作输入捕获
    VSF_TIMER_CHANNEL_MODE_INPUT_CAPTURE    = (0x03 << 0),
#   define VSF_TIMER_CHANNEL_MODE_INPUT_CAPTURE  VSF_TIMER_CHANNEL_MODE_INPUT_CAPTURE
 
    // \~english Encoder Mode : The timer channel will be used as a encoder
    // \~chinese 编码器模式：定时器通道将用作编码器
    VSF_TIMER_CHANNEL_MODE_ENCODER          = (0x04 << 0),
#   define VSF_TIMER_CHANNEL_MODE_ENCODER  VSF_TIMER_CHANNEL_MODE_ENCODER
 
    // \~english One Pulse Mode : The timer channel will be used as a one pulse mode
    // \~chinese 单脉冲模式：定时器通道将用作单脉冲模式
    VSF_TIMER_CHANNEL_MODE_ONE_PULSE        = (0x05 << 0),
#   define VSF_TIMER_CHANNEL_MODE_ONE_PULSE  VSF_TIMER_CHANNEL_MODE_ONE_PULSE
 
    // \~english Hall Sensor Mode : The timer channel will be used as a hall sensor
    // \~chinese 霍尔传感器模式：定时器通道将用作霍尔传感器
    VSF_TIMER_CHANNEL_MODE_HALL_SENSOR      = (0x06 << 0),
#   define VSF_TIMER_CHANNEL_MODE_HALL_SENSOR  VSF_TIMER_CHANNEL_MODE_HALL_SENSOR
#endif
 
    /********************************************************************************/
 
    // Counter Mode
    // Oneshot : The timer will stop after the first overflow
    VSF_TIMER_BASE_ONESHOT                      = (0x00 << 5),
    // Continues : The timer will continue to count after overflow
    VSF_TIMER_BASE_CONTINUES                    = (0x01 << 5),
#if __VSF_TIMER_CFG_SUPPORT_STANDARD_OPTIONAL
    // \~english Some timer may support more counter direction like center-aligned etc.
    //           The following mode only valid for VSF_TIMER_CHANNEL_MODE_BASE
    // \~chinese 有些定时器可能支持更多的计数模式，如中心对齐等。以下模式仅适用于 VSF_TIMER_CHANNEL_MODE_BASE
    VSF_TIMER_BASE_COUNTER_UP                   = (0x00 << 4),
#   define VSF_TIMER_BASE_COUNTER_UP  VSF_TIMER_BASE_COUNTER_UP
    VSF_TIMER_BASE_COUNTER_DOWN                 = (0x01 << 4),
#   define VSF_TIMER_BASE_COUNTER_DOWN  VSF_TIMER_BASE_COUNTER_DOWN
    VSF_TIMER_BASE_COUNTER_CENTER_ALIGNED1      = (0x02 << 4),
#   define VSF_TIMER_BASE_COUNTER_CENTER_ALIGNED1  VSF_TIMER_BASE_COUNTER_CENTER_ALIGNED1
    VSF_TIMER_BASE_COUNTER_CENTER_ALIGNED2      = (0x03 << 4),
#   define VSF_TIMER_BASE_COUNTER_CENTER_ALIGNED2  VSF_TIMER_BASE_COUNTER_CENTER_ALIGNED2
    VSF_TIMER_BASE_COUNTER_CENTER_ALIGNED3      = (0x04 << 4),
#   define VSF_TIMER_BASE_COUNTER_CENTER_ALIGNED3  VSF_TIMER_BASE_COUNTER_CENTER_ALIGNED3
 
    // \~english Some timer may support more clock division like 1, 2, 4 etc.
    // \~chinese 有些定时器可能支持更多的时钟分频，如 1、2、4 等。
    VSF_TIEMR_BASE_CLOCKDIVISION_DIV_1           = (0x00 << 8),
#   define VSF_TIEMR_BASE_CLOCKDIVISION_DIV_1  VSF_TIEMR_BASE_CLOCKDIVISION_DIV_1
    VSF_TIEMR_BASE_CLOCKDIVISION_DIV_2           = (0x01 << 8),
#   define VSF_TIEMR_BASE_CLOCKDIVISION_DIV_2  VSF_TIEMR_BASE_CLOCKDIVISION_DIV_2
    VSF_TIEMR_BASE_CLOCKDIVISION_DIV_4           = (0x02 << 8),
#   define VSF_TIEMR_BASE_CLOCKDIVISION_DIV_4  VSF_TIEMR_BASE_CLOCKDIVISION_DIV_4
#endif
 
#if __VSF_TIMER_CFG_SUPPORT_STANDARD_OPTIONAL
    /********************************************************************************/
    // \~english The following mode only valid for VSF_TIMER_CHANNEL_MODE_PWM
    // \~chinese 以下模式仅适用于 VSF_TIMER_CHANNEL_MODE_PWM
    // Output Compare Mode
    VSF_TIMER_OUTPUT_COMPARE_ACTIVE             = (0x00 << 4),
#   define VSF_TIMER_OUTPUT_COMPARE_ACTIVE  VSF_TIMER_OUTPUT_COMPARE_ACTIVE
    VSF_TIMER_OUTPUT_COMPARE_INACTIVE           = (0x01 << 4),
#   define VSF_TIMER_OUTPUT_COMPARE_INACTIVE  VSF_TIMER_OUTPUT_COMPARE_INACTIVE
    VSF_TIMER_OUTPUT_COMPARE_TOGGLE             = (0x02 << 4),
#   define VSF_TIMER_OUTPUT_COMPARE_TOGGLE  VSF_TIMER_OUTPUT_COMPARE_TOGGLE
    VSF_TIMER_OUTPUT_COMPARE_PWM1               = (0x03 << 4),
#   define VSF_TIMER_OUTPUT_COMPARE_PWM1  VSF_TIMER_OUTPUT_COMPARE_PWM1
    VSF_TIMER_OUTPUT_COMPARE_PWM2               = (0x04 << 4),
#   define VSF_TIMER_OUTPUT_COMPARE_PWM2  VSF_TIMER_OUTPUT_COMPARE_PWM2
    VSF_TIMER_OUTPUT_COMPARE_FORCED_ACTIVE      = (0x05 << 4),
#   define VSF_TIMER_OUTPUT_COMPARE_FORCED_ACTIVE  VSF_TIMER_OUTPUT_COMPARE_FORCED_ACTIVE
    VSF_TIMER_OUTPUT_COMPARE_FORCED_INACTIVE    = (0x06 << 4),
#   define VSF_TIMER_OUTPUT_COMPARE_FORCED_INACTIVE  VSF_TIMER_OUTPUT_COMPARE_FORCED_INACTIVE
 
    /********************************************************************************/
    // \~english The following mode only valid for VSF_TIMER_CHANNEL_MODE_OUTPUT_COMPARE
    // \~chinese 以下模式仅适用于 VSF_TIMER_CHANNEL_MODE_OUTPUT_COMPARE
 
    // \~english Output Compare Polarity and N Polarity
    // \~chinese 输出比较极性和 N 极性
    VSF_TIMER_OUTPUT_COMPARE_POLARITY_HIGH      = (0x00 << 8),
#   define VSF_TIMER_OUTPUT_COMPARE_POLARITY_HIGH  VSF_TIMER_OUTPUT_COMPARE_POLARITY_HIGH
    VSF_TIMER_OUTPUT_COMPARE_POLARITY_LOW       = (0x01 << 8),
#   define VSF_TIMER_OUTPUT_COMPARE_POLARITY_LOW   VSF_TIMER_OUTPUT_COMPARE_POLARITY_LOW
    VSF_TIMER_OUTPUT_COMPARE_N_POLARITY_HIGH    = (0x00 << 8),
#   define VSF_TIMER_OUTPUT_COMPARE_N_POLARITY_HIGH  VSF_TIMER_OUTPUT_COMPARE_N_POLARITY_HIGH
    VSF_TIMER_OUTPUT_COMPARE_N_POLARITY_LOW     = (0x01 << 8),
#   define VSF_TIMER_OUTPUT_COMPARE_N_POLARITY_LOW   VSF_TIMER_OUTPUT_COMPARE_N_POLARITY_LOW
 
    /********************************************************************************/
    // \~english The following mode only valid for VSF_TIMER_CHANNEL_MODE_PWM
    // \~chinese 以下模式仅适用于 VSF_TIMER_CHANNEL_MODE_PWM
 
    // \~english PWM Output Polarity
    // \~chinese PWM 输出极性
    VSF_TIMER_PWM_OUTPUT_POLARITY_HIGH                  = (0x00 << 4),
#   define VSF_TIMER_PWM_OUTPUT_POLARITY_HIGH  VSF_TIMER_PWM_OUTPUT_POLARITY_HIGH
    VSF_TIMER_PWM_OUTPUT_POLARITY_LOW                   = (0x01 << 4),
#   define VSF_TIMER_PWM_OUTPUT_POLARITY_LOW   VSF_TIMER_PWM_OUTPUT_POLARITY_LOW
 
    /********************************************************************************/
    // \~english The following mode only valid for VSF_TIMER_CHANNEL_MODE_INPUT_CAPTURE
    // \~chinese 以下模式仅适用于 VSF_TIMER_CHANNEL_MODE_INPUT_CAPTURE
 
    // \~english Input Capture Polarity
    // \~chinese 输入捕获极性
    VSF_TIMER_INPUT_CAPTURE_POLARITY_RISING             = (0x00 << 4),
#   define VSF_TIMER_INPUT_CAPTURE_POLARITY_RISING  VSF_TIMER_INPUT_CAPTURE_POLARITY_RISING
    VSF_TIMER_INPUT_CAPTURE_POLARITY_FALLING            = (0x01 << 4),
#   define VSF_TIMER_INPUT_CAPTURE_POLARITY_FALLING  VSF_TIMER_INPUT_CAPTURE_POLARITY_FALLING
    VSF_TIMER_INPUT_CAPTURE_POLARITY_BOTH               = (0x02 << 4),
#   define VSF_TIMER_INPUT_CAPTURE_POLARITY_BOTH  VSF_TIMER_INPUT_CAPTURE_POLARITY_BOTH
 
    // \~english Input Capture Filter
    // \~chinese 输入捕获滤波
    VSF_TIMER_INPUT_CAPTURE_FILTER_MASK                 = (0x0F << 4),
    VSF_TIMER_INPUT_CAPTURE_FILTER_OFFSET               = 4,
#endif
 
#if __VSF_TIMER_CFG_SUPPORT_STANDARD_OPTIONAL
    /********************************************************************************/
    // \~english The following mode only valid for VSF_TIMER_CHANNEL_MODE_ENCODER
    // \~chinese 以下模式仅适用于 VSF_TIMER_CHANNEL_MODE_ENCODER
 
    // \~english Encoder Mode
    // \~chinese 编码器模式
    VSF_TIMER_ENCODER_CHANNEL_A_POLARITY_RISING         = (0x00 << 4),
#   define VSF_TIMER_ENCODER_CHANNEL_A_POLARITY_RISING  VSF_TIMER_ENCODER_CHANNEL_A_POLARITY_RISING
    VSF_TIMER_ENCODER_CHANNEL_A_POLARITY_FALLING        = (0x01 << 4),
#   define VSF_TIMER_ENCODER_CHANNEL_A_POLARITY_FALLING  VSF_TIMER_ENCODER_CHANNEL_A_POLARITY_FALLING
    VSF_TIMER_ENCODER_CHANNEL_A_POLARITY_BOTH           = (0x02 << 4),
#   define VSF_TIMER_ENCODER_CHANNEL_A_POLARITY_BOTH  VSF_TIMER_ENCODER_CHANNEL_A_POLARITY_BOTH
    VSF_TIMER_ENCODER_CHANNEL_B_POLARITY_RISING         = (0x00 << 6),
#   define VSF_TIMER_ENCODER_CHANNEL_B_POLARITY_RISING  VSF_TIMER_ENCODER_CHANNEL_B_POLARITY_RISING
    VSF_TIMER_ENCODER_CHANNEL_B_POLARITY_FALLING        = (0x01 << 6),
#   define VSF_TIMER_ENCODER_CHANNEL_B_POLARITY_FALLING  VSF_TIMER_ENCODER_CHANNEL_B_POLARITY_FALLING
    VSF_TIMER_ENCODER_CHANNEL_B_POLARITY_BOTH           = (0x02 << 6),
#   define VSF_TIMER_ENCODER_CHANNEL_B_POLARITY_BOTH  VSF_TIMER_ENCODER_CHANNEL_B_POLARITY_BOTH
#endif
} vsf_timer_channel_mode_t;
#endif
 
enum {
#ifndef VSF_TIMER_CHANNEL_MODE_MASK
    VSF_TIMER_CHANNEL_MODE_MASK = VSF_TIMER_CHANNEL_MODE_BASE
#ifdef VSF_TIMER_CHANNEL_MODE_PWM
                                | VSF_TIMER_CHANNEL_MODE_PWM
#endif
#ifdef VSF_TIMER_CHANNEL_MODE_OUTPUT_COMPARE
                                | VSF_TIMER_CHANNEL_MODE_OUTPUT_COMPARE
#endif
#ifdef VSF_TIMER_CHANNEL_MODE_INPUT_CAPTURE
                                | VSF_TIMER_CHANNEL_MODE_INPUT_CAPTURE
#endif
#ifdef VSF_TIMER_CHANNEL_MODE_ENCODER
                                | VSF_TIMER_CHANNEL_MODE_ENCODER
#endif
#ifdef VSF_TIMER_CHANNEL_MODE_ONE_PULSE
                                | VSF_TIMER_CHANNEL_MODE_ONE_PULSE
#endif
#ifdef VSF_TIMER_CHANNEL_MODE_HALL_SENSOR
                                | VSF_TIMER_CHANNEL_MODE_HALL_SENSOR
#endif
                                ,
#endif
 
#ifndef VSF_TIMER_BASE_COUNTER_MASK
    VSF_TIMER_BASE_COUNTER_MASK = VSF_TIMER_BASE_ONESHOT
                                | VSF_TIMER_BASE_CONTINUES,
#endif
 
#ifndef VSF_TIMER_CHANNEL_MODE_ALL_MASK
    VSF_TIMER_CHANNEL_MODE_ALL_MASK = VSF_TIMER_CHANNEL_MODE_MASK
                                    | VSF_TIMER_BASE_COUNTER_MASK
#endif
};
 
#if VSF_TIMER_CFG_REIMPLEMENT_TYPE_IRQ_MASK == DISABLED
typedef enum vsf_timer_irq_mask_t {
    VSF_TIMER_IRQ_MASK_OVERFLOW = (0x01 << 0),
 
    /*
    // \~english We can define more channel irq mask here
    // \~chinese 我们可以在这里定义更多的通道的不同模式的中断掩码
 
    VSF_TIMER_IRQ_MASK_CHANNEL_0_INPUT_CAPTURE  = (0x01 << 1),
    VSF_TIMER_IRQ_MASK_CHANNEL_0_OUTPUT_COMPARE = (0x01 << 2),
    VSF_TIMER_IRQ_MASK_CHANNEL_0_PWM            = (0x01 << 3),
 
    // We can define more channel irq mask here
    VSF_TIMER_IRQ_MASK_CHANNEL_1_INPUT_CAPTURE = (0x01 << 3),
    #define VSF_TIMER_IRQ_MASK_CHANNEL_1_INPUT_CAPTURE  VSF_TIMER_IRQ_MASK_CHANNEL_1_INPUT_CAPTURE
    VSF_TIMER_IRQ_MASK_CHANNEL_1_OUTPUT_COMPARE = (0x01 << 4),
    #define VSF_TIMER_IRQ_MASK_CHANNEL_1_OUTPUT_COMPARE  VSF_TIMER_IRQ_MASK_CHANNEL_1_OUTPUT_COMPARE
    VSF_TIMER_IRQ_MASK_CHANNEL_2_INPUT_CAPTURE = (0x01 << 5),
    #define VSF_TIMER_IRQ_MASK_CHANNEL_2_INPUT_CAPTURE  VSF_TIMER_IRQ_MASK_CHANNEL_2_INPUT_CAPTURE
    VSF_TIMER_IRQ_MASK_CHANNEL_2_OUTPUT_COMPARE = (0x01 << 6),
    #define VSF_TIMER_IRQ_MASK_CHANNEL_2_OUTPUT_COMPARE  VSF_TIMER_IRQ_MASK_CHANNEL_2_OUTPUT_COMPARE
    */
} vsf_timer_irq_mask_t;
#endif
 
enum {
    VSF_TIMER_IRQ_COUNT         = 1,
    VSF_TIMER_IRQ_ALL_BITS_MASK = VSF_TIMER_IRQ_MASK_OVERFLOW,
};
 
#if VSF_TIMER_CFG_REIMPLEMENT_TYPE_CFG == DISABLED
typedef struct vsf_timer_t vsf_timer_t;
 
typedef void vsf_timer_isr_handler_t(void *target_ptr,
                                     vsf_timer_t *timer_ptr,
                                     vsf_timer_irq_mask_t irq_mask);
 
typedef struct vsf_timer_isr_t {
    vsf_timer_isr_handler_t *handler_fn;
    void *target_ptr;
    vsf_arch_prio_t prio;
} vsf_timer_isr_t;
 
 
typedef struct vsf_timer_cfg_t {
    uint32_t period;          
    union {
        uint32_t freq;
        uint32_t min_freq;
    };
    vsf_timer_isr_t isr;         
} vsf_timer_cfg_t;
#endif
 
#if VSF_TIMER_CFG_REIMPLEMENT_TYPE_CHANNEL_CFG == DISABLED
typedef struct vsf_timer_channel_cfg_t {
    vsf_timer_channel_mode_t mode;
    uint32_t                 pulse;
} vsf_timer_channel_cfg_t;
#endif
 
 
#if VSF_TIMER_CFG_REIMPLEMENT_TYPE_CTRL == DISABLED
typedef enum vsf_timer_ctrl_t {
    __VSF_TIMER_CTRL_DUMMY = 0,
 
    // ------------------------------------------------------------------------
    // Optional members (documented only, not defined here).
    // Concrete hardware drivers may add the following commands by enabling
    // VSF_TIMER_CFG_REIMPLEMENT_TYPE_CTRL and redefining vsf_timer_ctrl_t,
    // together with a same-name macro so callers can probe support via #ifdef.
    // They are optional because each command is only meaningful when the
    // underlying hardware exhibits a specific constraint; drivers without
    // that constraint should simply omit the command.
    //
    //   VSF_TIMER_CTRL_GET_FREQ
    //     Purpose       : return the actual tick frequency chosen by
    //                     vsf_timer_init when the divider is discrete and
    //                     cannot exactly honour the requested min_freq.
    //     Param         : uint32_t * (out) - receives the actual tick freq in Hz.
    //     Returns       : VSF_ERR_NONE on success;
    //                     VSF_ERR_NOT_READY if init has not been called;
    //                     VSF_ERR_NOT_SUPPORT when the driver does not
    //                     implement the command.
    //     Applicability : timer/PWM drivers whose picked tick may overshoot
    //                     min_freq due to non-continuous divider steps;
    //                     drivers that can always match min_freq exactly
    //                     do not need this command.
    //
    // 可选成员（仅文档化，这里不定义）。
    // 具体硬件驱动可通过启用 VSF_TIMER_CFG_REIMPLEMENT_TYPE_CTRL 并重新
    // 定义 vsf_timer_ctrl_t 来增加以下命令，并提供同名宏以便调用方通过
    // #ifdef 在编译期探测是否支持。之所以为可选，是因为每条命令仅在
    // 底层硬件存在特定约束时才有意义；不具备该约束的驱动直接省略即可。
    //
    //   VSF_TIMER_CTRL_GET_FREQ
    //     用途         : 当分频器档位离散、无法精确命中调用方请求的
    //                    min_freq 时，返回 vsf_timer_init 实际选中的
    //                    tick 频率。
    //     参数         : uint32_t *（输出） - 接收实际 tick 频率（单位 Hz）。
    //     返回值       : 成功返回 VSF_ERR_NONE；
    //                    未初始化返回 VSF_ERR_NOT_READY；
    //                    驱动未实现此命令时返回 VSF_ERR_NOT_SUPPORT。
    //     适用场景     : 由于分频档位非连续、实际 tick 可能高于 min_freq
    //                    的 timer/PWM 驱动；能精确命中 min_freq 的驱动
    //                    无需实现此命令。
    // ------------------------------------------------------------------------
} vsf_timer_ctrl_t;
#endif
 
#if VSF_TIMER_CFG_REIMPLEMENT_TYPE_CHANNEL_CTRL == DISABLED
typedef enum vsf_timer_channel_ctrl_t {
    __VSF_TIMER_CHANNEL_CTRL_DUMMY = 0,               
} vsf_timer_channel_ctrl_t;
#endif
 
#if VSF_TIMER_CFG_REIMPLEMENT_TYPE_CHANNEL_CFG == DISABLED
typedef struct vsf_timer_channel_request_t {
    uint16_t length;
    union {
        // for VSF_TIMER_CHANNEL_MODE_BASE mode
        uint32_t *period_buffer;
        // for VSF_TIMER_CHANNEL_MODE_PWM mode and VSF_TIMER_CHANNEL_MODE_OUTPUT_COMPARE mode
        uint32_t *pulse_buffer;
        // for VSF_TIMER_CHANNEL_MODE_INPUT_CAPTURE mode
        uint32_t *input_capture_buffer;
        // for VSF_TIMER_CHANNEL_MODE_ENCODER mode
        struct {
            uint32_t *channel_a_buffer;
            uint32_t *channel_b_buffer;
        };
    };
} vsf_timer_channel_request_t;
#endif
 
#if VSF_TIMER_CFG_REIMPLEMENT_TYPE_SET_COUNTER_MODE == DISABLED
typedef enum vsf_timer_set_counter_mode_t {
    __VSF_TIMER_SET_COUNTER_MODE_DUMMY = 0,
} vsf_timer_set_counter_mode_t;
#endif
 
#if VSF_TIMER_CFG_REIMPLEMENT_TYPE_STATUS == DISABLED
typedef struct vsf_timer_status_t {
    union {
        inherit(vsf_peripheral_status_t)
        uint32_t value;
    };
} vsf_timer_status_t;
#endif
 
 
#if VSF_TIMER_CFG_REIMPLEMENT_TYPE_CAPABILITY == DISABLED
typedef struct vsf_timer_capability_t {
#if VSF_TIMER_CFG_INHERIT_HAL_CAPABILITY == ENABLED
    inherit(vsf_peripheral_capability_t)
#endif
    // support interrupt for timer
    vsf_timer_irq_mask_t irq_mask;
 
    // timer bit length, like 16bit, 32bit etc.
    uint8_t timer_bitlen;
    // timer channel count, like 1, 2, 4 etc.
    uint8_t channel_cnt;
 
    // support different channel mode
    // we can redefine it if different channel support different mode.
    uint8_t support_pwm : 1;
    uint8_t support_output_compare : 1;
    uint8_t support_input_capture : 1;
    uint8_t support_one_pulse : 1;
} vsf_timer_capability_t;
#endif
 
typedef struct vsf_timer_op_t {
#undef __VSF_HAL_TEMPLATE_API
#define __VSF_HAL_TEMPLATE_API VSF_HAL_TEMPLATE_API_FP
 
    VSF_TIMER_APIS(vsf_timer)
} vsf_timer_op_t;
 
#if VSF_TIMER_CFG_MULTI_CLASS == ENABLED
struct vsf_timer_t  {
    const vsf_timer_op_t * op;
};
#endif
 
/*============================ GLOBAL VARIABLES ==============================*/
/*============================ PROTOTYPES ====================================*/
 
extern vsf_err_t vsf_timer_init(vsf_timer_t *timer_ptr, vsf_timer_cfg_t *cfg_ptr);
 
extern void vsf_timer_fini(vsf_timer_t *timer_ptr);
 
extern fsm_rt_t vsf_timer_enable(vsf_timer_t *timer_ptr);
 
extern fsm_rt_t vsf_timer_disable(vsf_timer_t *timer_ptr);
 
extern void vsf_timer_irq_enable(vsf_timer_t *timer_ptr, vsf_timer_irq_mask_t irq_mask);
 
extern void vsf_timer_irq_disable(vsf_timer_t *timer_ptr, vsf_timer_irq_mask_t irq_mask);
 
extern vsf_timer_irq_mask_t vsf_timer_irq_clear(vsf_timer_t *timer_ptr, vsf_timer_irq_mask_t irq_mask);
 
extern vsf_timer_status_t vsf_timer_status(vsf_timer_t *timer_ptr);
 
extern vsf_timer_capability_t vsf_timer_capability(vsf_timer_t *timer_ptr);
 
extern vsf_err_t vsf_timer_get_configuration(vsf_timer_t *timer_ptr, vsf_timer_cfg_t *cfg_ptr);
 
extern vsf_err_t vsf_timer_set_period(vsf_timer_t *timer_ptr, uint32_t period);
 
uint32_t vsf_timer_get_counter(vsf_timer_t *timer_ptr);
 
vsf_err_t vsf_timer_set_counter(vsf_timer_t *timer_ptr, uint32_t value,
                                 vsf_timer_set_counter_mode_t mode);
 
extern vsf_err_t vsf_timer_ctrl(vsf_timer_t *timer_ptr, vsf_timer_ctrl_t ctrl, void *param);
 
extern vsf_err_t vsf_timer_channel_config(vsf_timer_t             *timer_ptr,
                                          uint8_t                 channel,
                                          vsf_timer_channel_cfg_t *channel_cfg_ptr);
 
extern vsf_err_t vsf_timer_channel_start(vsf_timer_t *timer_ptr, uint8_t channel);
 
extern vsf_err_t vsf_timer_channel_stop(vsf_timer_t *timer_ptr, uint8_t channel);
 
extern vsf_err_t vsf_timer_channel_request_start(vsf_timer_t *timer_ptr, uint8_t channel, vsf_timer_channel_request_t *request_ptr);
 
extern vsf_err_t vsf_timer_channel_request_stop(vsf_timer_t *timer_ptr, uint8_t channel);
 
extern vsf_err_t vsf_timer_channel_ctrl(vsf_timer_t *timer_ptr, uint8_t channel, vsf_timer_channel_ctrl_t ctrl, void *param);
 
/*============================ MACROFIED FUNCTIONS ===========================*/
 
#if VSF_TIMER_CFG_FUNCTION_RENAME == ENABLED
#   define __vsf_timer_t                                VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_t)
#   define vsf_timer_init(__TIME, ...)                  VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_init)                 ((__vsf_timer_t *)(__TIME), ##__VA_ARGS__)
#   define vsf_timer_fini(__TIME)                       VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_fini)                 ((__vsf_timer_t *)(__TIME))
#   define vsf_timer_enable(__TIME)                     VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_enable)               ((__vsf_timer_t *)(__TIME))
#   define vsf_timer_disable(__TIME)                    VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_disable)              ((__vsf_timer_t *)(__TIME))
#   define vsf_timer_status(__TIMER)                    VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_status)               ((__vsf_timer_t *)(__TIMER))
#   define vsf_timer_capability(__TIME)                 VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_capability)           ((__vsf_timer_t *)(__TIME))
#   define vsf_timer_get_configuration(__TIME, ...)     VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_get_configuration)    ((__vsf_timer_t *)(__TIME), ##__VA_ARGS__)
#   define vsf_timer_irq_enable(__TIME, ...)            VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_irq_enable)           ((__vsf_timer_t *)(__TIME), ##__VA_ARGS__)
#   define vsf_timer_irq_disable(__TIME, ...)           VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_irq_disable)          ((__vsf_timer_t *)(__TIME), ##__VA_ARGS__)
#   define vsf_timer_irq_clear(__TIME, ...)             VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_irq_clear)            ((__vsf_timer_t *)(__TIME), ##__VA_ARGS__)
#   define vsf_timer_set_period(__TIME, ...)            VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_set_period)           ((__vsf_timer_t *)(__TIME), ##__VA_ARGS__)
#   define vsf_timer_get_counter(__TIME)                VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_get_counter)          ((__vsf_timer_t *)(__TIME))
#   define vsf_timer_set_counter(__TIME, ...)           VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_set_counter)          ((__vsf_timer_t *)(__TIME), ##__VA_ARGS__)
#   define vsf_timer_ctrl(__TIME, ...)                  VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_ctrl)                 ((__vsf_timer_t *)(__TIME), ##__VA_ARGS__)
#   define vsf_timer_channel_config(__TIME, ...)        VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_channel_config)       ((__vsf_timer_t *)(__TIME), ##__VA_ARGS__)
#   define vsf_timer_channel_start(__TIME, ...)         VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_channel_start)        ((__vsf_timer_t *)(__TIME), ##__VA_ARGS__)
#   define vsf_timer_channel_stop(__TIME, ...)          VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_channel_stop)         ((__vsf_timer_t *)(__TIME), ##__VA_ARGS__)
#   define vsf_timer_channel_request_start(__TIME, ...) VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_channel_request_start)((__vsf_timer_t *)(__TIME), ##__VA_ARGS__)
#   define vsf_timer_channel_request_stop(__TIME, ...)  VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_channel_request_stop) ((__vsf_timer_t *)(__TIME), ##__VA_ARGS__)
#   define vsf_timer_channel_ctrl(__TIME, ...)          VSF_MCONNECT(VSF_TIMER_CFG_PREFIX, _timer_channel_ctrl)         ((__vsf_timer_t *)(__TIME), ##__VA_ARGS__)
#endif
 
#ifdef __cplusplus
}
#endif
 
#endif  /*__VSF_TEMPLATE_TIMER_H__*/