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.
- Since
3.4
- Version
0.8.0
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.
-
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.