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