Line data Source code
1 1 : /**
2 : * @file
3 : * @brief NVMEM Devicetree public API header file.
4 : */
5 :
6 : /*
7 : * Copyright (c) 2024, Andriy Gelman
8 : * Copyright (c) 2025, Basalte bv
9 : *
10 : * SPDX-License-Identifier: Apache-2.0
11 : */
12 :
13 : #ifndef INCLUDE_ZEPHYR_DEVICETREE_NVMEM_H_
14 : #define INCLUDE_ZEPHYR_DEVICETREE_NVMEM_H_
15 :
16 : #ifdef __cplusplus
17 : extern "C" {
18 : #endif
19 :
20 : /**
21 : * @defgroup devicetree-nvmem Devicetree NVMEM API
22 : * @ingroup devicetree
23 : * @{
24 : */
25 :
26 : /**
27 : * @brief Test if a node has an nvmem-cells phandle-array property at a given index
28 : *
29 : * This expands to 1 if the given index is a valid nvmem-cells property phandle-array index.
30 : * Otherwise, it expands to 0.
31 : *
32 : * Example devicetree fragment:
33 : *
34 : * @code{.dts}
35 : * eth: ethernet {
36 : * nvmem-cells = <&mac_address>;
37 : * nvmem-cell-names = "mac-address";
38 : * };
39 : * @endcode
40 : *
41 : * Example usage:
42 : *
43 : * @code{.c}
44 : * DT_NVMEM_CELLS_HAS_IDX(DT_NODELABEL(eth), 0) // 1
45 : * DT_NVMEM_CELLS_HAS_IDX(DT_NODELABEL(eth), 1) // 0
46 : * @endcode
47 : *
48 : * @param node_id node identifier; may or may not have any nvmem-cells property
49 : * @param idx index of a nvmem-cells property phandle-array whose existence to check
50 : *
51 : * @return 1 if the index exists, 0 otherwise
52 : */
53 1 : #define DT_NVMEM_CELLS_HAS_IDX(node_id, idx) DT_PROP_HAS_IDX(node_id, nvmem_cells, idx)
54 :
55 : /**
56 : * @brief Test if a node has an nvmem-cell-names array property hold a given name.
57 : *
58 : * This expands to 1 if the name is available as nvmem-cells-name array property cell.
59 : * Otherwise, it expands to 0.
60 : *
61 : * Example devicetree fragment:
62 : *
63 : * @code{.dts}
64 : * eth: ethernet {
65 : * nvmem-cells = <&mac_address>;
66 : * nvmem-cell-names = "mac-address";
67 : * };
68 : * @endcode
69 : *
70 : * Example usage:
71 : *
72 : * @code{.c}
73 : * DT_NVMEM_CELLS_HAS_NAME(DT_NODELABEL(eth), mac_address) // 1
74 : * DT_NVMEM_CELLS_HAS_NAME(DT_NODELABEL(eth), bogus) // 0
75 : * @endcode
76 : *
77 : * @param node_id node identifier; may or may not have any nvmem-cell-names property
78 : * @param name lowercase-and-underscores nvmem-cell-names cell value name to check
79 : *
80 : * @return 1 if the index exists, 0 otherwise
81 : */
82 1 : #define DT_NVMEM_CELLS_HAS_NAME(node_id, name) DT_PROP_HAS_NAME(node_id, nvmem_cells, name)
83 :
84 : /**
85 : * @brief Get the number of elements in an nvmem-cells property
86 : *
87 : * Example devicetree fragment:
88 : *
89 : * @code{.dts}
90 : * eth: ethernet {
91 : * nvmem-cells = <&mac_address>;
92 : * nvmem-cell-names = "mac-address";
93 : * };
94 : * @endcode
95 : *
96 : * Example usage:
97 : *
98 : * @code{.c}
99 : * DT_NUM_NVMEM_CELLS(DT_NODELABEL(eth)) // 1
100 : * @endcode
101 : *
102 : * @param node_id node identifier with an nvmem-cells property
103 : *
104 : * @return number of elements in the property
105 : */
106 1 : #define DT_NUM_NVMEM_CELLS(node_id) DT_PROP_LEN(node_id, nvmem_cells)
107 :
108 : /**
109 : * @brief Get the node identifier for the NVMEM cell from the nvmem-cells property by index.
110 : *
111 : * Example devicetree fragment:
112 : *
113 : * @code{.dts}
114 : * mac_eeprom: mac_eeprom@2 {
115 : * nvmem-layout {
116 : * compatible = "fixed-layout";
117 : * #address-cells = <1>;
118 : * #size-cells = <1>;
119 : *
120 : * mac_address: mac_address@fa {
121 : * reg = <0xfa 0x06>;
122 : * #nvmem-cell-cells = <0>;
123 : * };
124 : * };
125 : * };
126 : *
127 : * eth: ethernet {
128 : * nvmem-cells = <&mac_address>;
129 : * nvmem-cell-names = "mac-address";
130 : * };
131 : * @endcode
132 : *
133 : * Example usage:
134 : *
135 : * @code{.c}
136 : * DT_NVMEM_CELL_BY_IDX(DT_NODELABEL(eth), 0) // DT_NODELABEL(mac_address)
137 : * @endcode
138 : *
139 : * @param node_id node identifier for a node with a nvmem-cells property
140 : * @param idx index into the nvmem-cells property
141 : *
142 : * @return the node identifier for the NVMEM cell at index idx
143 : */
144 1 : #define DT_NVMEM_CELL_BY_IDX(node_id, idx) DT_PHANDLE_BY_IDX(node_id, nvmem_cells, idx)
145 :
146 : /**
147 : * @brief Equivalent to DT_NVMEM_CELL_BY_IDX(node_id, 0)
148 : *
149 : * @param node_id node identifier
150 : *
151 : * @return a node identifier for the NVMEM cell at index 0
152 : * in "nvmem-cells"
153 : *
154 : * @see DT_NVMEM_CELL_BY_IDX()
155 : */
156 1 : #define DT_NVMEM_CELL(node_id) DT_NVMEM_CELL_BY_IDX(node_id, 0)
157 :
158 : /**
159 : * @brief Get the node identifier for the NVMEM cell from the nvmem-cells property by name.
160 : *
161 : * Example devicetree fragment:
162 : *
163 : * @code{.dts}
164 : * mac_eeprom: mac_eeprom@2 {
165 : * nvmem-layout {
166 : * compatible = "fixed-layout";
167 : * #address-cells = <1>;
168 : * #size-cells = <1>;
169 : *
170 : * mac_address: mac_address@fa {
171 : * reg = <0xfa 0x06>;
172 : * #nvmem-cell-cells = <0>;
173 : * };
174 : * };
175 : * };
176 : *
177 : * eth: ethernet {
178 : * nvmem-cells = <&mac_address>;
179 : * nvmem-cell-names = "mac-address";
180 : * };
181 : * @endcode
182 : *
183 : * Example usage:
184 : *
185 : * @code{.c}
186 : * DT_NVMEM_CELL_BY_NAME(DT_NODELABEL(eth), mac_address) // DT_NODELABEL(mac_address)
187 : * @endcode
188 : *
189 : * @param node_id node identifier for a node with a nvmem-cells property
190 : * @param name lowercase-and-underscores name of an nvmem-cells element
191 : * as defined by the node's nvmem-cell-names property
192 : *
193 : * @return the node identifier for the NVMEM cell by name
194 : */
195 1 : #define DT_NVMEM_CELL_BY_NAME(node_id, name) DT_PHANDLE_BY_NAME(node_id, nvmem_cells, name)
196 :
197 : /**
198 : * @brief Equivalent to DT_NVMEM_CELLS_HAS_IDX(DT_DRV_INST(inst), idx)
199 : *
200 : * @param inst DT_DRV_COMPAT instance number; may or may not have any nvmem-cells property
201 : * @param idx index of an nvmem-cells property phandle-array whose existence to check
202 : *
203 : * @return 1 if the index exists, 0 otherwise
204 : */
205 1 : #define DT_INST_NVMEM_CELLS_HAS_IDX(inst, idx) DT_NVMEM_CELLS_HAS_IDX(DT_DRV_INST(inst), idx)
206 :
207 : /**
208 : * @brief Equivalent to DT_NVMEM_CELLS_HAS_NAME(DT_DRV_INST(inst), name)
209 : *
210 : * @param inst DT_DRV_COMPAT instance number; may or may not have any nvmem-cell-names property.
211 : * @param name lowercase-and-underscores nvmem-cell-names cell value name to check
212 : *
213 : * @return 1 if the nvmem cell name exists, 0 otherwise
214 : */
215 1 : #define DT_INST_NVMEM_CELLS_HAS_NAME(inst, name) DT_NVMEM_CELLS_HAS_NAME(DT_DRV_INST(inst), name)
216 :
217 : /**
218 : * @brief Equivalent to DT_NUM_NVMEM_CELLS(DT_DRV_INST(inst))
219 : *
220 : * @param inst instance number
221 : *
222 : * @return number of elements in the nvmem-cells property
223 : */
224 1 : #define DT_INST_NUM_NVMEM_CELLS(inst) DT_NUM_NVMEM_CELLS(DT_DRV_INST(inst))
225 :
226 : /**
227 : * @brief Get the node identifier for the controller phandle from an
228 : * nvmem-cells phandle-array property at an index
229 : *
230 : * @param inst instance number
231 : * @param idx logical index into nvmem-cells
232 : *
233 : * @return the node identifier for the nvmem cell referenced at
234 : * index "idx"
235 : *
236 : * @see DT_NVMEM_CELL_CTLR_BY_IDX()
237 : */
238 1 : #define DT_INST_NVMEM_CELL_BY_IDX(inst, idx) DT_NVMEM_CELL_BY_IDX(DT_DRV_INST(inst), idx)
239 :
240 : /**
241 : * @brief Equivalent to DT_INST_NVMEM_CELL_BY_IDX(inst, 0)
242 : *
243 : * @param inst instance number
244 : *
245 : * @return a node identifier for the nvmem cell at index 0
246 : * in nvmem-cells
247 : *
248 : * @see DT_NVMEM_CELL()
249 : */
250 1 : #define DT_INST_NVMEM_CELL(inst) DT_INST_NVMEM_CELL_BY_IDX(inst, 0)
251 :
252 : /**
253 : * @brief Get the node identifier for the controller phandle from an
254 : * nvmem-cells phandle-array property by name
255 : *
256 : * @param inst instance number
257 : * @param name lowercase-and-underscores name of an nvmem-cells element
258 : * as defined by the node's nvmem-cell-names property
259 : *
260 : * @return the node identifier for the nvmem cell referenced by
261 : * the named element
262 : *
263 : * @see DT_NVMEM_CELL_BY_NAME()
264 : */
265 1 : #define DT_INST_NVMEM_CELL_BY_NAME(inst, name) DT_NVMEM_CELL_BY_NAME(DT_DRV_INST(inst), name)
266 :
267 : /**
268 : * @brief Get the node identifier of the memory controller for an nvmem cell.
269 : *
270 : * Example devicetree fragment:
271 : *
272 : * @code{.dts}
273 : * mac_eeprom: mac_eeprom@2 {
274 : * nvmem-layout {
275 : * compatible = "fixed-layout";
276 : * #address-cells = <1>;
277 : * #size-cells = <1>;
278 : *
279 : * mac_address: mac_address@fa {
280 : * reg = <0xfa 0x06>;
281 : * #nvmem-cell-cells = <0>;
282 : * };
283 : * };
284 : * };
285 : *
286 : * eth: ethernet {
287 : * nvmem-cells = <&mac_address>;
288 : * nvmem-cell-names = "mac-address";
289 : * };
290 : * @endcode
291 : *
292 : * Example usage:
293 : *
294 : * @code{.c}
295 : * DT_MTD_FROM_NVMEM_CELL(DT_NVMEM_CELL(DT_NODELABEL(eth))) // DT_NODELABEL(mac_eeprom)
296 : * @endcode
297 : *
298 : * @param node_id node identifier for an nvmem cell node
299 : *
300 : * @return the node identifier of the Memory Technology Device (MTD) that
301 : * contains the nvmem cell node.
302 : */
303 1 : #define DT_MTD_FROM_NVMEM_CELL(node_id) DT_GPARENT(node_id)
304 :
305 : /**
306 : * @}
307 : */
308 :
309 : #ifdef __cplusplus
310 : }
311 : #endif
312 :
313 : #endif /* INCLUDE_ZEPHYR_DEVICETREE_NVMEM_H_ */
|