Line data Source code
1 1 : /*
2 : * Copyright (c) 2021 Nordic Semiconductor ASA
3 : * SPDX-License-Identifier: Apache-2.0
4 : */
5 :
6 : #ifndef ZEPHYR_INCLUDE_DEVICETREE_PINCTRL_H_
7 : #define ZEPHYR_INCLUDE_DEVICETREE_PINCTRL_H_
8 :
9 : /**
10 : * @file
11 : * @brief Devicetree pin control helpers
12 : */
13 :
14 : /**
15 : * @defgroup devicetree-pinctrl Pin control
16 : * @ingroup devicetree
17 : * @ingroup pinctrl_interface
18 : * @{
19 : */
20 :
21 : /**
22 : * @brief Get a node identifier for a phandle in a pinctrl property by index
23 : *
24 : * Example devicetree fragment:
25 : *
26 : * n: node {
27 : * pinctrl-0 = <&foo &bar>;
28 : * pinctrl-1 = <&baz &blub>;
29 : * }
30 : *
31 : * Example usage:
32 : *
33 : * DT_PINCTRL_BY_IDX(DT_NODELABEL(n), 0, 1) // DT_NODELABEL(bar)
34 : * DT_PINCTRL_BY_IDX(DT_NODELABEL(n), 1, 0) // DT_NODELABEL(baz)
35 : *
36 : * @param node_id node with a pinctrl-'pc_idx' property
37 : * @param pc_idx index of the pinctrl property itself
38 : * @param idx index into the value of the pinctrl property
39 : * @return node identifier for the phandle at index 'idx' in 'pinctrl-'pc_idx''
40 : */
41 1 : #define DT_PINCTRL_BY_IDX(node_id, pc_idx, idx) \
42 : DT_CAT6(node_id, _P_pinctrl_, pc_idx, _IDX_, idx, _PH)
43 :
44 : /**
45 : * @brief Get a node identifier from a pinctrl-0 property
46 : *
47 : * This is equivalent to:
48 : *
49 : * DT_PINCTRL_BY_IDX(node_id, 0, idx)
50 : *
51 : * It is provided for convenience since pinctrl-0 is commonly used.
52 : *
53 : * @param node_id node with a pinctrl-0 property
54 : * @param idx index into the pinctrl-0 property
55 : * @return node identifier for the phandle at index idx in the pinctrl-0
56 : * property of that node
57 : */
58 1 : #define DT_PINCTRL_0(node_id, idx) DT_PINCTRL_BY_IDX(node_id, 0, idx)
59 :
60 : /**
61 : * @brief Get a node identifier for a phandle inside a pinctrl node by name
62 : *
63 : * Example devicetree fragment:
64 : *
65 : * n: node {
66 : * pinctrl-0 = <&foo &bar>;
67 : * pinctrl-1 = <&baz &blub>;
68 : * pinctrl-names = "default", "sleep";
69 : * };
70 : *
71 : * Example usage:
72 : *
73 : * DT_PINCTRL_BY_NAME(DT_NODELABEL(n), default, 1) // DT_NODELABEL(bar)
74 : * DT_PINCTRL_BY_NAME(DT_NODELABEL(n), sleep, 0) // DT_NODELABEL(baz)
75 : *
76 : * @param node_id node with a named pinctrl property
77 : * @param name lowercase-and-underscores pinctrl property name
78 : * @param idx index into the value of the named pinctrl property
79 : * @return node identifier for the phandle at that index in the pinctrl
80 : * property
81 : */
82 1 : #define DT_PINCTRL_BY_NAME(node_id, name, idx) \
83 : DT_CAT6(node_id, _PINCTRL_NAME_, name, _IDX_, idx, _PH)
84 :
85 : /**
86 : * @brief Convert a pinctrl name to its corresponding index
87 : *
88 : * Example devicetree fragment:
89 : *
90 : * n: node {
91 : * pinctrl-0 = <&foo &bar>;
92 : * pinctrl-1 = <&baz &blub>;
93 : * pinctrl-names = "default", "sleep";
94 : * };
95 : *
96 : * Example usage:
97 : *
98 : * DT_PINCTRL_NAME_TO_IDX(DT_NODELABEL(n), default) // 0
99 : * DT_PINCTRL_NAME_TO_IDX(DT_NODELABEL(n), sleep) // 1
100 : *
101 : * @param node_id node identifier with a named pinctrl property
102 : * @param name lowercase-and-underscores name name of the pinctrl whose index to get
103 : * @return integer literal for the index of the pinctrl property with that name
104 : */
105 1 : #define DT_PINCTRL_NAME_TO_IDX(node_id, name) \
106 : DT_CAT4(node_id, _PINCTRL_NAME_, name, _IDX)
107 :
108 : /**
109 : * @brief Convert a pinctrl property index to its name as a token
110 : *
111 : * This allows you to get a pinctrl property's name, and "remove the
112 : * quotes" from it.
113 : *
114 : * DT_PINCTRL_IDX_TO_NAME_TOKEN() can only be used if the node has a
115 : * pinctrl-'pc_idx' property and a pinctrl-names property element for
116 : * that index. It is an error to use it in other circumstances.
117 : *
118 : * Example devicetree fragment:
119 : *
120 : * n: node {
121 : * pinctrl-0 = <...>;
122 : * pinctrl-1 = <...>;
123 : * pinctrl-names = "default", "f.o.o2";
124 : * };
125 : *
126 : * Example usage:
127 : *
128 : * DT_PINCTRL_IDX_TO_NAME_TOKEN(DT_NODELABEL(n), 0) // default
129 : * DT_PINCTRL_IDX_TO_NAME_TOKEN(DT_NODELABEL(n), 1) // f_o_o2
130 : *
131 : * The same caveats and restrictions that apply to DT_STRING_TOKEN()'s
132 : * return value also apply here.
133 : *
134 : * @param node_id node identifier
135 : * @param pc_idx index of a pinctrl property in that node
136 : * @return name of the pinctrl property, as a token, without any quotes
137 : * and with non-alphanumeric characters converted to underscores
138 : */
139 1 : #define DT_PINCTRL_IDX_TO_NAME_TOKEN(node_id, pc_idx) \
140 : DT_CAT4(node_id, _PINCTRL_IDX_, pc_idx, _TOKEN)
141 :
142 : /**
143 : * @brief Like DT_PINCTRL_IDX_TO_NAME_TOKEN(), but with an uppercased result
144 : *
145 : * This does the a similar conversion as
146 : * DT_PINCTRL_IDX_TO_NAME_TOKEN(node_id, pc_idx). The only difference
147 : * is that alphabetical characters in the result are uppercased.
148 : *
149 : * Example devicetree fragment:
150 : *
151 : * n: node {
152 : * pinctrl-0 = <...>;
153 : * pinctrl-1 = <...>;
154 : * pinctrl-names = "default", "f.o.o2";
155 : * };
156 : *
157 : * Example usage:
158 : *
159 : * DT_PINCTRL_IDX_TO_NAME_TOKEN(DT_NODELABEL(n), 0) // DEFAULT
160 : * DT_PINCTRL_IDX_TO_NAME_TOKEN(DT_NODELABEL(n), 1) // F_O_O2
161 : *
162 : * The same caveats and restrictions that apply to
163 : * DT_STRING_UPPER_TOKEN()'s return value also apply here.
164 : */
165 1 : #define DT_PINCTRL_IDX_TO_NAME_UPPER_TOKEN(node_id, pc_idx) \
166 : DT_CAT4(node_id, _PINCTRL_IDX_, pc_idx, _UPPER_TOKEN)
167 :
168 : /**
169 : * @brief Get the number of phandles in a pinctrl property
170 : *
171 : * Example devicetree fragment:
172 : *
173 : * n1: node-1 {
174 : * pinctrl-0 = <&foo &bar>;
175 : * };
176 : *
177 : * n2: node-2 {
178 : * pinctrl-0 = <&baz>;
179 : * };
180 : *
181 : * Example usage:
182 : *
183 : * DT_NUM_PINCTRLS_BY_IDX(DT_NODELABEL(n1), 0) // 2
184 : * DT_NUM_PINCTRLS_BY_IDX(DT_NODELABEL(n2), 0) // 1
185 : *
186 : * @param node_id node identifier with a pinctrl property
187 : * @param pc_idx index of the pinctrl property itself
188 : * @return number of phandles in the property with that index
189 : */
190 1 : #define DT_NUM_PINCTRLS_BY_IDX(node_id, pc_idx) \
191 : DT_CAT4(node_id, _P_pinctrl_, pc_idx, _LEN)
192 :
193 : /**
194 : * @brief Like DT_NUM_PINCTRLS_BY_IDX(), but by name instead
195 : *
196 : * Example devicetree fragment:
197 : *
198 : * n: node {
199 : * pinctrl-0 = <&foo &bar>;
200 : * pinctrl-1 = <&baz>
201 : * pinctrl-names = "default", "sleep";
202 : * };
203 : *
204 : * Example usage:
205 : *
206 : * DT_NUM_PINCTRLS_BY_NAME(DT_NODELABEL(n), default) // 2
207 : * DT_NUM_PINCTRLS_BY_NAME(DT_NODELABEL(n), sleep) // 1
208 : *
209 : * @param node_id node identifier with a pinctrl property
210 : * @param name lowercase-and-underscores name name of the pinctrl property
211 : * @return number of phandles in the property with that name
212 : */
213 1 : #define DT_NUM_PINCTRLS_BY_NAME(node_id, name) \
214 : DT_NUM_PINCTRLS_BY_IDX(node_id, DT_PINCTRL_NAME_TO_IDX(node_id, name))
215 :
216 : /**
217 : * @brief Get the number of pinctrl properties in a node
218 : *
219 : * This expands to 0 if there are no pinctrl-i properties.
220 : * Otherwise, it expands to the number of such properties.
221 : *
222 : * Example devicetree fragment:
223 : *
224 : * n1: node-1 {
225 : * pinctrl-0 = <...>;
226 : * pinctrl-1 = <...>;
227 : * };
228 : *
229 : * n2: node-2 {
230 : * };
231 : *
232 : * Example usage:
233 : *
234 : * DT_NUM_PINCTRL_STATES(DT_NODELABEL(n1)) // 2
235 : * DT_NUM_PINCTRL_STATES(DT_NODELABEL(n2)) // 0
236 : *
237 : * @param node_id node identifier; may or may not have any pinctrl properties
238 : * @return number of pinctrl properties in the node
239 : */
240 1 : #define DT_NUM_PINCTRL_STATES(node_id) DT_CAT(node_id, _PINCTRL_NUM)
241 :
242 : /**
243 : * @brief Test if a node has a pinctrl property with an index
244 : *
245 : * This expands to 1 if the pinctrl-'idx' property exists.
246 : * Otherwise, it expands to 0.
247 : *
248 : * Example devicetree fragment:
249 : *
250 : * n1: node-1 {
251 : * pinctrl-0 = <...>;
252 : * pinctrl-1 = <...>;
253 : * };
254 : *
255 : * n2: node-2 {
256 : * };
257 : *
258 : * Example usage:
259 : *
260 : * DT_PINCTRL_HAS_IDX(DT_NODELABEL(n1), 0) // 1
261 : * DT_PINCTRL_HAS_IDX(DT_NODELABEL(n1), 1) // 1
262 : * DT_PINCTRL_HAS_IDX(DT_NODELABEL(n1), 2) // 0
263 : * DT_PINCTRL_HAS_IDX(DT_NODELABEL(n2), 0) // 0
264 : *
265 : * @param node_id node identifier; may or may not have any pinctrl properties
266 : * @param pc_idx index of a pinctrl property whose existence to check
267 : * @return 1 if the property exists, 0 otherwise
268 : */
269 1 : #define DT_PINCTRL_HAS_IDX(node_id, pc_idx) \
270 : IS_ENABLED(DT_CAT4(node_id, _PINCTRL_IDX_, pc_idx, _EXISTS))
271 :
272 : /**
273 : * @brief Test if a node has a pinctrl property with a name
274 : *
275 : * This expands to 1 if the named pinctrl property exists.
276 : * Otherwise, it expands to 0.
277 : *
278 : * Example devicetree fragment:
279 : *
280 : * n1: node-1 {
281 : * pinctrl-0 = <...>;
282 : * pinctrl-names = "default";
283 : * };
284 : *
285 : * n2: node-2 {
286 : * };
287 : *
288 : * Example usage:
289 : *
290 : * DT_PINCTRL_HAS_NAME(DT_NODELABEL(n1), default) // 1
291 : * DT_PINCTRL_HAS_NAME(DT_NODELABEL(n1), sleep) // 0
292 : * DT_PINCTRL_HAS_NAME(DT_NODELABEL(n2), default) // 0
293 : *
294 : * @param node_id node identifier; may or may not have any pinctrl properties
295 : * @param name lowercase-and-underscores pinctrl property name to check
296 : * @return 1 if the property exists, 0 otherwise
297 : */
298 1 : #define DT_PINCTRL_HAS_NAME(node_id, name) \
299 : IS_ENABLED(DT_CAT4(node_id, _PINCTRL_NAME_, name, _EXISTS))
300 :
301 : /**
302 : * @brief Get a node identifier for a phandle in a pinctrl property by index
303 : * for a DT_DRV_COMPAT instance
304 : *
305 : * This is equivalent to DT_PINCTRL_BY_IDX(DT_DRV_INST(inst), pc_idx, idx).
306 : *
307 : * @param inst instance number
308 : * @param pc_idx index of the pinctrl property itself
309 : * @param idx index into the value of the pinctrl property
310 : * @return node identifier for the phandle at index 'idx' in 'pinctrl-'pc_idx''
311 : */
312 1 : #define DT_INST_PINCTRL_BY_IDX(inst, pc_idx, idx) \
313 : DT_PINCTRL_BY_IDX(DT_DRV_INST(inst), pc_idx, idx)
314 :
315 : /**
316 : * @brief Get a node identifier from a pinctrl-0 property for a
317 : * DT_DRV_COMPAT instance
318 : *
319 : * This is equivalent to:
320 : *
321 : * DT_PINCTRL_BY_IDX(DT_DRV_INST(inst), 0, idx)
322 : *
323 : * It is provided for convenience since pinctrl-0 is commonly used.
324 : *
325 : * @param inst instance number
326 : * @param idx index into the pinctrl-0 property
327 : * @return node identifier for the phandle at index idx in the pinctrl-0
328 : * property of that instance
329 : */
330 1 : #define DT_INST_PINCTRL_0(inst, idx) \
331 : DT_PINCTRL_BY_IDX(DT_DRV_INST(inst), 0, idx)
332 :
333 : /**
334 : * @brief Get a node identifier for a phandle inside a pinctrl node
335 : * for a DT_DRV_COMPAT instance
336 : *
337 : * This is equivalent to DT_PINCTRL_BY_NAME(DT_DRV_INST(inst), name, idx).
338 : *
339 : * @param inst instance number
340 : * @param name lowercase-and-underscores pinctrl property name
341 : * @param idx index into the value of the named pinctrl property
342 : * @return node identifier for the phandle at that index in the pinctrl
343 : * property
344 : */
345 1 : #define DT_INST_PINCTRL_BY_NAME(inst, name, idx) \
346 : DT_PINCTRL_BY_NAME(DT_DRV_INST(inst), name, idx)
347 :
348 : /**
349 : * @brief Convert a pinctrl name to its corresponding index
350 : * for a DT_DRV_COMPAT instance
351 : *
352 : * This is equivalent to DT_PINCTRL_NAME_TO_IDX(DT_DRV_INST(inst),
353 : * name).
354 : *
355 : * @param inst instance number
356 : * @param name lowercase-and-underscores name of the pinctrl whose index to get
357 : * @return integer literal for the index of the pinctrl property with that name
358 : */
359 1 : #define DT_INST_PINCTRL_NAME_TO_IDX(inst, name) \
360 : DT_PINCTRL_NAME_TO_IDX(DT_DRV_INST(inst), name)
361 :
362 : /**
363 : * @brief Convert a pinctrl index to its name as an uppercased token
364 : *
365 : * This is equivalent to
366 : * DT_PINCTRL_IDX_TO_NAME_TOKEN(DT_DRV_INST(inst), pc_idx).
367 : *
368 : * @param inst instance number
369 : * @param pc_idx index of the pinctrl property itself
370 : * @return name of the pin control property as a token
371 : */
372 1 : #define DT_INST_PINCTRL_IDX_TO_NAME_TOKEN(inst, pc_idx) \
373 : DT_PINCTRL_IDX_TO_NAME_TOKEN(DT_DRV_INST(inst), pc_idx)
374 :
375 : /**
376 : * @brief Convert a pinctrl index to its name as an uppercased token
377 : *
378 : * This is equivalent to
379 : * DT_PINCTRL_IDX_TO_NAME_UPPER_TOKEN(DT_DRV_INST(inst), idx).
380 : *
381 : * @param inst instance number
382 : * @param pc_idx index of the pinctrl property itself
383 : * @return name of the pin control property as an uppercase token
384 : */
385 1 : #define DT_INST_PINCTRL_IDX_TO_NAME_UPPER_TOKEN(inst, pc_idx) \
386 : DT_PINCTRL_IDX_TO_NAME_UPPER_TOKEN(DT_DRV_INST(inst), pc_idx)
387 :
388 : /**
389 : * @brief Get the number of phandles in a pinctrl property
390 : * for a DT_DRV_COMPAT instance
391 : *
392 : * This is equivalent to DT_NUM_PINCTRLS_BY_IDX(DT_DRV_INST(inst),
393 : * pc_idx).
394 : *
395 : * @param inst instance number
396 : * @param pc_idx index of the pinctrl property itself
397 : * @return number of phandles in the property with that index
398 : */
399 1 : #define DT_INST_NUM_PINCTRLS_BY_IDX(inst, pc_idx) \
400 : DT_NUM_PINCTRLS_BY_IDX(DT_DRV_INST(inst), pc_idx)
401 :
402 : /**
403 : * @brief Like DT_INST_NUM_PINCTRLS_BY_IDX(), but by name instead
404 : *
405 : * This is equivalent to DT_NUM_PINCTRLS_BY_NAME(DT_DRV_INST(inst),
406 : * name).
407 : *
408 : * @param inst instance number
409 : * @param name lowercase-and-underscores name of the pinctrl property
410 : * @return number of phandles in the property with that name
411 : */
412 1 : #define DT_INST_NUM_PINCTRLS_BY_NAME(inst, name) \
413 : DT_NUM_PINCTRLS_BY_NAME(DT_DRV_INST(inst), name)
414 :
415 : /**
416 : * @brief Get the number of pinctrl properties in a DT_DRV_COMPAT instance
417 : *
418 : * This is equivalent to DT_NUM_PINCTRL_STATES(DT_DRV_INST(inst)).
419 : *
420 : * @param inst instance number
421 : * @return number of pinctrl properties in the instance
422 : */
423 1 : #define DT_INST_NUM_PINCTRL_STATES(inst) \
424 : DT_NUM_PINCTRL_STATES(DT_DRV_INST(inst))
425 :
426 : /**
427 : * @brief Test if a DT_DRV_COMPAT instance has a pinctrl property
428 : * with an index
429 : *
430 : * This is equivalent to DT_PINCTRL_HAS_IDX(DT_DRV_INST(inst), pc_idx).
431 : *
432 : * @param inst instance number
433 : * @param pc_idx index of a pinctrl property whose existence to check
434 : * @return 1 if the property exists, 0 otherwise
435 : */
436 1 : #define DT_INST_PINCTRL_HAS_IDX(inst, pc_idx) \
437 : DT_PINCTRL_HAS_IDX(DT_DRV_INST(inst), pc_idx)
438 :
439 : /**
440 : * @brief Test if a DT_DRV_COMPAT instance has a pinctrl property with a name
441 : *
442 : * This is equivalent to DT_PINCTRL_HAS_NAME(DT_DRV_INST(inst), name).
443 : *
444 : * @param inst instance number
445 : * @param name lowercase-and-underscores pinctrl property name to check
446 : * @return 1 if the property exists, 0 otherwise
447 : */
448 1 : #define DT_INST_PINCTRL_HAS_NAME(inst, name) \
449 : DT_PINCTRL_HAS_NAME(DT_DRV_INST(inst), name)
450 :
451 :
452 : /**
453 : * @}
454 : */
455 :
456 : #endif /* ZEPHYR_INCLUDE_DEVICETREE_PINCTRL_H_ */
|
