vsf_template_flash.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_FLASH_H__
#define __VSF_TEMPLATE_FLASH_H__
 
/*============================ INCLUDES ======================================*/
 
#include "./vsf_template_hal_driver.h"
#include "hal/arch/vsf_arch.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*============================ MACROS ========================================*/
/*============================ MACROFIED FUNCTIONS ===========================*/
 
#ifndef VSF_FLASH_CFG_MULTI_CLASS
#   define VSF_FLASH_CFG_MULTI_CLASS                        ENABLED
#endif
 
#if defined(VSF_HW_FLASH_COUNT) && !defined(VSF_HW_FLASH_MASK)
#   define VSF_HW_FLASH_MASK                                VSF_HAL_COUNT_TO_MASK(VSF_HW_FLASH_COUNT)
#endif
 
#if defined(VSF_HW_FLASH_MASK) && !defined(VSF_HW_FLASH_COUNT)
#   define VSF_HW_FLASH_COUNT                               VSF_HAL_MASK_TO_COUNT(VSF_HW_FLASH_MASK)
#endif
 
#ifndef VSF_FLASH_CFG_PREFIX
#   if VSF_FLASH_CFG_MULTI_CLASS == ENABLED
#       define VSF_FLASH_CFG_PREFIX                         vsf
#   elif defined(VSF_HW_FLASH_COUNT) && (VSF_HW_FLASH_COUNT != 0)
#       define VSF_FLASH_CFG_PREFIX                         vsf_hw
#   else
#       define VSF_FLASH_CFG_PREFIX                         vsf
#   endif
#endif
 
#ifndef VSF_FLASH_CFG_FUNCTION_RENAME
#   define VSF_FLASH_CFG_FUNCTION_RENAME                    ENABLED
#endif
 
#ifndef VSF_FLASH_CFG_REIMPLEMENT_TYPE_IRQ_MASK
#   define VSF_FLASH_CFG_REIMPLEMENT_TYPE_IRQ_MASK          DISABLED
#endif
 
#ifndef VSF_FLASH_CFG_REIMPLEMENT_TYPE_FLASH_SIZE
#   define VSF_FLASH_CFG_REIMPLEMENT_TYPE_FLASH_SIZE        DISABLED
#endif
 
#ifndef VSF_FLASH_CFG_REIMPLEMENT_TYPE_STATUS
#   define VSF_FLASH_CFG_REIMPLEMENT_TYPE_STATUS            DISABLED
#endif
 
#ifndef VSF_FLASH_CFG_REIMPLEMENT_TYPE_CFG
#   define VSF_FLASH_CFG_REIMPLEMENT_TYPE_CFG               DISABLED
#endif
 
#ifndef VSF_FLASH_CFG_REIMPLEMENT_TYPE_CAPABILITY
#   define VSF_FLASH_CFG_REIMPLEMENT_TYPE_CAPABILITY        DISABLED
#endif
 
#ifndef VSF_FLASH_CFG_INHERIT_HAL_CAPABILITY
#   define VSF_FLASH_CFG_INHERIT_HAL_CAPABILITY              ENABLED
#endif
 
#ifndef VSF_FLASH_CFG_REIMPLEMENT_TYPE_CTRL
#   define VSF_FLASH_CFG_REIMPLEMENT_TYPE_CTRL              DISABLED
#endif
 
/*============================ MACROFIED FUNCTIONS ===========================*/
 
