Jinu Andrews / nRF51

lib/ble/inc/nrf_mbr.h@0:6ba9b94b8997, 2017-02-09 (annotated)

Committer:
jinu
Date:
Thu Feb 09 06:08:17 2017 +0000
Revision:
0:6ba9b94b8997
NRF51 serialization libraries for mDot

Who changed what in which revision?

UserRevisionLine numberNew contents of line
jinu 0:6ba9b94b8997 1 /* Copyright (c) Nordic Semiconductor ASA
jinu 0:6ba9b94b8997 2 * All rights reserved.
jinu 0:6ba9b94b8997 3 *
jinu 0:6ba9b94b8997 4 * Redistribution and use in source and binary forms, with or without modification,
jinu 0:6ba9b94b8997 5 * are permitted provided that the following conditions are met:
jinu 0:6ba9b94b8997 6 *
jinu 0:6ba9b94b8997 7 * 1. Redistributions of source code must retain the above copyright notice, this
jinu 0:6ba9b94b8997 8 * list of conditions and the following disclaimer.
jinu 0:6ba9b94b8997 9 *
jinu 0:6ba9b94b8997 10 * 2. Redistributions in binary form must reproduce the above copyright notice, this
jinu 0:6ba9b94b8997 11 * list of conditions and the following disclaimer in the documentation and/or
jinu 0:6ba9b94b8997 12 * other materials provided with the distribution.
jinu 0:6ba9b94b8997 13 *
jinu 0:6ba9b94b8997 14 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other
jinu 0:6ba9b94b8997 15 * contributors to this software may be used to endorse or promote products
jinu 0:6ba9b94b8997 16 * derived from this software without specific prior written permission.
jinu 0:6ba9b94b8997 17 *
jinu 0:6ba9b94b8997 18 * 4. This software must only be used in a processor manufactured by Nordic
jinu 0:6ba9b94b8997 19 * Semiconductor ASA, or in a processor manufactured by a third party that
jinu 0:6ba9b94b8997 20 * is used in combination with a processor manufactured by Nordic Semiconductor.
jinu 0:6ba9b94b8997 21 *
jinu 0:6ba9b94b8997 22 *
jinu 0:6ba9b94b8997 23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
jinu 0:6ba9b94b8997 24 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
jinu 0:6ba9b94b8997 25 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
jinu 0:6ba9b94b8997 26 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
jinu 0:6ba9b94b8997 27 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
jinu 0:6ba9b94b8997 28 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
jinu 0:6ba9b94b8997 29 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
jinu 0:6ba9b94b8997 30 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
jinu 0:6ba9b94b8997 31 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
jinu 0:6ba9b94b8997 32 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
jinu 0:6ba9b94b8997 33 */
jinu 0:6ba9b94b8997 34 /**
jinu 0:6ba9b94b8997 35 @defgroup nrf_mbr_api Master Boot Record API
jinu 0:6ba9b94b8997 36 @{
jinu 0:6ba9b94b8997 37
jinu 0:6ba9b94b8997 38 @brief APIs for updating SoftDevice and BootLoader
jinu 0:6ba9b94b8997 39
jinu 0:6ba9b94b8997 40 */
jinu 0:6ba9b94b8997 41
jinu 0:6ba9b94b8997 42 /* Header guard */
jinu 0:6ba9b94b8997 43 #ifndef NRF_MBR_H__
jinu 0:6ba9b94b8997 44 #define NRF_MBR_H__
jinu 0:6ba9b94b8997 45
jinu 0:6ba9b94b8997 46 #include "nrf_svc.h"
jinu 0:6ba9b94b8997 47 #include <stdint.h>
jinu 0:6ba9b94b8997 48
jinu 0:6ba9b94b8997 49
jinu 0:6ba9b94b8997 50 /** @addtogroup NRF_MBR_DEFINES Defines
jinu 0:6ba9b94b8997 51 * @{ */
jinu 0:6ba9b94b8997 52
jinu 0:6ba9b94b8997 53 /**@brief MBR SVC Base number. */
jinu 0:6ba9b94b8997 54 #define MBR_SVC_BASE 0x18
jinu 0:6ba9b94b8997 55 /** @} */
jinu 0:6ba9b94b8997 56
jinu 0:6ba9b94b8997 57 /** @addtogroup NRF_MBR_ENUMS Enumerations
jinu 0:6ba9b94b8997 58 * @{ */
jinu 0:6ba9b94b8997 59
jinu 0:6ba9b94b8997 60 /**@brief nRF Master Boot Record API SVC numbers. */
jinu 0:6ba9b94b8997 61 enum NRF_MBR_SVCS
jinu 0:6ba9b94b8997 62 {
jinu 0:6ba9b94b8997 63 SD_MBR_COMMAND = MBR_SVC_BASE, /**< ::sd_mbr_command */
jinu 0:6ba9b94b8997 64 };
jinu 0:6ba9b94b8997 65
jinu 0:6ba9b94b8997 66 /**@brief Possible values for ::sd_mbr_command_t.command */
jinu 0:6ba9b94b8997 67 enum NRF_MBR_COMMANDS
jinu 0:6ba9b94b8997 68 {
jinu 0:6ba9b94b8997 69 SD_MBR_COMMAND_COPY_BL, /**< Copy a new a new BootLoader. @see sd_mbr_command_copy_bl_t */
jinu 0:6ba9b94b8997 70 SD_MBR_COMMAND_COPY_SD, /**< Copy a new SoftDevice. @see ::sd_mbr_command_copy_sd_t*/
jinu 0:6ba9b94b8997 71 SD_MBR_COMMAND_INIT_SD, /**< Init forwarding interrupts to SD, and run reset function in SD*/
jinu 0:6ba9b94b8997 72 SD_MBR_COMMAND_COMPARE, /**< This command works like memcmp. @see ::sd_mbr_command_compare_t*/
jinu 0:6ba9b94b8997 73 SD_MBR_COMMAND_VECTOR_TABLE_BASE_SET, /**< Start forwarding all exception to this address @see ::sd_mbr_command_vector_table_base_set_t*/
jinu 0:6ba9b94b8997 74 };
jinu 0:6ba9b94b8997 75
jinu 0:6ba9b94b8997 76 /** @} */
jinu 0:6ba9b94b8997 77
jinu 0:6ba9b94b8997 78 /** @addtogroup NRF_MBR_TYPES Types
jinu 0:6ba9b94b8997 79 * @{ */
jinu 0:6ba9b94b8997 80
jinu 0:6ba9b94b8997 81 /**@brief This command copies part of a new SoftDevice
jinu 0:6ba9b94b8997 82 * The destination area is erased before copying.
jinu 0:6ba9b94b8997 83 * If dst is in the middle of a flash page, that whole flash page will be erased.
jinu 0:6ba9b94b8997 84 * If (dst+len) is in the middle of a flash page, that whole flash page will be erased.
jinu 0:6ba9b94b8997 85 *
jinu 0:6ba9b94b8997 86 * The user of this function is responsible for setting the PROTENSET registers.
jinu 0:6ba9b94b8997 87 *
jinu 0:6ba9b94b8997 88 * @retval ::NRF_SUCCESS indicates that the contents of the memory blocks where copied correctly.
jinu 0:6ba9b94b8997 89 * @retval ::NRF_ERROR_INTERNAL indicates that the contents of the memory blocks where not verified correctly after copying.
jinu 0:6ba9b94b8997 90 */
jinu 0:6ba9b94b8997 91 typedef struct
jinu 0:6ba9b94b8997 92 {
jinu 0:6ba9b94b8997 93 uint32_t *src; /**< Pointer to the source of data to be copied.*/
jinu 0:6ba9b94b8997 94 uint32_t *dst; /**< Pointer to the destination where the content is to be copied.*/
jinu 0:6ba9b94b8997 95 uint32_t len; /**< Number of 32 bit words to copy. Must be a multiple of 256 words*/
jinu 0:6ba9b94b8997 96 }sd_mbr_command_copy_sd_t;
jinu 0:6ba9b94b8997 97
jinu 0:6ba9b94b8997 98
jinu 0:6ba9b94b8997 99 /**@brief This command works like memcmp, but takes the length in words.
jinu 0:6ba9b94b8997 100 *
jinu 0:6ba9b94b8997 101 * @retval ::NRF_SUCCESS indicates that the contents of both memory blocks are equal.
jinu 0:6ba9b94b8997 102 * @retval ::NRF_ERROR_NULL indicates that the contents of the memory blocks are not equal.
jinu 0:6ba9b94b8997 103 */
jinu 0:6ba9b94b8997 104 typedef struct
jinu 0:6ba9b94b8997 105 {
jinu 0:6ba9b94b8997 106 uint32_t *ptr1; /**< Pointer to block of memory */
jinu 0:6ba9b94b8997 107 uint32_t *ptr2; /**< Pointer to block of memory */
jinu 0:6ba9b94b8997 108 uint32_t len; /**< Number of 32 bit words to compare*/
jinu 0:6ba9b94b8997 109 }sd_mbr_command_compare_t;
jinu 0:6ba9b94b8997 110
jinu 0:6ba9b94b8997 111
jinu 0:6ba9b94b8997 112 /**@brief This command copies a new BootLoader.
jinu 0:6ba9b94b8997 113 * With this command, destination of BootLoader is always the address written in NRF_UICR->BOOTADDR.
jinu 0:6ba9b94b8997 114 *
jinu 0:6ba9b94b8997 115 * Destination is erased by this function.
jinu 0:6ba9b94b8997 116 * If (destination+bl_len) is in the middle of a flash page, that whole flash page will be erased.
jinu 0:6ba9b94b8997 117 *
jinu 0:6ba9b94b8997 118 * This function will use PROTENSET to protect the flash that is not intended to be written.
jinu 0:6ba9b94b8997 119 *
jinu 0:6ba9b94b8997 120 * On Success, this function will not return. It will start the new BootLoader from reset-vector as normal.
jinu 0:6ba9b94b8997 121 *
jinu 0:6ba9b94b8997 122 * @retval ::NRF_ERROR_INVALID_STATE indicates that something was wrong.
jinu 0:6ba9b94b8997 123 * @retval ::NRF_ERROR_INTERNAL indicates an internal error that should not happen.
jinu 0:6ba9b94b8997 124 * @retval ::NRF_ERROR_FORBIDDEN if NRF_UICR->BOOTADDR is not set
jinu 0:6ba9b94b8997 125 * @retval ::NRF_ERROR_INVALID_LENGTH is invalid.
jinu 0:6ba9b94b8997 126 */
jinu 0:6ba9b94b8997 127 typedef struct
jinu 0:6ba9b94b8997 128 {
jinu 0:6ba9b94b8997 129 uint32_t *bl_src; /**< Pointer to the source of the Bootloader to be be copied.*/
jinu 0:6ba9b94b8997 130 uint32_t bl_len; /**< Number of 32 bit words to copy for BootLoader */
jinu 0:6ba9b94b8997 131 }sd_mbr_command_copy_bl_t;
jinu 0:6ba9b94b8997 132
jinu 0:6ba9b94b8997 133 /**@brief Sets the base address of the interrupt vector table for interrupts forwarded from the MBR
jinu 0:6ba9b94b8997 134 *
jinu 0:6ba9b94b8997 135 * Once this function has been called, this address is where the MBR will start to forward interrupts to after a reset.
jinu 0:6ba9b94b8997 136 *
jinu 0:6ba9b94b8997 137 * To restore default forwarding thiss function should be called with @param address set to 0.
jinu 0:6ba9b94b8997 138 * The MBR will then start forwarding to interrupts to the adress in NFR_UICR->BOOTADDR or to the SoftDevice if the BOOTADDR is not set.
jinu 0:6ba9b94b8997 139 *
jinu 0:6ba9b94b8997 140 * @retval ::NRF_SUCCESS
jinu 0:6ba9b94b8997 141 */
jinu 0:6ba9b94b8997 142 typedef struct
jinu 0:6ba9b94b8997 143 {
jinu 0:6ba9b94b8997 144 uint32_t address; /**< The base address of the interrupt vector table for forwarded interrupts.*/
jinu 0:6ba9b94b8997 145 }sd_mbr_command_vector_table_base_set_t;
jinu 0:6ba9b94b8997 146
jinu 0:6ba9b94b8997 147 typedef struct
jinu 0:6ba9b94b8997 148 {
jinu 0:6ba9b94b8997 149 uint32_t command; /**< type of command to be issued see @ref NRF_MBR_COMMANDS. */
jinu 0:6ba9b94b8997 150 union
jinu 0:6ba9b94b8997 151 {
jinu 0:6ba9b94b8997 152 sd_mbr_command_copy_sd_t copy_sd; /**< Parameters for copy*/
jinu 0:6ba9b94b8997 153 sd_mbr_command_copy_bl_t copy_bl; /**< Parameters for copy SoftDevice and BootLoader*/
jinu 0:6ba9b94b8997 154 sd_mbr_command_compare_t compare; /**< Parameters for verify*/
jinu 0:6ba9b94b8997 155 sd_mbr_command_vector_table_base_set_t base_set; /**< Parameters for vector table base set.*/
jinu 0:6ba9b94b8997 156 } params;
jinu 0:6ba9b94b8997 157 }sd_mbr_command_t;
jinu 0:6ba9b94b8997 158
jinu 0:6ba9b94b8997 159 /** @} */
jinu 0:6ba9b94b8997 160
jinu 0:6ba9b94b8997 161 /** @addtogroup NRF_MBR_FUNCTIONS Functions
jinu 0:6ba9b94b8997 162 * @{ */
jinu 0:6ba9b94b8997 163
jinu 0:6ba9b94b8997 164 /**@brief Issue Master Boot Record commands
jinu 0:6ba9b94b8997 165 *
jinu 0:6ba9b94b8997 166 * Commands used when updating a SoftDevice and bootloader
jinu 0:6ba9b94b8997 167 *
jinu 0:6ba9b94b8997 168 * @param[in] param Pointer to a struct describing the command
jinu 0:6ba9b94b8997 169 *
jinu 0:6ba9b94b8997 170 *@note for retvals see ::sd_mbr_command_copy_sd_t ::sd_mbr_command_copy_bl_t ::sd_mbr_command_compare_t
jinu 0:6ba9b94b8997 171
jinu 0:6ba9b94b8997 172 */
jinu 0:6ba9b94b8997 173 SVCALL(SD_MBR_COMMAND, uint32_t, sd_mbr_command(sd_mbr_command_t* param));
jinu 0:6ba9b94b8997 174
jinu 0:6ba9b94b8997 175 /** @} */
jinu 0:6ba9b94b8997 176 #endif // NRF_MBR_H__
jinu 0:6ba9b94b8997 177
jinu 0:6ba9b94b8997 178 /**
jinu 0:6ba9b94b8997 179 @}
jinu 0:6ba9b94b8997 180 */
jinu 0:6ba9b94b8997 181