Line data Source code
1 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 0 : typedef ssize_t (*retention_size_api)(const struct device *dev); 36 0 : typedef int (*retention_is_valid_api)(const struct device *dev); 37 0 : typedef int (*retention_read_api)(const struct device *dev, off_t offset, uint8_t *buffer, 38 : size_t size); 39 0 : typedef int (*retention_write_api)(const struct device *dev, off_t offset, 40 : const uint8_t *buffer, size_t size); 41 0 : typedef int (*retention_clear_api)(const struct device *dev); 42 : 43 0 : struct retention_api { 44 0 : retention_size_api size; 45 0 : retention_is_valid_api is_valid; 46 0 : retention_read_api read; 47 0 : retention_write_api write; 48 0 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : int retention_clear(const struct device *dev); 108 : 109 : /** 110 : * @} 111 : */ 112 : 113 : #ifdef __cplusplus 114 : } 115 : #endif 116 : 117 : #endif /* ZEPHYR_INCLUDE_RETENTION_ */