Peripheral CPU DFU (PCD)

The peripheral CPU DFU (PCD) library provides functionality for transferring DFU images from the application core to the network core on the nRF5340 System on Chip (SoC).

Overview

In the nRF5340 SoC, the application core cannot access the flash of the network core. However, firmware upgrades for the network core are stored in the application flash. This is because of the limited size of the network core flash. Hence, a mechanism for downloading firmware updates from the application to the network core flash is needed. The PCD library provides functionality for both cores in this situation. A region of SRAM, accessible by both cores, is used for inter-core communication.

The application core uses the PCD library to communicate where the network core can find the firmware update and its expected SHA. This is done after verifying the signature of a firmware update targeting the network core. When the update instructions are written, the application core enables the network core, and waits for a pcd_status indicating that the update has successfully completed. The SRAM region used to communicate update instructions to the network core is locked before the application is started on the application core. This is done to avoid compromised code from being able to perform updates of the network core firmware.

The network core uses the PCD library to look for instructions on where to find the updates. Once an update instruction is found, this library is used to transfer the firmware update image.

On the application core, the PCD library is used by the MCUboot sample. On the network core, the PCD library is used by the nRF5340: Network core bootloader sample.

API documentation

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

API for handling DFU of peripheral cores.

The PCD API provides functions for transferring DFU images from a generic core to a peripheral core to which there is no flash access from the generic core.

The cores communicate through a command structure (CMD) which is stored in a shared memory location.

The nRF5340 is an example of a system with these properties.

Enums

enum pcd_status

Values:

enumerator PCD_STATUS_COPY
enumerator PCD_STATUS_COPY_DONE
enumerator PCD_STATUS_COPY_FAILED

Functions

int pcd_network_core_update(const void *src_addr, size_t len)

Sets up the PCD command structure with the location and size of the firmware update. Then boots the network core and checks if the update completed successfully.

Parameters
  • src_addr – Start address of the data which is to be copied into the network core.

  • len – Length of the data which is to be copied into the network core.

Return values

0 – on success, -1 on failure.

int pcd_network_core_update_initiate(const void *src_addr, size_t len)

Sets up the PCD command structure with the location and size of the firmware update. Then boots the network core and initiates the update procedure. The function will return before the update procedure on the network core has completed or failed, and will indicate succes as long as the initialization of the update procedure was successful. The network core will still be in a powered on state when this function returns.

Parameters
  • src_addr – Start address of the data which is to be copied into the network core.

  • len – Length of the data which is to be copied into the network core.

Return values

0 – on success, an error code on failure.

void pcd_lock_ram(void)

Lock the RAM section used for IPC with the network core bootloader.

void pcd_fw_copy_done(void)

Update the PCD CMD to indicate that the copy operation has completed successfully.

void pcd_fw_copy_invalidate(void)

Invalidate the PCD CMD, indicating that the copy failed.

enum pcd_status pcd_fw_copy_status_get(void)

Check the PCD CMD to find the status of the update.

Returns

PCD_STATUS_COPY if update is pending

Returns

PCD_STATUS_COPY_DONE if update has completed successfully

Returns

PCD_STATUS_COPY_FAILED if update has completed unsuccessfully

const void *pcd_cmd_data_ptr_get(void)

Get value of ‘data’ member of pcd cmd.

Return values

value – of ‘data’ member.

int pcd_fw_copy(const struct device *fdev)

Perform the DFU image transfer.

Use the information in the PCD CMD to load a DFU image to the provided flash device.

Parameters
  • fdev – The flash device to transfer the DFU image to.

Return values

non-negative – integer on success, negative errno code on failure.