bootloader.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_bootloader Bootloader API.
00036  * @{     
00037  *
00038  * @brief Bootloader module interface.
00039  */
00040 
00041 #ifndef BOOTLOADER_H__
00042 #define BOOTLOADER_H__
00043 
00044 #include <stdbool.h>
00045 #include <stdint.h>
00046 #include "bootloader_types.h "
00047 #include <dfu_types.h >
00048 
00049 /**@brief Function for initializing the Bootloader.
00050  * 
00051  * @retval     NRF_SUCCESS If bootloader was succesfully initialized. 
00052  */
00053 uint32_t bootloader_init(void);
00054 
00055 /**@brief Function for validating application region in flash.
00056  * 
00057  * @param[in]  app_addr      Address to the region in flash where the application is stored.
00058  * 
00059  * @retval     true          If Application region is valid.
00060  * @retval     false         If Application region is not valid.
00061  */
00062 bool bootloader_app_is_valid(uint32_t app_addr);
00063 
00064 /**@brief Function for starting the Device Firmware Update.
00065  * 
00066  * @retval     NRF_SUCCESS If new application image was successfully transferred.
00067  */
00068 uint32_t bootloader_dfu_start(void);
00069 
00070 /**@brief Function for exiting bootloader and booting into application.
00071  *
00072  * @details This function will disable SoftDevice and all interrupts before jumping to application.
00073  *          The SoftDevice vector table base for interrupt forwarding will be set the application
00074  *          address.
00075  *
00076  * @param[in]  app_addr      Address to the region where the application is stored.
00077  */
00078 void bootloader_app_start(uint32_t app_addr);
00079 
00080 /**@brief Function for retrieving the bootloader settings.
00081  *
00082  * @param[out] p_settings    A copy of the current bootloader settings is returned in the structure
00083  *                           provided.
00084  */
00085 void bootloader_settings_get(bootloader_settings_t * const p_settings);
00086 
00087 /**@brief Function for processing DFU status update.
00088  *
00089  * @param[in]  update_status DFU update status.
00090  */
00091 void bootloader_dfu_update_process(dfu_update_status_t update_status);
00092 
00093 /**@brief Function getting state of SoftDevice update in progress.
00094  *        After a successfull SoftDevice transfer the system restarts in orderto disable SoftDevice
00095  *        and complete the update.
00096  *
00097  * @retval     true          A SoftDevice update is in progress. This indicates that second stage 
00098  *                           of a SoftDevice update procedure can be initiated.
00099  * @retval     false         No SoftDevice update is in progress.
00100  */
00101 bool bootloader_dfu_sd_in_progress(void);
00102 
00103 /**@brief Function for continuing the Device Firmware Update of a SoftDevice.
00104  * 
00105  * @retval     NRF_SUCCESS If the final stage of SoftDevice update was successful. 
00106  */
00107 uint32_t bootloader_dfu_sd_update_continue(void);
00108 
00109 /**@brief Function for finalizing the Device Firmware Update of a SoftDevice.
00110  * 
00111  * @retval     NRF_SUCCESS If the final stage of SoftDevice update was successful. 
00112  */
00113 uint32_t bootloader_dfu_sd_update_finalize(void);
00114 
00115 #endif // BOOTLOADER_H__
00116 
00117 /**@} */