gr533x_dfu.h

Go to the documentation of this file.

/**
 ******************************************************************************
 *
 * @file gr533x_dfu.h
 *
 * @brief Device Firmware Update API
 *
 ******************************************************************************
 * @attention
  #####Copyright (c) 2019 GOODIX
  All rights reserved.
 
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:
  * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
  * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.
  * Neither the name of GOODIX nor the names of its contributors may be used
    to endorse or promote products derived from this software without
    specific prior written permission.
 
  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  POSSIBILITY OF SUCH DAMAGE.
 *****************************************************************************************
 */
 
/**
* @addtogroup SYSTEM
* @{
*/
/**
 @addtogroup DFU Device Firmware Update
 @{
 @brief Definitions and prototypes for the DFU interface.
*/
 
#ifndef __GR533X_DFU_H__
#define __GR533X_DFU_H__
 
#include "gr533x_sys.h"
#include <stdbool.h>
#include <stdint.h>
#include "ble_error.h"
 
/** @addtogroup DFU_DEFINES Defines
 * @{ */
#define DFU_MAX_HEADER_LEN      20          /**< The max length of DFU header data is 20 bytes. */
#define DFU_MAX_BUFFER_LEN      8192        /**< The max length of received data is 8192 bytes. */
#define DFU_FW_COPY_PATTERN     0x434f5059  /**< The pattern of dfu copy. */
#define DFU_INFO_ADDR           0x0027E000  /**< The address of DFU information. */
 
#define DFU_FRAME_RECEIVE_MAX_LENGTH    2048        /**< The max length of received data is 2048 bytes. */
#define DFU_IMG_INFO_PATTERN            0x4744      /**< The pattern of image info. */
/** @} */
 
 
/** @addtogroup DFU_ENUMERATIONS Enumerations
  * @{
  */
 
/** @defgroup DFU_CACHE_TYPE dfu cache buffer type
  * @{
  */
enum
{
    DFU_CACHE_TYPE_CALL_STACK = 0x00,   /**< call stack buffer. */
    DFU_CACHE_TYPE_REG,                 /**< register buffer. */
};
/**@} */
/**@} */
 
 
/**@addtogroup DFU_STRUCTURES Structures
 * @{ */
/**@brief DFU frame information definition. */
typedef struct
{
    uint16_t    cmd_type;   /**< CMD type. */
    uint16_t    data_len;   /**< Length of data. */
    uint8_t    *data;       /**< Pointer to data. */
    uint16_t    check_sum;  /**< Check sum. */
} dfu_receive_frame_t;
 
/**@brief Boot information definition. */
typedef struct
{
    uint32_t bin_size;
    uint32_t check_sum;
    uint32_t load_addr;
    uint32_t run_addr ;
    uint32_t xqspi_xip_cmd;
    uint32_t xqspi_speed:4;           /*!< bit: 0..3  clock speed */
    uint32_t code_copy_mode:1;        /*!< bit: 4 code copy mode */
    uint32_t system_clk:3;            /*!< bit: 5..7 system clock */
    uint32_t check_image:1;           /*!< bit: 8 check image */
    uint32_t boot_delay:1;            /*!< bit: 9 boot delay time */
    uint32_t signature_algorithm:2;   /*!< bit: 10..11 signature algorithm */
    uint32_t reserved:20;             /*!< bit: 20 reserved */
} dfu_boot_info_t;
 
/**@brief Image information definition. */
typedef struct
{
    uint16_t        pattern;        /**< Image info pattern. */
    uint16_t        version;        /**< Image version. */
    dfu_boot_info_t boot_info;      /**< Image boot info. */
    uint8_t         comments[12];   /**< Image comments. */
} dfu_image_info_t;
 
 
/**@brief DFU used functions config definition. */
typedef struct
{
    void (*dfu_ble_send_data)(uint8_t *data, uint16_t size);
    void (*dfu_uart_send_data)(uint8_t *data, uint16_t size);
 
    uint32_t (*dfu_flash_read)(uint32_t addr, uint8_t *buf, uint32_t size);
    uint32_t (*dfu_flash_write)(uint32_t addr, uint8_t *buf, uint32_t size);
    uint32_t (*dfu_flash_erase)(uint32_t erase_type, uint32_t addr, uint32_t size);
    void     (*dfu_flash_get_info)(uint32_t *id, uint32_t *size);
    uint32_t (*dfu_flash_feat_enable)(uint32_t feature);
}dfu_func_t;
 
 
/**@brief SPI used functions config definition. */
typedef struct
{
    void (*dfu_spi_flash_init)(uint8_t *p_data);                                                   /**< The function is used to config flash spi. */
    uint32_t (*dfu_spi_flash_read)(uint32_t addr, uint8_t *buf, uint32_t size);                    /**< The function is used to read external flash . */
    uint32_t (*dfu_spi_flash_write)(uint32_t addr, uint8_t *buf, uint32_t size);                   /**< The function is used to write external flash. */
    bool (*dfu_spi_flash_erase)(uint32_t erase_type, uint32_t addr, uint32_t size);                /**< The function is used to erase external flash by address. */
    void (*dfu_spi_flash_get_info)(uint32_t *id, uint32_t *size);                                  /**< The function is used to get external flash id and size. */
    uint32_t (*dfu_flash_feat_enable)(uint32_t feature);                                           /**< The function is used to enable dfu flash feature. */
}dfu_spi_flash_func_t;
 
 
/**@brief DFU used buffers definition. */
typedef struct
{
    uint8_t   *frame_buf;   /**< DFU command frame buffer. */
    uint32_t   frame_size;  /**< DFU command frame buffer size. */
    uint8_t   *jlink_buf;   /**< DFU command jlink buffer. */
    uint32_t   jlink_size;  /**< DFU command jlink buffer size. */
    uint8_t   *cache_buf;   /**< DFU function call cache buffer. */
    uint32_t   cache_size;  /**< DFU function call cache buffer size. */
    uint8_t   *env_buf;     /**< DFU function call env buffer. */
    uint32_t   env_size;    /**< DFU function call env buffer size. */
} dfu_buf_table_t;
 
 
/**@brief DFU program state callback definition. */
typedef struct
{
    void (*dfu_program_start_callback)(void);          /**<DFU program start callback. */
    void (*dfu_programing_callback)(uint8_t pro);      /**<DFU programing callback. */
    void (*dfu_program_end_callback)(uint8_t status);  /**<DFU program end callback. */
    void (*dfu_flash_copy_process)(uint32_t addr);     /**<DFU flash copy callback. */
} dfu_pro_callback_t;
 
