Full modem firmware update from flash device

The fmfu_fdev library provides an API for applying a full modem firmware update from a flash device.

Functionality

The modem firmware and metadata stored in the flash device must conform to a specific serialization format. For more information, see Full modem upgrades.

The serialized modem firmware contains the hash of the firmware and a signature. These fields are used to pre-validate the modem firmware before it is programmed to the modem, ensuring that the data about to be written corresponds to the data that have been signed. Once the modem firmware is pre-validated, it is written to the modem using the nrf_modem_bootloader.h API.

Serialization

The modem firmware is serialized using the following CDDL scheme.

;
; Copyright (c) 2021 Nordic Semiconductor ASA
;
; SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
;


Segment = (
    target_addr: uint,
    len: uint
)

Segments = [ + Segment ]

Manifest = [
    version: uint,
    compat: uint,
    blob_hash: bstr .size 32,
    segments: bstr .cbor Segments
]

Wrapper = #6.18(COSE_Sign1_Manifest)

COSE_Sign1_Manifest = [
    protected: bstr .cbor header_map,
    unprotected: {},
    payload : bstr .cbor Manifest,
    signature : bstr .size 256
]

header_map = {
    1 => sign_RSA256  ; algorithm identifier
}

sign_RSA256 = -37 ; RSASSA-PSS, SHA256

Sig_structure1 = [
    context : "Signature1",
    body_protected : bstr .cbor header_map,
    external_aad : '',   ; 0 length bstr
    payload : bstr
]

The resulting serialized firmware file uses the .cbor extension. A generated decoder, modem_update_decode.c, is used for parsing the data serialized with this format.

Prerequisites

  • The serialized modem firmware must be stored in the flash device.

  • The modem library must be initialized in DFU mode.

API documentation

Header file: include/dfu/fmfu_fdev.h
Source files: subsys/dfu/fmfu_fdev/src/
group fmfu_fdev

Functions for applying a full modem firmware update from flash device.

Functions

int fmfu_fdev_load(uint8_t *buf, size_t buf_len, const struct device *fdev, size_t offset)

Load the modem firmware update from the specified flash device to the modem.

The modem library must be initialized in DFU mode before calling this function.

Parameters:

  • buf – [in] Pointer to buffer used to read data from external flash.

  • buf_len – [in] Length of provided buffer.

  • fdev – [in] Flash device to read modem firmware from.

  • offset – [in] Offset within configured flash device to first byte of modem update data.

Returns:

non-negative on success, negative error code on failure.