Retained Memory

Overview

The retained memory driver API provides a way of reading from/writing to memory areas whereby the contents of the memory is retained whilst the device is powered (data may be lost in low power modes).

Configuration Options

Related configuration options:

Mutex protection

Mutex protection of retained memory drivers is enabled by default when applications are compiled with multithreading support. This means that different threads can safely call the retained memory functions without clashing with other concurrent thread function usage, but means that retained memory functions cannot be used from ISRs. It is possible to disable mutex protection globally on all retained memory drivers by enabling CONFIG_RETAINED_MEM_MUTEX_FORCE_DISABLE - users are then responsible for ensuring that the function calls do not conflict with each other.

API Reference

group retained_mem_interface

Retained memory driver interface.

Typedefs

typedef ssize_t (*retained_mem_size_api)(const struct device *dev)

Callback API to get size of retained memory area.

See retained_mem_size() for argument description.

typedef int (*retained_mem_read_api)(const struct device *dev, off_t offset, uint8_t *buffer, size_t size)

Callback API to read from retained memory area.

See retained_mem_read() for argument description.

typedef int (*retained_mem_write_api)(const struct device *dev, off_t offset, const uint8_t *buffer, size_t size)

Callback API to write to retained memory area.

See retained_mem_write() for argument description.

typedef int (*retained_mem_clear_api)(const struct device *dev)

Callback API to clear retained memory area (reset all data to 0x00).

See retained_mem_clear() for argument description.

Functions

ssize_t retained_mem_size(const struct device *dev)

Returns the size of the retained memory area.

Parameters:
  • dev – Retained memory device to use.

Return values:

Positive – value indicating size in bytes on success, else negative errno code.

int retained_mem_read(const struct device *dev, off_t offset, uint8_t *buffer, size_t size)

Reads data from the Retained memory area.

Parameters:
  • dev – Retained memory device to use.

  • offset – Offset to read data from.

  • buffer – Buffer to store read data in.

  • size – Size of data to read.

Return values:

0 – on success else negative errno code.

int retained_mem_write(const struct device *dev, off_t offset, const uint8_t *buffer, size_t size)

Writes data to the Retained memory area - underlying data does not need to be cleared prior to writing.

Parameters:
  • dev – Retained memory device to use.

  • offset – Offset to write data to.

  • buffer – Data to write.

  • size – Size of data to be written.

Return values:

0 – on success else negative errno code.

int retained_mem_clear(const struct device *dev)

Clears data in the retained memory area by setting it to 0x00.

Parameters:
  • dev – Retained memory device to use.

Return values:

0 – on success else negative errno code.

struct retained_mem_driver_api
#include <retained_mem.h>

Retained memory driver API API which can be used by a device to store data in a retained memory area.

Retained memory is memory that is retained while the device is powered but is lost when power to the device is lost (note that low power modes in some devices may clear the data also). This may be in a non-initialised RAM region, or in specific registers, but is not reset when a different application begins execution or the device is rebooted (without power loss). It must support byte-level reading and writing without a need to erase data before writing.

Note that drivers must implement all functions, none of the functions are optional.