gr55xx_dfu.h
Go to the documentation of this file.
1 /**
2  ******************************************************************************
3  *
4  * @file gr55xx_dfu.h
5  *
6  * @brief Device Firmware Update API
7  *
8  ******************************************************************************
9  * @attention
10  #####Copyright (c) 2019 GOODIX
11  All rights reserved.
12 
13  Redistribution and use in source and binary forms, with or without
14  modification, are permitted provided that the following conditions are met:
15  * Redistributions of source code must retain the above copyright
16  notice, this list of conditions and the following disclaimer.
17  * Redistributions in binary form must reproduce the above copyright
18  notice, this list of conditions and the following disclaimer in the
19  documentation and/or other materials provided with the distribution.
20  * Neither the name of GOODIX nor the names of its contributors may be used
21  to endorse or promote products derived from this software without
22  specific prior written permission.
23 
24  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27  ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
28  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34  POSSIBILITY OF SUCH DAMAGE.
35  *****************************************************************************************
36  */
37 
38 /**
39 * @addtogroup SYSTEM
40 * @{
41 */
42 /**
43  @addtogroup DFU Device Firmware Update
44  @{
45  @brief Definitions and prototypes for the DFU interface.
46 */
47 
48 #ifndef __GR55XX_DFU_H__
49 #define __GR55XX_DFU_H__
50 
51 #include <stdbool.h>
52 #include <stdint.h>
53 
54 /** @addtogroup DFU_DEFINES Defines
55  * @{ */
56 #define DFU_FRAME_RECEIVE_MAX_LENGTH 2048 /**< The max length of received data is 2048 bytes. */
57 #define DFU_IMG_INFO_PATTERN 0x4744 /**< The pattern of image info. */
58 
59 /**@defgroup DFU_CMD_DISABLE DFU cmd disable option (bitmask)
60  * @{ */
61 #define DFU_WRITE_RAM_DISABLE 0x0001 /**< Disable DFU write ram. */
62 #define DFU_READ_RAM_DISABLE 0x0002 /**< Disable DFU read ram. */
63 #define DFU_DUMP_FLASH_DISABLE 0x0004 /**< Disable DFU dump flash. */
64 #define DFU_ERASE_FLASH_DISABLE 0x0008 /**< Disable DFU erase flash. */
65 #define DFU_UPDAE_FLASH_DISABLE 0x0010 /**< Disable DFU update flash. */
66 #define DFU_OPERATE_SYSTEM_INFO_DISABLE 0x0020 /**< Disable DFU operate system info area. */
67 #define DFU_OPERATE_NVDS_DISABLE 0x0040 /**< Disable DFU operate NVDS. */
68 #define DFU_OPERATE_EFUSE_DISABLE 0x0080 /**< Disable DFU operate EFUSE. */
69 #define DFU_CONFIG_SPI_FLASH_DISABLE 0x0100 /**< Disable DFU config spi flash. */
70 #define DFU_OPERATE_REG_DISABLE 0x0200 /**< Disable DFU operate register. */
71 /**@} */
72 
73 /** @} */
74 
75 /**@addtogroup DFU_STRUCTURES Structures
76  * @{ */
77 /**@brief DFU frame information definition. */
78 typedef struct
79 {
80  uint16_t cmd_type; /**< CMD type. */
81  uint16_t data_len; /**< Length of data. */
82  uint8_t *data; /**< Pointer to data. */
83  uint16_t check_sum; /**< Check sum. */
84 } dfu_receive_frame_t;
85 
86 /**@brief Boot information definition. */
87 typedef struct
88 {
89  uint32_t bin_size; /**< Firmware Size. */
90  uint32_t check_sum; /**< Firmware Check Sum Value. */
91  uint32_t load_addr; /**< Firmware Load Address. */
92  uint32_t run_addr ; /**< Firmware Run Address. */
93  uint32_t xqspi_xip_cmd; /**< XIP Read Mode. 0x03: Read mode, 0x0B: Fast Read mode, 0x3B: DualOut Fast Read mode, 0xBB: DualIO Fast Read mode, 0x6B: QuadOut Fast Read mode, 0xEB: QuadIO Fast Read mode */
94  uint32_t xqspi_speed: 4; /**< Bit: 0-3 clock speed. 0 :64 MHz, 1:48 MHz, 2:32 MHz, 3:24 MHz, 4:16 MHz. */
95  uint32_t code_copy_mode: 1; /**< Bit: 4 code copy mode. 0:XIP,1:QSPI. */
96  uint32_t system_clk: 3; /**< Bit: 5-7 system clock. 0:64 MHz, 1:48 MHz, 2:32 MHz(xo), 3:24 MHz, 4:16 MHz, 5:32 MHz(cpll). */
97  uint32_t check_image:1; /**< Bit: 8 check image. */
98  uint32_t boot_delay:1; /**< Bit: Boot delay flag. */
99  uint32_t is_dap_boot:1; /**< Bit: 11 check if boot dap mode. */
100  uint32_t reserved:21; /**< Bit: 24 reserved. */
101 } dfu_boot_info_t;
102 
103 /**@brief Image information definition. */
104 typedef struct
105 {
106  uint16_t pattern; /**< Image info pattern. */
107  uint16_t version; /**< Image version. */
108  dfu_boot_info_t boot_info; /**< Image boot info. */
109  uint8_t comments[12]; /**< Image comments. */
110 } dfu_image_info_t;
111 
112 
113 /**@brief DFU used functions config definition. */
114 typedef struct
115 {
116  void (*dfu_ble_send_data)(uint8_t *p_data, uint16_t length); /**< The function is used to send data to master by BLE. */
117  void (*dfu_uart_send_data)(uint8_t *p_data, uint16_t length); /**< The function is used to send data to master by UART. */
118  uint32_t (*dfu_flash_read)(const uint32_t addr, uint8_t *p_buf, const uint32_t size); /**< The function is used to read data from flash. */
119  uint32_t (*dfu_flash_write)(const uint32_t addr, const uint8_t *p_buf, const uint32_t size); /**< The function is used to write data to flash. */
120  bool (*dfu_flash_erase)(const uint32_t addr, const uint32_t size); /**< The function is used to erase flash by address. */
121  bool (*dfu_flash_erase_chip)(void); /**< The function is used to erase flash chip. */
122  void (*dfu_flash_set_security)(bool enable); /**< The function is used to set the flash security mode as Enable or Disable. */
123  bool (*dfu_flash_get_security)(void); /**< The function is used to get the flash security mode (Enable or Disable). */
124  void (*dfu_flash_get_info)(uint32_t *id, uint32_t *size); /**< The function is used to get the flash id and size. */
125 } dfu_func_t;
126 
127 /**@brief SPI used functions config definition. */
128 typedef struct
129 {
130  void (*dfu_spi_flash_init)(uint8_t *p_data); /**< The function is used to config flash spi. */
131  uint32_t (*dfu_spi_flash_read)(uint32_t addr, uint8_t *buf, uint32_t size); /**< The function is used to read external flash . */
132  uint32_t (*dfu_spi_flash_write)(uint32_t addr, uint8_t *buf, uint32_t size); /**< The function is used to write external flash. */
133  bool (*dfu_spi_flash_erase)(uint32_t addr, uint32_t size); /**< The function is used to erase external flash by address. */
134  bool (*dfu_spi_flash_erase_chip)(void); /**< The function is used to erase exteral flash chip. */
135  void (*dfu_spi_flash_get_info)(uint32_t *id, uint32_t *size); /**< The function is used to get external flash id and size. */
136 }dfu_spi_flash_func_t;
137 
138 
139 /**@brief DFU program state callback definition. */
140 typedef struct
141 {
142  void (*dfu_program_start_callback)(void); /**<DFU program start callback. */
143  void (*dfu_programing_callback)(uint8_t pro); /**<DFU programing callback. */
144  void (*dfu_program_end_callback)(uint8_t status); /**<DFU program end callback. */
145 } dfu_pro_callback_t;
146 /** @} */
147 
148 /**
149  * @defgroup DFU_TYPEDEF Typedefs
150  * @{
151  */
152 /** @} */
153 /**@brief DFU receive cmd handler type. */
154 typedef void (*dfu_receive_cmd_handler_t)(dfu_receive_frame_t *);
155 
156 /** @addtogroup DFU_FUNCTIONS Functions
157  * @{ */
158 /**
159  *****************************************************************************************
160  * @brief Function for initializing the DFU Used and Program State Callback.
161  *
162  * @note When APP wants to add DFU features, the flash_read and flash_write functions should be registered.
163  * To creat own DFU bootloaders, all functions in dfu_func_t should be registered. In order to show
164  * DFU program states by own DFU bootloaders, all functions in @ref dfu_pro_callback_t should be registered.
165  *
166  * @param[in] p_app_dfu_func: DFU used functions.
167  * @param[in] p_dfu_buffer: DFU data receiving buffer.
168  * @param[in] p_dfu_callback: DFU program state callback functions.
169  *****************************************************************************************
170  */
171 void dfu_init(dfu_func_t *p_app_dfu_func, uint8_t* p_dfu_buffer, dfu_pro_callback_t *p_dfu_callback);
172 
173 /**
174  *****************************************************************************************
175  * @brief Function for reset the DFU cmd parse state.
176  *
177  * @note When APP wants to add DFU timeout feature, shoulde reset DFU cmd parse state when timeout.
178  *****************************************************************************************
179  */
180 void dfu_cmd_parse_state_reset(void);
181 
182 /**
183  *****************************************************************************************
184  * @brief Function for setting the BLE MTU size.
185  *
186  * @note If the user wants to create his or her own DFU bootloader, the DFU MTU size should be
187  * set by using this function (when the MTU size is updated, this function should be called).
188  *
189  * @param[in] mtu_size: The BLE MTU size.
190  *****************************************************************************************
191  */
192 void dfu_ble_set_mtu_size(uint16_t mtu_size);
193 
194 /**
195  *****************************************************************************************
196  * @brief This function should be called when BLE stack sends data completely.
197  *
198  * @note This function should be used when the user wants to create his or her own DFU bootloader.
199  *
200  * @retval void
201  *****************************************************************************************
202  */
203 void dfu_ble_send_data_cmpl_process(void);
204 
205 /**
206  *****************************************************************************************
207  * @brief This function should be called when BLE receives data.
208  *
209  * @note This function should be used when the user wants to create his or her own DFU bootloader.
210  *
211  * @param[in] p_data: The received data from BLE.
212  * @param[in] length: The length of data.
213  *****************************************************************************************
214  */
215 void dfu_ble_receive_data_process(uint8_t *p_data, uint16_t length);
216 
217 /**
218  *****************************************************************************************
219  * @brief This function should be called when UART receives data.
220  *
221  * @note This function should be used when the user wants to create his or her own DFU bootloader.
222  *
223  * @param[in] p_data: The received data from UART
224  * @param[in] length: The length of data
225  *****************************************************************************************
226  */
227 void dfu_uart_receive_data_process(uint8_t *p_data, uint16_t length);
228 
229 /**
230  *****************************************************************************************
231  * @brief Function for checking DFU cmd.
232  *
233  * @note This function should be called in main loop.
234  *****************************************************************************************
235  */
236 void dfu_schedule(void);
237 
238 /**
239  *****************************************************************************************
240  * @brief Function for set DFU disable cmd.
241  *
242  * @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,
243  * this function can be called.
244  *
245  * @param[in] disable_cmd_bit_map: The bitmask of DFU disable cmd See @ref DFU_CMD_DISABLE.
246  *****************************************************************************************
247  */
248 void dfu_set_disable_cmd(uint16_t disable_cmd_bit_map);
249 
250 /**
251  *****************************************************************************************
252  * @brief Function for set DFU cmd handler.
253  *
254  * @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,
255  * this function can be called.
256  *
257  * @param[in] index: The index of DFU cmd.
258  * @param[in] cmd: The code of DFU cmd.
259  * @param[in] cmd_handler: The handler of DFU cmd.
260  *****************************************************************************************
261  */
262 void dfu_set_cmd_handler(uint8_t index, uint16_t cmd, dfu_receive_cmd_handler_t cmd_handler);
263 
264 /**
265  *****************************************************************************************
266  * @brief Function for initializing the DFU SPI Flash Callback.
267  *
268  * @note When APP wants to add DFU operationally external flash feature, the dfu_spi_flash_func_t should be registered.
269  *
270  * @param[in] spi_flash_func: DFU operationally external flash used functions.
271  *****************************************************************************************
272  */
273 void dfu_spi_flash_func_config(dfu_spi_flash_func_t *spi_flash_func);
274 
275 /** @} */
276 #endif
277 /** @} */
278 /** @} */
dfu_image_info_t
Image information definition.
Definition: gr55xx_dfu.h:105
dfu_init
void dfu_init(dfu_func_t *p_app_dfu_func, uint8_t *p_dfu_buffer, dfu_pro_callback_t *p_dfu_callback)
Function for initializing the DFU Used and Program State Callback.
dfu_set_disable_cmd
void dfu_set_disable_cmd(uint16_t disable_cmd_bit_map)
Function for set DFU disable cmd.
dfu_receive_frame_t::data
uint8_t * data
Definition: gr55xx_dfu.h:82
dfu_boot_info_t::is_dap_boot
uint32_t is_dap_boot
Definition: gr55xx_dfu.h:99
dfu_func_t
DFU used functions config definition.
Definition: gr55xx_dfu.h:115
dfu_ble_receive_data_process
void dfu_ble_receive_data_process(uint8_t *p_data, uint16_t length)
This function should be called when BLE receives data.
dfu_receive_frame_t::cmd_type
uint16_t cmd_type
Definition: gr55xx_dfu.h:80
dfu_uart_receive_data_process
void dfu_uart_receive_data_process(uint8_t *p_data, uint16_t length)
This function should be called when UART receives data.
dfu_ble_set_mtu_size
void dfu_ble_set_mtu_size(uint16_t mtu_size)
Function for setting the BLE MTU size.
dfu_boot_info_t::xqspi_xip_cmd
uint32_t xqspi_xip_cmd
Definition: gr55xx_dfu.h:93
dfu_ble_send_data_cmpl_process
void dfu_ble_send_data_cmpl_process(void)
This function should be called when BLE stack sends data completely.
dfu_receive_frame_t::check_sum
uint16_t check_sum
Definition: gr55xx_dfu.h:83
dfu_boot_info_t::system_clk
uint32_t system_clk
Definition: gr55xx_dfu.h:96
dfu_boot_info_t
Boot information definition.
Definition: gr55xx_dfu.h:88
dfu_boot_info_t::xqspi_speed
uint32_t xqspi_speed
Definition: gr55xx_dfu.h:94
dfu_receive_frame_t
DFU frame information definition.
Definition: gr55xx_dfu.h:79
dfu_image_info_t::version
uint16_t version
Definition: gr55xx_dfu.h:107
dfu_boot_info_t::boot_delay
uint32_t boot_delay
Definition: gr55xx_dfu.h:98
dfu_boot_info_t::code_copy_mode
uint32_t code_copy_mode
Definition: gr55xx_dfu.h:95
dfu_schedule
void dfu_schedule(void)
Function for checking DFU cmd.
dfu_boot_info_t::check_image
uint32_t check_image
Definition: gr55xx_dfu.h:97
dfu_set_cmd_handler
void dfu_set_cmd_handler(uint8_t index, uint16_t cmd, dfu_receive_cmd_handler_t cmd_handler)
Function for set DFU cmd handler.
dfu_image_info_t::boot_info
dfu_boot_info_t boot_info
Definition: gr55xx_dfu.h:108
dfu_boot_info_t::load_addr
uint32_t load_addr
Definition: gr55xx_dfu.h:91
dfu_spi_flash_func_config
void dfu_spi_flash_func_config(dfu_spi_flash_func_t *spi_flash_func)
Function for initializing the DFU SPI Flash Callback.
dfu_boot_info_t::run_addr
uint32_t run_addr
Definition: gr55xx_dfu.h:92
dfu_spi_flash_func_t
SPI used functions config definition.
Definition: gr55xx_dfu.h:129
dfu_boot_info_t::check_sum
uint32_t check_sum
Definition: gr55xx_dfu.h:90
dfu_receive_frame_t::data_len
uint16_t data_len
Definition: gr55xx_dfu.h:81
dfu_pro_callback_t
DFU program state callback definition.
Definition: gr55xx_dfu.h:141
dfu_cmd_parse_state_reset
void dfu_cmd_parse_state_reset(void)
Function for reset the DFU cmd parse state.
dfu_image_info_t::pattern
uint16_t pattern
Definition: gr55xx_dfu.h:106
dfu_boot_info_t::reserved
uint32_t reserved
Definition: gr55xx_dfu.h:100
dfu_receive_cmd_handler_t
void(* dfu_receive_cmd_handler_t)(dfu_receive_frame_t *)
DFU receive cmd handler type.
Definition: gr55xx_dfu.h:154
dfu_boot_info_t::bin_size
uint32_t bin_size
Definition: gr55xx_dfu.h:89