1 /* 2 * Copyright (c) 2023 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 /** 8 * @file 9 * @brief Public API for retention API 10 */ 11 12 #ifndef ZEPHYR_INCLUDE_RETENTION_ 13 #define ZEPHYR_INCLUDE_RETENTION_ 14 15 #include <stdint.h> 16 #include <stddef.h> 17 #include <sys/types.h> 18 #include <zephyr/kernel.h> 19 #include <zephyr/device.h> 20 #include <zephyr/types.h> 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 /** 27 * @brief Retention API 28 * @defgroup retention_api Retention API 29 * @since 3.4 30 * @version 0.1.0 31 * @ingroup os_services 32 * @{ 33 */ 34 35 typedef ssize_t (*retention_size_api)(const struct device *dev); 36 typedef int (*retention_is_valid_api)(const struct device *dev); 37 typedef int (*retention_read_api)(const struct device *dev, off_t offset, uint8_t *buffer, 38 size_t size); 39 typedef int (*retention_write_api)(const struct device *dev, off_t offset, 40 const uint8_t *buffer, size_t size); 41 typedef int (*retention_clear_api)(const struct device *dev); 42 43 struct retention_api { 44 retention_size_api size; 45 retention_is_valid_api is_valid; 46 retention_read_api read; 47 retention_write_api write; 48 retention_clear_api clear; 49 }; 50 51 /** 52 * @brief Returns the size of the retention area. 53 * 54 * @param dev Retention device to use. 55 * 56 * @retval Positive value indicating size in bytes on success, else negative errno 57 * code. 58 */ 59 ssize_t retention_size(const struct device *dev); 60 61 /** 62 * @brief Checks if the underlying data in the retention area is valid or not. 63 * 64 * @param dev Retention device to use. 65 * 66 * @retval 1 If successful and data is valid. 67 * @retval 0 If data is not valid. 68 * @retval -ENOTSUP If there is no header/checksum configured for the retention area. 69 * @retval -errno Error code code. 70 */ 71 int retention_is_valid(const struct device *dev); 72 73 /** 74 * @brief Reads data from the retention area. 75 * 76 * @param dev Retention device to use. 77 * @param offset Offset to read data from. 78 * @param buffer Buffer to store read data in. 79 * @param size Size of data to read. 80 * 81 * @retval 0 If successful. 82 * @retval -errno Error code code. 83 */ 84 int retention_read(const struct device *dev, off_t offset, uint8_t *buffer, size_t size); 85 86 /** 87 * @brief Writes data to the retention area (underlying data does not need to be 88 * cleared prior to writing), once function returns with a success code, the 89 * data will be classed as valid if queried using retention_is_valid(). 90 * 91 * @param dev Retention device to use. 92 * @param offset Offset to write data to. 93 * @param buffer Data to write. 94 * @param size Size of data to be written. 95 * 96 * @retval 0 on success else negative errno code. 97 */ 98 int retention_write(const struct device *dev, off_t offset, const uint8_t *buffer, size_t size); 99 100 /** 101 * @brief Clears all data in the retention area (sets it to 0) 102 * 103 * @param dev Retention device to use. 104 * 105 * @retval 0 on success else negative errno code. 106 */ 107 int retention_clear(const struct device *dev); 108 109 /** 110 * @} 111 */ 112 113 #ifdef __cplusplus 114 } 115 #endif 116 117 #endif /* ZEPHYR_INCLUDE_RETENTION_ */ 118
