Line data Source code
1 1 : /**
2 : * @file
3 : * @brief Clocks Devicetree macro public API header file.
4 : */
5 :
6 : /*
7 : * Copyright (c) 2020, Linaro Ltd.
8 : *
9 : * SPDX-License-Identifier: Apache-2.0
10 : */
11 :
12 : #ifndef ZEPHYR_INCLUDE_DEVICETREE_CLOCKS_H_
13 : #define ZEPHYR_INCLUDE_DEVICETREE_CLOCKS_H_
14 :
15 : #ifdef __cplusplus
16 : extern "C" {
17 : #endif
18 :
19 : /**
20 : * @defgroup devicetree-clocks Devicetree Clocks API
21 : * @ingroup devicetree
22 : * @ingroup clock_control_interface
23 : * @{
24 : */
25 :
26 : /**
27 : * @brief Test if a node has a clocks phandle-array property at a given index
28 : *
29 : * This expands to 1 if the given index is valid clocks property phandle-array index.
30 : * Otherwise, it expands to 0.
31 : *
32 : * Example devicetree fragment:
33 : *
34 : * n1: node-1 {
35 : * clocks = <...>, <...>;
36 : * };
37 : *
38 : * n2: node-2 {
39 : * clocks = <...>;
40 : * };
41 : *
42 : * Example usage:
43 : *
44 : * DT_CLOCKS_HAS_IDX(DT_NODELABEL(n1), 0) // 1
45 : * DT_CLOCKS_HAS_IDX(DT_NODELABEL(n1), 1) // 1
46 : * DT_CLOCKS_HAS_IDX(DT_NODELABEL(n1), 2) // 0
47 : * DT_CLOCKS_HAS_IDX(DT_NODELABEL(n2), 1) // 0
48 : *
49 : * @param node_id node identifier; may or may not have any clocks property
50 : * @param idx index of a clocks property phandle-array whose existence to check
51 : * @return 1 if the index exists, 0 otherwise
52 : */
53 1 : #define DT_CLOCKS_HAS_IDX(node_id, idx) \
54 : DT_PROP_HAS_IDX(node_id, clocks, idx)
55 :
56 : /**
57 : * @brief Test if a node has a clock-names array property holds a given name
58 : *
59 : * This expands to 1 if the name is available as clocks-name array property cell.
60 : * Otherwise, it expands to 0.
61 : *
62 : * Example devicetree fragment:
63 : *
64 : * n1: node-1 {
65 : * clocks = <...>, <...>;
66 : * clock-names = "alpha", "beta";
67 : * };
68 : *
69 : * n2: node-2 {
70 : * clocks = <...>;
71 : * clock-names = "alpha";
72 : * };
73 : *
74 : * Example usage:
75 : *
76 : * DT_CLOCKS_HAS_NAME(DT_NODELABEL(n1), alpha) // 1
77 : * DT_CLOCKS_HAS_NAME(DT_NODELABEL(n1), beta) // 1
78 : * DT_CLOCKS_HAS_NAME(DT_NODELABEL(n2), beta) // 0
79 : *
80 : * @param node_id node identifier; may or may not have any clock-names property.
81 : * @param name lowercase-and-underscores clock-names cell value name to check
82 : * @return 1 if the clock name exists, 0 otherwise
83 : */
84 1 : #define DT_CLOCKS_HAS_NAME(node_id, name) \
85 : DT_PROP_HAS_NAME(node_id, clocks, name)
86 :
87 : /**
88 : * @brief Get the number of elements in a clocks property
89 : *
90 : * Example devicetree fragment:
91 : *
92 : * n1: node-1 {
93 : * clocks = <&foo>, <&bar>;
94 : * };
95 : *
96 : * n2: node-2 {
97 : * clocks = <&foo>;
98 : * };
99 : *
100 : * Example usage:
101 : *
102 : * DT_NUM_CLOCKS(DT_NODELABEL(n1)) // 2
103 : * DT_NUM_CLOCKS(DT_NODELABEL(n2)) // 1
104 : *
105 : * @param node_id node identifier with a clocks property
106 : * @return number of elements in the property
107 : */
108 1 : #define DT_NUM_CLOCKS(node_id) \
109 : DT_PROP_LEN(node_id, clocks)
110 :
111 :
112 : /**
113 : * @brief Get the node identifier for the controller phandle from a
114 : * "clocks" phandle-array property at an index
115 : *
116 : * Example devicetree fragment:
117 : *
118 : * clk1: clock-controller@... { ... };
119 : *
120 : * clk2: clock-controller@... { ... };
121 : *
122 : * n: node {
123 : * clocks = <&clk1 10 20>, <&clk2 30 40>;
124 : * };
125 : *
126 : * Example usage:
127 : *
128 : * DT_CLOCKS_CTLR_BY_IDX(DT_NODELABEL(n), 0)) // DT_NODELABEL(clk1)
129 : * DT_CLOCKS_CTLR_BY_IDX(DT_NODELABEL(n), 1)) // DT_NODELABEL(clk2)
130 : *
131 : * @param node_id node identifier
132 : * @param idx logical index into "clocks"
133 : * @return the node identifier for the clock controller referenced at
134 : * index "idx"
135 : * @see DT_PHANDLE_BY_IDX()
136 : */
137 1 : #define DT_CLOCKS_CTLR_BY_IDX(node_id, idx) \
138 : DT_PHANDLE_BY_IDX(node_id, clocks, idx)
139 :
140 : /**
141 : * @brief Equivalent to DT_CLOCKS_CTLR_BY_IDX(node_id, 0)
142 : * @param node_id node identifier
143 : * @return a node identifier for the clocks controller at index 0
144 : * in "clocks"
145 : * @see DT_CLOCKS_CTLR_BY_IDX()
146 : */
147 1 : #define DT_CLOCKS_CTLR(node_id) DT_CLOCKS_CTLR_BY_IDX(node_id, 0)
148 :
149 : /**
150 : * @brief Get the node identifier for the controller phandle from a
151 : * clocks phandle-array property by name
152 : *
153 : * Example devicetree fragment:
154 : *
155 : * clk1: clock-controller@... { ... };
156 : *
157 : * clk2: clock-controller@... { ... };
158 : *
159 : * n: node {
160 : * clocks = <&clk1 10 20>, <&clk2 30 40>;
161 : * clock-names = "alpha", "beta";
162 : * };
163 : *
164 : * Example usage:
165 : *
166 : * DT_CLOCKS_CTLR_BY_NAME(DT_NODELABEL(n), beta) // DT_NODELABEL(clk2)
167 : *
168 : * @param node_id node identifier
169 : * @param name lowercase-and-underscores name of a clocks element
170 : * as defined by the node's clock-names property
171 : * @return the node identifier for the clock controller referenced by name
172 : * @see DT_PHANDLE_BY_NAME()
173 : */
174 1 : #define DT_CLOCKS_CTLR_BY_NAME(node_id, name) \
175 : DT_PHANDLE_BY_NAME(node_id, clocks, name)
176 :
177 : /**
178 : * @brief Get a clock specifier's cell value at an index
179 : *
180 : * Example devicetree fragment:
181 : *
182 : * clk1: clock-controller@... {
183 : * compatible = "vnd,clock";
184 : * #clock-cells = < 2 >;
185 : * };
186 : *
187 : * n: node {
188 : * clocks = < &clk1 10 20 >, < &clk1 30 40 >;
189 : * };
190 : *
191 : * Bindings fragment for the vnd,clock compatible:
192 : *
193 : * clock-cells:
194 : * - bus
195 : * - bits
196 : *
197 : * Example usage:
198 : *
199 : * DT_CLOCKS_CELL_BY_IDX(DT_NODELABEL(n), 0, bus) // 10
200 : * DT_CLOCKS_CELL_BY_IDX(DT_NODELABEL(n), 1, bits) // 40
201 : *
202 : * @param node_id node identifier for a node with a clocks property
203 : * @param idx logical index into clocks property
204 : * @param cell lowercase-and-underscores cell name
205 : * @return the cell value at index "idx"
206 : * @see DT_PHA_BY_IDX()
207 : */
208 1 : #define DT_CLOCKS_CELL_BY_IDX(node_id, idx, cell) \
209 : DT_PHA_BY_IDX(node_id, clocks, idx, cell)
210 :
211 : /**
212 : * @brief Get a clock specifier's cell value by name
213 : *
214 : * Example devicetree fragment:
215 : *
216 : * clk1: clock-controller@... {
217 : * compatible = "vnd,clock";
218 : * #clock-cells = < 2 >;
219 : * };
220 : *
221 : * n: node {
222 : * clocks = < &clk1 10 20 >, < &clk1 30 40 >;
223 : * clock-names = "alpha", "beta";
224 : * };
225 : *
226 : * Bindings fragment for the vnd,clock compatible:
227 : *
228 : * clock-cells:
229 : * - bus
230 : * - bits
231 : *
232 : * Example usage:
233 : *
234 : * DT_CLOCKS_CELL_BY_NAME(DT_NODELABEL(n), alpha, bus) // 10
235 : * DT_CLOCKS_CELL_BY_NAME(DT_NODELABEL(n), beta, bits) // 40
236 : *
237 : * @param node_id node identifier for a node with a clocks property
238 : * @param name lowercase-and-underscores name of a clocks element
239 : * as defined by the node's clock-names property
240 : * @param cell lowercase-and-underscores cell name
241 : * @return the cell value in the specifier at the named element
242 : * @see DT_PHA_BY_NAME()
243 : */
244 1 : #define DT_CLOCKS_CELL_BY_NAME(node_id, name, cell) \
245 : DT_PHA_BY_NAME(node_id, clocks, name, cell)
246 :
247 : /**
248 : * @brief Equivalent to DT_CLOCKS_CELL_BY_IDX(node_id, 0, cell)
249 : * @param node_id node identifier for a node with a clocks property
250 : * @param cell lowercase-and-underscores cell name
251 : * @return the cell value at index 0
252 : * @see DT_CLOCKS_CELL_BY_IDX()
253 : */
254 1 : #define DT_CLOCKS_CELL(node_id, cell) DT_CLOCKS_CELL_BY_IDX(node_id, 0, cell)
255 :
256 : /**
257 : * @brief Equivalent to DT_CLOCKS_HAS_IDX(DT_DRV_INST(inst), idx)
258 : * @param inst DT_DRV_COMPAT instance number; may or may not have any clocks property
259 : * @param idx index of a clocks property phandle-array whose existence to check
260 : * @return 1 if the index exists, 0 otherwise
261 : */
262 1 : #define DT_INST_CLOCKS_HAS_IDX(inst, idx) \
263 : DT_CLOCKS_HAS_IDX(DT_DRV_INST(inst), idx)
264 :
265 : /**
266 : * @brief Equivalent to DT_CLOCK_HAS_NAME(DT_DRV_INST(inst), name)
267 : * @param inst DT_DRV_COMPAT instance number; may or may not have any clock-names property.
268 : * @param name lowercase-and-underscores clock-names cell value name to check
269 : * @return 1 if the clock name exists, 0 otherwise
270 : */
271 1 : #define DT_INST_CLOCKS_HAS_NAME(inst, name) \
272 : DT_CLOCKS_HAS_NAME(DT_DRV_INST(inst), name)
273 :
274 : /**
275 : * @brief Equivalent to DT_NUM_CLOCKS(DT_DRV_INST(inst))
276 : * @param inst instance number
277 : * @return number of elements in the clocks property
278 : */
279 1 : #define DT_INST_NUM_CLOCKS(inst) \
280 : DT_NUM_CLOCKS(DT_DRV_INST(inst))
281 :
282 : /**
283 : * @brief Get the node identifier for the controller phandle from a
284 : * "clocks" phandle-array property at an index
285 : *
286 : * @param inst instance number
287 : * @param idx logical index into "clocks"
288 : * @return the node identifier for the clock controller referenced at
289 : * index "idx"
290 : * @see DT_CLOCKS_CTLR_BY_IDX()
291 : */
292 1 : #define DT_INST_CLOCKS_CTLR_BY_IDX(inst, idx) \
293 : DT_CLOCKS_CTLR_BY_IDX(DT_DRV_INST(inst), idx)
294 :
295 : /**
296 : * @brief Equivalent to DT_INST_CLOCKS_CTLR_BY_IDX(inst, 0)
297 : * @param inst instance number
298 : * @return a node identifier for the clocks controller at index 0
299 : * in "clocks"
300 : * @see DT_CLOCKS_CTLR()
301 : */
302 1 : #define DT_INST_CLOCKS_CTLR(inst) DT_INST_CLOCKS_CTLR_BY_IDX(inst, 0)
303 :
304 : /**
305 : * @brief Get the node identifier for the controller phandle from a
306 : * clocks phandle-array property by name
307 : *
308 : * @param inst instance number
309 : * @param name lowercase-and-underscores name of a clocks element
310 : * as defined by the node's clock-names property
311 : * @return the node identifier for the clock controller referenced by
312 : * the named element
313 : * @see DT_CLOCKS_CTLR_BY_NAME()
314 : */
315 1 : #define DT_INST_CLOCKS_CTLR_BY_NAME(inst, name) \
316 : DT_CLOCKS_CTLR_BY_NAME(DT_DRV_INST(inst), name)
317 :
318 : /**
319 : * @brief Get a DT_DRV_COMPAT instance's clock specifier's cell value
320 : * at an index
321 : * @param inst DT_DRV_COMPAT instance number
322 : * @param idx logical index into clocks property
323 : * @param cell lowercase-and-underscores cell name
324 : * @return the cell value at index "idx"
325 : * @see DT_CLOCKS_CELL_BY_IDX()
326 : */
327 1 : #define DT_INST_CLOCKS_CELL_BY_IDX(inst, idx, cell) \
328 : DT_CLOCKS_CELL_BY_IDX(DT_DRV_INST(inst), idx, cell)
329 :
330 : /**
331 : * @brief Get a DT_DRV_COMPAT instance's clock specifier's cell value by name
332 : * @param inst DT_DRV_COMPAT instance number
333 : * @param name lowercase-and-underscores name of a clocks element
334 : * as defined by the node's clock-names property
335 : * @param cell lowercase-and-underscores cell name
336 : * @return the cell value in the specifier at the named element
337 : * @see DT_CLOCKS_CELL_BY_NAME()
338 : */
339 1 : #define DT_INST_CLOCKS_CELL_BY_NAME(inst, name, cell) \
340 : DT_CLOCKS_CELL_BY_NAME(DT_DRV_INST(inst), name, cell)
341 :
342 : /**
343 : * @brief Equivalent to DT_INST_CLOCKS_CELL_BY_IDX(inst, 0, cell)
344 : * @param inst DT_DRV_COMPAT instance number
345 : * @param cell lowercase-and-underscores cell name
346 : * @return the value of the cell inside the specifier at index 0
347 : */
348 1 : #define DT_INST_CLOCKS_CELL(inst, cell) \
349 : DT_INST_CLOCKS_CELL_BY_IDX(inst, 0, cell)
350 :
351 : /**
352 : * @}
353 : */
354 :
355 : #ifdef __cplusplus
356 : }
357 : #endif
358 :
359 : #endif /* ZEPHYR_INCLUDE_DEVICETREE_CLOCKS_H_ */
|