Nordic Semiconductor / nrf51-sdk

Nordic nrf51 sdk sources. Mirrored from https://github.com/ARMmbed/nrf51-sdk.

Dependents:   nRF51822 nRF51822

source/nordic_sdk/components/softdevice/s130/headers/nrf_mbr.h@28:041dac1366b2, 2016-04-07 (annotated)

Committer:
vcoubard
Date:
Thu Apr 07 17:37:56 2016 +0100
Revision:
28:041dac1366b2
Parent:
20:a90c48eb1d30
Child:
29:286940b7ee5a
Synchronized with git rev 012b8118

Author: Liyou Zhou

Pull in files from sdk 10.0

Who changed what in which revision?

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