bugfix for duplicate symbol
Fork of nRF51822 by
Embed:
(wiki syntax)
Show/hide line numbers
dfu_init.h
Go to the documentation of this file.
00001 /* Copyright (c) 2014 Nordic Semiconductor. All Rights Reserved. 00002 * 00003 * The information contained herein is property of Nordic Semiconductor ASA. 00004 * Terms and conditions of usage are described in detail in NORDIC 00005 * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT. 00006 * 00007 * Licensees are granted free, non-transferable use of the information. NO 00008 * WARRANTY of ANY KIND is provided. This heading must NOT be removed from 00009 * the file. 00010 * 00011 */ 00012 00013 /**@file 00014 * 00015 * @defgroup nrf_dfu_init Init packet handling in DFU. 00016 * @{ 00017 * 00018 * @brief Device Firmware Update module type and function declaration for init packet handling. 00019 * 00020 * @details This header contains basic functionality for performing safety checks on software 00021 * updates for nRF51 based devices. It provides a skeleton for pre-checking an init packet 00022 * to ensure the following image is compatible with this device. A safety check should 00023 * always be performed to prevent accidental flashing of unsupported applications or a 00024 * wrong combination of application and SoftDevice. 00025 * The device information contains information such as: 00026 * - Device type (2 bytes), for example Heart Rate. The device type is a number defined by 00027 * the customer. It can be located in UICR or FICR. 00028 * - Device revision (2 bytes), for example major revision 1, minor revision 0. The device 00029 * revision is a number defined by the customer. It can be located in UICR or FICR. 00030 * - List of SoftDevices supported by this application, for example 00031 * 0x0049 = S110v6_0_0 00032 * 0xFFFE = S110 development (any SoftDevice accepted), 00033 * - CRC or hash of firmware image 00034 * 00035 * @note This module does not support security features such as image signing, but the corresponding 00036 * implementation allows for such extensions. 00037 * If the init packet is signed by a trusted source, it must be decrypted before it can be 00038 * processed. 00039 */ 00040 00041 #ifndef DFU_INIT_H__ 00042 #define DFU_INIT_H__ 00043 00044 #include <stdint.h> 00045 #include "nrf51.h" 00046 00047 /**@brief Structure contained in an init packet. Contains information on device type, revision, and 00048 * supported SoftDevices. 00049 */ 00050 typedef struct 00051 { 00052 uint16_t device_type; /**< Device type (2 bytes), for example Heart Rate. This number must be defined by the customer before production. It can be located in UICR or FICR. */ 00053 uint16_t device_rev; /**< Device revision (2 bytes), for example major revision 1, minor revision 0. This number must be defined by the customer before production. It can be located in UICR or FICR. */ 00054 uint32_t app_version; /**< Application version for the image software. This field allows for additional checking, for example ensuring that a downgrade is not allowed. */ 00055 uint16_t softdevice_len; /**< Number of different SoftDevice revisions compatible with this application. The list of SoftDevice firmware IDs is defined in @ref softdevice. */ 00056 uint16_t softdevice[1]; /**< Variable length array of SoftDevices compatible with this application. The length of the array is specified in the length field. SoftDevice firmware id 0xFFFE indicates any SoftDevice. */ 00057 } dfu_init_packet_t; 00058 00059 /**@brief Structure holding basic device information settings. 00060 */ 00061 typedef struct 00062 { 00063 uint16_t device_type; /**< Device type (2 bytes), for example Heart Rate. This number must be defined by the customer before production. It can be located in UICR or FICR. */ 00064 uint16_t device_rev; /**< Device revision (2 bytes), for example major revision 1, minor revision 0. This number must be defined by the customer before production. It can be located in UICR or FICR. */ 00065 } dfu_device_info_t; 00066 00067 /** The device info offset can be modified to place the device info settings at a different location. 00068 * If the customer reserved UICR location is used for other application specific data, the offset 00069 * must be updated to avoid collision with that data. 00070 */ 00071 /** [DFU UICR DEV offset] */ 00072 #define UICR_CUSTOMER_DEVICE_INFO_OFFSET 0x0 /**< Device info offset inside the customer UICR reserved area. Customers may change this value to place the device information in a user-preferred location. */ 00073 /** [DFU UICR DEV offset] */ 00074 00075 #define UICR_CUSTOMER_RESERVED_OFFSET 0x80 /**< Customer reserved area in the UICR. The area from UICR + 0x80 is reserved for customer usage. */ 00076 #define DFU_DEVICE_INFO_BASE (NRF_UICR_BASE + \ 00077 UICR_CUSTOMER_RESERVED_OFFSET + \ 00078 UICR_CUSTOMER_DEVICE_INFO_OFFSET) /**< The device information base address inside of UICR. */ 00079 #define DFU_DEVICE_INFO ((dfu_device_info_t *)DFU_DEVICE_INFO_BASE) /**< The memory mapped structure for device information data. */ 00080 00081 #define DFU_DEVICE_TYPE_EMPTY ((uint16_t)0xFFFF) /**< Mask indicating no device type is present in UICR. 0xFFFF is default flash pattern when not written with data. */ 00082 #define DFU_DEVICE_REVISION_EMPTY ((uint16_t)0xFFFF) /**< Mask indicating no device revision is present in UICR. 0xFFFF is default flash pattern when not written with data. */ 00083 #define DFU_SOFTDEVICE_ANY ((uint16_t)0xFFFE) /**< Mask indicating that any SoftDevice is allowed for updating this application. Allows for easy development. Not to be used in production images. */ 00084 00085 00086 /**@brief DFU prevalidate call for pre-checking the received init packet. 00087 * 00088 * @details Pre-validation will safety check the firmware image to be transfered in second stage. 00089 * The function currently checks the device type, device revision, application firmware 00090 * version, and supported SoftDevices. More checks should be added according to 00091 * customer-specific requirements. 00092 * 00093 * @param[in] p_init_data Pointer to the init packet. If the init packet is encrypted or signed, 00094 * it must first be decrypted before being checked. 00095 * @param[in] init_data_len Length of the init data. 00096 * 00097 * @retval NRF_SUCCESS If the pre-validation succeeded, that means the image is 00098 * supported by the device and it is considered to come from a 00099 * trusted source (signing). 00100 * @retval NRF_ERROR_INVALID_DATA If the pre-validation failed, that means the image is not 00101 * supported by the device or comes from an un-trusted source 00102 * (signing). 00103 * @retval NRF_ERROR_INVALID_LENGTH If the size of the init packet is not within the limits of 00104 * the init packet handler. 00105 */ 00106 uint32_t dfu_init_prevalidate(uint8_t * p_init_data, uint32_t init_data_len); 00107 00108 /**@brief DFU postvalidate call for post-checking the received image using the init packet. 00109 * 00110 * @details Post-validation can verify the integrity check the firmware image received before 00111 * activating the image. 00112 * Checks performed can be: 00113 * - A simple CRC as shown in the corresponding implementation of this API in the file 00114 * dfu_init_template.c 00115 * - A hash for better verification of the image. 00116 * - A signature to ensure the image originates from a trusted source. 00117 * Checks are intended to be expanded for customer-specific requirements. 00118 * 00119 * @param[in] p_image Pointer to the received image. The init data provided in the call 00120 * \ref dfu_init_prevalidate will be used for validating the image. 00121 * @param[in] image_len Length of the image data. 00122 * 00123 * @retval NRF_SUCCESS If the post-validation succeeded, that meant the integrity of the 00124 * image has been verified and the image originates from a trusted 00125 * source (signing). 00126 * @retval NRF_ERROR_INVALID_DATA If the post-validation failed, that meant the post check of the 00127 * image failed such as the CRC is not matching the image transfered 00128 * or the verification of the image fails (signing). 00129 */ 00130 uint32_t dfu_init_postvalidate(uint8_t * p_image, uint32_t image_len); 00131 00132 #endif // DFU_INIT_H__ 00133 00134 /**@} */
Generated on Tue Jul 12 2022 16:20:24 by 1.7.2