dfu_ble_svc.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_ble_svc DFU BLE SVC 
00036  * @{
00037  *
00038  * @brief DFU BLE SVC in bootloader. The DFU BLE SuperVisor Calls allow an application to execute
00039  *        functions in the installed bootloader. 
00040  *
00041  * @details This module implements handling of SuperVisor Calls in the bootloader. 
00042  *          SuperVisor Calls allow for an application to execute calls into the bootloader.
00043  *          Currently, it is possible to exchange bonding information (like keys) from the 
00044  *          application to a bootloader supporting DFU OTA using BLE, so the update process can be 
00045  *          done through an already existing bond.
00046  *
00047  * @note The application must make sure that all SuperVisor Calls (SVC) are forwarded to the 
00048  *       bootloader to ensure correct behavior. Forwarding of SVCs to the bootloader is 
00049  *       done using the SoftDevice SVC @ref sd_softdevice_vector_table_base_set with the value 
00050  *       present in @c NRF_UICR->BOOTLOADERADDR.
00051  */
00052  
00053 #ifndef DFU_BLE_SVC_H__
00054 #define DFU_BLE_SVC_H__
00055 
00056 #include "nrf_svc.h"
00057 #include <stdint.h>
00058 #include "ble_gap.h"
00059 #include "nrf51.h"
00060 #include "nrf_soc.h"
00061 #include "nrf_error_sdm.h"
00062 
00063 #define BOOTLOADER_SVC_BASE     0x0     /**< The number of the lowest SVC number reserved for the bootloader. */
00064 #define SYSTEM_SERVICE_ATT_SIZE 8       /**< Size of the system service attribute length including CRC-16 at the end. */  
00065 
00066 /**@brief The SVC numbers used by the SVC functions in the SoC library. */
00067 enum BOOTLOADER_SVCS
00068 {
00069     DFU_BLE_SVC_SET_PEER_DATA = BOOTLOADER_SVC_BASE,    /**< SVC number for the setting of peer data call. */
00070     BOOTLOADER_SVC_LAST
00071 };
00072 
00073 /**@brief   DFU Peer data structure.
00074  *
00075  * @details This structure contains peer data needed for connection to a bonded device during DFU.
00076  *          The peer data must be provided by the application to the bootloader during buttonless
00077  *          update. See @ref dfu_ble_svc_set_peer_data. It contains bond information about the
00078  *          desired DFU peer.
00079  */
00080 typedef struct
00081 {
00082     ble_gap_addr_t      addr;                                   /**< BLE GAP address of the device that initiated the DFU process. */
00083     ble_gap_irk_t       irk;                                    /**< IRK of the device that initiated the DFU process if this device uses Private Resolvable Addresses. */
00084     ble_gap_enc_key_t   enc_key;                                /**< Encryption key structure containing encrypted diversifier and LTK for re-establishing the bond. */
00085     uint8_t             sys_serv_attr[SYSTEM_SERVICE_ATT_SIZE]; /**< System service attributes for restoring of Service Changed Indication setting in DFU mode. */
00086 } dfu_ble_peer_data_t;
00087 
00088 /**@brief   SVC Function for setting peer data containing address, IRK, and LTK to establish bonded
00089  *          connection in DFU mode.
00090  *
00091  * @param[in] p_peer_data  Pointer to the peer data containing keys for the connection.
00092  *
00093  * @retval NRF_ERROR_NULL If a NULL pointer was provided as argument.
00094  * @retval NRF_SUCCESS    If the function completed successfully.
00095  */
00096 SVCALL(DFU_BLE_SVC_SET_PEER_DATA, uint32_t, dfu_ble_svc_set_peer_data(dfu_ble_peer_data_t * p_peer_data));
00097 
00098 #endif // DFU_BLE_SVC_H__
00099 
00100 /** @} */