nrf_mbr.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  *   4. This software must only be used in a processor manufactured by Nordic
00020  *   Semiconductor ASA, or in a processor manufactured by a third party that
00021  *   is used in combination with a processor manufactured by Nordic Semiconductor.
00022  *
00023  *
00024  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
00025  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00026  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00027  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
00028  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00029  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00030  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
00031  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00032  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00033  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00034  *
00035  */
00036 /**
00037   @defgroup nrf_mbr_api Master Boot Record API
00038   @{
00039 
00040   @brief APIs for updating SoftDevice and BootLoader
00041 
00042 */
00043 
00044 /* Header guard */
00045 #ifndef NRF_MBR_H__
00046 #define NRF_MBR_H__
00047 
00048 #include "nrf_svc.h"
00049 #include <stdint.h>
00050 
00051 
00052 /** @addtogroup NRF_MBR_DEFINES Defines
00053  * @{ */
00054 
00055 /**@brief MBR SVC Base number. */
00056 #define MBR_SVC_BASE        (0x18)
00057 
00058 /**@brief Page size in words. */
00059 #define PAGE_SIZE_IN_WORDS 256
00060 /** @} */
00061 
00062 /** @addtogroup NRF_MBR_ENUMS Enumerations
00063  * @{ */
00064 
00065 /**@brief nRF Master Boot Record API SVC numbers. */
00066 enum NRF_MBR_SVCS
00067 {
00068   SD_MBR_COMMAND = MBR_SVC_BASE, /**< ::sd_mbr_command */
00069 };
00070 
00071 /**@brief Possible values for ::sd_mbr_command_t.command */
00072 enum NRF_MBR_COMMANDS
00073 {
00074   SD_MBR_COMMAND_COPY_BL,               /**< Copy a new BootLoader. @see sd_mbr_command_copy_bl_t */
00075   SD_MBR_COMMAND_COPY_SD,               /**< Copy a new SoftDevice. @see ::sd_mbr_command_copy_sd_t*/
00076   SD_MBR_COMMAND_INIT_SD,               /**< Init forwarding interrupts to SD, and run reset function in SD*/
00077   SD_MBR_COMMAND_COMPARE,               /**< This command works like memcmp. @see ::sd_mbr_command_compare_t*/
00078   SD_MBR_COMMAND_VECTOR_TABLE_BASE_SET, /**< Start forwarding all exception to this address @see ::sd_mbr_command_vector_table_base_set_t*/
00079 };
00080 
00081 /** @} */
00082 
00083 /** @addtogroup NRF_MBR_TYPES Types
00084  * @{ */
00085 
00086 /**@brief This command copies part of a new SoftDevice
00087  * The destination area is erased before copying.
00088  * If dst is in the middle of a flash page, that whole flash page will be erased.
00089  * If (dst+len) is in the middle of a flash page, that whole flash page will be erased.
00090  *
00091  * The user of this function is responsible for setting the PROTENSET registers.
00092  *
00093  * @retval ::NRF_SUCCESS indicates that the contents of the memory blocks where copied correctly.
00094  * @retval ::NRF_ERROR_INTERNAL indicates that the contents of the memory blocks where not verified correctly after copying.
00095  */
00096 typedef struct
00097 {
00098   uint32_t *src;  /**< Pointer to the source of data to be copied.*/
00099   uint32_t *dst;  /**< Pointer to the destination where the content is to be copied.*/
00100   uint32_t len;   /**< Number of 32 bit words to copy. Must be a multiple of @ref PAGE_SIZE_IN_WORDS words.*/
00101 } sd_mbr_command_copy_sd_t;
00102 
00103 
00104 /**@brief This command works like memcmp, but takes the length in words.
00105  *
00106  * @retval ::NRF_SUCCESS indicates that the contents of both memory blocks are equal.
00107  * @retval ::NRF_ERROR_NULL indicates that the contents of the memory blocks are not equal.
00108  */
00109 typedef struct
00110 {
00111   uint32_t *ptr1; /**< Pointer to block of memory. */
00112   uint32_t *ptr2; /**< Pointer to block of memory. */
00113   uint32_t len;   /**< Number of 32 bit words to compare.*/
00114 } sd_mbr_command_compare_t;
00115 
00116 
00117 /**@brief This command copies a new BootLoader.
00118  *  With this command, destination of BootLoader is always the address written in NRF_UICR->BOOTADDR.
00119  *
00120  *  Destination is erased by this function.
00121  *  If (destination+bl_len) is in the middle of a flash page, that whole flash page will be erased.
00122  *
00123  *  This function will use PROTENSET to protect the flash that is not intended to be written.
00124  *
00125  *  On Success, this function will not return. It will start the new BootLoader from reset-vector as normal.
00126  *
00127  * @retval ::NRF_ERROR_INTERNAL indicates an internal error that should not happen.
00128  * @retval ::NRF_ERROR_FORBIDDEN if NRF_UICR->BOOTADDR is not set.
00129  * @retval ::NRF_ERROR_INVALID_LENGTH if parameters attempts to read or write outside flash area.
00130  */
00131 typedef struct
00132 {
00133   uint32_t *bl_src;  /**< Pointer to the source of the Bootloader to be be copied.*/
00134   uint32_t bl_len;   /**< Number of 32 bit words to copy for BootLoader. */
00135 } sd_mbr_command_copy_bl_t;
00136 
00137 /**@brief Sets the base address of the interrupt vector table for interrupts forwarded from the MBR
00138  *
00139  * Once this function has been called, this address is where the MBR will start to forward interrupts to after a reset.
00140  *
00141  * To restore default forwarding this function should be called with @param address set to 0.
00142  * 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.
00143  *
00144  * @retval ::NRF_ERROR_INTERNAL indicates an internal error that should not happen.
00145  * @retval ::NRF_ERROR_INVALID_ADDR if parameter address is outside of the flash size.
00146  */
00147 typedef struct
00148 {
00149   uint32_t address; /**< The base address of the interrupt vector table for forwarded interrupts.*/
00150 } sd_mbr_command_vector_table_base_set_t;
00151 
00152 typedef struct
00153 {
00154   uint32_t command;  /**< type of command to be issued see @ref NRF_MBR_COMMANDS. */
00155   union
00156   {
00157     sd_mbr_command_copy_sd_t copy_sd;  /**< Parameters for copy SoftDevice.*/
00158     sd_mbr_command_copy_bl_t copy_bl;  /**< Parameters for copy BootLoader.*/
00159     sd_mbr_command_compare_t compare;  /**< Parameters for verify.*/
00160     sd_mbr_command_vector_table_base_set_t base_set; /**< Parameters for vector table base set.*/
00161   } params;
00162 } sd_mbr_command_t;
00163 
00164 /** @} */
00165 
00166 /** @addtogroup NRF_MBR_FUNCTIONS Functions
00167  * @{ */
00168 
00169 /**@brief Issue Master Boot Record commands
00170  *
00171  * Commands used when updating a SoftDevice and bootloader.
00172  *
00173  * @param[in]  param Pointer to a struct describing the command.
00174  *
00175  *@note for retvals see ::sd_mbr_command_copy_sd_t ::sd_mbr_command_copy_bl_t ::sd_mbr_command_compare_t
00176 
00177 */
00178 SVCALL(SD_MBR_COMMAND, uint32_t, sd_mbr_command(sd_mbr_command_t* param));
00179 
00180 /** @} */
00181 #endif // NRF_MBR_H__
00182 
00183 /**
00184   @}
00185 */