#define VSF_FLASH_APIS(__prefix_name) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              flash, init,                  VSF_MCONNECT(__prefix_name, _t) *flash_ptr, vsf_flash_cfg_t *cfg_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, void,                   flash, fini,                  VSF_MCONNECT(__prefix_name, _t) *flash_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              flash, get_configuration,     VSF_MCONNECT(__prefix_name, _t) *flash_ptr, vsf_flash_cfg_t *cfg_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, fsm_rt_t,               flash, enable,                VSF_MCONNECT(__prefix_name, _t) *flash_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, fsm_rt_t,               flash, disable,               VSF_MCONNECT(__prefix_name, _t) *flash_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_flash_status_t,     flash, status,                VSF_MCONNECT(__prefix_name, _t) *flash_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_flash_capability_t, flash, capability,            VSF_MCONNECT(__prefix_name, _t) *flash_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, void,                   flash, irq_enable,            VSF_MCONNECT(__prefix_name, _t) *flash_ptr, vsf_flash_irq_mask_t irq_mask) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, void,                   flash, irq_disable,           VSF_MCONNECT(__prefix_name, _t) *flash_ptr, vsf_flash_irq_mask_t irq_mask) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              flash, erase_one_sector,      VSF_MCONNECT(__prefix_name, _t) *flash_ptr, vsf_flash_size_t offset_of_bytes) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              flash, erase_multi_sector,    VSF_MCONNECT(__prefix_name, _t) *flash_ptr, vsf_flash_size_t offset_of_bytes, vsf_flash_size_t size_of_bytes) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              flash, erase_all,             VSF_MCONNECT(__prefix_name, _t) *flash_ptr) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              flash, write_one_sector,      VSF_MCONNECT(__prefix_name, _t) *flash_ptr, vsf_flash_size_t offset_of_bytes, uint8_t* buffer, vsf_flash_size_t size_of_bytes) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              flash, write_multi_sector,    VSF_MCONNECT(__prefix_name, _t) *flash_ptr, vsf_flash_size_t offset_of_bytes, uint8_t* buffer, vsf_flash_size_t size_of_bytes) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              flash, read_one_sector,       VSF_MCONNECT(__prefix_name, _t) *flash_ptr, vsf_flash_size_t offset_of_bytes, uint8_t* buffer, vsf_flash_size_t size_of_bytes) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              flash, read_multi_sector,     VSF_MCONNECT(__prefix_name, _t) *flash_ptr, vsf_flash_size_t offset_of_bytes, uint8_t* buffer, vsf_flash_size_t size_of_bytes) \
    __VSF_HAL_TEMPLATE_API(__prefix_name, vsf_err_t,              flash, ctrl,                  VSF_MCONNECT(__prefix_name, _t) *flash_ptr, vsf_flash_ctrl_t ctrl, void* param)
 
/*============================ TYPES =========================================*/
 
#if VSF_FLASH_CFG_REIMPLEMENT_TYPE_IRQ_MASK == DISABLED
typedef enum vsf_flash_irq_mask_t {
    VSF_FLASH_IRQ_ERASE_MASK        = (0x1ul << 0),  
    VSF_FLASH_IRQ_WRITE_MASK        = (0x1ul << 1),  
    VSF_FLASH_IRQ_READ_MASK         = (0x1ul << 2),  
 
    VSF_FLASH_IRQ_ERASE_ERROR_MASK  = (0x1ul << 3),  
    VSF_FLASH_IRQ_WRITE_ERROR_MASK  = (0x1ul << 4),  
    VSF_FLASH_IRQ_READ_ERROR_MASK   = (0x1ul << 5),  
} vsf_flash_irq_mask_t;
#endif
 
enum {
    VSF_FLASH_IRQ_COUNT             = 6,
    VSF_FLASH_IRQ_ALL_BITS_MASK     = VSF_FLASH_IRQ_ERASE_MASK       |
                                      VSF_FLASH_IRQ_WRITE_MASK       |
                                      VSF_FLASH_IRQ_READ_MASK        |
                                      VSF_FLASH_IRQ_ERASE_ERROR_MASK |
                                      VSF_FLASH_IRQ_WRITE_ERROR_MASK |
                                      VSF_FLASH_IRQ_READ_ERROR_MASK,
};
 
#if VSF_FLASH_CFG_REIMPLEMENT_TYPE_FLASH_SIZE == DISABLED
typedef uint_fast32_t vsf_flash_size_t;
#endif
 
#if VSF_FLASH_CFG_REIMPLEMENT_TYPE_CFG == DISABLED
typedef struct vsf_flash_t vsf_flash_t;
typedef void vsf_flash_isr_handler_t(void *target_ptr, vsf_flash_t *flash_ptr,
                                     vsf_flash_irq_mask_t mask);
typedef struct vsf_flash_isr_t {
    vsf_flash_isr_handler_t *handler_fn;  
    void                    *target_ptr;  
    vsf_arch_prio_t          prio;        
} vsf_flash_isr_t;
typedef struct vsf_flash_cfg_t {
    vsf_flash_isr_t isr;                  
} vsf_flash_cfg_t;
#endif
 
#if VSF_FLASH_CFG_REIMPLEMENT_TYPE_STATUS == DISABLED
typedef struct vsf_flash_status_t {
    union {
        inherit(vsf_peripheral_status_t)
        struct {
            uint32_t is_busy : 1;         
        };
    };
} vsf_flash_status_t;
#endif
 
