DFU lock utility

The DFU lock utility provides a synchronization mechanism for accessing the DFU flash. It is needed for application configurations that support more than one DFU transport.

The DFU lock utility provides a basic synchronization API for all declared DFU owners. Each DFU owner can be declared using the dfu_lock_owner structure. The dfu_lock_claim() function is used to claim ownership over the DFU flash. This function returns an error if the lock has already been taken by another DFU owner. The dfu_lock_release() function is used by the current owner to release the DFU flash when it is no longer used. This function returns an error on the release attempt that is not triggered by the current owner. The dfu_lock_owner.owner_changed callback is used to indicate the change in ownership. The previous owner can use this callback for tracking the DFU flash status and the need to erase it before subsequent DFU attempts.

Note

The nRF Desktop DFU transports must voluntarily take lock before accessing flash and release it after they stop using it. The DFU lock utility does not provide any protection against the DFU transport module that writes to flash memory without taking a lock.

Configuration

Use the CONFIG_DESKTOP_DFU_LOCK option to enable the utility.

Currently, the DFU lock utility is automatically used if you enable both supported DFU transports in your application:

You can adjust the logging level of this utility by changing the CONFIG_DESKTOP_DFU_LOCK_LOG_LEVEL Kconfig option.

Implementation details

The DFU lock utility uses the Mutexes for synchronizing updates to its internal state.

API documentation

Header file: applications/nrf_desktop/src/util/dfu_lock.h
Source files: applications/nrf_desktop/src/util/dfu_lock.c
group dfu_lock

DFU Lock API.

Functions

int dfu_lock_claim(const struct dfu_lock_owner *new_owner)

Claim the DFU lock.

Claim the DFU lock for the provided owner instance. You can start to interact with the DFU flash memory once this function returns with success.

Claiming the DFU lock that you already claimed with the same owner instance has no effect and does not change the module state.

Parameters:

  • new_owner – New DFU owner descriptor.

Return values:

  • 0 – on success.

  • -EPERM – if the DFU lock has already been claimed by another owner.

int dfu_lock_release(const struct dfu_lock_owner *owner)

Release the DFU lock.

Release the DFU lock for the provided owner instance to allow other owners to lock it. You must stop interacting with the DFU flash memory once you release the DFU lock.

Parameters:

  • owner – DFU owner descriptor.

Return values:

  • 0 – on success.

  • -EPERM – if the DFU lock has not been claimed by the owner.

struct dfu_lock_owner
#include <dfu_lock.h>

DFU lock owner descriptor.

Public Members

const char *name

Owner name.

void (*owner_changed)(const struct dfu_lock_owner *new_owner)

Notify the previous DFU owner that another DFU owner claimed the lock.

This information can be used to perform the cleanup operations before the subsequent DFU attempts of the previous DFU owner. Typically, the previous DFU owner should reset its DFU progress and make sure that the DFU flash memory is erased before writing new image content. Please note that the flash erase operation can only be done once the previous owner reclaims the DFU lock.

This callback is executed from the context used by the new DFU owner to claim lock. During the callback execution, mutex of the DFU lock module is locked. It is recommended to perform simple operations within the context of this callback.

Param new_owner:

New DFU owner descriptor.