/**@addtogroup DFU_TYPEDEF Typedefs
 * @{ */
/**@brief DFU CMD handler typed. */
typedef void(*dfu_receive_cmd_handler_t)(dfu_receive_frame_t *p_frame);
/** @} */
 
/** @addtogroup DFU_FUNCTIONS Functions
 * @{ */
/**
 *****************************************************************************************
 * @brief Function for initializing the DFU Used and Program State Callback.
 *
 * @note When APP wants to add DFU features, the flash_read and flash_write functions should be registered.
 *       To creat own DFU bootloaders, all functions in dfu_func_t should be registered. In order to show
 *       DFU program states by own DFU bootloaders, all functions in @ref dfu_pro_callback_t should be registered.
 *
 * @param[in]  p_app_func: DFU used functions.
 * @param[in]  p_buffer: DFU data receiving buffer.
 * @param[in]  p_callback: DFU program state callback functions.
 *
 * @return Result of service initialization.
 *****************************************************************************************
 */
sdk_err_t dfu_init(dfu_func_t *p_app_func, dfu_buf_table_t* p_buffer, dfu_pro_callback_t *p_callback);
 
/**
 *****************************************************************************************
 * @brief Function for reset the DFU cmd parse state.
 *
 * @note When APP wants to add DFU timeout feature, shoulde reset DFU cmd parse state when timeout.
 *****************************************************************************************
 */
void dfu_cmd_parse_reset(void);
 
/**
 *****************************************************************************************
 * @brief This function should be called when dfu receives data.
 *
 * @note This function should be used when the user wants to create his or her own DFU bootloader.
 *
 * @param[in]  p_data: The received data
 * @param[in]  length: The length of data
 *****************************************************************************************
 */
void dfu_receive_data_process(uint8_t *p_data, uint16_t length);
 
/**
 *****************************************************************************************
 * @brief Function for checking DFU cmd.
 *
 * @note This function should be called in main loop.
 *****************************************************************************************
 */
void dfu_schedule(void);
 
/**
 *****************************************************************************************
 * @brief Function for setting the BLE MTU size.
 *
 * @note If the user wants to create his or her own DFU bootloader, the DFU MTU size should be 
 *       set by using this function (when the MTU size is updated, this function should be called).
 *
 * @param[in]  mtu_size: The BLE MTU size.
 *****************************************************************************************
 */
void dfu_ble_set_mtu_size(uint16_t mtu_size);
 
/**
 *****************************************************************************************
 * @brief This function should be called when BLE stack sends data completely.
 *
 * @note This function should be used when the user wants to create his or her own DFU bootloader.
 *
 * @retval void
 *****************************************************************************************
 */
void dfu_ble_send_data_cmpl_process(void);
 
 
/**
 *****************************************************************************************
 * @brief This function should be called when BLE receives data.
 *
 * @note This function should be used when the user wants to create his or her own DFU bootloader.
 *
 * @param[in]  p_data: The received data from BLE.
 * @param[in]  length: The length of data.
 *****************************************************************************************
 */
void dfu_ble_receive_data_process(uint8_t *p_data, uint16_t length);
 
/**
 *****************************************************************************************
 * @brief This function should be called when UART receives data.
 *
 * @note This function should be used when the user wants to create his or her own DFU bootloader.
 *
 * @param[in]  p_data: The received data from UART
 * @param[in]  length: The length of data
 *****************************************************************************************
 */
void dfu_uart_receive_data_process(uint8_t *p_data, uint16_t length);
 
/**
 *****************************************************************************************
 * @brief Function for set DFU disable cmd.
 *
 * @note In Apps, if the user wants to jump to ROM DFU run,but want to be able to control the operation permissions of DFU,
 *       this function can be called.
 *
 * @param[in]  cmd_bit_map: The bitmask of DFU disable cmd.
 *****************************************************************************************
 */
void dfu_disable_cmd_set(uint16_t cmd_bit_map);
 
/**
 *****************************************************************************************
 * @brief Function for set DFU cmd handler.
 *
 * @param[in] index:       Index of DFU cmd.
 * @param[in] cmd:         DFU cmd.
 * @param[in] cmd_handler: DFU cmd handler.
 *****************************************************************************************
 */
bool dfu_cmd_handler_set(uint8_t index, uint16_t cmd, dfu_receive_cmd_handler_t cmd_handler);
 
/**
 *****************************************************************************************
 * @brief Function for initializing the DFU SPI Flash Callback.
 *
 * @note When APP wants to add DFU operationally external flash feature, the dfu_spi_flash_func_t should be registered.
 *
 * @param[in]  spi_flash_func: DFU operationally external flash used functions.
 *****************************************************************************************
 */
void dfu_spi_flash_func_config(dfu_spi_flash_func_t *spi_flash_func);
 
/** @} */
#endif
/** @} */
/** @} */
/** @} */