2020-04-22 01:33:39 -04:00
/*
* Copyright ( c ) 2014 - 2017 , Nordic Semiconductor ASA
* All rights reserved .
*
* Redistribution and use in source and binary forms , with or without modification ,
* are permitted provided that the following conditions are met :
*
* 1. Redistributions of source code must retain the above copyright notice , this
* list of conditions and the following disclaimer .
*
* 2. Redistributions in binary form , except as embedded into a Nordic
* Semiconductor ASA integrated circuit in a product or a software update for
* such product , must reproduce the above copyright notice , this list of
* conditions and the following disclaimer in the documentation and / or other
* materials provided with the distribution .
*
* 3. Neither the name of Nordic Semiconductor ASA nor the names of its
* contributors may be used to endorse or promote products derived from this
* software without specific prior written permission .
*
* 4. This software , with or without modification , must only be used with a
* Nordic Semiconductor ASA integrated circuit .
*
* 5. Any software provided in binary form under this license must not be reverse
* engineered , decompiled , modified and / or disassembled .
*
* THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA " AS IS " AND ANY EXPRESS
* OR IMPLIED WARRANTIES , INCLUDING , BUT NOT LIMITED TO , THE IMPLIED WARRANTIES
* OF MERCHANTABILITY , NONINFRINGEMENT , AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED . IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT , INDIRECT , INCIDENTAL , SPECIAL , EXEMPLARY , OR
* CONSEQUENTIAL DAMAGES ( INCLUDING , BUT NOT LIMITED TO , PROCUREMENT OF SUBSTITUTE
* GOODS OR SERVICES ; LOSS OF USE , DATA , OR PROFITS ; OR BUSINESS INTERRUPTION )
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY , WHETHER IN CONTRACT , STRICT
* LIABILITY , OR TORT ( INCLUDING NEGLIGENCE OR OTHERWISE ) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE , EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE .
*/
/**
@ defgroup nrf_mbr_api Master Boot Record API
@ {
@ brief APIs for updating SoftDevice and BootLoader
*/
# ifndef NRF_MBR_H__
# define NRF_MBR_H__
# include "nrf_svc.h"
# include <stdint.h>
# ifdef __cplusplus
extern " C " {
# endif
/** @addtogroup NRF_MBR_DEFINES Defines
* @ { */
/**@brief MBR SVC Base number. */
# define MBR_SVC_BASE (0x18)
/**@brief Page size in words. */
# define MBR_PAGE_SIZE_IN_WORDS (1024)
/** @brief The size that must be reserved for the MBR when a SoftDevice is written to flash.
This is the offset where the first byte of the SoftDevice hex file is written . */
# define MBR_SIZE (0x1000)
/** @brief Location (in the flash memory) of the bootloader address. */
# define MBR_BOOTLOADER_ADDR (0xFF8)
/** @brief Location (in UICR) of the bootloader address. */
# define MBR_UICR_BOOTLOADER_ADDR (&(NRF_UICR->NRFFW[0]))
/** @brief Location (in the flash memory) of the address of the MBR parameter page. */
# define MBR_PARAM_PAGE_ADDR (0xFFC)
/** @brief Location (in UICR) of the address of the MBR parameter page. */
# define MBR_UICR_PARAM_PAGE_ADDR (&(NRF_UICR->NRFFW[1]))
/** @} */
/** @addtogroup NRF_MBR_ENUMS Enumerations
* @ { */
/**@brief nRF Master Boot Record API SVC numbers. */
enum NRF_MBR_SVCS
{
2021-03-15 09:57:36 -04:00
SD_MBR_COMMAND = MBR_SVC_BASE , /**< ::sd_mbr_command */
2020-04-22 01:33:39 -04:00
} ;
/**@brief Possible values for ::sd_mbr_command_t.command */
enum NRF_MBR_COMMANDS
{
2021-03-15 09:57:36 -04:00
SD_MBR_COMMAND_COPY_BL , /**< Copy a new BootLoader. @see ::sd_mbr_command_copy_bl_t*/
SD_MBR_COMMAND_COPY_SD , /**< Copy a new SoftDevice. @see ::sd_mbr_command_copy_sd_t*/
SD_MBR_COMMAND_INIT_SD , /**< Initialize forwarding interrupts to SD, and run reset function in SD. Does not require any parameters in ::sd_mbr_command_t params.*/
SD_MBR_COMMAND_COMPARE , /**< This command works like memcmp. @see ::sd_mbr_command_compare_t*/
SD_MBR_COMMAND_VECTOR_TABLE_BASE_SET , /**< Change the address the MBR starts after a reset. @see ::sd_mbr_command_vector_table_base_set_t*/
SD_MBR_COMMAND_RESERVED ,
SD_MBR_COMMAND_IRQ_FORWARD_ADDRESS_SET , /**< Start forwarding all interrupts to this address. @see ::sd_mbr_command_irq_forward_address_set_t*/
2020-04-22 01:33:39 -04:00
} ;
/** @} */
/** @addtogroup NRF_MBR_TYPES Types
* @ { */
/**@brief This command copies part of a new SoftDevice
*
* The destination area is erased before copying .
* If dst is in the middle of a flash page , that whole flash page will be erased .
* If ( dst + len ) is in the middle of a flash page , that whole flash page will be erased .
*
* The user of this function is responsible for setting the BPROT registers .
*
* @ retval : : NRF_SUCCESS indicates that the contents of the memory blocks where copied correctly .
* @ retval : : NRF_ERROR_INTERNAL indicates that the contents of the memory blocks where not verified correctly after copying .
*/
typedef struct
{
2021-03-15 09:57:36 -04:00
uint32_t * src ; /**< Pointer to the source of data to be copied.*/
uint32_t * dst ; /**< Pointer to the destination where the content is to be copied.*/
uint32_t len ; /**< Number of 32 bit words to copy. Must be a multiple of @ref MBR_PAGE_SIZE_IN_WORDS words.*/
2020-04-22 01:33:39 -04:00
} sd_mbr_command_copy_sd_t ;
/**@brief This command works like memcmp, but takes the length in words.
*
* @ retval : : NRF_SUCCESS indicates that the contents of both memory blocks are equal .
* @ retval : : NRF_ERROR_NULL indicates that the contents of the memory blocks are not equal .
*/
typedef struct
{
2021-03-15 09:57:36 -04:00
uint32_t * ptr1 ; /**< Pointer to block of memory. */
uint32_t * ptr2 ; /**< Pointer to block of memory. */
uint32_t len ; /**< Number of 32 bit words to compare.*/
2020-04-22 01:33:39 -04:00
} sd_mbr_command_compare_t ;
/**@brief This command copies a new BootLoader.
*
* The MBR assumes that either @ ref MBR_BOOTLOADER_ADDR or @ ref MBR_UICR_BOOTLOADER_ADDR is set to
* the address where the bootloader will be copied . If both addresses are set , the MBR will prioritize
* @ ref MBR_BOOTLOADER_ADDR .
*
* The bootloader destination is erased by this function .
* If ( destination + bl_len ) is in the middle of a flash page , that whole flash page will be erased .
*
* This command requires that @ ref MBR_PARAM_PAGE_ADDR or @ ref MBR_UICR_PARAM_PAGE_ADDR is set ,
* see @ ref sd_mbr_command .
*
* This command will use the flash protect peripheral ( BPROT or ACL ) to protect the flash that is
* not intended to be written .
*
* On success , this function will not return . It will start the new bootloader from reset - vector as normal .
*
* @ retval : : NRF_ERROR_INTERNAL indicates an internal error that should not happen .
* @ retval : : NRF_ERROR_FORBIDDEN if the bootloader address is not set .
* @ retval : : NRF_ERROR_INVALID_LENGTH if parameters attempts to read or write outside flash area .
* @ retval : : NRF_ERROR_NO_MEM No MBR parameter page is provided . See @ ref sd_mbr_command .
*/
typedef struct
{
2021-03-15 09:57:36 -04:00
uint32_t * bl_src ; /**< Pointer to the source of the bootloader to be be copied.*/
uint32_t bl_len ; /**< Number of 32 bit words to copy for BootLoader. */
2020-04-22 01:33:39 -04:00
} sd_mbr_command_copy_bl_t ;
/**@brief Change the address the MBR starts after a reset
*
* Once this function has been called , this address is where the MBR will start to forward
* interrupts to after a reset .
*
* To restore default forwarding , this function should be called with @ ref address set to 0. If a
* bootloader is present , interrupts will be forwarded to the bootloader . If not , interrupts will
* be forwarded to the SoftDevice .
*
* The location of a bootloader can be specified in @ ref MBR_BOOTLOADER_ADDR or
* @ ref MBR_UICR_BOOTLOADER_ADDR . If both addresses are set , the MBR will prioritize
* @ ref MBR_BOOTLOADER_ADDR .
*
* This command requires that @ ref MBR_PARAM_PAGE_ADDR or @ ref MBR_UICR_PARAM_PAGE_ADDR is set ,
* see @ ref sd_mbr_command .
*
* On success , this function will not return . It will reset the device .
*
* @ retval : : NRF_ERROR_INTERNAL indicates an internal error that should not happen .
* @ retval : : NRF_ERROR_INVALID_ADDR if parameter address is outside of the flash size .
* @ retval : : NRF_ERROR_NO_MEM No MBR parameter page is provided . See @ ref sd_mbr_command .
*/
typedef struct
{
2021-03-15 09:57:36 -04:00
uint32_t address ; /**< The base address of the interrupt vector table for forwarded interrupts.*/
2020-04-22 01:33:39 -04:00
} sd_mbr_command_vector_table_base_set_t ;
/**@brief Sets the base address of the interrupt vector table for interrupts forwarded from the MBR
*
* Unlike sd_mbr_command_vector_table_base_set_t , this function does not reset , and it does not
* change where the MBR starts after reset .
*
* @ retval : : NRF_SUCCESS
*/
typedef struct
{
2021-03-15 09:57:36 -04:00
uint32_t address ; /**< The base address of the interrupt vector table for forwarded interrupts.*/
2020-04-22 01:33:39 -04:00
} sd_mbr_command_irq_forward_address_set_t ;
/**@brief Input structure containing data used when calling ::sd_mbr_command
*
* Depending on what command value that is set , the corresponding params value type must also be
* set . See @ ref NRF_MBR_COMMANDS for command types and corresponding params value type . If command
* @ ref SD_MBR_COMMAND_INIT_SD is set , it is not necessary to set any values under params .
*/
typedef struct
{
2021-03-15 09:57:36 -04:00
uint32_t command ; /**< Type of command to be issued. See @ref NRF_MBR_COMMANDS. */
union
{
sd_mbr_command_copy_sd_t copy_sd ; /**< Parameters for copy SoftDevice.*/
sd_mbr_command_compare_t compare ; /**< Parameters for verify.*/
sd_mbr_command_copy_bl_t copy_bl ; /**< Parameters for copy BootLoader. Requires parameter page. */
sd_mbr_command_vector_table_base_set_t base_set ; /**< Parameters for vector table base set. Requires parameter page.*/
sd_mbr_command_irq_forward_address_set_t irq_forward_address_set ; /**< Parameters for irq forward address set*/
} params ; /**< Command parameters. */
2020-04-22 01:33:39 -04:00
} sd_mbr_command_t ;
/** @} */
/** @addtogroup NRF_MBR_FUNCTIONS Functions
* @ { */
/**@brief Issue Master Boot Record commands
*
* Commands used when updating a SoftDevice and bootloader .
*
* The @ ref SD_MBR_COMMAND_COPY_BL and @ ref SD_MBR_COMMAND_VECTOR_TABLE_BASE_SET requires
* parameters to be retained by the MBR when resetting the IC . This is done in a separate flash
* page . The location of the flash page should be provided by the application in either
* @ ref MBR_PARAM_PAGE_ADDR or @ ref MBR_UICR_PARAM_PAGE_ADDR . If both addresses are set , the MBR
* will prioritize @ ref MBR_PARAM_PAGE_ADDR . This page will be cleared by the MBR and is used to
* store the command before reset . When an address is specified , the page it refers to must not be
* used by the application . If no address is provided by the application , i . e . both
* @ ref MBR_PARAM_PAGE_ADDR and @ ref MBR_UICR_PARAM_PAGE_ADDR is 0xFFFFFFFF , MBR commands which use
* flash will be unavailable and return @ ref NRF_ERROR_NO_MEM .
*
* @ param [ in ] param Pointer to a struct describing the command .
*
* @ note For a complete set of return values , see : : sd_mbr_command_copy_sd_t ,
* : : sd_mbr_command_copy_bl_t , : : sd_mbr_command_compare_t ,
* : : sd_mbr_command_vector_table_base_set_t , : : sd_mbr_command_irq_forward_address_set_t
*
* @ retval : : NRF_ERROR_NO_MEM No MBR parameter page provided
* @ retval : : NRF_ERROR_INVALID_PARAM if an invalid command is given .
*/
2021-03-15 09:57:36 -04:00
SVCALL ( SD_MBR_COMMAND , uint32_t , sd_mbr_command ( sd_mbr_command_t * param ) ) ;
2020-04-22 01:33:39 -04:00
/** @} */
# ifdef __cplusplus
}
# endif
# endif // NRF_MBR_H__
/**
@ }
*/