1 /**
2  * @file
3  * @brief Reset Controller Devicetree macro public API header file.
4  */
5 
6 /*
7  * Copyright (c) 2022, Andrei-Edward Popa
8  *
9  * SPDX-License-Identifier: Apache-2.0
10  */
11 
12 #ifndef ZEPHYR_INCLUDE_DEVICETREE_RESET_H_
13 #define ZEPHYR_INCLUDE_DEVICETREE_RESET_H_
14 
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18 
19 /**
20  * @defgroup devicetree-reset-controller Devicetree Reset Controller API
21  * @ingroup devicetree
22  * @{
23  */
24 
25 /**
26  * @brief Get the node identifier for the controller phandle from a
27  *        "resets" phandle-array property at an index
28  *
29  * Example devicetree fragment:
30  *
31  *     reset1: reset-controller@... { ... };
32  *
33  *     reset2: reset-controller@... { ... };
34  *
35  *     n: node {
36  *             resets = <&reset1 10>, <&reset2 20>;
37  *     };
38  *
39  * Example usage:
40  *
41  *     DT_RESET_CTLR_BY_IDX(DT_NODELABEL(n), 0)) // DT_NODELABEL(reset1)
42  *     DT_RESET_CTLR_BY_IDX(DT_NODELABEL(n), 1)) // DT_NODELABEL(reset2)
43  *
44  * @param node_id node identifier
45  * @param idx logical index into "resets"
46  * @return the node identifier for the reset controller referenced at
47  *         index "idx"
48  * @see DT_PHANDLE_BY_IDX()
49  */
50 #define DT_RESET_CTLR_BY_IDX(node_id, idx) \
51 	DT_PHANDLE_BY_IDX(node_id, resets, idx)
52 
53 /**
54  * @brief Equivalent to DT_RESET_CTLR_BY_IDX(node_id, 0)
55  * @param node_id node identifier
56  * @return a node identifier for the reset controller at index 0
57  *         in "resets"
58  * @see DT_RESET_CTLR_BY_IDX()
59  */
60 #define DT_RESET_CTLR(node_id) \
61 	DT_RESET_CTLR_BY_IDX(node_id, 0)
62 
63 /**
64  * @brief Get the node identifier for the controller phandle from a
65  *        resets phandle-array property by name
66  *
67  * Example devicetree fragment:
68  *
69  *     reset1: reset-controller@... { ... };
70  *
71  *     reset2: reset-controller@... { ... };
72  *
73  *     n: node {
74  *             resets = <&reset1 10>, <&reset2 20>;
75  *             reset-names = "alpha", "beta";
76  *     };
77  *
78  * Example usage:
79  *
80  *     DT_RESET_CTLR_BY_NAME(DT_NODELABEL(n), alpha) // DT_NODELABEL(reset1)
81  *     DT_RESET_CTLR_BY_NAME(DT_NODELABEL(n), beta) // DT_NODELABEL(reset2)
82  *
83  * @param node_id node identifier
84  * @param name lowercase-and-underscores name of a resets element
85  *             as defined by the node's reset-names property
86  * @return the node identifier for the reset controller referenced by name
87  * @see DT_PHANDLE_BY_NAME()
88  */
89 #define DT_RESET_CTLR_BY_NAME(node_id, name) \
90 	DT_PHANDLE_BY_NAME(node_id, resets, name)
91 
92 /**
93  * @brief Get a reset specifier's cell value at an index
94  *
95  * Example devicetree fragment:
96  *
97  *     reset: reset-controller@... {
98  *             compatible = "vnd,reset";
99  *             #reset-cells = <1>;
100  *     };
101  *
102  *     n: node {
103  *             resets = <&reset 10>;
104  *     };
105  *
106  * Bindings fragment for the vnd,reset compatible:
107  *
108  *     reset-cells:
109  *       - id
110  *
111  * Example usage:
112  *
113  *     DT_RESET_CELL_BY_IDX(DT_NODELABEL(n), 0, id) // 10
114  *
115  * @param node_id node identifier for a node with a resets property
116  * @param idx logical index into resets property
117  * @param cell lowercase-and-underscores cell name
118  * @return the cell value at index "idx"
119  * @see DT_PHA_BY_IDX()
120  */
121 #define DT_RESET_CELL_BY_IDX(node_id, idx, cell) \
122 	DT_PHA_BY_IDX(node_id, resets, idx, cell)
123 
124 /**
125  * @brief Get a reset specifier's cell value by name
126  *
127  * Example devicetree fragment:
128  *
129  *     reset: reset-controller@... {
130  *             compatible = "vnd,reset";
131  *             #reset-cells = <1>;
132  *     };
133  *
134  *     n: node {
135  *             resets = <&reset 10>;
136  *             reset-names = "alpha";
137  *     };
138  *
139  * Bindings fragment for the vnd,reset compatible:
140  *
141  *     reset-cells:
142  *       - id
143  *
144  * Example usage:
145  *
146  *     DT_RESET_CELL_BY_NAME(DT_NODELABEL(n), alpha, id) // 10
147  *
148  * @param node_id node identifier for a node with a resets property
149  * @param name lowercase-and-underscores name of a resets element
150  *             as defined by the node's reset-names property
151  * @param cell lowercase-and-underscores cell name
152  * @return the cell value in the specifier at the named element
153  * @see DT_PHA_BY_NAME()
154  */
155 #define DT_RESET_CELL_BY_NAME(node_id, name, cell) \
156 	DT_PHA_BY_NAME(node_id, resets, name, cell)
157 
158 /**
159  * @brief Equivalent to DT_RESET_CELL_BY_IDX(node_id, 0, cell)
160  * @param node_id node identifier for a node with a resets property
161  * @param cell lowercase-and-underscores cell name
162  * @return the cell value at index 0
163  * @see DT_RESET_CELL_BY_IDX()
164  */
165 #define DT_RESET_CELL(node_id, cell) \
166 	DT_RESET_CELL_BY_IDX(node_id, 0, cell)
167 
168 /**
169  * @brief Get the node identifier for the controller phandle from a
170  *        "resets" phandle-array property at an index
171  *
172  * @param inst instance number
173  * @param idx logical index into "resets"
174  * @return the node identifier for the reset controller referenced at
175  *         index "idx"
176  * @see DT_RESET_CTLR_BY_IDX()
177  */
178 #define DT_INST_RESET_CTLR_BY_IDX(inst, idx) \
179 	DT_RESET_CTLR_BY_IDX(DT_DRV_INST(inst), idx)
180 
181 /**
182  * @brief Equivalent to DT_INST_RESET_CTLR_BY_IDX(inst, 0)
183  * @param inst instance number
184  * @return a node identifier for the reset controller at index 0
185  *         in "resets"
186  * @see DT_RESET_CTLR()
187  */
188 #define DT_INST_RESET_CTLR(inst) \
189 	DT_INST_RESET_CTLR_BY_IDX(inst, 0)
190 
191 /**
192  * @brief Get the node identifier for the controller phandle from a
193  *        resets phandle-array property by name
194  *
195  * @param inst instance number
196  * @param name lowercase-and-underscores name of a resets element
197  *             as defined by the node's reset-names property
198  * @return the node identifier for the reset controller referenced by
199  *         the named element
200  * @see DT_RESET_CTLR_BY_NAME()
201  */
202 #define DT_INST_RESET_CTLR_BY_NAME(inst, name) \
203 	DT_RESET_CTLR_BY_NAME(DT_DRV_INST(inst), name)
204 
205 /**
206  * @brief Get a DT_DRV_COMPAT instance's reset specifier's cell value
207  *        at an index
208  * @param inst DT_DRV_COMPAT instance number
209  * @param idx logical index into resets property
210  * @param cell lowercase-and-underscores cell name
211  * @return the cell value at index "idx"
212  * @see DT_RESET_CELL_BY_IDX()
213  */
214 #define DT_INST_RESET_CELL_BY_IDX(inst, idx, cell) \
215 	DT_RESET_CELL_BY_IDX(DT_DRV_INST(inst), idx, cell)
216 
217 /**
218  * @brief Get a DT_DRV_COMPAT instance's reset specifier's cell value by name
219  * @param inst DT_DRV_COMPAT instance number
220  * @param name lowercase-and-underscores name of a resets element
221  *             as defined by the node's reset-names property
222  * @param cell lowercase-and-underscores cell name
223  * @return the cell value in the specifier at the named element
224  * @see DT_RESET_CELL_BY_NAME()
225  */
226 #define DT_INST_RESET_CELL_BY_NAME(inst, name, cell) \
227 	DT_RESET_CELL_BY_NAME(DT_DRV_INST(inst), name, cell)
228 
229 /**
230  * @brief Equivalent to DT_INST_RESET_CELL_BY_IDX(inst, 0, cell)
231  * @param inst DT_DRV_COMPAT instance number
232  * @param cell lowercase-and-underscores cell name
233  * @return the value of the cell inside the specifier at index 0
234  */
235 #define DT_INST_RESET_CELL(inst, cell) \
236 	DT_INST_RESET_CELL_BY_IDX(inst, 0, cell)
237 
238 /**
239  * @brief Get a Reset Controller specifier's id cell at an index
240  *
241  * This macro only works for Reset Controller specifiers with cells named "id".
242  * Refer to the node's binding to check if necessary.
243  *
244  * Example devicetree fragment:
245  *
246  *     reset: reset-controller@... {
247  *             compatible = "vnd,reset";
248  *             #reset-cells = <1>;
249  *     };
250  *
251  *     n: node {
252  *             resets = <&reset 10>;
253  *     };
254  *
255  * Bindings fragment for the vnd,reset compatible:
256  *
257  *     reset-cells:
258  *       - id
259  *
260  * Example usage:
261  *
262  *     DT_RESET_ID_BY_IDX(DT_NODELABEL(n), 0) // 10
263  *
264  * @param node_id node identifier
265  * @param idx logical index into "resets"
266  * @return the id cell value at index "idx"
267  * @see DT_PHA_BY_IDX()
268  */
269 #define DT_RESET_ID_BY_IDX(node_id, idx) \
270 	DT_PHA_BY_IDX(node_id, resets, idx, id)
271 
272 /**
273  * @brief Equivalent to DT_RESET_ID_BY_IDX(node_id, 0)
274  * @param node_id node identifier
275  * @return the id cell value at index 0
276  * @see DT_RESET_ID_BY_IDX()
277  */
278 #define DT_RESET_ID(node_id) \
279 	DT_RESET_ID_BY_IDX(node_id, 0)
280 
281 /**
282  * @brief Get a DT_DRV_COMPAT instance's Reset Controller specifier's id cell value
283  *        at an index
284  * @param inst DT_DRV_COMPAT instance number
285  * @param idx logical index into "resets"
286  * @return the id cell value at index "idx"
287  * @see DT_RESET_ID_BY_IDX()
288  */
289 #define DT_INST_RESET_ID_BY_IDX(inst, idx) \
290 	DT_RESET_ID_BY_IDX(DT_DRV_INST(inst), idx)
291 
292 /**
293  * @brief Equivalent to DT_INST_RESET_ID_BY_IDX(inst, 0)
294  * @param inst DT_DRV_COMPAT instance number
295  * @return the id cell value at index 0
296  * @see DT_INST_RESET_ID_BY_IDX()
297  */
298 #define DT_INST_RESET_ID(inst) \
299 	DT_INST_RESET_ID_BY_IDX(inst, 0)
300 
301 /**
302  * @}
303  */
304 
305 #ifdef __cplusplus
306 }
307 #endif
308 
309 #endif  /* ZEPHYR_INCLUDE_DEVICETREE_RESET_H_ */
310