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_ADV_MAX_LENGTH 18 /**< The max length of advertisement is 18 bytes. */ 57 #define RECEIVE_MAX_LEN 2048 /**< The max length of received data is 2048 bytes. */ 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_ENUMERATIONS Enumerations 76 * @{ */ 77 78 /** @brief UART baudrate definition. */ 79 typedef enum { 80 DFU_UART_BAUDRATE_9600 = 9600, /**< Baudrate 9600. */ 81 DFU_UART_BAUDRATE_19200 = 19200, /**< Baudrate 19200. */ 82 DFU_UART_BAUDRATE_38400 = 38400, /**< Baudrate 38400. */ 83 DFU_UART_BAUDRATE_57600 = 57600, /**< Baudrate 57600. */ 84 DFU_UART_BAUDRATE_115200 = 115200, /**< Baudrate 115200. */ 85 DFU_UART_BAUDRATE_230400 = 230400, /**< Baudrate 230400. */ 86 DFU_UART_BAUDRATE_921600 = 921600, /**< Baudrate 921600. */ 87 } dfu_uart_baudrate_t; 88 89 /** @brief UART data bit definition. */ 90 typedef enum { 91 DFU_UART_DATA_BIT_5 = 0, /**< Data bit 5. */ 92 DFU_UART_DATA_BIT_6, /**< Data bit 6. */ 93 DFU_UART_DATA_BIT_7, /**< Data bit 7. */ 94 DFU_UART_DATA_BIT_8, /**< Data bit 8. */ 95 } dfu_uart_data_bit_t; 96 97 /** @brief UART stop bit definition. */ 98 typedef enum { 99 DFU_UART_STOP_BIT_1 = 0, /**< Stop bit 1. Avaliable when data bit = 5,6,7,8. */ 100 DFU_UART_STOP_BIT_1_5, /**< Stop bit 1.5. Avaliable when data bit = 5. */ 101 DFU_UART_STOP_BIT_2, /**< Stop bit 2. Avaliable when data bit = 6,7,8. */ 102 } dfu_uart_stop_bit_t; 103 104 /** @brief UART parity definition. */ 105 typedef enum { 106 DFU_UART_PARITY_NONE = 0, /**< Parity none. */ 107 DFU_UART_PARITY_ODD, /**< Parity odd. */ 108 DFU_UART_PARITY_EVEN, /**< Parity even. */ 109 DFU_UART_PARITY_SP_0, /**< Parity stick 0. */ 110 DFU_UART_PARITY_SP_1, /**< Parity stick 1. */ 111 } dfu_uart_parity_bit_t; 112 113 /** @brief UART pin group definition. */ 114 typedef enum { 115 DFU_UART_PIN_GROUP_0 = 0, /**< GPIO0_PIN3 -> UART0_TXD(MUX0),GPIO0_PIN4 -> UART0_RXD(MUX0)*/ 116 DFU_UART_PIN_GROUP_1, /**< GPIO0_PIN10 -> UART0_TXD(MUX2),GPIO0_PIN11 -> UART0_RXD(MUX2)*/ 117 DFU_UART_PIN_GROUP_2, /**< GPIO0_PIN0 -> UART0_TXD(MUX4),GPIO0_PIN1 -> UART0_RXD(MUX4)*/ 118 DFU_UART_PIN_GROUP_3, /**< GPIO1_PIN14 -> UART0_TXD(MUX5),GPIO1_PIN10 -> UART0_RXD(MUX5)*/ 119 DFU_UART_PIN_GROUP_4, /**< GPIO0_PIN7 -> UART1_TXD(MUX3),GPIO0_PIN6 -> UART1_RXD(MUX3)*/ 120 DFU_UART_PIN_GROUP_5, /**< GPIO0_PIN9 -> UART1_TXD(MUX3),GPIO0_PIN8 -> UART1_RXD(MUX3)*/ 121 } dfu_uart_pin_group_t; 122 123 /** @brief DFU informatica status. */ 124 typedef enum { 125 DFU_INFO_DISABLE = 0x5775, /**< DFU Config Info Disable. */ 126 DFU_INFO_ENABLE = 0x7ff7, /**< DFU Config Info Enable. */ 127 DFU_INFO_DEFAULT = 0x4774, /**< DFU Config Info DEFAULT */ 128 } dfu_info_state; 129 /** @} */ 130 131 /** @addtogroup DFU_STRUCTURES Structures 132 * @{ */ 133 134 /** @brief BootLoader information definition. */ 135 typedef struct { 136 uint32_t bin_size; /**< Firmware Size. */ 137 uint32_t check_sum; /**< Firmware Check Sum Value. */ 138 uint32_t load_addr; /**< Firmware Load Address. */ 139 uint32_t run_addr ; /**< Firmware Run Address. */ 140 uint32_t xqspi_xip_cmd; /**< XIP Read Mode. 0x03: Read mode, 0x0B: Fast Read mode, 141 0x3B: DualOut Fast Read mode, 142 0xBB: DualIO Fast Read mode, 143 0x6B: QuadOut Fast Read mode, 144 0xEB: QuadIO Fast Read mode */ 145 uint32_t xqspi_speed : 4; /**< Bit: 0-3 clock speed. 0 :64 MHz, 1:48 MHz, 146 2:32 MHz, 3:24 MHz, 4:16 MHz. */ 147 uint32_t code_copy_mode : 1; /**< Bit: 4 code copy mode. 0:XIP,1:QSPI. */ 148 uint32_t system_clk : 3; /**< Bit: 5-7 system clock. 0:64 MHz, 1:48 MHz, 2:32 MHz(xo), 149 3:24 MHz, 4:16 MHz, 5:32 MHz(cpll). */ 150 uint32_t check_image : 1; /**< Bit: 8 check image. */ 151 uint32_t boot_delay : 1; /**< Bit: Boot delay flag. */ 152 uint32_t is_dap_boot : 1; /**< Bit: 11 check if boot dap mode. */ 153 uint32_t reserved : 21; /**< Bit: 24 reserved. */ 154 } boot_info_t; 155 156 157 /** @brief DFU uart config definition. */ 158 typedef struct { 159 dfu_info_state state; /**< DFU UART Enable or Disable. This parameter can be a value of 160 @ref dfu_info_state. */ 161 dfu_uart_baudrate_t baud_rate; /**< UART communication baudrate. This parameter can be a value of 162 @ref dfu_uart_baudrate_t. */ 163 dfu_uart_data_bit_t data_bit; /**< The number of data bits transmitted or received in a frame. 164 This parameter can be a value of @ref dfu_uart_data_bit_t. */ 165 dfu_uart_stop_bit_t stop_bits; /**< The number of stop bits transmitted. 166 This parameter can be a value of @ref dfu_uart_stop_bit_t. */ 167 dfu_uart_parity_bit_t parity; /**< Specify the parity mode. This parameter can be a value of 168 @ref dfu_uart_parity_bit_t. */ 169 dfu_uart_pin_group_t pin_group; /**< Uart pin group. This parameter can be a value of 170 @ref dfu_uart_pin_group_t. */ 171 } dfu_uart_info_t; 172 173 /** @brief DFU Advertisement name config definition. */ 174 typedef struct { 175 dfu_info_state state; /**< If a set name is used, this parameter can be a value of 176 @ref dfu_info_state. */ 177 uint8_t adv_name[DFU_ADV_MAX_LENGTH]; /**< Adv name data. */ 178 uint16_t adv_name_length; /**< The length of the name. */ 179 } dfu_adv_name_info_t; 180 181 /** @brief DFU NVDS init info definition. */ 182 typedef struct { 183 dfu_info_state state; /**< If NVDS init is required, this parameter can be a value of 184 @ref dfu_info_state. */ 185 uint16_t page_size; /**< NVDS page size. */ 186 uint32_t start_address; /**< NVDS start address. */ 187 } dfu_nvds_info_t; 188 189 /** @brief DFU cmd disable info definition. */ 190 typedef struct { 191 dfu_info_state state; /**< If DFU cmd disable config is required, this parameter can be a value of 192 @ref dfu_info_state. */ 193 uint16_t cmd_bit_map; /**< NVDS start address. */ 194 } dfu_cmd_disable_t; 195 196 197 /** @brief DFU used functions config definition. */ 198 typedef struct { 199 /**< The function is used to send data to master by BLE. */ 200 void (*dfu_ble_send_data)(uint8_t *p_data, uint16_t length); 201 /**< The function is used to send data to master by UART. */ 202 void (*dfu_uart_send_data)(uint8_t *p_data, uint16_t length); 203 /**< The function is used to read data from flash. */ 204 uint32_t (*dfu_flash_read)(const uint32_t addr, uint8_t *p_buf, const uint32_t size); 205 /**< The function is used to write data to flash. */ 206 uint32_t (*dfu_flash_write)(const uint32_t addr, const uint8_t *p_buf, const uint32_t size); 207 /**< The function is used to erase flash by address. */ 208 bool (*dfu_flash_erase)(const uint32_t addr, const uint32_t size); 209 /**< The function is used to erase flash chip. */ 210 bool (*dfu_flash_erase_chip)(void); 211 /**< The function is used to set the flash security mode as Enable or Disable. */ 212 void (*dfu_flash_set_security)(bool enable); 213 /**< The function is used to get the flash security mode (Enable or Disable). */ 214 bool (*dfu_flash_get_security)(void); 215 /**< The function is used to get the flash id and size. */ 216 void (*dfu_flash_get_info)(uint32_t *id, uint32_t *size); 217 } dfu_func_t; 218 219 /** @brief SPI used functions config definition. */ 220 typedef struct { 221 /**< The function is used to config flash spi. */ 222 void (*dfu_spi_flash_init)(uint8_t *p_data); 223 /**< The function is used to read external flash . */ 224 uint32_t (*dfu_spi_flash_read)(uint32_t addr, uint8_t *buf, uint32_t size); 225 /**< The function is used to write external flash. */ 226 uint32_t (*dfu_spi_flash_write)(uint32_t addr, uint8_t *buf, uint32_t size); 227 /**< The function is used to erase external flash by address. */ 228 bool (*dfu_spi_flash_erase)(uint32_t addr, uint32_t size); 229 /**< The function is used to erase exteral flash chip. */ 230 bool (*dfu_spi_flash_erase_chip)(void); 231 /**< The function is used to get external flash id and size. */ 232 void (*dfu_spi_flash_get_info)(uint32_t *id, uint32_t *size); 233 } dfu_spi_flash_func_t; 234 235 236 /** @brief DFU program state callback definition. */ 237 typedef struct { 238 void (*dfu_program_start_callback)(void); /**<DFU program start callback. */ 239 void (*dfu_programing_callback)(uint8_t pro); /**<DFU programing callback. */ 240 void (*dfu_program_end_callback)(uint8_t status); /**<DFU program end callback. */ 241 } dfu_pro_callback_t; 242 243 /** @} */ 244 245 246 /** @addtogroup DFU_FUNCTIONS Functions 247 * @{ */ 248 /** 249 ***************************************************************************************** 250 * @brief Function for initializing the DFU Used and Program State Callback. 251 * 252 * @note When APP wants to add DFU features, the flash_read and flash_write functions should be registered. 253 * To creat own DFU bootloaders, all functions in dfu_func_t should be registered. In order to show 254 * DFU program states by own DFU bootloaders, all functions in @ref dfu_pro_callback_t should be registered. 255 * 256 * @param[in] p_app_dfu_func: DFU used functions. 257 * @param[in] p_dfu_buffer: DFU data receiving buffer. 258 * @param[in] p_dfu_callback: DFU program state callback functions. 259 ***************************************************************************************** 260 */ 261 void dfu_init(dfu_func_t *p_app_dfu_func, uint8_t* p_dfu_buffer, dfu_pro_callback_t *p_dfu_callback); 262 263 /** 264 ***************************************************************************************** 265 * @brief Function for reset the DFU cmd parse state. 266 * 267 * @note When APP wants to add DFU timeout feature, shoulde reset DFU cmd parse state when timeout. 268 ***************************************************************************************** 269 */ 270 void dfu_cmd_parse_state_reset(void); 271 272 /** 273 ***************************************************************************************** 274 * @brief Function for setting the BLE MTU size. 275 * 276 * @note If the user wants to create his or her own DFU bootloader, the DFU MTU size should be 277 * set by using this function (when the MTU size is updated, this function should be called). 278 * 279 * @param[in] mtu_size: The BLE MTU size. 280 ***************************************************************************************** 281 */ 282 void dfu_ble_set_mtu_size(uint16_t mtu_size); 283 284 /** 285 ***************************************************************************************** 286 * @brief This function should be called when BLE stack sends data completely. 287 * 288 * @note This function should be used when the user wants to create his or her own DFU bootloader. 289 * 290 * @retval void 291 ***************************************************************************************** 292 */ 293 void dfu_ble_send_data_cmpl_process(void); 294 295 /** 296 ***************************************************************************************** 297 * @brief This function should be called when BLE receives data. 298 * 299 * @note This function should be used when the user wants to create his or her own DFU bootloader. 300 * 301 * @param[in] p_data: The received data from BLE. 302 * @param[in] length: The length of data. 303 ***************************************************************************************** 304 */ 305 void dfu_ble_receive_data_process(uint8_t *p_data, uint16_t length); 306 307 /** 308 ***************************************************************************************** 309 * @brief This function should be called when UART receives data. 310 * 311 * @note This function should be used when the user wants to create his or her own DFU bootloader. 312 * 313 * @param[in] p_data: The received data from UART 314 * @param[in] length: The length of data 315 ***************************************************************************************** 316 */ 317 void dfu_uart_receive_data_process(uint8_t *p_data, uint16_t length); 318 319 /** 320 ***************************************************************************************** 321 * @brief Function for checking DFU cmd. 322 * 323 * @note This function should be called in main loop. 324 ***************************************************************************************** 325 */ 326 void dfu_schedule(void); 327 328 /** 329 ***************************************************************************************** 330 * @brief Function for jumping to address to run. 331 * 332 * @note In Apps, if the user wants to jump to another APP or own a DFU bootloader and run the code, 333 * this function can be called. This function does not change the boot info, 334 * so the original APP will run after resetting. 335 * 336 * @param[in] start_addr: The jumped address. 337 ***************************************************************************************** 338 */ 339 void dfu_start_jump(uint32_t start_addr); 340 341 /** 342 ***************************************************************************************** 343 * @brief Function for changing the boot info and reseting device. 344 * 345 * @note In Apps, if the user wants to jump to another APP or own a DFU bootloader and run the code, 346 * this function can be called (the boot info will be changed). 347 * 348 * @param[in] p_boot_info: The boot info of the APP you want to run. 349 ***************************************************************************************** 350 */ 351 void dfu_start_address(boot_info_t *p_boot_info); 352 353 /** 354 ***************************************************************************************** 355 * @brief Function for starting the default DFU bootloader(Only available for GR5515_D Chip). 356 * 357 * @note If the user wants to enter the default DFU bootloader, this function will be called. 358 * The dfu_uart_info can be used to start the UART DFU feature, and the DFU adv_name_info can 359 * be used to set the dfu adv name. 360 * (By default, the UART DFU feature ID is closed, and the default adv name is ble_dfu.). 361 * 362 * @param[in] p_dfu_uart_info: Default DFU bootloader UART info, NULL--the UART DFU feature is closed. 363 * @param[in] p_dfu_adv_name_info: Default DFU bootloader adv name, NULL--the adv name is ble_dfu. 364 * @param[in] p_dfu_nvds_info: NVDS init info, NULL--Not init NVDS. 365 ***************************************************************************************** 366 */ 367 void dfu_start_default(dfu_uart_info_t *p_dfu_uart_info, dfu_adv_name_info_t *p_dfu_adv_name_info, 368 dfu_nvds_info_t *p_dfu_nvds_info); 369 370 /** 371 ***************************************************************************************** 372 * @brief Function for set the default DFU bootloader informatica(Only available for GR5515_D Chip). 373 * 374 * @note If the user wants to set the default DFU bootloader informatica, this function will be called. 375 * The dfu_uart_info can be used to start the UART DFU feature, and the DFU adv_name_info can be 376 * used to set the dfu adv name. 377 * (By default, the UART DFU feature ID is closed, and the default adv name is ble_dfu.). 378 * 379 * @param[in] p_dfu_uart_info: Default DFU bootloader UART info, NULL--the UART DFU feature is closed. 380 * @param[in] p_dfu_adv_name_info: Default DFU bootloader adv name, NULL--the adv name is ble_dfu. 381 * @param[in] p_dfu_nvds_info: NVDS init info, NULL--Not init NVDS. 382 ***************************************************************************************** 383 */ 384 void dfu_start_set(dfu_uart_info_t *p_dfu_uart_info, dfu_adv_name_info_t *p_dfu_adv_name_info, 385 dfu_nvds_info_t *p_dfu_nvds_info); 386 387 388 /** 389 ***************************************************************************************** 390 * @brief Function for set DFU disable cmd. 391 * 392 * @note In Apps, if the user wants to jump to ROM DFU run,but want to be able to control 393 * the operation permissions of DFU, 394 * this function can be called. 395 * 396 * @param[in] disable_cmd_bit_map: The bitmask of DFU disable cmd See @ref DFU_CMD_DISABLE. 397 ***************************************************************************************** 398 */ 399 void dfu_set_disable_cmd(uint16_t disable_cmd_bit_map); 400 401 /** 402 ***************************************************************************************** 403 * @brief Function for initializing the DFU SPI Flash Callback. 404 * 405 * @note When APP wants to add DFU operationally external flash feature, the dfu_spi_flash_func_t should be registered. 406 * 407 * @param[in] spi_flash_func: DFU operationally external flash used functions. 408 ***************************************************************************************** 409 */ 410 void dfu_spi_flash_func_config(dfu_spi_flash_func_t *spi_flash_func); 411 412 /** @} */ 413 #endif 414 /** @} */ 415 /** @} */ 416