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 * @ingroup os_services 30 * @{ 31 */ 32 33 typedef ssize_t (*retention_size_api)(const struct device *dev); 34 typedef int (*retention_is_valid_api)(const struct device *dev); 35 typedef int (*retention_read_api)(const struct device *dev, off_t offset, uint8_t *buffer, 36 size_t size); 37 typedef int (*retention_write_api)(const struct device *dev, off_t offset, 38 const uint8_t *buffer, size_t size); 39 typedef int (*retention_clear_api)(const struct device *dev); 40 41 struct retention_api { 42 retention_size_api size; 43 retention_is_valid_api is_valid; 44 retention_read_api read; 45 retention_write_api write; 46 retention_clear_api clear; 47 }; 48 49 /** 50 * @brief Returns the size of the retention area. 51 * 52 * @param dev Retention device to use. 53 * 54 * @retval Positive value indicating size in bytes on success, else negative errno 55 * code. 56 */ 57 ssize_t retention_size(const struct device *dev); 58 59 /** 60 * @brief Checks if the underlying data in the retention area is valid or not. 61 * 62 * @param dev Retention device to use. 63 * 64 * @retval 1 If successful and data is valid. 65 * @retval 0 If data is not valid. 66 * @retval -ENOTSUP If there is no header/checksum configured for the retention area. 67 * @retval -errno Error code code. 68 */ 69 int retention_is_valid(const struct device *dev); 70 71 /** 72 * @brief Reads data from the retention area. 73 * 74 * @param dev Retention device to use. 75 * @param offset Offset to read data from. 76 * @param buffer Buffer to store read data in. 77 * @param size Size of data to read. 78 * 79 * @retval 0 If successful. 80 * @retval -errno Error code code. 81 */ 82 int retention_read(const struct device *dev, off_t offset, uint8_t *buffer, size_t size); 83 84 /** 85 * @brief Writes data to the retention area (underlying data does not need to be 86 * cleared prior to writing), once function returns with a success code, the 87 * data will be classed as valid if queried using retention_is_valid(). 88 * 89 * @param dev Retention device to use. 90 * @param offset Offset to write data to. 91 * @param buffer Data to write. 92 * @param size Size of data to be written. 93 * 94 * @retval 0 on success else negative errno code. 95 */ 96 int retention_write(const struct device *dev, off_t offset, const uint8_t *buffer, size_t size); 97 98 /** 99 * @brief Clears all data in the retention area (sets it to 0) 100 * 101 * @param dev Retention device to use. 102 * 103 * @retval 0 on success else negative errno code. 104 */ 105 int retention_clear(const struct device *dev); 106 107 /** 108 * @} 109 */ 110 111 #ifdef __cplusplus 112 } 113 #endif 114 115 #endif /* ZEPHYR_INCLUDE_RETENTION_ */ 116
