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