mbed official / mbed

The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

mbed 2

This is the mbed 2 library. If you'd like to learn about Mbed OS please see the mbed-os docs.

TARGET_NRF51_DONGLE/TOOLCHAIN_IAR/dfu.h@171:3a7713b1edbc, 2018-11-08 (annotated)

Committer:
AnnaBridge
Date:
Thu Nov 08 11:45:42 2018 +0000
Revision:
171:3a7713b1edbc
Parent:
TARGET_NRF51_DK/TARGET_NORDIC/TARGET_NRF5x/TARGET_SDK_11/libraries/bootloader_dfu/dfu.h@169:a7c7b631e539 
mbed library. Release version 164

Who changed what in which revision?

UserRevisionLine numberNew contents of line
AnnaBridge 143:86740a56073b 1 /*
AnnaBridge 143:86740a56073b 2 * Copyright (c) 2013 Nordic Semiconductor ASA
AnnaBridge 143:86740a56073b 3 * All rights reserved.
AnnaBridge 143:86740a56073b 4 *
AnnaBridge 143:86740a56073b 5 * Redistribution and use in source and binary forms, with or without modification,
AnnaBridge 143:86740a56073b 6 * are permitted provided that the following conditions are met:
AnnaBridge 143:86740a56073b 7 *
AnnaBridge 143:86740a56073b 8 * 1. Redistributions of source code must retain the above copyright notice, this list
AnnaBridge 143:86740a56073b 9 * of conditions and the following disclaimer.
AnnaBridge 143:86740a56073b 10 *
AnnaBridge 143:86740a56073b 11 * 2. Redistributions in binary form, except as embedded into a Nordic Semiconductor ASA
AnnaBridge 143:86740a56073b 12 * integrated circuit in a product or a software update for such product, must reproduce
AnnaBridge 143:86740a56073b 13 * the above copyright notice, this list of conditions and the following disclaimer in
AnnaBridge 143:86740a56073b 14 * the documentation and/or other materials provided with the distribution.
AnnaBridge 143:86740a56073b 15 *
AnnaBridge 143:86740a56073b 16 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its contributors may be
AnnaBridge 143:86740a56073b 17 * used to endorse or promote products derived from this software without specific prior
AnnaBridge 143:86740a56073b 18 * written permission.
AnnaBridge 143:86740a56073b 19 *
AnnaBridge 143:86740a56073b 20 * 4. This software, with or without modification, must only be used with a
AnnaBridge 143:86740a56073b 21 * Nordic Semiconductor ASA integrated circuit.
AnnaBridge 143:86740a56073b 22 *
AnnaBridge 143:86740a56073b 23 * 5. Any software provided in binary or object form under this license must not be reverse
AnnaBridge 143:86740a56073b 24 * engineered, decompiled, modified and/or disassembled.
AnnaBridge 143:86740a56073b 25 *
AnnaBridge 143:86740a56073b 26 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
AnnaBridge 143:86740a56073b 27 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
AnnaBridge 143:86740a56073b 28 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
AnnaBridge 143:86740a56073b 29 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
AnnaBridge 143:86740a56073b 30 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
AnnaBridge 143:86740a56073b 31 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
AnnaBridge 143:86740a56073b 32 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
AnnaBridge 143:86740a56073b 33 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
AnnaBridge 143:86740a56073b 34 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
AnnaBridge 143:86740a56073b 35 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
AnnaBridge 143:86740a56073b 36 *
AnnaBridge 143:86740a56073b 37 */
AnnaBridge 143:86740a56073b 38
AnnaBridge 143:86740a56073b 39
AnnaBridge 143:86740a56073b 40 /**@file
AnnaBridge 143:86740a56073b 41 *
AnnaBridge 143:86740a56073b 42 * @defgroup nrf_dfu Device Firmware Update API.
AnnaBridge 143:86740a56073b 43 * @{
AnnaBridge 143:86740a56073b 44 *
AnnaBridge 143:86740a56073b 45 * @brief Device Firmware Update module interface.
AnnaBridge 143:86740a56073b 46 */
AnnaBridge 143:86740a56073b 47
AnnaBridge 143:86740a56073b 48 #ifndef DFU_H__
AnnaBridge 143:86740a56073b 49 #define DFU_H__
AnnaBridge 143:86740a56073b 50
AnnaBridge 143:86740a56073b 51 #include <dfu_types.h>
AnnaBridge 143:86740a56073b 52 #include <stdbool.h>
AnnaBridge 143:86740a56073b 53 #include <stdint.h>
AnnaBridge 143:86740a56073b 54
AnnaBridge 143:86740a56073b 55
AnnaBridge 143:86740a56073b 56 /**@brief DFU event callback for asynchronous calls.
AnnaBridge 143:86740a56073b 57 *
AnnaBridge 143:86740a56073b 58 * @param[in] packet Packet type for which this callback is related. START_PACKET, DATA_PACKET.
AnnaBridge 143:86740a56073b 59 * @param[in] result Operation result code. NRF_SUCCESS when a queued operation was successful.
AnnaBridge 143:86740a56073b 60 * @param[in] p_data Pointer to the data to which the operation is related.
AnnaBridge 143:86740a56073b 61 */
AnnaBridge 143:86740a56073b 62 typedef void (*dfu_callback_t)(uint32_t packet, uint32_t result, uint8_t * p_data);
AnnaBridge 143:86740a56073b 63
AnnaBridge 143:86740a56073b 64 /**@brief Function for initializing the Device Firmware Update module.
AnnaBridge 143:86740a56073b 65 *
AnnaBridge 143:86740a56073b 66 * @return NRF_SUCCESS on success, an error_code otherwise.
AnnaBridge 143:86740a56073b 67 */
AnnaBridge 143:86740a56073b 68 uint32_t dfu_init(void);
AnnaBridge 143:86740a56073b 69
AnnaBridge 143:86740a56073b 70 /**@brief Function for registering a callback listener for \ref dfu_data_pkt_handle callbacks.
AnnaBridge 143:86740a56073b 71 *
AnnaBridge 143:86740a56073b 72 * @param[in] callback_handler Callback handler for receiving DFU events on completed operations
AnnaBridge 143:86740a56073b 73 * of DFU packets.
AnnaBridge 143:86740a56073b 74 */
AnnaBridge 143:86740a56073b 75 void dfu_register_callback(dfu_callback_t callback_handler);
AnnaBridge 143:86740a56073b 76
AnnaBridge 143:86740a56073b 77 /**@brief Function for setting the DFU image size.
AnnaBridge 143:86740a56073b 78 *
AnnaBridge 143:86740a56073b 79 * @details Function sets the DFU image size. This function must be called when an update is started
AnnaBridge 143:86740a56073b 80 * in order to notify the DFU of the new image size. If multiple images are to be
AnnaBridge 143:86740a56073b 81 * transferred within the same update context then this function must be called with size
AnnaBridge 143:86740a56073b 82 * information for each image being transfered.
AnnaBridge 143:86740a56073b 83 * If an image type is not being transfered, e.g. SoftDevice but no Application , then the
AnnaBridge 143:86740a56073b 84 * image size for application must be zero.
AnnaBridge 143:86740a56073b 85 *
AnnaBridge 143:86740a56073b 86 * @param[in] p_packet Pointer to the DFU packet containing information on DFU update process to
AnnaBridge 143:86740a56073b 87 * be started.
AnnaBridge 143:86740a56073b 88 *
AnnaBridge 143:86740a56073b 89 * @return NRF_SUCCESS on success, an error_code otherwise.
AnnaBridge 143:86740a56073b 90 */
AnnaBridge 143:86740a56073b 91 uint32_t dfu_start_pkt_handle(dfu_update_packet_t * p_packet);
AnnaBridge 143:86740a56073b 92
AnnaBridge 143:86740a56073b 93 /**@brief Function for handling DFU data packets.
AnnaBridge 143:86740a56073b 94 *
AnnaBridge 143:86740a56073b 95 * @param[in] p_packet Pointer to the DFU packet.
AnnaBridge 143:86740a56073b 96 *
AnnaBridge 143:86740a56073b 97 * @return NRF_SUCCESS on success, an error_code otherwise.
AnnaBridge 143:86740a56073b 98 */
AnnaBridge 143:86740a56073b 99 uint32_t dfu_data_pkt_handle(dfu_update_packet_t * p_packet);
AnnaBridge 143:86740a56073b 100
AnnaBridge 143:86740a56073b 101 /**@brief Function for handling DFU init packets.
AnnaBridge 143:86740a56073b 102 *
AnnaBridge 143:86740a56073b 103 * @return NRF_SUCCESS on success, an error_code otherwise.
AnnaBridge 143:86740a56073b 104 */
AnnaBridge 143:86740a56073b 105 uint32_t dfu_init_pkt_handle(dfu_update_packet_t * p_packet);
AnnaBridge 143:86740a56073b 106
AnnaBridge 143:86740a56073b 107 /**@brief Function for validating a transferred image after the transfer has completed.
AnnaBridge 143:86740a56073b 108 *
AnnaBridge 143:86740a56073b 109 * @return NRF_SUCCESS on success, an error_code otherwise.
AnnaBridge 143:86740a56073b 110 */
AnnaBridge 143:86740a56073b 111 uint32_t dfu_image_validate(void);
AnnaBridge 143:86740a56073b 112
AnnaBridge 143:86740a56073b 113 /**@brief Function for activating the transfered image after validation has successfully completed.
AnnaBridge 143:86740a56073b 114 *
AnnaBridge 143:86740a56073b 115 * @return NRF_SUCCESS on success, an error_code otherwise.
AnnaBridge 143:86740a56073b 116 */
AnnaBridge 143:86740a56073b 117 uint32_t dfu_image_activate(void);
AnnaBridge 143:86740a56073b 118
AnnaBridge 143:86740a56073b 119 /**@brief Function for reseting the current update procedure and return to initial state.
AnnaBridge 143:86740a56073b 120 *
AnnaBridge 143:86740a56073b 121 * @details This function call will result in a system reset to ensure correct system behavior.
AnnaBridge 143:86740a56073b 122 * The reset will might be scheduled to execute at a later point in time to ensure pending
AnnaBridge 143:86740a56073b 123 * flash operations has completed.
AnnaBridge 143:86740a56073b 124 */
AnnaBridge 143:86740a56073b 125 void dfu_reset(void);
AnnaBridge 143:86740a56073b 126
AnnaBridge 143:86740a56073b 127 /**@brief Function for validating that new bootloader has been correctly installed.
AnnaBridge 143:86740a56073b 128 *
AnnaBridge 143:86740a56073b 129 * @return NRF_SUCCESS if install was successful. NRF_ERROR_NULL if the images differs.
AnnaBridge 143:86740a56073b 130 */
AnnaBridge 143:86740a56073b 131 uint32_t dfu_bl_image_validate(void);
AnnaBridge 143:86740a56073b 132
AnnaBridge 143:86740a56073b 133 /**@brief Function for validating that new SoftDevicehas been correctly installed.
AnnaBridge 143:86740a56073b 134 *
AnnaBridge 143:86740a56073b 135 * @return NRF_SUCCESS if install was successful. NRF_ERROR_NULL if the images differs.
AnnaBridge 143:86740a56073b 136 */
AnnaBridge 143:86740a56073b 137 uint32_t dfu_sd_image_validate(void);
AnnaBridge 143:86740a56073b 138
AnnaBridge 143:86740a56073b 139 /**@brief Function for swapping existing bootloader with newly received.
AnnaBridge 143:86740a56073b 140 *
AnnaBridge 143:86740a56073b 141 * @return NRF_SUCCESS on succesfull swapping. For error code please refer to
AnnaBridge 143:86740a56073b 142 * \ref sd_mbr_command_copy_bl_t.
AnnaBridge 143:86740a56073b 143 */
AnnaBridge 143:86740a56073b 144 uint32_t dfu_bl_image_swap(void);
AnnaBridge 143:86740a56073b 145
AnnaBridge 143:86740a56073b 146 /**@brief Function for swapping existing SoftDevice with newly received.
AnnaBridge 143:86740a56073b 147 *
AnnaBridge 143:86740a56073b 148 * @return NRF_SUCCESS on succesfull swapping. For error code please refer to
AnnaBridge 143:86740a56073b 149 * \ref sd_mbr_command_copy_sd_t.
AnnaBridge 143:86740a56073b 150 */
AnnaBridge 143:86740a56073b 151 uint32_t dfu_sd_image_swap(void);
AnnaBridge 143:86740a56073b 152
AnnaBridge 143:86740a56073b 153 /**@brief Function for handling DFU init packet complete.
AnnaBridge 143:86740a56073b 154 *
AnnaBridge 143:86740a56073b 155 * @return NRF_SUCCESS on success, an error_code otherwise.
AnnaBridge 143:86740a56073b 156 */
AnnaBridge 143:86740a56073b 157 uint32_t dfu_init_pkt_complete(void);
AnnaBridge 143:86740a56073b 158
AnnaBridge 143:86740a56073b 159 #endif // DFU_H__
AnnaBridge 143:86740a56073b 160
AnnaBridge 143:86740a56073b 161 /** @} */