nrf_mbr.h

00001 /*
00002  * Copyright (c) 2014 Nordic Semiconductor. All Rights Reserved.
00003  *
00004  * The information contained herein is confidential property of Nordic Semiconductor. The use,
00005  * copying, transfer or disclosure of such information is prohibited except by express written
00006  * agreement with Nordic Semiconductor.
00007  *
00008  */
00009 /**
00010   @defgroup nrf_mbr_api Master Boot Record API
00011   @{
00012      
00013   @brief APIs for updating SoftDevice and BootLoader
00014  
00015 */
00016 
00017 /* Header guard */
00018 #ifndef NRF_MBR_H__
00019 #define NRF_MBR_H__
00020 
00021 #include "nrf_svc.h"
00022 #include <stdint.h>
00023 
00024 
00025 /** @addtogroup NRF_MBR_DEFINES Defines
00026  * @{ */
00027 
00028 /**@brief MBR SVC Base number. */
00029 #define MBR_SVC_BASE 0x18   
00030 /** @} */
00031 
00032 /** @addtogroup NRF_MBR_ENUMS Enumerations
00033  * @{ */
00034 
00035 /**@brief nRF Master Boot Record API SVC numbers. */
00036 enum NRF_MBR_SVCS
00037 {
00038   SD_MBR_COMMAND = MBR_SVC_BASE, /**< ::sd_mbr_command */
00039 };
00040 
00041 /**@brief Possible values for ::sd_mbr_command_t.command */
00042 enum NRF_MBR_COMMANDS
00043 {
00044   SD_MBR_COMMAND_COPY_BL,               /**< Copy a new a new BootLoader. @see sd_mbr_command_copy_bl_t */
00045   SD_MBR_COMMAND_COPY_SD,               /**< Copy a new SoftDevice. @see ::sd_mbr_command_copy_sd_t*/
00046   SD_MBR_COMMAND_INIT_SD,               /**< Init forwarding interrupts to SD, and run reset function in SD*/
00047   SD_MBR_COMMAND_COMPARE,               /**< This command works like memcmp. @see ::sd_mbr_command_compare_t*/
00048   SD_MBR_COMMAND_VECTOR_TABLE_BASE_SET, /**< Start forwarding all exception to this address @see ::sd_mbr_command_vector_table_base_set_t*/
00049 };
00050 
00051 /** @} */
00052 
00053 /** @addtogroup NRF_MBR_TYPES Types
00054  * @{ */
00055 
00056 /**@brief This command copies part of a new SoftDevice
00057  * The destination area is erased before copying. 
00058  * If dst is in the middle of a flash page, that whole flash page will be erased.
00059  * If (dst+len) is in the middle of a flash page, that whole flash page will be erased.
00060  * 
00061  * The user of this function is responsible for setting the PROTENSET registers.
00062  * 
00063  * @retval ::NRF_SUCCESS indicates that the contents of the memory blocks where copied correctly.
00064  * @retval ::NRF_ERROR_INTERNAL indicates that the contents of the memory blocks where not verified correctly after copying.
00065  */
00066 typedef struct
00067 {
00068   uint32_t *src;  /**< Pointer to the source of data to be copied.*/
00069   uint32_t *dst;  /**< Pointer to the destination where the content is to be copied.*/
00070   uint32_t len;   /**< Number of 32 bit words to copy. Must be a multiple of 256 words*/
00071 }sd_mbr_command_copy_sd_t;
00072 
00073 
00074 /**@brief This command works like memcmp, but takes the length in words.
00075  *
00076  * @retval ::NRF_SUCCESS indicates that the contents of both memory blocks are equal.
00077  * @retval ::NRF_ERROR_NULL indicates that the contents of the memory blocks are not equal.
00078  */
00079 typedef struct
00080 {
00081   uint32_t *ptr1; /**< Pointer to block of memory */
00082   uint32_t *ptr2; /**< Pointer to block of memory */
00083   uint32_t len;   /**< Number of 32 bit words to compare*/
00084 }sd_mbr_command_compare_t;
00085 
00086 
00087 /**@brief This command copies a new BootLoader.
00088  *  With this command, destination of BootLoader is always the address written in NRF_UICR->BOOTADDR.
00089  *
00090  *  Destination is erased by this function.
00091  *  If (destination+bl_len) is in the middle of a flash page, that whole flash page will be erased.
00092  *
00093  *  This function will use PROTENSET to protect the flash that is not intended to be written.
00094  * 
00095  *  On Success, this function will not return. It will start the new BootLoader from reset-vector as normal.
00096  *
00097  * @retval ::NRF_ERROR_INVALID_STATE indicates that something was wrong.
00098  * @retval ::NRF_ERROR_INTERNAL indicates an internal error that should not happen.
00099  * @retval ::NRF_ERROR_FORBIDDEN if NRF_UICR->BOOTADDR is not set
00100  * @retval ::NRF_ERROR_INVALID_LENGTH is invalid.
00101  */
00102 typedef struct
00103 {
00104   uint32_t *bl_src;  /**< Pointer to the source of the Bootloader to be be copied.*/
00105   uint32_t bl_len;   /**< Number of 32 bit words to copy for BootLoader */
00106 }sd_mbr_command_copy_bl_t;
00107 
00108 /**@brief Sets the base address of the interrupt vector table for interrupts forwarded from the MBR
00109  * 
00110  * Once this function has been called, this address is where the MBR will start to forward interrupts to after a reset.
00111  *
00112  * To restore default forwarding thiss function should be called with @param address set to 0.
00113  * 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.
00114  *
00115  * @retval ::NRF_SUCCESS
00116  */
00117 typedef struct
00118 { 
00119   uint32_t address; /**< The base address of the interrupt vector table for forwarded interrupts.*/
00120 }sd_mbr_command_vector_table_base_set_t;
00121 
00122 typedef struct
00123 {
00124   uint32_t command;  /**< type of command to be issued see @ref NRF_MBR_COMMANDS. */
00125   union 
00126   {
00127     sd_mbr_command_copy_sd_t copy_sd;  /**< Parameters for copy*/
00128     sd_mbr_command_copy_bl_t copy_bl;  /**< Parameters for copy SoftDevice and BootLoader*/
00129     sd_mbr_command_compare_t compare;  /**< Parameters for verify*/
00130     sd_mbr_command_vector_table_base_set_t base_set; /**< Parameters for vector table base set.*/
00131   } params;
00132 }sd_mbr_command_t;
00133 
00134 /** @} */
00135 
00136 /** @addtogroup NRF_MBR_FUNCTIONS Functions
00137  * @{ */
00138 
00139 /**@brief Issue Master Boot Record commands
00140  *
00141  * Commands used when updating a SoftDevice and bootloader
00142  *
00143  * @param[in]  param Pointer to a struct describing the command
00144  *
00145  *@note for retvals see ::sd_mbr_command_copy_sd_t ::sd_mbr_command_copy_bl_t ::sd_mbr_command_compare_t
00146 
00147 */
00148 SVCALL(SD_MBR_COMMAND, uint32_t, sd_mbr_command(sd_mbr_command_t* param));
00149 
00150 /** @} */
00151 #endif // NRF_MBR_H__
00152 
00153 /**
00154   @}
00155 */