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_IMG_INFO_PATTERN 0x4744 /**< The pattern of image info. */
57 /**@} */
58
59 /**@addtogroup DFU_STRUCTURES Structures
60 * @{ */
61 /**@brief DFU frame information definition. */
62 typedef struct
63 {
64 uint16_t cmd_type; /**< CMD type. */
65 uint16_t data_len; /**< Length of data. */
66 uint8_t *data; /**< Pointer to data. */
67 uint16_t check_sum; /**< Check sum. */
68 } dfu_receive_frame_t;
69
70 /**@brief Boot information definition. */
71 typedef struct
72 {
73 uint32_t bin_size; /**< Firmware Size. */
74 uint32_t check_sum; /**< Firmware Check Sum Value. */
75 uint32_t load_addr; /**< Firmware Load Address. */
76 uint32_t run_addr ; /**< Firmware Run Address. */
77 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 */
78 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. */
79 uint32_t code_copy_mode: 1; /**< Bit: 4 code copy mode. 0:XIP,1:QSPI. */
80 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). */
81 uint32_t check_image:1; /**< Bit: 8 check image. */
82 uint32_t boot_delay:1; /**< Bit: Boot delay flag. */
83 uint32_t is_dap_boot:1; /**< Bit: 11 check if boot dap mode. */
84 uint32_t reserved:21; /**< Bit: 24 reserved. */
85 } dfu_boot_info_t;
86
87 /**@brief Image information definition. */
88 typedef struct
89 {
90 uint16_t pattern; /**< Image info pattern. */
91 uint16_t version; /**< Image version. */
92 dfu_boot_info_t boot_info; /**< Image boot info. */
93 uint8_t comments[12]; /**< Image comments. */
94 } dfu_image_info_t;
95
96
97 /**@brief DFU used functions config definition. */
98 typedef struct
99 {
100 void (*dfu_ble_send_data)(uint8_t *p_data, uint16_t length); /**< The function is used to send data to master by BLE. */
101 void (*dfu_uart_send_data)(uint8_t *p_data, uint16_t length); /**< The function is used to send data to master by UART. */
102 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. */
103 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. */
104 bool (*dfu_flash_erase)(const uint32_t addr, const uint32_t size); /**< The function is used to erase flash by address. */
105 bool (*dfu_flash_erase_chip)(void); /**< The function is used to erase flash chip. */
106 void (*dfu_flash_set_security)(bool enable); /**< The function is used to set the flash security mode as Enable or Disable. */
107 bool (*dfu_flash_get_security)(void); /**< The function is used to get the flash security mode (Enable or Disable). */
108 void (*dfu_flash_get_info)(uint32_t *id, uint32_t *size); /**< The function is used to get the flash id and size. */
109 } dfu_func_t;
110
111 /**@brief SPI used functions config definition. */
112 typedef struct
113 {
114 void (*dfu_spi_flash_init)(uint8_t *p_data); /**< The function is used to config flash spi. */
115 uint32_t (*dfu_spi_flash_read)(uint32_t addr, uint8_t *buf, uint32_t size); /**< The function is used to read external flash . */
116 uint32_t (*dfu_spi_flash_write)(uint32_t addr, uint8_t *buf, uint32_t size); /**< The function is used to write external flash. */
117 bool (*dfu_spi_flash_erase)(uint32_t addr, uint32_t size); /**< The function is used to erase external flash by address. */
118 bool (*dfu_spi_flash_erase_chip)(void); /**< The function is used to erase exteral flash chip. */
119 void (*dfu_spi_flash_get_info)(uint32_t *id, uint32_t *size); /**< The function is used to get external flash id and size. */
120 }dfu_spi_flash_func_t;
121
122
123 /**@brief DFU program state callback definition. */
124 typedef struct
125 {
126 void (*dfu_program_start_callback)(void); /**<DFU program start callback. */
127 void (*dfu_programing_callback)(uint8_t pro); /**<DFU programing callback. */
128 void (*dfu_program_end_callback)(uint8_t status); /**<DFU program end callback. */
129 } dfu_pro_callback_t;
130 /** @} */
131
132 /**
133 * @defgroup DFU_TYPEDEF Typedefs
134 * @{
135 */
136 /** @} */
137 /**@brief DFU receive cmd handler type. */
138 typedef void (*dfu_receive_cmd_handler_t)(dfu_receive_frame_t *);
139
140 /** @addtogroup DFU_FUNCTIONS Functions
141 * @{ */
142 /**
143 *****************************************************************************************
144 * @brief Function for initializing the DFU Used and Program State Callback.
145 *
146 * @note When APP wants to add DFU features, the flash_read and flash_write functions should be registered.
147 * To creat own DFU bootloaders, all functions in dfu_func_t should be registered. In order to show
148 * DFU program states by own DFU bootloaders, all functions in @ref dfu_pro_callback_t should be registered.
149 *
150 * @param[in] p_app_dfu_func: DFU used functions.
151 * @param[in] p_dfu_buffer: DFU data receiving buffer.
152 * @param[in] p_dfu_callback: DFU program state callback functions.
153 *****************************************************************************************
154 */
155 void dfu_init(dfu_func_t *p_app_dfu_func, uint8_t* p_dfu_buffer, dfu_pro_callback_t *p_dfu_callback);
156
157 /**
158 *****************************************************************************************
159 * @brief Function for reset the DFU cmd parse state.
160 *
161 * @note When APP wants to add DFU timeout feature, shoulde reset DFU cmd parse state when timeout.
162 *****************************************************************************************
163 */
164 void dfu_cmd_parse_state_reset(void);
165
166 /**
167 *****************************************************************************************
168 * @brief Function for setting the BLE MTU size.
169 *
170 * @note If the user wants to create his or her own DFU bootloader, the DFU MTU size should be
171 * set by using this function (when the MTU size is updated, this function should be called).
172 *
173 * @param[in] mtu_size: The BLE MTU size.
174 *****************************************************************************************
175 */
176 void dfu_ble_set_mtu_size(uint16_t mtu_size);
177
178 /**
179 *****************************************************************************************
180 * @brief This function should be called when BLE stack sends data completely.
181 *
182 * @note This function should be used when the user wants to create his or her own DFU bootloader.
183 *
184 * @retval void
185 *****************************************************************************************
186 */
187 void dfu_ble_send_data_cmpl_process(void);
188
189 /**
190 *****************************************************************************************
191 * @brief This function should be called when BLE receives data.
192 *
193 * @note This function should be used when the user wants to create his or her own DFU bootloader.
194 *
195 * @param[in] p_data: The received data from BLE.
196 * @param[in] length: The length of data.
197 *****************************************************************************************
198 */
199 void dfu_ble_receive_data_process(uint8_t *p_data, uint16_t length);
200
201 /**
202 *****************************************************************************************
203 * @brief This function should be called when UART receives data.
204 *
205 * @note This function should be used when the user wants to create his or her own DFU bootloader.
206 *
207 * @param[in] p_data: The received data from UART
208 * @param[in] length: The length of data
209 *****************************************************************************************
210 */
211 void dfu_uart_receive_data_process(uint8_t *p_data, uint16_t length);
212
213 /**
214 *****************************************************************************************
215 * @brief Function for checking DFU cmd.
216 *
217 * @note This function should be called in main loop.
218 *****************************************************************************************
219 */
220 void dfu_schedule(void);
221
222 /**
223 *****************************************************************************************
224 * @brief Function for set DFU cmd handler.
225 *
226 * @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,
227 * this function can be called.
228 *
229 * @param[in] index: The index of DFU cmd.
230 * @param[in] cmd: The code of DFU cmd.
231 * @param[in] cmd_handler: The handler of DFU cmd.
232 *****************************************************************************************
233 */
234 void dfu_set_cmd_handler(uint8_t index, uint16_t cmd, dfu_receive_cmd_handler_t cmd_handler);
235
236 /**
237 *****************************************************************************************
238 * @brief Function for initializing the DFU SPI Flash Callback.
239 *
240 * @note When APP wants to add DFU operationally external flash feature, the dfu_spi_flash_func_t should be registered.
241 *
242 * @param[in] spi_flash_func: DFU operationally external flash used functions.
243 *****************************************************************************************
244 */
245 void dfu_spi_flash_func_config(dfu_spi_flash_func_t *spi_flash_func);
246
247 /** @} */
248 #endif
249 /** @} */
250 /** @} */
dfu_image_info_t
Image information definition.
Definition: gr55xx_dfu.h:89
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_receive_frame_t::data
uint8_t * data
Pointer to data.
Definition: gr55xx_dfu.h:66
dfu_boot_info_t::is_dap_boot
uint32_t is_dap_boot
Bit: 11 check if boot dap mode.
Definition: gr55xx_dfu.h:83
dfu_func_t
DFU used functions config definition.
Definition: gr55xx_dfu.h:99
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
CMD type.
Definition: gr55xx_dfu.h:64
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
XIP Read Mode.
Definition: gr55xx_dfu.h:77
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
Check sum.
Definition: gr55xx_dfu.h:67
dfu_boot_info_t::system_clk
uint32_t system_clk
Bit: 5-7 system clock.
Definition: gr55xx_dfu.h:80
dfu_boot_info_t
Boot information definition.
Definition: gr55xx_dfu.h:72
dfu_boot_info_t::xqspi_speed
uint32_t xqspi_speed
Bit: 0-3 clock speed.
Definition: gr55xx_dfu.h:78
dfu_receive_frame_t
DFU frame information definition.
Definition: gr55xx_dfu.h:63
dfu_image_info_t::version
uint16_t version
Image version.
Definition: gr55xx_dfu.h:91
dfu_boot_info_t::boot_delay
uint32_t boot_delay
Bit: Boot delay flag.
Definition: gr55xx_dfu.h:82
dfu_boot_info_t::code_copy_mode
uint32_t code_copy_mode
Bit: 4 code copy mode.
Definition: gr55xx_dfu.h:79
dfu_schedule
void dfu_schedule(void)
Function for checking DFU cmd.
dfu_boot_info_t::check_image
uint32_t check_image
Bit: 8 check image.
Definition: gr55xx_dfu.h:81
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
Image boot info.
Definition: gr55xx_dfu.h:92
dfu_boot_info_t::load_addr
uint32_t load_addr
Firmware Load Address.
Definition: gr55xx_dfu.h:75
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
Firmware Run Address.
Definition: gr55xx_dfu.h:76
dfu_spi_flash_func_t
SPI used functions config definition.
Definition: gr55xx_dfu.h:113
dfu_boot_info_t::check_sum
uint32_t check_sum
Firmware Check Sum Value.
Definition: gr55xx_dfu.h:74
dfu_receive_frame_t::data_len
uint16_t data_len
Length of data.
Definition: gr55xx_dfu.h:65
dfu_pro_callback_t
DFU program state callback definition.
Definition: gr55xx_dfu.h:125
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
Image info pattern.
Definition: gr55xx_dfu.h:90
dfu_boot_info_t::reserved
uint32_t reserved
Bit: 24 reserved.
Definition: gr55xx_dfu.h:84
dfu_receive_cmd_handler_t
void(* dfu_receive_cmd_handler_t)(dfu_receive_frame_t *)
DFU receive cmd handler type.
Definition: gr55xx_dfu.h:138
dfu_boot_info_t::bin_size
uint32_t bin_size
Firmware Size.
Definition: gr55xx_dfu.h:73