Line data Source code
1 1 : /*
2 : * Copyright (c) 2021 Google Inc
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @ingroup bbram_interface
10 : * @brief Main header file for Battery-Backed RAM (BBRAM) driver API.
11 : */
12 :
13 : #ifndef ZEPHYR_INCLUDE_DRIVERS_BBRAM_H
14 : #define ZEPHYR_INCLUDE_DRIVERS_BBRAM_H
15 :
16 : #include <errno.h>
17 :
18 : #include <zephyr/device.h>
19 :
20 : /**
21 : * @brief Interfaces for Battery-Backed RAM (BBRAM).
22 : * @defgroup bbram_interface BBRAM
23 : * @ingroup io_interfaces
24 : * @{
25 : */
26 :
27 : #ifdef __cplusplus
28 : extern "C" {
29 : #endif
30 :
31 : /**
32 : * @typedef bbram_api_check_invalid_t
33 : * @brief API template to check if the BBRAM is invalid.
34 : *
35 : * @see bbram_check_invalid
36 : */
37 1 : typedef int (*bbram_api_check_invalid_t)(const struct device *dev);
38 :
39 : /**
40 : * @typedef bbram_api_check_standby_power_t
41 : * @brief API template to check for standby power failure.
42 : *
43 : * @see bbram_check_standby_power
44 : */
45 1 : typedef int (*bbram_api_check_standby_power_t)(const struct device *dev);
46 :
47 : /**
48 : * @typedef bbram_api_check_power_t
49 : * @brief API template to check for V CC1 power failure.
50 : *
51 : * @see bbram_check_power
52 : */
53 1 : typedef int (*bbram_api_check_power_t)(const struct device *dev);
54 :
55 : /**
56 : * @typedef bbram_api_get_size_t
57 : * @brief API template to check the size of the BBRAM
58 : *
59 : * @see bbram_get_size
60 : */
61 1 : typedef int (*bbram_api_get_size_t)(const struct device *dev, size_t *size);
62 :
63 : /**
64 : * @typedef bbram_api_read_t
65 : * @brief API template to read from BBRAM.
66 : *
67 : * @see bbram_read
68 : */
69 1 : typedef int (*bbram_api_read_t)(const struct device *dev, size_t offset, size_t size,
70 : uint8_t *data);
71 :
72 : /**
73 : * @typedef bbram_api_write_t
74 : * @brief API template to write to BBRAM.
75 : *
76 : * @see bbram_write
77 : */
78 1 : typedef int (*bbram_api_write_t)(const struct device *dev, size_t offset, size_t size,
79 : const uint8_t *data);
80 :
81 0 : __subsystem struct bbram_driver_api {
82 0 : bbram_api_check_invalid_t check_invalid;
83 0 : bbram_api_check_standby_power_t check_standby_power;
84 0 : bbram_api_check_power_t check_power;
85 0 : bbram_api_get_size_t get_size;
86 0 : bbram_api_read_t read;
87 0 : bbram_api_write_t write;
88 : };
89 :
90 : /**
91 : * @brief Check if BBRAM is invalid
92 : *
93 : * Check if "Invalid Battery-Backed RAM" status is set then reset the status bit. This may occur as
94 : * a result to low voltage at the VBAT pin.
95 : *
96 : * @param[in] dev BBRAM device pointer.
97 : * @return 0 if the Battery-Backed RAM data is valid, -EFAULT otherwise.
98 : */
99 1 : __syscall int bbram_check_invalid(const struct device *dev);
100 :
101 : static inline int z_impl_bbram_check_invalid(const struct device *dev)
102 : {
103 : const struct bbram_driver_api *api =
104 : (const struct bbram_driver_api *)dev->api;
105 :
106 : if (!api->check_invalid) {
107 : return -ENOTSUP;
108 : }
109 :
110 : return api->check_invalid(dev);
111 : }
112 :
113 : /**
114 : * @brief Check for standby (Volt SBY) power failure.
115 : *
116 : * Check if the V standby power domain is turned on after it was off then reset the status bit.
117 : *
118 : * @param[in] dev BBRAM device pointer.
119 : * @return 0 if V SBY power domain is in normal operation.
120 : */
121 1 : __syscall int bbram_check_standby_power(const struct device *dev);
122 :
123 : static inline int z_impl_bbram_check_standby_power(const struct device *dev)
124 : {
125 : const struct bbram_driver_api *api =
126 : (const struct bbram_driver_api *)dev->api;
127 :
128 : if (!api->check_standby_power) {
129 : return -ENOTSUP;
130 : }
131 :
132 : return api->check_standby_power(dev);
133 : }
134 :
135 : /**
136 : * @brief Check for V CC1 power failure.
137 : *
138 : * This will return an error if the V CC1 power domain is turned on after it was off and reset the
139 : * status bit.
140 : *
141 : * @param[in] dev BBRAM device pointer.
142 : * @return 0 if the V CC1 power domain is in normal operation, -EFAULT otherwise.
143 : */
144 1 : __syscall int bbram_check_power(const struct device *dev);
145 :
146 : static inline int z_impl_bbram_check_power(const struct device *dev)
147 : {
148 : const struct bbram_driver_api *api =
149 : (const struct bbram_driver_api *)dev->api;
150 :
151 : if (!api->check_power) {
152 : return -ENOTSUP;
153 : }
154 :
155 : return api->check_power(dev);
156 : }
157 :
158 : /**
159 : * @brief Get the size of the BBRAM (in bytes).
160 : *
161 : * @param[in] dev BBRAM device pointer.
162 : * @param[out] size Pointer to write the size to.
163 : * @return 0 for success, -EFAULT otherwise.
164 : */
165 1 : __syscall int bbram_get_size(const struct device *dev, size_t *size);
166 :
167 : static inline int z_impl_bbram_get_size(const struct device *dev, size_t *size)
168 : {
169 : const struct bbram_driver_api *api =
170 : (const struct bbram_driver_api *)dev->api;
171 :
172 : if (!api->get_size) {
173 : return -ENOTSUP;
174 : }
175 :
176 : return api->get_size(dev, size);
177 : }
178 :
179 : /**
180 : * @brief Read bytes from BBRAM.
181 : *
182 : * @param[in] dev The BBRAM device pointer to read from.
183 : * @param[in] offset The offset into the RAM address to start reading from.
184 : * @param[in] size The number of bytes to read.
185 : * @param[out] data The buffer to load the data into.
186 : * @return 0 on success, -EFAULT if the address range is out of bounds.
187 : */
188 1 : __syscall int bbram_read(const struct device *dev, size_t offset, size_t size,
189 : uint8_t *data);
190 :
191 : static inline int z_impl_bbram_read(const struct device *dev, size_t offset,
192 : size_t size, uint8_t *data)
193 : {
194 : const struct bbram_driver_api *api =
195 : (const struct bbram_driver_api *)dev->api;
196 :
197 : if (!api->read) {
198 : return -ENOTSUP;
199 : }
200 :
201 : return api->read(dev, offset, size, data);
202 : }
203 :
204 : /**
205 : * @brief Write bytes to BBRAM.
206 : *
207 : * @param[in] dev The BBRAM device pointer to write to.
208 : * @param[in] offset The offset into the RAM address to start writing to.
209 : * @param[in] size The number of bytes to write.
210 : * @param[out] data Pointer to the start of data to write.
211 : * @return 0 on success, -EFAULT if the address range is out of bounds.
212 : */
213 1 : __syscall int bbram_write(const struct device *dev, size_t offset, size_t size,
214 : const uint8_t *data);
215 :
216 : static inline int z_impl_bbram_write(const struct device *dev, size_t offset,
217 : size_t size, const uint8_t *data)
218 : {
219 : const struct bbram_driver_api *api =
220 : (const struct bbram_driver_api *)dev->api;
221 :
222 : if (!api->write) {
223 : return -ENOTSUP;
224 : }
225 :
226 : return api->write(dev, offset, size, data);
227 : }
228 :
229 : /**
230 : * @brief Set the emulated BBRAM driver's invalid state
231 : *
232 : * Calling this will affect the emulated behavior of bbram_check_invalid().
233 : *
234 : * @param[in] dev The emulated device to modify
235 : * @param[in] is_invalid The new invalid state
236 : * @return 0 on success, negative values on error.
237 : */
238 1 : int bbram_emul_set_invalid(const struct device *dev, bool is_invalid);
239 :
240 : /**
241 : * @brief Set the emulated BBRAM driver's standby power state
242 : *
243 : * Calling this will affect the emulated behavior of bbram_check_standby_power().
244 : *
245 : * @param[in] dev The emulated device to modify
246 : * @param[in] failure Whether or not standby power failure should be emulated
247 : * @return 0 on success, negative values on error.
248 : */
249 1 : int bbram_emul_set_standby_power_state(const struct device *dev, bool failure);
250 :
251 : /**
252 : * @brief Set the emulated BBRAM driver's power state
253 : *
254 : * Calling this will affect the emulated behavior of bbram_check_power().
255 : *
256 : * @param[in] dev The emulated device to modify
257 : * @param[in] failure Whether or not a power failure should be emulated
258 : * @return 0 on success, negative values on error.
259 : */
260 1 : int bbram_emul_set_power_state(const struct device *dev, bool failure);
261 :
262 : #ifdef __cplusplus
263 : }
264 : #endif
265 :
266 : /**
267 : * @}
268 : */
269 :
270 : #include <zephyr/syscalls/bbram.h>
271 :
272 : #endif /* ZEPHYR_INCLUDE_DRIVERS_BBRAM_H */
|
