nrf_dfu_req_handler.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345
  1. /**
  2. * Copyright (c) 2016 - 2020, Nordic Semiconductor ASA
  3. *
  4. * All rights reserved.
  5. *
  6. * Redistribution and use in source and binary forms, with or without modification,
  7. * are permitted provided that the following conditions are met:
  8. *
  9. * 1. Redistributions of source code must retain the above copyright notice, this
  10. * list of conditions and the following disclaimer.
  11. *
  12. * 2. Redistributions in binary form, except as embedded into a Nordic
  13. * Semiconductor ASA integrated circuit in a product or a software update for
  14. * such product, must reproduce the above copyright notice, this list of
  15. * conditions and the following disclaimer in the documentation and/or other
  16. * materials provided with the distribution.
  17. *
  18. * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
  19. * contributors may be used to endorse or promote products derived from this
  20. * software without specific prior written permission.
  21. *
  22. * 4. This software, with or without modification, must only be used with a
  23. * Nordic Semiconductor ASA integrated circuit.
  24. *
  25. * 5. Any software provided in binary form under this license must not be reverse
  26. * engineered, decompiled, modified and/or disassembled.
  27. *
  28. * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
  29. * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  30. * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
  31. * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
  32. * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  33. * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  34. * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  35. * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  36. * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  37. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  38. *
  39. */
  40. /**@file
  41. *
  42. * @defgroup sdk_nrf_dfu_req_handler Request handling
  43. * @{
  44. * @ingroup nrf_dfu
  45. */
  46. #ifndef NRF_DFU_REQ_HANDLER_H__
  47. #define NRF_DFU_REQ_HANDLER_H__
  48. #include <stdint.h>
  49. #include <stdbool.h>
  50. #include "app_util_platform.h"
  51. #include "nrf_dfu_flash.h"
  52. #include "nrf_dfu_types.h"
  53. #ifdef __cplusplus
  54. extern "C"
  55. {
  56. #endif
  57. ANON_UNIONS_ENABLE;
  58. /**
  59. * @brief DFU object types.
  60. */
  61. typedef enum
  62. {
  63. NRF_DFU_OBJ_TYPE_INVALID, //!< Invalid object type.
  64. NRF_DFU_OBJ_TYPE_COMMAND, //!< Command object.
  65. NRF_DFU_OBJ_TYPE_DATA, //!< Data object.
  66. } nrf_dfu_obj_type_t;
  67. /**
  68. * @brief DFU protocol operation.
  69. */
  70. typedef enum
  71. {
  72. NRF_DFU_OP_PROTOCOL_VERSION = 0x00, //!< Retrieve protocol version.
  73. NRF_DFU_OP_OBJECT_CREATE = 0x01, //!< Create selected object.
  74. NRF_DFU_OP_RECEIPT_NOTIF_SET = 0x02, //!< Set receipt notification.
  75. NRF_DFU_OP_CRC_GET = 0x03, //!< Request CRC of selected object.
  76. NRF_DFU_OP_OBJECT_EXECUTE = 0x04, //!< Execute selected object.
  77. NRF_DFU_OP_OBJECT_SELECT = 0x06, //!< Select object.
  78. NRF_DFU_OP_MTU_GET = 0x07, //!< Retrieve MTU size.
  79. NRF_DFU_OP_OBJECT_WRITE = 0x08, //!< Write selected object.
  80. NRF_DFU_OP_PING = 0x09, //!< Ping.
  81. NRF_DFU_OP_HARDWARE_VERSION = 0x0A, //!< Retrieve hardware version.
  82. NRF_DFU_OP_FIRMWARE_VERSION = 0x0B, //!< Retrieve firmware version.
  83. NRF_DFU_OP_ABORT = 0x0C, //!< Abort the DFU procedure.
  84. NRF_DFU_OP_RESPONSE = 0x60, //!< Response.
  85. NRF_DFU_OP_INVALID = 0xFF,
  86. } nrf_dfu_op_t;
  87. /**
  88. * @brief DFU operation result code.
  89. */
  90. typedef enum
  91. {
  92. NRF_DFU_RES_CODE_INVALID = 0x00, //!< Invalid opcode.
  93. NRF_DFU_RES_CODE_SUCCESS = 0x01, //!< Operation successful.
  94. NRF_DFU_RES_CODE_OP_CODE_NOT_SUPPORTED = 0x02, //!< Opcode not supported.
  95. NRF_DFU_RES_CODE_INVALID_PARAMETER = 0x03, //!< Missing or invalid parameter value.
  96. NRF_DFU_RES_CODE_INSUFFICIENT_RESOURCES = 0x04, //!< Not enough memory for the data object.
  97. NRF_DFU_RES_CODE_INVALID_OBJECT = 0x05, //!< Data object does not match the firmware and hardware requirements, the signature is wrong, or parsing the command failed.
  98. NRF_DFU_RES_CODE_UNSUPPORTED_TYPE = 0x07, //!< Not a valid object type for a Create request.
  99. NRF_DFU_RES_CODE_OPERATION_NOT_PERMITTED = 0x08, //!< The state of the DFU process does not allow this operation.
  100. NRF_DFU_RES_CODE_OPERATION_FAILED = 0x0A, //!< Operation failed.
  101. NRF_DFU_RES_CODE_EXT_ERROR = 0x0B, //!< Extended error. The next byte of the response contains the error code of the extended error (see @ref nrf_dfu_ext_error_code_t.
  102. } nrf_dfu_result_t;
  103. typedef enum
  104. {
  105. NRF_DFU_FIRMWARE_TYPE_SOFTDEVICE = 0x00,
  106. NRF_DFU_FIRMWARE_TYPE_APPLICATION = 0x01,
  107. NRF_DFU_FIRMWARE_TYPE_BOOTLOADER = 0x02,
  108. NRF_DFU_FIRMWARE_TYPE_UNKNOWN = 0xFF,
  109. } nrf_dfu_firmware_type_t;
  110. /**
  111. * @brief @ref NRF_DFU_OP_PROTOCOL_VERSION response details.
  112. */
  113. typedef struct
  114. {
  115. uint8_t version; //!< Protocol version.
  116. } nrf_dfu_response_protocol_t;
  117. /**
  118. * @brief @ref NRF_DFU_OP_HARDWARE_VERSION response details.
  119. */
  120. typedef struct
  121. {
  122. uint32_t part; //!< Hardware part, from FICR register.
  123. uint32_t variant; //!< Hardware variant, from FICR register.
  124. struct
  125. {
  126. uint32_t rom_size; //!< ROM size, in bytes.
  127. uint32_t ram_size; //!< RAM size, in bytes.
  128. uint32_t rom_page_size; //!< ROM flash page size, in bytes.
  129. } memory;
  130. } nrf_dfu_response_hardware_t;
  131. /**
  132. * @brief @ref NRF_DFU_OP_FIRMWARE_VERSION response details.
  133. */
  134. typedef struct
  135. {
  136. nrf_dfu_firmware_type_t type; //!< Firmware type.
  137. uint32_t version; //!< Firmware version.
  138. uint32_t addr; //!< Firmware address in flash.
  139. uint32_t len; //!< Firmware length in bytes.
  140. } nrf_dfu_response_firmware_t;
  141. /**
  142. * @brief @ref NRF_DFU_OP_OBJECT_SELECT response details.
  143. */
  144. typedef struct
  145. {
  146. uint32_t offset; //!< Current offset.
  147. uint32_t crc; //!< Current CRC.
  148. uint32_t max_size; //!< Maximum size of selected object.
  149. } nrf_dfu_response_select_t;
  150. /**
  151. * @brief @ref NRF_DFU_OP_OBJECT_CREATE response details.
  152. */
  153. typedef struct
  154. {
  155. uint32_t offset; //!< Current offset
  156. uint32_t crc; //!< Current CRC.
  157. } nrf_dfu_response_create_t;
  158. /**
  159. * @brief @ref NRF_DFU_OP_OBJECT_WRITE response details.
  160. */
  161. typedef struct
  162. {
  163. uint32_t offset; //!< Used only when packet receipt notification is used.
  164. uint32_t crc; //!< Used only when packet receipt notification is used.
  165. } nrf_dfu_response_write_t;
  166. /**
  167. * @brief @ref NRF_DFU_OP_CRC_GET response details.
  168. */
  169. typedef struct
  170. {
  171. uint32_t offset; //!< Current offset.
  172. uint32_t crc; //!< Current CRC.
  173. } nrf_dfu_response_crc_t;
  174. /**
  175. * @brief @ref NRF_DFU_OP_PING response details.
  176. */
  177. typedef struct
  178. {
  179. uint8_t id; //!< The received ID which is echoed back.
  180. } nrf_dfu_response_ping_t;
  181. /**
  182. * @brief @ref NRF_DFU_OP_MTU_GET response details.
  183. */
  184. typedef struct
  185. {
  186. uint16_t size; //!< The MTU size as specified by the local transport.
  187. } nrf_dfu_response_mtu_t;
  188. /**
  189. * @brief DFU response message.
  190. */
  191. typedef struct
  192. {
  193. nrf_dfu_op_t request; //!< Requested operation.
  194. nrf_dfu_result_t result; //!< Result of the operation.
  195. union
  196. {
  197. nrf_dfu_response_protocol_t protocol; //!< Protocol version response.
  198. nrf_dfu_response_hardware_t hardware; //!< Hardware version response.
  199. nrf_dfu_response_firmware_t firmware; //!< Firmware version response.
  200. nrf_dfu_response_select_t select; //!< Select object response..
  201. nrf_dfu_response_create_t create; //!< Create object response..
  202. nrf_dfu_response_write_t write; //!< Write object response.
  203. nrf_dfu_response_crc_t crc; //!< CRC response.
  204. nrf_dfu_response_ping_t ping; //!< Ping response.
  205. nrf_dfu_response_mtu_t mtu; //!< MTU response.
  206. };
  207. } nrf_dfu_response_t;
  208. /**
  209. * @brief @ref NRF_DFU_OP_FIRMWARE_VERSION request details.
  210. */
  211. typedef struct
  212. {
  213. uint8_t image_number; //!< Index of the firmware.
  214. } nrf_dfu_request_firmware_t;
  215. /**
  216. * @brief @ref NRF_DFU_OP_OBJECT_SELECT request details.
  217. */
  218. typedef struct
  219. {
  220. uint32_t object_type; //!< Object type. See @ref nrf_dfu_obj_type_t.
  221. } nrf_dfu_request_select_t;
  222. /**
  223. * @brief @ref NRF_DFU_OP_OBJECT_CREATE request details.
  224. */
  225. typedef struct
  226. {
  227. uint32_t object_type; //!< Object type. See @ref nrf_dfu_obj_type_t.
  228. uint32_t object_size; //!< Object size in bytes.
  229. } nrf_dfu_request_create_t;
  230. /**
  231. * @brief @ref NRF_DFU_OP_OBJECT_WRITE request details.
  232. */
  233. typedef struct
  234. {
  235. uint8_t const * p_data; //!< Data.
  236. uint16_t len; //!< Length of data in @ref nrf_dfu_request_write_t::p_data.
  237. } nrf_dfu_request_write_t;
  238. /**
  239. * @brief @ref NRF_DFU_OP_PING request details.
  240. */
  241. typedef struct
  242. {
  243. uint8_t id; //!< Ping ID that will be returned in response.
  244. } nrf_dfu_request_ping_t;
  245. /**
  246. * @brief @ref NRF_DFU_OP_MTU_GET request details.
  247. */
  248. typedef struct
  249. {
  250. uint16_t size; //!< Transport MTU size in bytes.
  251. } nrf_dfu_request_mtu_t;
  252. /**
  253. * @brief @ref NRF_DFU_OP_RECEIPT_NOTIF_SET request details.
  254. */
  255. typedef struct
  256. {
  257. uint32_t target; //!< Target PRN.
  258. } nrf_dfu_request_prn_t;
  259. typedef void (*nrf_dfu_response_callback_t)(nrf_dfu_response_t * p_res, void * p_context);
  260. /**
  261. *@brief DFU request.
  262. */
  263. typedef struct
  264. {
  265. nrf_dfu_op_t request; //!< Requested operation.
  266. void * p_context;
  267. struct
  268. {
  269. nrf_dfu_response_callback_t response; //!< Callback to call to send the response.
  270. nrf_dfu_flash_callback_t write;
  271. } callback;
  272. union
  273. {
  274. nrf_dfu_request_firmware_t firmware; //!< Firmware version request.
  275. nrf_dfu_request_select_t select; //!< Select object request.
  276. nrf_dfu_request_create_t create; //!< Create object request.
  277. nrf_dfu_request_write_t write; //!< Write object request.
  278. nrf_dfu_request_ping_t ping; //!< Ping.
  279. nrf_dfu_request_mtu_t mtu; //!< MTU size request.
  280. nrf_dfu_request_prn_t prn; //!< Set receipt notification request.
  281. };
  282. } nrf_dfu_request_t;
  283. /**@brief Function for initializing the request handling module.
  284. *
  285. * @param observer Callback function for receiving notifications.
  286. *
  287. * @retval NRF_SUCCESS If the operation was successful.
  288. * @retval NRF_ERROR_INTERNAL If the init packet in flash is not valid.
  289. * @retval NRF_ERROR_INVALID_PARAM If observer is not provided.
  290. */
  291. ret_code_t nrf_dfu_req_handler_init(nrf_dfu_observer_t observer);
  292. /**@brief Function for scheduling processing of a DFU request.
  293. *
  294. * Requests are processed asynchronously by the scheduler.
  295. *
  296. * @param[in] p_req Request to be handled. The response callback must be non-null.
  297. *
  298. * @retval NRF_SUCCESS If the command request was executed successfully.
  299. * @retval NRF_ERROR_NO_MEM If the scheduler ran out of memory.
  300. * @retval NRF_ERROR_INVALID_PARAM If the response callback is NULL.
  301. */
  302. ret_code_t nrf_dfu_req_handler_on_req(nrf_dfu_request_t * p_req);
  303. ANON_UNIONS_DISABLE;
  304. #ifdef __cplusplus
  305. }
  306. #endif
  307. #endif // NRF_DFU_REQ_HANDLER_H__
  308. /** @} */