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_ */
|