nRF51 SDK - S130 SoftDevice
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Init packet handling in DFU.

Device Firmware Update module type and function declaration for init packet handling. More...

Data Structures

struct  dfu_init_packet_t
 Structure contained in an init packet. Contains information on device type, revision, and supported SoftDevices. More...
 
struct  dfu_device_info_t
 Structure holding basic device information settings. More...
 

Macros

#define UICR_CUSTOMER_DEVICE_INFO_OFFSET   0x0
 
#define UICR_CUSTOMER_RESERVED_OFFSET   0x80
 
#define DFU_DEVICE_INFO_BASE
 
#define DFU_DEVICE_INFO   ((dfu_device_info_t *)DFU_DEVICE_INFO_BASE)
 
#define DFU_DEVICE_TYPE_EMPTY   ((uint16_t)0xFFFF)
 
#define DFU_DEVICE_REVISION_EMPTY   ((uint16_t)0xFFFF)
 
#define DFU_SOFTDEVICE_ANY   ((uint16_t)0xFFFE)
 

Functions

uint32_t dfu_init_prevalidate (uint8_t *p_init_data, uint32_t init_data_len)
 DFU prevalidate call for pre-checking the received init packet. More...
 
uint32_t dfu_init_postvalidate (uint8_t *p_image, uint32_t image_len)
 DFU postvalidate call for post-checking the received image using the init packet. More...
 

Detailed Description

Device Firmware Update module type and function declaration for init packet handling.

This header contains basic functionality for performing safety checks on software updates for nRF51 based devices. It provides a skeleton for pre-checking an init packet to ensure the following image is compatible with this device. A safety check should always be performed to prevent accidental flashing of unsupported applications or a wrong combination of application and SoftDevice. The device information contains information such as:

Note
This module does not support security features such as image signing, but the corresponding implementation allows for such extensions. If the init packet is signed by a trusted source, it must be decrypted before it can be processed.

Macro Definition Documentation

#define DFU_DEVICE_INFO   ((dfu_device_info_t *)DFU_DEVICE_INFO_BASE)

The memory mapped structure for device information data.

#define DFU_DEVICE_INFO_BASE
Value:
(NRF_UICR_BASE + \
UICR_CUSTOMER_RESERVED_OFFSET + \
UICR_CUSTOMER_DEVICE_INFO_OFFSET)

The device information base address inside of UICR.

#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.

#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.

#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.

#define UICR_CUSTOMER_DEVICE_INFO_OFFSET   0x0

The device info offset can be modified to place the device info settings at a different location. If the customer reserved UICR location is used for other application specific data, the offset must be updated to avoid collision with that data.[DFU UICR DEV offset] Device info offset inside the customer UICR reserved area. Customers may change this value to place the device information in a user-preferred location.

#define UICR_CUSTOMER_RESERVED_OFFSET   0x80

[DFU UICR DEV offset] Customer reserved area in the UICR. The area from UICR + 0x80 is reserved for customer usage.

Function Documentation

uint32_t dfu_init_postvalidate ( uint8_t *  p_image,
uint32_t  image_len 
)

DFU postvalidate call for post-checking the received image using the init packet.

Post-validation can verify the integrity check the firmware image received before activating the image. Checks performed can be:

  • A simple CRC as shown in the corresponding implementation of this API in the file dfu_init_template.c
  • A hash for better verification of the image.
  • A signature to ensure the image originates from a trusted source. Checks are intended to be expanded for customer-specific requirements.
Parameters
[in]p_imagePointer to the received image. The init data provided in the call dfu_init_prevalidate will be used for validating the image.
[in]image_lenLength of the image data.
Return values
NRF_SUCCESSIf the post-validation succeeded, that meant the integrity of the image has been verified and the image originates from a trusted source (signing).
NRF_ERROR_INVALID_DATAIf the post-validation failed, that meant the post check of the image failed such as the CRC is not matching the image transfered or the verification of the image fails (signing).
uint32_t dfu_init_prevalidate ( uint8_t *  p_init_data,
uint32_t  init_data_len 
)

DFU prevalidate call for pre-checking the received init packet.

Pre-validation will safety check the firmware image to be transfered in second stage. The function currently checks the device type, device revision, application firmware version, and supported SoftDevices. More checks should be added according to customer-specific requirements.

Parameters
[in]p_init_dataPointer to the init packet. If the init packet is encrypted or signed, it must first be decrypted before being checked.
[in]init_data_lenLength of the init data.
Return values
NRF_SUCCESSIf the pre-validation succeeded, that means the image is supported by the device and it is considered to come from a trusted source (signing).
NRF_ERROR_INVALID_DATAIf the pre-validation failed, that means the image is not supported by the device or comes from an un-trusted source (signing).
NRF_ERROR_INVALID_LENGTHIf the size of the init packet is not within the limits of the init packet handler.