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 retained memory drivers 10 : */ 11 : 12 : #ifndef ZEPHYR_INCLUDE_DRIVERS_RETAINED_MEM_ 13 : #define ZEPHYR_INCLUDE_DRIVERS_RETAINED_MEM_ 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 : #include <zephyr/sys/math_extras.h> 22 : 23 : #ifdef __cplusplus 24 : extern "C" { 25 : #endif 26 : 27 : BUILD_ASSERT(!(sizeof(off_t) > sizeof(size_t)), 28 0 : "Size of off_t must be equal or less than size of size_t"); 29 : 30 : /** 31 : * @brief Retained memory driver interface 32 : * @defgroup retained_mem_interface Retained memory driver interface 33 : * @since 3.4 34 : * @version 0.8.0 35 : * @ingroup io_interfaces 36 : * @{ 37 : */ 38 : 39 : /** 40 : * @typedef retained_mem_size_api 41 : * @brief Callback API to get size of retained memory area. 42 : * See retained_mem_size() for argument description. 43 : */ 44 1 : typedef ssize_t (*retained_mem_size_api)(const struct device *dev); 45 : 46 : /** 47 : * @typedef retained_mem_read_api 48 : * @brief Callback API to read from retained memory area. 49 : * See retained_mem_read() for argument description. 50 : */ 51 1 : typedef int (*retained_mem_read_api)(const struct device *dev, off_t offset, uint8_t *buffer, 52 : size_t size); 53 : 54 : /** 55 : * @typedef retained_mem_write_api 56 : * @brief Callback API to write to retained memory area. 57 : * See retained_mem_write() for argument description. 58 : */ 59 1 : typedef int (*retained_mem_write_api)(const struct device *dev, off_t offset, 60 : const uint8_t *buffer, size_t size); 61 : 62 : /** 63 : * @typedef retained_mem_clear_api 64 : * @brief Callback API to clear retained memory area (reset all data to 0x00). 65 : * See retained_mem_clear() for argument description. 66 : */ 67 1 : typedef int (*retained_mem_clear_api)(const struct device *dev); 68 : 69 : /** 70 : * @brief Retained memory driver API 71 : * API which can be used by a device to store data in a retained memory area. Retained memory is 72 : * memory that is retained while the device is powered but is lost when power to the device is 73 : * lost (note that low power modes in some devices may clear the data also). This may be in a 74 : * non-initialised RAM region, or in specific registers, but is not reset when a different 75 : * application begins execution or the device is rebooted (without power loss). It must support 76 : * byte-level reading and writing without a need to erase data before writing. 77 : * 78 : * Note that drivers must implement all functions, none of the functions are optional. 79 : */ 80 1 : __subsystem struct retained_mem_driver_api { 81 0 : retained_mem_size_api size; 82 0 : retained_mem_read_api read; 83 0 : retained_mem_write_api write; 84 0 : retained_mem_clear_api clear; 85 : }; 86 : 87 : /** 88 : * @brief Returns the size of the retained memory area. 89 : * 90 : * @param dev Retained memory device to use. 91 : * 92 : * @retval Positive value indicating size in bytes on success, else negative errno 93 : * code. 94 : */ 95 1 : __syscall ssize_t retained_mem_size(const struct device *dev); 96 : 97 : static inline ssize_t z_impl_retained_mem_size(const struct device *dev) 98 : { 99 : struct retained_mem_driver_api *api = (struct retained_mem_driver_api *)dev->api; 100 : 101 : return api->size(dev); 102 : } 103 : 104 : /** 105 : * @brief Reads data from the Retained memory area. 106 : * 107 : * @param dev Retained memory device to use. 108 : * @param offset Offset to read data from. 109 : * @param buffer Buffer to store read data in. 110 : * @param size Size of data to read. 111 : * 112 : * @retval 0 on success else negative errno code. 113 : */ 114 1 : __syscall int retained_mem_read(const struct device *dev, off_t offset, uint8_t *buffer, 115 : size_t size); 116 : 117 : static inline int z_impl_retained_mem_read(const struct device *dev, off_t offset, 118 : uint8_t *buffer, size_t size) 119 : { 120 : struct retained_mem_driver_api *api = (struct retained_mem_driver_api *)dev->api; 121 : size_t area_size; 122 : 123 : /* Validate user-supplied parameters */ 124 : if (size == 0) { 125 : return 0; 126 : } 127 : 128 : area_size = api->size(dev); 129 : 130 : if (offset < 0 || size > area_size || (area_size - size) < (size_t)offset) { 131 : return -EINVAL; 132 : } 133 : 134 : return api->read(dev, offset, buffer, size); 135 : } 136 : 137 : /** 138 : * @brief Writes data to the Retained memory area - underlying data does not need to 139 : * be cleared prior to writing. 140 : * 141 : * @param dev Retained memory device to use. 142 : * @param offset Offset to write data to. 143 : * @param buffer Data to write. 144 : * @param size Size of data to be written. 145 : * 146 : * @retval 0 on success else negative errno code. 147 : */ 148 1 : __syscall int retained_mem_write(const struct device *dev, off_t offset, const uint8_t *buffer, 149 : size_t size); 150 : 151 : static inline int z_impl_retained_mem_write(const struct device *dev, off_t offset, 152 : const uint8_t *buffer, size_t size) 153 : { 154 : struct retained_mem_driver_api *api = (struct retained_mem_driver_api *)dev->api; 155 : size_t area_size; 156 : 157 : /* Validate user-supplied parameters */ 158 : if (size == 0) { 159 : return 0; 160 : } 161 : 162 : area_size = api->size(dev); 163 : 164 : if (offset < 0 || size > area_size || (area_size - size) < (size_t)offset) { 165 : return -EINVAL; 166 : } 167 : 168 : return api->write(dev, offset, buffer, size); 169 : } 170 : 171 : /** 172 : * @brief Clears data in the retained memory area by setting it to 0x00. 173 : * 174 : * @param dev Retained memory device to use. 175 : * 176 : * @retval 0 on success else negative errno code. 177 : */ 178 1 : __syscall int retained_mem_clear(const struct device *dev); 179 : 180 : static inline int z_impl_retained_mem_clear(const struct device *dev) 181 : { 182 : struct retained_mem_driver_api *api = (struct retained_mem_driver_api *)dev->api; 183 : 184 : return api->clear(dev); 185 : } 186 : 187 : /** 188 : * @} 189 : */ 190 : 191 : #ifdef __cplusplus 192 : } 193 : #endif 194 : 195 : #include <zephyr/syscalls/retained_mem.h> 196 : 197 : #endif /* ZEPHYR_INCLUDE_DRIVERS_RETAINED_MEM_ */
