gr533x_dfu.h
Go to the documentation of this file.
1 /**
2 ******************************************************************************
3 *
4 * @file gr533x_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 __GR533X_DFU_H__
49 #define __GR533X_DFU_H__
50
51 #include "gr533x_sys.h"
52 #include <stdbool.h>
53 #include <stdint.h>
54 #include "ble_error.h"
55
56 /** @addtogroup DFU_DEFINES Defines
57 * @{ */
58 #define DFU_MAX_HEADER_LEN 20 /**< The max length of DFU header data is 20 bytes. */
59 #define DFU_MAX_BUFFER_LEN 8192 /**< The max length of received data is 8192 bytes. */
60 #define DFU_FW_COPY_PATTERN 0x434f5059 /**< The pattern of dfu copy. */
61 #define DFU_INFO_ADDR 0x0027E000 /**< The address of DFU information. */
62
63 #define DFU_FRAME_RECEIVE_MAX_LENGTH 2048 /**< The max length of received data is 2048 bytes. */
64 #define DFU_IMG_INFO_PATTERN 0x4744 /**< The pattern of image info. */
65 /** @} */
66
67
68 /** @addtogroup DFU_ENUMERATIONS Enumerations
69 * @{
70 */
71
72 /** @defgroup DFU_CACHE_TYPE dfu cache buffer type
73 * @{
74 */
75 enum
76 {
77 DFU_CACHE_TYPE_CALL_STACK = 0x00, /**< call stack buffer. */
78 DFU_CACHE_TYPE_REG, /**< register buffer. */
79 };
80 /**@} */
81 /**@} */
82
83
84 /**@addtogroup DFU_STRUCTURES Structures
85 * @{ */
86 /**@brief DFU frame information definition. */
87 typedef struct
88 {
89 uint16_t cmd_type; /**< CMD type. */
90 uint16_t data_len; /**< Length of data. */
91 uint8_t *data; /**< Pointer to data. */
92 uint16_t check_sum; /**< Check sum. */
93 } dfu_receive_frame_t;
94
95 /**@brief Boot information definition. */
96 typedef struct
97 {
98 uint32_t bin_size;
99 uint32_t check_sum;
100 uint32_t load_addr;
101 uint32_t run_addr ;
102 uint32_t xqspi_xip_cmd;
103 uint32_t xqspi_speed:4; /*!< bit: 0..3 clock speed */
104 uint32_t code_copy_mode:1; /*!< bit: 4 code copy mode */
105 uint32_t system_clk:3; /*!< bit: 5..7 system clock */
106 uint32_t check_image:1; /*!< bit: 8 check image */
107 uint32_t boot_delay:1; /*!< bit: 9 boot delay time */
108 uint32_t signature_algorithm:2; /*!< bit: 10..11 signature algorithm */
109 uint32_t reserved:20; /*!< bit: 20 reserved */
110 } dfu_boot_info_t;
111
112 /**@brief Image information definition. */
113 typedef struct
114 {
115 uint16_t pattern; /**< Image info pattern. */
116 uint16_t version; /**< Image version. */
117 dfu_boot_info_t boot_info; /**< Image boot info. */
118 uint8_t comments[12]; /**< Image comments. */
119 } dfu_image_info_t;
120
121
122 /**@brief DFU used functions config definition. */
123 typedef struct
124 {
125 void (*dfu_ble_send_data)(uint8_t *data, uint16_t size);
126 void (*dfu_uart_send_data)(uint8_t *data, uint16_t size);
127
128 uint32_t (*dfu_flash_read)(uint32_t addr, uint8_t *buf, uint32_t size);
129 uint32_t (*dfu_flash_write)(uint32_t addr, uint8_t *buf, uint32_t size);
130 uint32_t (*dfu_flash_erase)(uint32_t erase_type, uint32_t addr, uint32_t size);
131 void (*dfu_flash_get_info)(uint32_t *id, uint32_t *size);
132 uint32_t (*dfu_flash_feat_enable)(uint32_t feature);
133 }dfu_func_t;
134
135
136 /**@brief SPI used functions config definition. */
137 typedef struct
138 {
139 void (*dfu_spi_flash_init)(uint8_t *p_data); /**< The function is used to config flash spi. */
140 uint32_t (*dfu_spi_flash_read)(uint32_t addr, uint8_t *buf, uint32_t size); /**< The function is used to read external flash . */
141 uint32_t (*dfu_spi_flash_write)(uint32_t addr, uint8_t *buf, uint32_t size); /**< The function is used to write external flash. */
142 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. */
143 void (*dfu_spi_flash_get_info)(uint32_t *id, uint32_t *size); /**< The function is used to get external flash id and size. */
144 uint32_t (*dfu_flash_feat_enable)(uint32_t feature); /**< The function is used to enable dfu flash feature. */
145 }dfu_spi_flash_func_t;
146
147
148 /**@brief DFU used buffers definition. */
149 typedef struct
150 {
151 uint8_t *frame_buf; /**< DFU command frame buffer. */
152 uint32_t frame_size; /**< DFU command frame buffer size. */
153 uint8_t *jlink_buf; /**< DFU command jlink buffer. */
154 uint32_t jlink_size; /**< DFU command jlink buffer size. */
155 uint8_t *cache_buf; /**< DFU function call cache buffer. */
156 uint32_t cache_size; /**< DFU function call cache buffer size. */
157 uint8_t *env_buf; /**< DFU function call env buffer. */
158 uint32_t env_size; /**< DFU function call env buffer size. */
159 } dfu_buf_table_t;
160
161
162 /**@brief DFU program state callback definition. */
163 typedef struct
164 {
165 void (*dfu_program_start_callback)(void); /**<DFU program start callback. */
166 void (*dfu_programing_callback)(uint8_t pro); /**<DFU programing callback. */
167 void (*dfu_program_end_callback)(uint8_t status); /**<DFU program end callback. */
168 void (*dfu_flash_copy_process)(uint32_t addr); /**<DFU flash copy callback. */
169 } dfu_pro_callback_t;
170
171 /**@addtogroup DFU_TYPEDEF Typedefs
172 * @{ */
173 /**@brief DFU CMD handler typed. */
174 typedef void(*dfu_receive_cmd_handler_t)(dfu_receive_frame_t *p_frame);
175 /** @} */
176
177 /** @addtogroup DFU_FUNCTIONS Functions
178 * @{ */
179 /**
180 *****************************************************************************************
181 * @brief Function for initializing the DFU Used and Program State Callback.
182 *
183 * @note When APP wants to add DFU features, the flash_read and flash_write functions should be registered.
184 * To creat own DFU bootloaders, all functions in dfu_func_t should be registered. In order to show
185 * DFU program states by own DFU bootloaders, all functions in @ref dfu_pro_callback_t should be registered.
186 *
187 * @param[in] p_app_func: DFU used functions.
188 * @param[in] p_buffer: DFU data receiving buffer.
189 * @param[in] p_callback: DFU program state callback functions.
190 *
191 * @return Result of service initialization.
192 *****************************************************************************************
193 */
194 sdk_err_t dfu_init(dfu_func_t *p_app_func, dfu_buf_table_t* p_buffer, dfu_pro_callback_t *p_callback);
195
196 /**
197 *****************************************************************************************
198 * @brief Function for reset the DFU cmd parse state.
199 *
200 * @note When APP wants to add DFU timeout feature, shoulde reset DFU cmd parse state when timeout.
201 *****************************************************************************************
202 */
203 void dfu_cmd_parse_reset(void);
204
205 /**
206 *****************************************************************************************
207 * @brief This function should be called when dfu 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
212 * @param[in] length: The length of data
213 *****************************************************************************************
214 */
215 void dfu_receive_data_process(uint8_t *p_data, uint16_t length);
216
217 /**
218 *****************************************************************************************
219 * @brief Function for checking DFU cmd.
220 *
221 * @note This function should be called in main loop.
222 *****************************************************************************************
223 */
224 void dfu_schedule(void);
225
226 /**
227 *****************************************************************************************
228 * @brief Function for setting the BLE MTU size.
229 *
230 * @note If the user wants to create his or her own DFU bootloader, the DFU MTU size should be
231 * set by using this function (when the MTU size is updated, this function should be called).
232 *
233 * @param[in] mtu_size: The BLE MTU size.
234 *****************************************************************************************
235 */
236 void dfu_ble_set_mtu_size(uint16_t mtu_size);
237
238 /**
239 *****************************************************************************************
240 * @brief This function should be called when BLE stack sends data completely.
241 *
242 * @note This function should be used when the user wants to create his or her own DFU bootloader.
243 *
244 * @retval void
245 *****************************************************************************************
246 */
247 void dfu_ble_send_data_cmpl_process(void);
248
249
250 /**
251 *****************************************************************************************
252 * @brief This function should be called when BLE receives data.
253 *
254 * @note This function should be used when the user wants to create his or her own DFU bootloader.
255 *
256 * @param[in] p_data: The received data from BLE.
257 * @param[in] length: The length of data.
258 *****************************************************************************************
259 */
260 void dfu_ble_receive_data_process(uint8_t *p_data, uint16_t length);
261
262 /**
263 *****************************************************************************************
264 * @brief This function should be called when UART receives data.
265 *
266 * @note This function should be used when the user wants to create his or her own DFU bootloader.
267 *
268 * @param[in] p_data: The received data from UART
269 * @param[in] length: The length of data
270 *****************************************************************************************
271 */
272 void dfu_uart_receive_data_process(uint8_t *p_data, uint16_t length);
273
274 /**
275 *****************************************************************************************
276 * @brief Function for set DFU disable cmd.
277 *
278 * @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,
279 * this function can be called.
280 *
281 * @param[in] cmd_bit_map: The bitmask of DFU disable cmd.
282 *****************************************************************************************
283 */
284 void dfu_disable_cmd_set(uint16_t cmd_bit_map);
285
286 /**
287 *****************************************************************************************
288 * @brief Function for set DFU cmd handler.
289 *
290 * @param[in] index: Index of DFU cmd.
291 * @param[in] cmd: DFU cmd.
292 * @param[in] cmd_handler: DFU cmd handler.
293 *****************************************************************************************
294 */
295 bool dfu_cmd_handler_set(uint8_t index, uint16_t cmd, dfu_receive_cmd_handler_t cmd_handler);
296
297 /**
298 *****************************************************************************************
299 * @brief Function for initializing the DFU SPI Flash Callback.
300 *
301 * @note When APP wants to add DFU operationally external flash feature, the dfu_spi_flash_func_t should be registered.
302 *
303 * @param[in] spi_flash_func: DFU operationally external flash used functions.
304 *****************************************************************************************
305 */
306 void dfu_spi_flash_func_config(dfu_spi_flash_func_t *spi_flash_func);
307
308 /** @} */
309 #endif
310 /** @} */
311 /** @} */
312 /** @} */
dfu_cmd_parse_reset
void dfu_cmd_parse_reset(void)
Function for reset the DFU cmd parse state.
dfu_image_info_t
Image information definition.
Definition: gr533x_dfu.h:114
dfu_buf_table_t::cache_size
uint32_t cache_size
Definition: gr533x_dfu.h:156
dfu_buf_table_t::env_size
uint32_t env_size
Definition: gr533x_dfu.h:158
dfu_receive_frame_t::data
uint8_t * data
Definition: gr533x_dfu.h:91
dfu_func_t
DFU used functions config definition.
Definition: gr533x_dfu.h:124
DFU_CACHE_TYPE_CALL_STACK
@ DFU_CACHE_TYPE_CALL_STACK
Definition: gr533x_dfu.h:77
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: gr533x_dfu.h:89
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_buf_table_t::jlink_size
uint32_t jlink_size
Definition: gr533x_dfu.h:154
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: gr533x_dfu.h:102
DFU_CACHE_TYPE_REG
@ DFU_CACHE_TYPE_REG
Definition: gr533x_dfu.h:78
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: gr533x_dfu.h:92
dfu_boot_info_t::signature_algorithm
uint32_t signature_algorithm
Definition: gr533x_dfu.h:108
dfu_buf_table_t
DFU used buffers definition.
Definition: gr533x_dfu.h:150
dfu_boot_info_t::system_clk
uint32_t system_clk
Definition: gr533x_dfu.h:105
dfu_boot_info_t
Boot information definition.
Definition: gr533x_dfu.h:97
dfu_boot_info_t::xqspi_speed
uint32_t xqspi_speed
Definition: gr533x_dfu.h:103
dfu_receive_frame_t
DFU frame information definition.
Definition: gr533x_dfu.h:88
dfu_buf_table_t::jlink_buf
uint8_t * jlink_buf
Definition: gr533x_dfu.h:153
dfu_image_info_t::version
uint16_t version
Definition: gr533x_dfu.h:116
dfu_cmd_handler_set
bool dfu_cmd_handler_set(uint8_t index, uint16_t cmd, dfu_receive_cmd_handler_t cmd_handler)
Function for set DFU cmd handler.
dfu_boot_info_t::boot_delay
uint32_t boot_delay
Definition: gr533x_dfu.h:107
dfu_boot_info_t::code_copy_mode
uint32_t code_copy_mode
Definition: gr533x_dfu.h:104
dfu_schedule
void dfu_schedule(void)
Function for checking DFU cmd.
dfu_buf_table_t::frame_size
uint32_t frame_size
Definition: gr533x_dfu.h:152
dfu_boot_info_t::check_image
uint32_t check_image
Definition: gr533x_dfu.h:106
ble_error.h
File that contains error codes.
dfu_receive_data_process
void dfu_receive_data_process(uint8_t *p_data, uint16_t length)
This function should be called when dfu receives data.
dfu_buf_table_t::cache_buf
uint8_t * cache_buf
Definition: gr533x_dfu.h:155
dfu_buf_table_t::env_buf
uint8_t * env_buf
Definition: gr533x_dfu.h:157
dfu_image_info_t::boot_info
dfu_boot_info_t boot_info
Definition: gr533x_dfu.h:117
dfu_boot_info_t::load_addr
uint32_t load_addr
Definition: gr533x_dfu.h:100
dfu_init
sdk_err_t dfu_init(dfu_func_t *p_app_func, dfu_buf_table_t *p_buffer, dfu_pro_callback_t *p_callback)
Function for initializing the DFU Used and Program State Callback.
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:257
dfu_disable_cmd_set
void dfu_disable_cmd_set(uint16_t cmd_bit_map)
Function for set DFU disable cmd.
dfu_buf_table_t::frame_buf
uint8_t * frame_buf
Definition: gr533x_dfu.h:151
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: gr533x_dfu.h:101
dfu_spi_flash_func_t
SPI used functions config definition.
Definition: gr533x_dfu.h:138
dfu_boot_info_t::check_sum
uint32_t check_sum
Definition: gr533x_dfu.h:99
dfu_receive_frame_t::data_len
uint16_t data_len
Definition: gr533x_dfu.h:90
dfu_pro_callback_t
DFU program state callback definition.
Definition: gr533x_dfu.h:164
dfu_receive_cmd_handler_t
void(* dfu_receive_cmd_handler_t)(dfu_receive_frame_t *p_frame)
DFU CMD handler typed.
Definition: gr533x_dfu.h:174
gr533x_sys.h
GR533X System API.
dfu_image_info_t::pattern
uint16_t pattern
Definition: gr533x_dfu.h:115
dfu_boot_info_t::reserved
uint32_t reserved
Definition: gr533x_dfu.h:109
dfu_boot_info_t::bin_size
uint32_t bin_size
Definition: gr533x_dfu.h:98