#if VSF_FLASH_CFG_REIMPLEMENT_TYPE_CAPABILITY == DISABLED
typedef struct vsf_flash_capability_t {
#if VSF_FLASH_CFG_INHERIT_HAL_CAPABILITY == ENABLED
    inherit(vsf_peripheral_capability_t)
#endif
    vsf_flash_irq_mask_t irq_mask;
 
    vsf_flash_size_t base_address;
    vsf_flash_size_t max_size;
    vsf_flash_size_t erase_sector_size;
    vsf_flash_size_t write_sector_size;
    struct {
        // Some flash allow only full sectors to be write or read
        uint8_t none_sector_aligned_write : 1;
        uint8_t none_sector_aligned_read  : 1;
    };
} vsf_flash_capability_t;
#endif
 
#if VSF_FLASH_CFG_REIMPLEMENT_TYPE_CTRL == DISABLED
typedef enum vsf_flash_ctrl_t {
    __VSF_FLASH_CTRL_DUMMY = 0,
 
    /*
    VSF_FLASH_CTRL_REQUEST_PAUSE  = (0x1ul << 0),    //! \~english Request to pause Flash operation \~chinese 请求暂停 Flash 操作
    VSF_FLASH_CTRL_REQUEST_RESUME = (0x1ul << 1),    //! \~english Request to resume Flash operation \~chinese 请求恢复 Flash 操作
    #define VSF_FLASH_CTRL_REQUEST_PAUSE VSF_FLASH_CTRL_REQUEST_PAUSE
    #define VSF_FLASH_CTRL_REQUEST_RESUME VSF_FLASH_CTRL_REQUEST_RESUME
    */
 
    /*
    VSF_FLASH_CTRL_POWER_DOWN    = (0x1ul << 2),    //! \~english Put Flash into power down mode \~chinese 使 Flash 进入掉电模式
    VSF_FLASH_CTRL_POWER_UP      = (0x1ul << 3),    //! \~english Wake Flash from power down mode \~chinese 从掉电模式唤醒 Flash
    #define VSF_FLASH_CTRL_POWER_DOWN VSF_FLASH_CTRL_POWER_DOWN
    #define VSF_FLASH_CTRL_POWER_UP VSF_FLASH_CTRL_POWER_UP
    */
} vsf_flash_ctrl_t;
#endif
 
typedef struct vsf_flash_op_t {
#undef __VSF_HAL_TEMPLATE_API
#define __VSF_HAL_TEMPLATE_API VSF_HAL_TEMPLATE_API_FP
 
    VSF_FLASH_APIS(vsf_flash)
} vsf_flash_op_t;
 
#if VSF_FLASH_CFG_MULTI_CLASS == ENABLED
struct vsf_flash_t {
    const vsf_flash_op_t * op;
};
#endif
 
/*============================ GLOBAL VARIABLES ==============================*/
/*============================ PROTOTYPES ====================================*/
 
extern vsf_err_t vsf_flash_init(vsf_flash_t *flash_ptr, vsf_flash_cfg_t *cfg_ptr);
 
extern void vsf_flash_fini(vsf_flash_t *flash_ptr);
 
extern vsf_err_t vsf_flash_get_configuration(vsf_flash_t *flash_ptr, vsf_flash_cfg_t *cfg_ptr);
 
extern fsm_rt_t vsf_flash_enable(vsf_flash_t *flash_ptr);
 
extern fsm_rt_t vsf_flash_disable(vsf_flash_t *flash_ptr);
 
extern vsf_flash_status_t vsf_flash_status(vsf_flash_t *flash_ptr);
 
extern vsf_flash_capability_t vsf_flash_capability(vsf_flash_t *flash_ptr);
 
 
extern void vsf_flash_irq_enable(vsf_flash_t *flash_ptr, vsf_flash_irq_mask_t irq_mask);
 
extern void vsf_flash_irq_disable(vsf_flash_t *flash_ptr, vsf_flash_irq_mask_t irq_mask);
 
extern vsf_err_t vsf_flash_erase_one_sector(vsf_flash_t *flash_ptr,
                                            vsf_flash_size_t offset_of_bytes);
 
extern vsf_err_t vsf_flash_erase_multi_sector(vsf_flash_t *flash_ptr,
                                              vsf_flash_size_t offset_of_bytes,
                                              vsf_flash_size_t size_of_bytes);
 
extern vsf_err_t vsf_flash_erase_all(vsf_flash_t *flash_ptr);
 
 
extern vsf_err_t vsf_flash_write_one_sector(vsf_flash_t *flash_ptr,
                                            vsf_flash_size_t offset_of_bytes,
                                            uint8_t* buffer,
                                            vsf_flash_size_t size_of_bytes);
 
