Line data Source code
1 1 : /**
2 : * @file
3 : * @brief GPIO Devicetree macro public API header file.
4 : */
5 :
6 : /*
7 : * Copyright (c) 2020, Linaro Ltd.
8 : * Copyright (c) 2020 Nordic Semiconductor
9 : *
10 : * SPDX-License-Identifier: Apache-2.0
11 : */
12 :
13 : #ifndef ZEPHYR_INCLUDE_DEVICETREE_GPIO_H_
14 : #define ZEPHYR_INCLUDE_DEVICETREE_GPIO_H_
15 :
16 : #ifdef __cplusplus
17 : extern "C" {
18 : #endif
19 :
20 : /**
21 : * @defgroup devicetree-gpio Devicetree GPIO API
22 : * @ingroup devicetree
23 : * @ingroup gpio_interface
24 : * @{
25 : *
26 : * @defgroup devicetree-gpio-pin-headers GPIO pin headers
27 : * @brief Constants for pins exposed on common GPIO pin headers
28 : * @{
29 : * @}
30 : */
31 :
32 : /**
33 : * @brief Get the node identifier for the controller phandle from a
34 : * gpio phandle-array property at an index
35 : *
36 : * Example devicetree fragment:
37 : *
38 : * gpio1: gpio@... { };
39 : *
40 : * gpio2: gpio@... { };
41 : *
42 : * n: node {
43 : * gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
44 : * <&gpio2 30 GPIO_ACTIVE_HIGH>;
45 : * };
46 : *
47 : * Example usage:
48 : *
49 : * DT_GPIO_CTLR_BY_IDX(DT_NODELABEL(n), gpios, 1) // DT_NODELABEL(gpio2)
50 : *
51 : * @param node_id node identifier
52 : * @param gpio_pha lowercase-and-underscores GPIO property with
53 : * type "phandle-array"
54 : * @param idx logical index into "gpio_pha"
55 : * @return the node identifier for the gpio controller referenced at
56 : * index "idx"
57 : * @see DT_PHANDLE_BY_IDX()
58 : */
59 1 : #define DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, idx) \
60 : DT_PHANDLE_BY_IDX(node_id, gpio_pha, idx)
61 :
62 : /**
63 : * @brief Equivalent to DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, 0)
64 : * @param node_id node identifier
65 : * @param gpio_pha lowercase-and-underscores GPIO property with
66 : * type "phandle-array"
67 : * @return a node identifier for the gpio controller at index 0
68 : * in "gpio_pha"
69 : * @see DT_GPIO_CTLR_BY_IDX()
70 : */
71 1 : #define DT_GPIO_CTLR(node_id, gpio_pha) \
72 : DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, 0)
73 :
74 : /**
75 : * @brief Get a GPIO specifier's pin cell at an index
76 : *
77 : * This macro only works for GPIO specifiers with cells named "pin".
78 : * Refer to the node's binding to check if necessary.
79 : *
80 : * Example devicetree fragment:
81 : *
82 : * gpio1: gpio@... {
83 : * compatible = "vnd,gpio";
84 : * #gpio-cells = <2>;
85 : * };
86 : *
87 : * gpio2: gpio@... {
88 : * compatible = "vnd,gpio";
89 : * #gpio-cells = <2>;
90 : * };
91 : *
92 : * n: node {
93 : * gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
94 : * <&gpio2 30 GPIO_ACTIVE_HIGH>;
95 : * };
96 : *
97 : * Bindings fragment for the vnd,gpio compatible:
98 : *
99 : * gpio-cells:
100 : * - pin
101 : * - flags
102 : *
103 : * Example usage:
104 : *
105 : * DT_GPIO_PIN_BY_IDX(DT_NODELABEL(n), gpios, 0) // 10
106 : * DT_GPIO_PIN_BY_IDX(DT_NODELABEL(n), gpios, 1) // 30
107 : *
108 : * @param node_id node identifier
109 : * @param gpio_pha lowercase-and-underscores GPIO property with
110 : * type "phandle-array"
111 : * @param idx logical index into "gpio_pha"
112 : * @return the pin cell value at index "idx"
113 : * @see DT_PHA_BY_IDX()
114 : */
115 1 : #define DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, idx) \
116 : DT_PHA_BY_IDX(node_id, gpio_pha, idx, pin)
117 :
118 : /**
119 : * @brief Equivalent to DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, 0)
120 : * @param node_id node identifier
121 : * @param gpio_pha lowercase-and-underscores GPIO property with
122 : * type "phandle-array"
123 : * @return the pin cell value at index 0
124 : * @see DT_GPIO_PIN_BY_IDX()
125 : */
126 1 : #define DT_GPIO_PIN(node_id, gpio_pha) \
127 : DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, 0)
128 :
129 : /**
130 : * @brief Get a GPIO specifier's flags cell at an index
131 : *
132 : * This macro expects GPIO specifiers with cells named "flags".
133 : * If there is no "flags" cell in the GPIO specifier, zero is returned.
134 : * Refer to the node's binding to check specifier cell names if necessary.
135 : *
136 : * Example devicetree fragment:
137 : *
138 : * gpio1: gpio@... {
139 : * compatible = "vnd,gpio";
140 : * #gpio-cells = <2>;
141 : * };
142 : *
143 : * gpio2: gpio@... {
144 : * compatible = "vnd,gpio";
145 : * #gpio-cells = <2>;
146 : * };
147 : *
148 : * n: node {
149 : * gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
150 : * <&gpio2 30 GPIO_ACTIVE_HIGH>;
151 : * };
152 : *
153 : * Bindings fragment for the vnd,gpio compatible:
154 : *
155 : * gpio-cells:
156 : * - pin
157 : * - flags
158 : *
159 : * Example usage:
160 : *
161 : * DT_GPIO_FLAGS_BY_IDX(DT_NODELABEL(n), gpios, 0) // GPIO_ACTIVE_LOW
162 : * DT_GPIO_FLAGS_BY_IDX(DT_NODELABEL(n), gpios, 1) // GPIO_ACTIVE_HIGH
163 : *
164 : * @param node_id node identifier
165 : * @param gpio_pha lowercase-and-underscores GPIO property with
166 : * type "phandle-array"
167 : * @param idx logical index into "gpio_pha"
168 : * @return the flags cell value at index "idx", or zero if there is none
169 : * @see DT_PHA_BY_IDX()
170 : */
171 1 : #define DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, idx) \
172 : DT_PHA_BY_IDX_OR(node_id, gpio_pha, idx, flags, 0)
173 :
174 : /**
175 : * @brief Equivalent to DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, 0)
176 : * @param node_id node identifier
177 : * @param gpio_pha lowercase-and-underscores GPIO property with
178 : * type "phandle-array"
179 : * @return the flags cell value at index 0, or zero if there is none
180 : * @see DT_GPIO_FLAGS_BY_IDX()
181 : */
182 1 : #define DT_GPIO_FLAGS(node_id, gpio_pha) \
183 : DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, 0)
184 :
185 : /**
186 : * @brief Get the number of GPIO hogs in a node
187 : *
188 : * This expands to the number of hogged GPIOs, or zero if there are none.
189 : *
190 : * Example devicetree fragment:
191 : *
192 : * gpio1: gpio@... {
193 : * compatible = "vnd,gpio";
194 : * #gpio-cells = <2>;
195 : *
196 : * n1: node-1 {
197 : * gpio-hog;
198 : * gpios = <0 GPIO_ACTIVE_HIGH>, <1 GPIO_ACTIVE_LOW>;
199 : * output-high;
200 : * };
201 : *
202 : * n2: node-2 {
203 : * gpio-hog;
204 : * gpios = <3 GPIO_ACTIVE_HIGH>;
205 : * output-low;
206 : * };
207 : * };
208 : *
209 : * Bindings fragment for the vnd,gpio compatible:
210 : *
211 : * gpio-cells:
212 : * - pin
213 : * - flags
214 : *
215 : * Example usage:
216 : *
217 : * DT_NUM_GPIO_HOGS(DT_NODELABEL(n1)) // 2
218 : * DT_NUM_GPIO_HOGS(DT_NODELABEL(n2)) // 1
219 : *
220 : * @param node_id node identifier; may or may not be a GPIO hog node.
221 : * @return number of hogged GPIOs in the node
222 : */
223 1 : #define DT_NUM_GPIO_HOGS(node_id) \
224 : COND_CODE_1(IS_ENABLED(DT_CAT(node_id, _GPIO_HOGS_EXISTS)), \
225 : (DT_CAT(node_id, _GPIO_HOGS_NUM)), (0))
226 :
227 : /**
228 : * @brief Get a GPIO hog specifier's pin cell at an index
229 : *
230 : * This macro only works for GPIO specifiers with cells named "pin".
231 : * Refer to the node's binding to check if necessary.
232 : *
233 : * Example devicetree fragment:
234 : *
235 : * gpio1: gpio@... {
236 : * compatible = "vnd,gpio";
237 : * #gpio-cells = <2>;
238 : *
239 : * n1: node-1 {
240 : * gpio-hog;
241 : * gpios = <0 GPIO_ACTIVE_HIGH>, <1 GPIO_ACTIVE_LOW>;
242 : * output-high;
243 : * };
244 : *
245 : * n2: node-2 {
246 : * gpio-hog;
247 : * gpios = <3 GPIO_ACTIVE_HIGH>;
248 : * output-low;
249 : * };
250 : * };
251 : *
252 : * Bindings fragment for the vnd,gpio compatible:
253 : *
254 : * gpio-cells:
255 : * - pin
256 : * - flags
257 : *
258 : * Example usage:
259 : *
260 : * DT_GPIO_HOG_PIN_BY_IDX(DT_NODELABEL(n1), 0) // 0
261 : * DT_GPIO_HOG_PIN_BY_IDX(DT_NODELABEL(n1), 1) // 1
262 : * DT_GPIO_HOG_PIN_BY_IDX(DT_NODELABEL(n2), 0) // 3
263 : *
264 : * @param node_id node identifier
265 : * @param idx logical index into "gpios"
266 : * @return the pin cell value at index "idx"
267 : */
268 1 : #define DT_GPIO_HOG_PIN_BY_IDX(node_id, idx) \
269 : DT_CAT4(node_id, _GPIO_HOGS_IDX_, idx, _VAL_pin)
270 :
271 : /**
272 : * @brief Get a GPIO hog specifier's flags cell at an index
273 : *
274 : * This macro expects GPIO specifiers with cells named "flags".
275 : * If there is no "flags" cell in the GPIO specifier, zero is returned.
276 : * Refer to the node's binding to check specifier cell names if necessary.
277 : *
278 : * Example devicetree fragment:
279 : *
280 : * gpio1: gpio@... {
281 : * compatible = "vnd,gpio";
282 : * #gpio-cells = <2>;
283 : *
284 : * n1: node-1 {
285 : * gpio-hog;
286 : * gpios = <0 GPIO_ACTIVE_HIGH>, <1 GPIO_ACTIVE_LOW>;
287 : * output-high;
288 : * };
289 : *
290 : * n2: node-2 {
291 : * gpio-hog;
292 : * gpios = <3 GPIO_ACTIVE_HIGH>;
293 : * output-low;
294 : * };
295 : * };
296 : *
297 : * Bindings fragment for the vnd,gpio compatible:
298 : *
299 : * gpio-cells:
300 : * - pin
301 : * - flags
302 : *
303 : * Example usage:
304 : *
305 : * DT_GPIO_HOG_FLAGS_BY_IDX(DT_NODELABEL(n1), 0) // GPIO_ACTIVE_HIGH
306 : * DT_GPIO_HOG_FLAGS_BY_IDX(DT_NODELABEL(n1), 1) // GPIO_ACTIVE_LOW
307 : * DT_GPIO_HOG_FLAGS_BY_IDX(DT_NODELABEL(n2), 0) // GPIO_ACTIVE_HIGH
308 : *
309 : * @param node_id node identifier
310 : * @param idx logical index into "gpios"
311 : * @return the flags cell value at index "idx", or zero if there is none
312 : */
313 1 : #define DT_GPIO_HOG_FLAGS_BY_IDX(node_id, idx) \
314 : COND_CODE_1(IS_ENABLED(DT_CAT4(node_id, _GPIO_HOGS_IDX_, idx, _VAL_flags_EXISTS)), \
315 : (DT_CAT4(node_id, _GPIO_HOGS_IDX_, idx, _VAL_flags)), (0))
316 :
317 : /**
318 : * @brief Get a DT_DRV_COMPAT instance's GPIO specifier's pin cell value
319 : * at an index
320 : * @param inst DT_DRV_COMPAT instance number
321 : * @param gpio_pha lowercase-and-underscores GPIO property with
322 : * type "phandle-array"
323 : * @param idx logical index into "gpio_pha"
324 : * @return the pin cell value at index "idx"
325 : * @see DT_GPIO_PIN_BY_IDX()
326 : */
327 1 : #define DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, idx) \
328 : DT_GPIO_PIN_BY_IDX(DT_DRV_INST(inst), gpio_pha, idx)
329 :
330 : /**
331 : * @brief Equivalent to DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, 0)
332 : * @param inst DT_DRV_COMPAT instance number
333 : * @param gpio_pha lowercase-and-underscores GPIO property with
334 : * type "phandle-array"
335 : * @return the pin cell value at index 0
336 : * @see DT_INST_GPIO_PIN_BY_IDX()
337 : */
338 1 : #define DT_INST_GPIO_PIN(inst, gpio_pha) \
339 : DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, 0)
340 :
341 : /**
342 : * @brief Get a DT_DRV_COMPAT instance's GPIO specifier's flags cell
343 : * at an index
344 : * @param inst DT_DRV_COMPAT instance number
345 : * @param gpio_pha lowercase-and-underscores GPIO property with
346 : * type "phandle-array"
347 : * @param idx logical index into "gpio_pha"
348 : * @return the flags cell value at index "idx", or zero if there is none
349 : * @see DT_GPIO_FLAGS_BY_IDX()
350 : */
351 1 : #define DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, idx) \
352 : DT_GPIO_FLAGS_BY_IDX(DT_DRV_INST(inst), gpio_pha, idx)
353 :
354 : /**
355 : * @brief Equivalent to DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, 0)
356 : * @param inst DT_DRV_COMPAT instance number
357 : * @param gpio_pha lowercase-and-underscores GPIO property with
358 : * type "phandle-array"
359 : * @return the flags cell value at index 0, or zero if there is none
360 : * @see DT_INST_GPIO_FLAGS_BY_IDX()
361 : */
362 1 : #define DT_INST_GPIO_FLAGS(inst, gpio_pha) \
363 : DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, 0)
364 :
365 : /**
366 : * @}
367 : */
368 :
369 : #ifdef __cplusplus
370 : }
371 : #endif
372 :
373 : #endif /* ZEPHYR_INCLUDE_DEVICETREE_GPIO_H_ */
|