Line data Source code
1 1 : /*
2 : * Copyright (c) 2021 Nordic Semiconductor ASA
3 : * SPDX-License-Identifier: Apache-2.0
4 : */
5 :
6 : /**
7 : * @file
8 : * @brief Main header file for pin control driver API.
9 : * @ingroup pinctrl_interface
10 : */
11 :
12 : #ifndef ZEPHYR_INCLUDE_DRIVERS_PINCTRL_H_
13 : #define ZEPHYR_INCLUDE_DRIVERS_PINCTRL_H_
14 :
15 : /**
16 : * @brief Interfaces for pin controllers.
17 : * @defgroup pinctrl_interface Pin Control
18 : * @since 3.0
19 : * @version 0.1.0
20 : * @ingroup io_interfaces
21 : * @{
22 : */
23 :
24 : #include <errno.h>
25 :
26 : #include <zephyr/device.h>
27 : #include <zephyr/devicetree.h>
28 : #include <zephyr/devicetree/pinctrl.h>
29 : #include <pinctrl_soc.h>
30 : #include <zephyr/sys/util.h>
31 :
32 : #ifdef __cplusplus
33 : extern "C" {
34 : #endif
35 :
36 : /**
37 : * @name Pin control states
38 : * @anchor PINCTRL_STATES
39 : * @{
40 : */
41 :
42 : /** Default state (state used when the device is in operational state). */
43 1 : #define PINCTRL_STATE_DEFAULT 0U
44 : /** Sleep state (state used when the device is in low power mode). */
45 1 : #define PINCTRL_STATE_SLEEP 1U
46 :
47 : /** This and higher values refer to custom private states. */
48 1 : #define PINCTRL_STATE_PRIV_START 2U
49 :
50 : /** @} */
51 :
52 : /** Pin control state configuration. */
53 1 : struct pinctrl_state {
54 : /** Pin configurations. */
55 1 : const pinctrl_soc_pin_t *pins;
56 : /** Number of pin configurations. */
57 1 : uint8_t pin_cnt;
58 : /** State identifier (see @ref PINCTRL_STATES). */
59 1 : uint8_t id;
60 : };
61 :
62 : /** Pin controller configuration for a given device. */
63 1 : struct pinctrl_dev_config {
64 : #if defined(CONFIG_PINCTRL_STORE_REG) || defined(__DOXYGEN__)
65 : /**
66 : * Device address (only available if @kconfig{CONFIG_PINCTRL_STORE_REG}
67 : * is enabled).
68 : */
69 1 : uintptr_t reg;
70 : #endif /* defined(CONFIG_PINCTRL_STORE_REG) || defined(__DOXYGEN__) */
71 : /** List of state configurations. */
72 1 : const struct pinctrl_state *states;
73 : /** Number of state configurations. */
74 1 : uint8_t state_cnt;
75 : };
76 :
77 : /** Utility macro to indicate no register is used. */
78 1 : #define PINCTRL_REG_NONE 0U
79 :
80 : /** @cond INTERNAL_HIDDEN */
81 :
82 : #if !defined(CONFIG_PINCTRL_KEEP_SLEEP_STATE)
83 : /** Out of power management configurations, ignore "sleep" state. */
84 : #define PINCTRL_SKIP_SLEEP 1
85 : #endif
86 :
87 : /**
88 : * @brief Obtain the state identifier for the given node and state index.
89 : *
90 : * @param state_idx State index.
91 : * @param node_id Node identifier.
92 : */
93 : #define Z_PINCTRL_STATE_ID(state_idx, node_id) \
94 : _CONCAT(PINCTRL_STATE_, \
95 : DT_PINCTRL_IDX_TO_NAME_UPPER_TOKEN(node_id, state_idx))
96 :
97 : /**
98 : * @brief Obtain the variable name storing pinctrl config for the given DT node
99 : * identifier.
100 : *
101 : * @param node_id Node identifier.
102 : */
103 : #define Z_PINCTRL_DEV_CONFIG_NAME(node_id) \
104 : _CONCAT(__pinctrl_dev_config, DEVICE_DT_NAME_GET(node_id))
105 :
106 : /**
107 : * @brief Obtain the variable name storing pinctrl states for the given DT node
108 : * identifier.
109 : *
110 : * @param node_id Node identifier.
111 : */
112 : #define Z_PINCTRL_STATES_NAME(node_id) \
113 : _CONCAT(__pinctrl_states, DEVICE_DT_NAME_GET(node_id))
114 :
115 : /**
116 : * @brief Obtain the variable name storing pinctrl pins for the given DT node
117 : * identifier and state index.
118 : *
119 : * @param state_idx State index.
120 : * @param node_id Node identifier.
121 : */
122 : #define Z_PINCTRL_STATE_PINS_NAME(state_idx, node_id) \
123 : _CONCAT(__pinctrl_state_pins_ ## state_idx, DEVICE_DT_NAME_GET(node_id))
124 :
125 : /**
126 : * @brief Utility macro to check if given state has to be skipped.
127 : *
128 : * If a certain state has to be skipped, a macro named PINCTRL_SKIP_<STATE>
129 : * can be defined evaluating to 1. This can be useful, for example, to
130 : * automatically ignore the sleep state if no device power management is
131 : * enabled.
132 : *
133 : * @param state_idx State index.
134 : * @param node_id Node identifier.
135 : */
136 : #define Z_PINCTRL_SKIP_STATE(state_idx, node_id) \
137 : _CONCAT(PINCTRL_SKIP_, \
138 : DT_PINCTRL_IDX_TO_NAME_UPPER_TOKEN(node_id, state_idx))
139 :
140 : /**
141 : * @brief Helper macro to define pins for a given pin control state.
142 : *
143 : * @param state_idx State index.
144 : * @param node_id Node identifier.
145 : */
146 : #define Z_PINCTRL_STATE_PINS_DEFINE(state_idx, node_id) \
147 : COND_CODE_1(Z_PINCTRL_SKIP_STATE(state_idx, node_id), (), \
148 : (static const pinctrl_soc_pin_t \
149 : Z_PINCTRL_STATE_PINS_NAME(state_idx, node_id)[] = \
150 : Z_PINCTRL_STATE_PINS_INIT(node_id, pinctrl_ ## state_idx)))
151 :
152 : /**
153 : * @brief Helper macro to initialize a pin control state.
154 : *
155 : * @param state_idx State index.
156 : * @param node_id Node identifier.
157 : */
158 : #define Z_PINCTRL_STATE_INIT(state_idx, node_id) \
159 : COND_CODE_1(Z_PINCTRL_SKIP_STATE(state_idx, node_id), (), \
160 : ({ \
161 : .pins = Z_PINCTRL_STATE_PINS_NAME(state_idx, node_id), \
162 : .pin_cnt = ARRAY_SIZE(Z_PINCTRL_STATE_PINS_NAME(state_idx, \
163 : node_id)), \
164 : .id = Z_PINCTRL_STATE_ID(state_idx, node_id) \
165 : }))
166 :
167 : /**
168 : * @brief Define all the states for the given node identifier.
169 : *
170 : * @param node_id Node identifier.
171 : */
172 : #define Z_PINCTRL_STATES_DEFINE(node_id) \
173 : static const struct pinctrl_state \
174 : Z_PINCTRL_STATES_NAME(node_id)[] = { \
175 : LISTIFY(DT_NUM_PINCTRL_STATES(node_id), \
176 : Z_PINCTRL_STATE_INIT, (,), node_id) \
177 : };
178 :
179 : #ifdef CONFIG_PINCTRL_STORE_REG
180 : /**
181 : * @brief Helper macro to initialize pin control config.
182 : *
183 : * @param node_id Node identifier.
184 : */
185 : #define Z_PINCTRL_DEV_CONFIG_INIT(node_id) \
186 : { \
187 : .reg = DT_REG_ADDR(node_id), \
188 : .states = Z_PINCTRL_STATES_NAME(node_id), \
189 : .state_cnt = ARRAY_SIZE(Z_PINCTRL_STATES_NAME(node_id)), \
190 : }
191 : #else
192 : #define Z_PINCTRL_DEV_CONFIG_INIT(node_id) \
193 : { \
194 : .states = Z_PINCTRL_STATES_NAME(node_id), \
195 : .state_cnt = ARRAY_SIZE(Z_PINCTRL_STATES_NAME(node_id)), \
196 : }
197 : #endif
198 :
199 : #ifdef CONFIG_PINCTRL_NON_STATIC
200 : #define Z_PINCTRL_DEV_CONFIG_STATIC
201 : #else
202 : #define Z_PINCTRL_DEV_CONFIG_STATIC static
203 : #endif
204 :
205 : #ifdef CONFIG_PINCTRL_DYNAMIC
206 : #define Z_PINCTRL_DEV_CONFIG_CONST
207 : #else
208 : #define Z_PINCTRL_DEV_CONFIG_CONST const
209 : #endif
210 :
211 : /** @endcond */
212 :
213 : #if defined(CONFIG_PINCTRL_NON_STATIC) || defined(__DOXYGEN__)
214 : /**
215 : * @brief Declare pin control configuration for a given node identifier.
216 : *
217 : * This macro should be used by tests or applications using runtime pin control
218 : * to declare the pin control configuration for a device.
219 : * #PINCTRL_DT_DEV_CONFIG_GET can later be used to obtain a reference to such
220 : * configuration.
221 : *
222 : * Only available if @kconfig{CONFIG_PINCTRL_NON_STATIC} is selected.
223 : *
224 : * @param node_id Node identifier.
225 : */
226 1 : #define PINCTRL_DT_DEV_CONFIG_DECLARE(node_id) \
227 : extern Z_PINCTRL_DEV_CONFIG_CONST struct pinctrl_dev_config \
228 : Z_PINCTRL_DEV_CONFIG_NAME(node_id)
229 : #endif /* defined(CONFIG_PINCTRL_NON_STATIC) || defined(__DOXYGEN__) */
230 :
231 : /**
232 : * @brief Define all pin control information for the given node identifier.
233 : *
234 : * This helper macro should be called together with device definition. It
235 : * defines and initializes the pin control configuration for the device
236 : * represented by node_id. Each pin control state (pinctrl-0, ..., pinctrl-N) is
237 : * also defined and initialized. Note that states marked to be skipped will not
238 : * be defined (refer to Z_PINCTRL_SKIP_STATE for more details).
239 : *
240 : * @param node_id Node identifier.
241 : */
242 1 : #define PINCTRL_DT_DEFINE(node_id) \
243 : LISTIFY(DT_NUM_PINCTRL_STATES(node_id), \
244 : Z_PINCTRL_STATE_PINS_DEFINE, (;), node_id); \
245 : Z_PINCTRL_STATES_DEFINE(node_id) \
246 : Z_PINCTRL_DEV_CONFIG_STATIC Z_PINCTRL_DEV_CONFIG_CONST \
247 : struct pinctrl_dev_config Z_PINCTRL_DEV_CONFIG_NAME(node_id) = \
248 : Z_PINCTRL_DEV_CONFIG_INIT(node_id)
249 :
250 : /**
251 : * @brief Define all pin control information for the given compatible index.
252 : *
253 : * @param inst Instance number.
254 : *
255 : * @see #PINCTRL_DT_DEFINE
256 : */
257 1 : #define PINCTRL_DT_INST_DEFINE(inst) PINCTRL_DT_DEFINE(DT_DRV_INST(inst))
258 :
259 : /**
260 : * @brief Obtain a reference to the pin control configuration given a node
261 : * identifier.
262 : *
263 : * @param node_id Node identifier.
264 : */
265 1 : #define PINCTRL_DT_DEV_CONFIG_GET(node_id) &Z_PINCTRL_DEV_CONFIG_NAME(node_id)
266 :
267 : /**
268 : * @brief Obtain a reference to the pin control configuration given current
269 : * compatible instance number.
270 : *
271 : * @param inst Instance number.
272 : *
273 : * @see #PINCTRL_DT_DEV_CONFIG_GET
274 : */
275 1 : #define PINCTRL_DT_INST_DEV_CONFIG_GET(inst) \
276 : PINCTRL_DT_DEV_CONFIG_GET(DT_DRV_INST(inst))
277 :
278 : /**
279 : * @brief Find the state configuration for the given state id.
280 : *
281 : * @param config Pin controller configuration.
282 : * @param id Pin controller state id (see @ref PINCTRL_STATES).
283 : * @param state Found state.
284 : *
285 : * @retval 0 If state has been found.
286 : * @retval -ENOENT If the state has not been found.
287 : */
288 1 : int pinctrl_lookup_state(const struct pinctrl_dev_config *config, uint8_t id,
289 : const struct pinctrl_state **state);
290 :
291 : /**
292 : * @brief Configure a set of pins.
293 : *
294 : * This function will configure the necessary hardware blocks to make the
295 : * configuration immediately effective.
296 : *
297 : * @warning This function must never be used to configure pins used by an
298 : * instantiated device driver.
299 : *
300 : * @param pins List of pins to be configured.
301 : * @param pin_cnt Number of pins.
302 : * @param reg Device register (optional, use #PINCTRL_REG_NONE if not used).
303 : *
304 : * @retval 0 If succeeded
305 : * @retval -errno Negative errno for other failures.
306 : */
307 1 : int pinctrl_configure_pins(const pinctrl_soc_pin_t *pins, uint8_t pin_cnt,
308 : uintptr_t reg);
309 :
310 : /**
311 : * @brief Apply a state directly from the provided state configuration.
312 : *
313 : * @param config Pin control configuration.
314 : * @param state State.
315 : *
316 : * @retval 0 If succeeded
317 : * @retval -errno Negative errno for other failures.
318 : */
319 1 : static inline int pinctrl_apply_state_direct(
320 : const struct pinctrl_dev_config *config,
321 : const struct pinctrl_state *state)
322 : {
323 : uintptr_t reg;
324 :
325 : #ifdef CONFIG_PINCTRL_STORE_REG
326 : reg = config->reg;
327 : #else
328 : ARG_UNUSED(config);
329 : reg = PINCTRL_REG_NONE;
330 : #endif
331 :
332 : return pinctrl_configure_pins(state->pins, state->pin_cnt, reg);
333 : }
334 :
335 : /**
336 : * @brief Apply a state from the given device configuration.
337 : *
338 : * @param config Pin control configuration.
339 : * @param id Id of the state to be applied (see @ref PINCTRL_STATES).
340 : *
341 : * @retval 0 If succeeded.
342 : * @retval -ENOENT If given state id does not exist.
343 : * @retval -errno Negative errno for other failures.
344 : */
345 1 : static inline int pinctrl_apply_state(const struct pinctrl_dev_config *config,
346 : uint8_t id)
347 : {
348 : int ret;
349 : const struct pinctrl_state *state;
350 :
351 : ret = pinctrl_lookup_state(config, id, &state);
352 : if (ret < 0) {
353 : return ret;
354 : }
355 :
356 : return pinctrl_apply_state_direct(config, state);
357 : }
358 :
359 : #if defined(CONFIG_PINCTRL_DYNAMIC) || defined(__DOXYGEN__)
360 : /**
361 : * @defgroup pinctrl_interface_dynamic Dynamic Pin Control
362 : * @{
363 : */
364 :
365 : /**
366 : * @brief Helper macro to define the pins of a pin control state from
367 : * Devicetree.
368 : *
369 : * The name of the defined state pins variable is the same used by @p prop. This
370 : * macro is expected to be used in conjunction with #PINCTRL_DT_STATE_INIT.
371 : *
372 : * @param node_id Node identifier containing @p prop.
373 : * @param prop Property within @p node_id containing state configuration.
374 : *
375 : * @see #PINCTRL_DT_STATE_INIT
376 : */
377 1 : #define PINCTRL_DT_STATE_PINS_DEFINE(node_id, prop) \
378 : static const pinctrl_soc_pin_t prop ## _pins[] = \
379 : Z_PINCTRL_STATE_PINS_INIT(node_id, prop); \
380 :
381 : /**
382 : * @brief Utility macro to initialize a pin control state.
383 : *
384 : * This macro should be used in conjunction with #PINCTRL_DT_STATE_PINS_DEFINE
385 : * when using dynamic pin control to define an alternative state configuration
386 : * stored in Devicetree.
387 : *
388 : * Example:
389 : *
390 : * @code{.devicetree}
391 : * // board.dts
392 : *
393 : * /{
394 : * zephyr,user {
395 : * // uart0_alt_default node contains alternative pin config
396 : * uart0_alt_default = <&uart0_alt_default>;
397 : * };
398 : * };
399 : * @endcode
400 : *
401 : * @code{.c}
402 : * // application
403 : *
404 : * PINCTRL_DT_STATE_PINS_DEFINE(DT_PATH(zephyr_user), uart0_alt_default);
405 : *
406 : * static const struct pinctrl_state uart0_alt[] = {
407 : * PINCTRL_DT_STATE_INIT(uart0_alt_default, PINCTRL_STATE_DEFAULT)
408 : * };
409 : * @endcode
410 : *
411 : * @param prop Property name in Devicetree containing state configuration.
412 : * @param state State represented by @p prop (see @ref PINCTRL_STATES).
413 : *
414 : * @see #PINCTRL_DT_STATE_PINS_DEFINE
415 : */
416 1 : #define PINCTRL_DT_STATE_INIT(prop, state) \
417 : { \
418 : .pins = prop ## _pins, \
419 : .pin_cnt = ARRAY_SIZE(prop ## _pins), \
420 : .id = state \
421 : }
422 :
423 : /**
424 : * @brief Update states with a new set.
425 : *
426 : * @note In order to guarantee device drivers correct operation the same states
427 : * have to be provided. For example, if @c default and @c sleep are in the
428 : * current list of states, it is expected that the new array of states also
429 : * contains both.
430 : *
431 : * @param config Pin control configuration.
432 : * @param states New states to be set.
433 : * @param state_cnt Number of new states to be set.
434 : *
435 : * @retval -EINVAL If the new configuration does not contain the same states as
436 : * the current active configuration.
437 : * @retval -ENOSYS If the functionality is not available.
438 : * @retval 0 On success.
439 : */
440 1 : int pinctrl_update_states(struct pinctrl_dev_config *config,
441 : const struct pinctrl_state *states,
442 : uint8_t state_cnt);
443 :
444 : /** @} */
445 : #else
446 : static inline int pinctrl_update_states(
447 : struct pinctrl_dev_config *config,
448 : const struct pinctrl_state *states, uint8_t state_cnt)
449 : {
450 : ARG_UNUSED(config);
451 : ARG_UNUSED(states);
452 : ARG_UNUSED(state_cnt);
453 : return -ENOSYS;
454 : }
455 : #endif /* defined(CONFIG_PINCTRL_DYNAMIC) || defined(__DOXYGEN__) */
456 :
457 : #ifdef __cplusplus
458 : }
459 : #endif
460 :
461 : /**
462 : * @}
463 : */
464 :
465 : #endif /* ZEPHYR_INCLUDE_DRIVERS_PINCTRL_H_ */
|
