test
Fork of nrf51-sdk by
Embed:
(wiki syntax)
Show/hide line numbers
dfu.h
Go to the documentation of this file.
00001 /* 00002 * Copyright (c) Nordic Semiconductor ASA 00003 * All rights reserved. 00004 * 00005 * Redistribution and use in source and binary forms, with or without modification, 00006 * are permitted provided that the following conditions are met: 00007 * 00008 * 1. Redistributions of source code must retain the above copyright notice, this 00009 * list of conditions and the following disclaimer. 00010 * 00011 * 2. Redistributions in binary form must reproduce the above copyright notice, this 00012 * list of conditions and the following disclaimer in the documentation and/or 00013 * other materials provided with the distribution. 00014 * 00015 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other 00016 * contributors to this software may be used to endorse or promote products 00017 * derived from this software without specific prior written permission. 00018 * 00019 * 00020 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 00021 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 00022 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 00023 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 00024 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 00025 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 00026 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 00027 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 00028 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 00029 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00030 * 00031 */ 00032 00033 /**@file 00034 * 00035 * @defgroup nrf_dfu Device Firmware Update API. 00036 * @{ 00037 * 00038 * @brief Device Firmware Update module interface. 00039 */ 00040 00041 #ifndef DFU_H__ 00042 #define DFU_H__ 00043 00044 #include <dfu_types.h > 00045 #include <stdbool.h> 00046 #include <stdint.h> 00047 00048 00049 /**@brief DFU event callback for asynchronous calls. 00050 * 00051 * @param[in] packet Packet type for which this callback is related. START_PACKET, DATA_PACKET. 00052 * @param[in] result Operation result code. NRF_SUCCESS when a queued operation was successful. 00053 * @param[in] p_data Pointer to the data to which the operation is related. 00054 */ 00055 typedef void (*dfu_callback_t)(uint32_t packet, uint32_t result, uint8_t * p_data); 00056 00057 /**@brief Function for initializing the Device Firmware Update module. 00058 * 00059 * @return NRF_SUCCESS on success, an error_code otherwise. 00060 */ 00061 uint32_t dfu_init(void); 00062 00063 /**@brief Function for registering a callback listener for \ref dfu_data_pkt_handle callbacks. 00064 * 00065 * @param[in] callback_handler Callback handler for receiving DFU events on completed operations 00066 * of DFU packets. 00067 */ 00068 void dfu_register_callback(dfu_callback_t callback_handler); 00069 00070 /**@brief Function for setting the DFU image size. 00071 * 00072 * @details Function sets the DFU image size. This function must be called when an update is started 00073 * in order to notify the DFU of the new image size. If multiple images are to be 00074 * transferred within the same update context then this function must be called with size 00075 * information for each image being transfered. 00076 * If an image type is not being transfered, e.g. SoftDevice but no Application , then the 00077 * image size for application must be zero. 00078 * 00079 * @param[in] p_packet Pointer to the DFU packet containing information on DFU update process to 00080 * be started. 00081 * 00082 * @return NRF_SUCCESS on success, an error_code otherwise. 00083 */ 00084 uint32_t dfu_start_pkt_handle(dfu_update_packet_t * p_packet); 00085 00086 /**@brief Function for handling DFU data packets. 00087 * 00088 * @param[in] p_packet Pointer to the DFU packet. 00089 * 00090 * @return NRF_SUCCESS on success, an error_code otherwise. 00091 */ 00092 uint32_t dfu_data_pkt_handle(dfu_update_packet_t * p_packet); 00093 00094 /**@brief Function for handling DFU init packets. 00095 * 00096 * @return NRF_SUCCESS on success, an error_code otherwise. 00097 */ 00098 uint32_t dfu_init_pkt_handle(dfu_update_packet_t * p_packet); 00099 00100 /**@brief Function for validating a transferred image after the transfer has completed. 00101 * 00102 * @return NRF_SUCCESS on success, an error_code otherwise. 00103 */ 00104 uint32_t dfu_image_validate(void); 00105 00106 /**@brief Function for activating the transfered image after validation has successfully completed. 00107 * 00108 * @return NRF_SUCCESS on success, an error_code otherwise. 00109 */ 00110 uint32_t dfu_image_activate(void); 00111 00112 /**@brief Function for reseting the current update procedure and return to initial state. 00113 * 00114 * @details This function call will result in a system reset to ensure correct system behavior. 00115 * The reset will might be scheduled to execute at a later point in time to ensure pending 00116 * flash operations has completed. 00117 */ 00118 void dfu_reset(void); 00119 00120 /**@brief Function for validating that new bootloader has been correctly installed. 00121 * 00122 * @return NRF_SUCCESS if install was successful. NRF_ERROR_NULL if the images differs. 00123 */ 00124 uint32_t dfu_bl_image_validate(void); 00125 00126 /**@brief Function for validating that new SoftDevicehas been correctly installed. 00127 * 00128 * @return NRF_SUCCESS if install was successful. NRF_ERROR_NULL if the images differs. 00129 */ 00130 uint32_t dfu_sd_image_validate(void); 00131 00132 /**@brief Function for swapping existing bootloader with newly received. 00133 * 00134 * @return NRF_SUCCESS on succesfull swapping. For error code please refer to 00135 * \ref sd_mbr_command_copy_bl_t. 00136 */ 00137 uint32_t dfu_bl_image_swap(void); 00138 00139 /**@brief Function for swapping existing SoftDevice with newly received. 00140 * 00141 * @return NRF_SUCCESS on succesfull swapping. For error code please refer to 00142 * \ref sd_mbr_command_copy_sd_t. 00143 */ 00144 uint32_t dfu_sd_image_swap(void); 00145 00146 /**@brief Function for handling DFU init packet complete. 00147 * 00148 * @return NRF_SUCCESS on success, an error_code otherwise. 00149 */ 00150 uint32_t dfu_init_pkt_complete(void); 00151 00152 #endif // DFU_H__ 00153 00154 /** @} */
Generated on Tue Jul 12 2022 15:51:26 by 1.7.2