extern vsf_err_t vsf_flash_write_multi_sector(vsf_flash_t *flash_ptr,
                                              vsf_flash_size_t offset_of_bytes,
                                              uint8_t* buffer,
                                              vsf_flash_size_t size_of_bytes);
 
extern vsf_err_t vsf_flash_read_one_sector(vsf_flash_t *flash_ptr,
                                           vsf_flash_size_t offset_of_bytes,
                                           uint8_t* buffer,
                                           vsf_flash_size_t size_of_bytes);
 
extern vsf_err_t vsf_flash_read_multi_sector(vsf_flash_t *flash_ptr,
                                             vsf_flash_size_t offset_of_bytes,
                                             uint8_t* buffer,
                                             vsf_flash_size_t size_of_bytes);
 
extern vsf_err_t vsf_flash_ctrl(vsf_flash_t *flash_ptr, vsf_flash_ctrl_t ctrl, void *param);
 
/*============================ MACROFIED FUNCTIONS ===========================*/
 
#if VSF_FLASH_CFG_FUNCTION_RENAME == ENABLED
#   define __vsf_flash_t                              VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_t)
#   define vsf_flash_init(__FLASH, ...)               VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_init)               ((__vsf_flash_t *)(__FLASH), ##__VA_ARGS__)
#   define vsf_flash_fini(__FLASH)                    VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_fini)               ((__vsf_flash_t *)(__FLASH))
#   define vsf_flash_get_configuration(__FLASH, ...)  VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_get_configuration)  ((__vsf_flash_t *)(__FLASH), ##__VA_ARGS__)
#   define vsf_flash_enable(__FLASH)                  VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_enable)             ((__vsf_flash_t *)(__FLASH))
#   define vsf_flash_disable(__FLASH)                 VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_disable)            ((__vsf_flash_t *)(__FLASH))
#   define vsf_flash_capability(__FLASH)              VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_capability)         ((__vsf_flash_t *)(__FLASH))
#   define vsf_flash_status(__FLASH)                  VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_status)             ((__vsf_flash_t *)(__FLASH))
#   define vsf_flash_irq_enable(__FLASH, ...)         VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_irq_enable)         ((__vsf_flash_t *)(__FLASH), ##__VA_ARGS__)
#   define vsf_flash_irq_disable(__FLASH, ...)        VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_irq_disable)        ((__vsf_flash_t *)(__FLASH), ##__VA_ARGS__)
#   define vsf_flash_erase_one_sector(__FLASH, ...)   VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_erase_one_sector)   ((__vsf_flash_t *)(__FLASH), ##__VA_ARGS__)
#   define vsf_flash_erase_multi_sector(__FLASH, ...) VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_erase_multi_sector) ((__vsf_flash_t *)(__FLASH), ##__VA_ARGS__)
#   define vsf_flash_erase(__FLASH, ...)              VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_erase_multi_sector) ((__vsf_flash_t *)(__FLASH), ##__VA_ARGS__)
#   define vsf_flash_erase_all(__FLASH, ...)          VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_erase_all)          ((__vsf_flash_t *)(__FLASH), ##__VA_ARGS__)
#   define vsf_flash_write_one_sector(__FLASH, ...)   VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_write_one_sector)   ((__vsf_flash_t *)(__FLASH), ##__VA_ARGS__)
#   define vsf_flash_write_multi_sector(__FLASH, ...) VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_write_multi_sector) ((__vsf_flash_t *)(__FLASH), ##__VA_ARGS__)
#   define vsf_flash_write(__FLASH, ...)              VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_write_multi_sector) ((__vsf_flash_t *)(__FLASH), ##__VA_ARGS__)
#   define vsf_flash_read_one_sector(__FLASH, ...)    VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_read_one_sector)    ((__vsf_flash_t *)(__FLASH), ##__VA_ARGS__)
#   define vsf_flash_read_multi_sector(__FLASH, ...)  VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_read_multi_sector)  ((__vsf_flash_t *)(__FLASH), ##__VA_ARGS__)
#   define vsf_flash_read(__FLASH, ...)               VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_read_multi_sector)  ((__vsf_flash_t *)(__FLASH), ##__VA_ARGS__)
#   define vsf_flash_ctrl(__FLASH, ...)               VSF_MCONNECT(VSF_FLASH_CFG_PREFIX, _flash_ctrl)               ((__vsf_flash_t *)(__FLASH), ##__VA_ARGS__)
#endif
 
#ifdef __cplusplus
}
#endif
 
#endif  /*__VSF_TEMPLATE_FLASH_H__*/