dfu.h

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 /** @} */