1 /*
2 * Copyright (C) 2015 Masahiro Yamada <yamada.masahiro@socionext.com>
3 *
4 * SPDX-License-Identifier: GPL-2.0+
5 */
6
7 #ifndef __PINCTRL_H
8 #define __PINCTRL_H
9
10 #define PINNAME_SIZE 10
11 #define PINMUX_SIZE 40
12
13 /**
14 * struct pinconf_param - pin config parameters
15 *
16 * @property: property name in DT nodes
17 * @param: ID for this config parameter
18 * @default_value: default value for this config parameter used in case
19 * no value is specified in DT nodes
20 */
21 struct pinconf_param {
22 const char * const property;
23 unsigned int param;
24 u32 default_value;
25 };
26
27 /**
28 * struct pinctrl_ops - pin control operations, to be implemented by
29 * pin controller drivers.
30 *
31 * The @set_state is the only mandatory operation. You can implement your
32 * pinctrl driver with its own @set_state. In this case, the other callbacks
33 * are not required. Otherwise, generic pinctrl framework is also available;
34 * use pinctrl_generic_set_state for @set_state, and implement other operations
35 * depending on your necessity.
36 *
37 * @get_pins_count: return number of selectable named pins available
38 * in this driver. (necessary to parse "pins" property in DTS)
39 * @get_pin_name: return the pin name of the pin selector,
40 * called by the core to figure out which pin it shall do
41 * operations to. (necessary to parse "pins" property in DTS)
42 * @get_groups_count: return number of selectable named groups available
43 * in this driver. (necessary to parse "groups" property in DTS)
44 * @get_group_name: return the group name of the group selector,
45 * called by the core to figure out which pin group it shall do
46 * operations to. (necessary to parse "groups" property in DTS)
47 * @get_functions_count: return number of selectable named functions available
48 * in this driver. (necessary for pin-muxing)
49 * @get_function_name: return the function name of the muxing selector,
50 * called by the core to figure out which mux setting it shall map a
51 * certain device to. (necessary for pin-muxing)
52 * @pinmux_set: enable a certain muxing function with a certain pin.
53 * The @func_selector selects a certain function whereas @pin_selector
54 * selects a certain pin to be used. On simple controllers one of them
55 * may be ignored. (necessary for pin-muxing against a single pin)
56 * @pinmux_group_set: enable a certain muxing function with a certain pin
57 * group. The @func_selector selects a certain function whereas
58 * @group_selector selects a certain set of pins to be used. On simple
59 * controllers one of them may be ignored.
60 * (necessary for pin-muxing against a pin group)
61 * @pinmux_property_set: enable a pinmux group. @pinmux_group should specify the
62 * pin identifier and mux settings. The exact format of a pinmux group is
63 * left up to the driver. The pin selector for the mux-ed pin should be
64 * returned on success. (necessary to parse the "pinmux" property in DTS)
65 * @pinconf_num_params: number of driver-specific parameters to be parsed
66 * from device trees (necessary for pin-configuration)
67 * @pinconf_params: list of driver_specific parameters to be parsed from
68 * device trees (necessary for pin-configuration)
69 * @pinconf_set: configure an individual pin with a given parameter.
70 * (necessary for pin-configuration against a single pin)
71 * @pinconf_group_set: configure all pins in a group with a given parameter.
72 * (necessary for pin-configuration against a pin group)
73 * @set_state: do pinctrl operations specified by @config, a pseudo device
74 * pointing a config node. (necessary for pinctrl_full)
75 * @set_state_simple: do needed pinctrl operations for a peripherl @periph.
76 * (necessary for pinctrl_simple)
77 * @get_pin_muxing: display the muxing of a given pin.
78 * @gpio_request_enable: requests and enables GPIO on a certain pin.
79 * Implement this only if you can mux every pin individually as GPIO. The
80 * affected GPIO range is passed along with an offset(pin number) into that
81 * specific GPIO range - function selectors and pin groups are orthogonal
82 * to this, the core will however make sure the pins do not collide.
83 * @gpio_disable_free: free up GPIO muxing on a certain pin, the reverse of
84 * @gpio_request_enable
85 */
86 struct pinctrl_ops {
87 int (*get_pins_count)(struct udevice *dev);
88 const char *(*get_pin_name)(struct udevice *dev, unsigned selector);
89 int (*get_groups_count)(struct udevice *dev);
90 const char *(*get_group_name)(struct udevice *dev, unsigned selector);
91 int (*get_functions_count)(struct udevice *dev);
92 const char *(*get_function_name)(struct udevice *dev,
93 unsigned selector);
94 int (*pinmux_set)(struct udevice *dev, unsigned pin_selector,
95 unsigned func_selector);
96 int (*pinmux_group_set)(struct udevice *dev, unsigned group_selector,
97 unsigned func_selector);
98 int (*pinmux_property_set)(struct udevice *dev, u32 pinmux_group);
99 unsigned int pinconf_num_params;
100 const struct pinconf_param *pinconf_params;
101 int (*pinconf_set)(struct udevice *dev, unsigned pin_selector,
102 unsigned param, unsigned argument);
103 int (*pinconf_group_set)(struct udevice *dev, unsigned group_selector,
104 unsigned param, unsigned argument);
105 int (*set_state)(struct udevice *dev, struct udevice *config);
106
107 /* for pinctrl-simple */
108 int (*set_state_simple)(struct udevice *dev, struct udevice *periph);
109 /**
110 * request() - Request a particular pinctrl function
111 *
112 * This activates the selected function.
113 *
114 * @dev: Device to adjust (UCLASS_PINCTRL)
115 * @func: Function number (driver-specific)
116 * @return 0 if OK, -ve on error
117 */
118 int (*request)(struct udevice *dev, int func, int flags);
119
120 /**
121 * get_periph_id() - get the peripheral ID for a device
122 *
123 * This generally looks at the peripheral's device tree node to work
124 * out the peripheral ID. The return value is normally interpreted as
125 * enum periph_id. so long as this is defined by the platform (which it
126 * should be).
127 *
128 * @dev: Pinctrl device to use for decoding
129 * @periph: Device to check
130 * @return peripheral ID of @periph, or -ENOENT on error
131 */
132 int (*get_periph_id)(struct udevice *dev, struct udevice *periph);
133
134 /**
135 * get_gpio_mux() - get the mux value for a particular GPIO
136 *
137 * This allows the raw mux value for a GPIO to be obtained. It is
138 * useful for displaying the function being used by that GPIO, such
139 * as with the 'gpio' command. This function is internal to the GPIO
140 * subsystem and should not be used by generic code. Typically it is
141 * used by a GPIO driver with knowledge of the SoC pinctrl setup.
142 *
143 * @dev: Pinctrl device to use
144 * @banknum: GPIO bank number
145 * @index: GPIO index within the bank
146 * @return mux value (SoC-specific, e.g. 0 for input, 1 for output)
147 */
148 int (*get_gpio_mux)(struct udevice *dev, int banknum, int index);
149
150 /**
151 * get_pin_muxing() - show pin muxing
152 *
153 * This allows to display the muxing of a given pin. It's useful for
154 * debug purpose to know if a pin is configured as GPIO or as an
155 * alternate function and which one.
156 * Typically it is used by a PINCTRL driver with knowledge of the SoC
157 * pinctrl setup.
158 *
159 * @dev: Pinctrl device to use
160 * @selector: Pin selector
161 * @buf Pin's muxing description
162 * @size Pin's muxing description length
163 * return 0 if OK, -ve on error
164 */
165 int (*get_pin_muxing)(struct udevice *dev, unsigned int selector,
166 char *buf, int size);
167
168 /**
169 * gpio_request_enable: requests and enables GPIO on a certain pin.
170 *
171 * @dev: Pinctrl device to use
172 * @selector: Pin selector
173 * return 0 if OK, -ve on error
174 */
175 int (*gpio_request_enable)(struct udevice *dev, unsigned int selector);
176
177 /**
178 * gpio_disable_free: free up GPIO muxing on a certain pin.
179 *
180 * @dev: Pinctrl device to use
181 * @selector: Pin selector
182 * return 0 if OK, -ve on error
183 */
184 int (*gpio_disable_free)(struct udevice *dev, unsigned int selector);
185 };
186
187 #define pinctrl_get_ops(dev) ((struct pinctrl_ops *)(dev)->driver->ops)
188
189 /**
190 * Generic pin configuration paramters
191 *
192 * @PIN_CONFIG_BIAS_DISABLE: disable any pin bias on the pin, a
193 * transition from say pull-up to pull-down implies that you disable
194 * pull-up in the process, this setting disables all biasing.
195 * @PIN_CONFIG_BIAS_HIGH_IMPEDANCE: the pin will be set to a high impedance
196 * mode, also know as "third-state" (tristate) or "high-Z" or "floating".
197 * On output pins this effectively disconnects the pin, which is useful
198 * if for example some other pin is going to drive the signal connected
199 * to it for a while. Pins used for input are usually always high
200 * impedance.
201 * @PIN_CONFIG_BIAS_BUS_HOLD: the pin will be set to weakly latch so that it
202 * weakly drives the last value on a tristate bus, also known as a "bus
203 * holder", "bus keeper" or "repeater". This allows another device on the
204 * bus to change the value by driving the bus high or low and switching to
205 * tristate. The argument is ignored.
206 * @PIN_CONFIG_BIAS_PULL_UP: the pin will be pulled up (usually with high
207 * impedance to VDD). If the argument is != 0 pull-up is enabled,
208 * if it is 0, pull-up is total, i.e. the pin is connected to VDD.
209 * @PIN_CONFIG_BIAS_PULL_DOWN: the pin will be pulled down (usually with high
210 * impedance to GROUND). If the argument is != 0 pull-down is enabled,
211 * if it is 0, pull-down is total, i.e. the pin is connected to GROUND.
212 * @PIN_CONFIG_BIAS_PULL_PIN_DEFAULT: the pin will be pulled up or down based
213 * on embedded knowledge of the controller hardware, like current mux
214 * function. The pull direction and possibly strength too will normally
215 * be decided completely inside the hardware block and not be readable
216 * from the kernel side.
217 * If the argument is != 0 pull up/down is enabled, if it is 0, the
218 * configuration is ignored. The proper way to disable it is to use
219 * @PIN_CONFIG_BIAS_DISABLE.
220 * @PIN_CONFIG_DRIVE_PUSH_PULL: the pin will be driven actively high and
221 * low, this is the most typical case and is typically achieved with two
222 * active transistors on the output. Setting this config will enable
223 * push-pull mode, the argument is ignored.
224 * @PIN_CONFIG_DRIVE_OPEN_DRAIN: the pin will be driven with open drain (open
225 * collector) which means it is usually wired with other output ports
226 * which are then pulled up with an external resistor. Setting this
227 * config will enable open drain mode, the argument is ignored.
228 * @PIN_CONFIG_DRIVE_OPEN_SOURCE: the pin will be driven with open source
229 * (open emitter). Setting this config will enable open source mode, the
230 * argument is ignored.
231 * @PIN_CONFIG_DRIVE_STRENGTH: the pin will sink or source at most the current
232 * passed as argument. The argument is in mA.
233 * @PIN_CONFIG_INPUT_ENABLE: enable the pin's input. Note that this does not
234 * affect the pin's ability to drive output. 1 enables input, 0 disables
235 * input.
236 * @PIN_CONFIG_INPUT_SCHMITT_ENABLE: control schmitt-trigger mode on the pin.
237 * If the argument != 0, schmitt-trigger mode is enabled. If it's 0,
238 * schmitt-trigger mode is disabled.
239 * @PIN_CONFIG_INPUT_SCHMITT: this will configure an input pin to run in
240 * schmitt-trigger mode. If the schmitt-trigger has adjustable hysteresis,
241 * the threshold value is given on a custom format as argument when
242 * setting pins to this mode.
243 * @PIN_CONFIG_INPUT_DEBOUNCE: this will configure the pin to debounce mode,
244 * which means it will wait for signals to settle when reading inputs. The
245 * argument gives the debounce time in usecs. Setting the
246 * argument to zero turns debouncing off.
247 * @PIN_CONFIG_POWER_SOURCE: if the pin can select between different power
248 * supplies, the argument to this parameter (on a custom format) tells
249 * the driver which alternative power source to use.
250 * @PIN_CONFIG_SLEW_RATE: if the pin can select slew rate, the argument to
251 * this parameter (on a custom format) tells the driver which alternative
252 * slew rate to use.
253 * @PIN_CONFIG_LOW_POWER_MODE: this will configure the pin for low power
254 * operation, if several modes of operation are supported these can be
255 * passed in the argument on a custom form, else just use argument 1
256 * to indicate low power mode, argument 0 turns low power mode off.
257 * @PIN_CONFIG_OUTPUT: this will configure the pin as an output. Use argument
258 * 1 to indicate high level, argument 0 to indicate low level. (Please
259 * see Documentation/pinctrl.txt, section "GPIO mode pitfalls" for a
260 * discussion around this parameter.)
261 * @PIN_CONFIG_END: this is the last enumerator for pin configurations, if
262 * you need to pass in custom configurations to the pin controller, use
263 * PIN_CONFIG_END+1 as the base offset.
264 */
265 #define PIN_CONFIG_BIAS_DISABLE 0
266 #define PIN_CONFIG_BIAS_HIGH_IMPEDANCE 1
267 #define PIN_CONFIG_BIAS_BUS_HOLD 2
268 #define PIN_CONFIG_BIAS_PULL_UP 3
269 #define PIN_CONFIG_BIAS_PULL_DOWN 4
270 #define PIN_CONFIG_BIAS_PULL_PIN_DEFAULT 5
271 #define PIN_CONFIG_DRIVE_PUSH_PULL 6
272 #define PIN_CONFIG_DRIVE_OPEN_DRAIN 7
273 #define PIN_CONFIG_DRIVE_OPEN_SOURCE 8
274 #define PIN_CONFIG_DRIVE_STRENGTH 9
275 #define PIN_CONFIG_INPUT_ENABLE 10
276 #define PIN_CONFIG_INPUT_SCHMITT_ENABLE 11
277 #define PIN_CONFIG_INPUT_SCHMITT 12
278 #define PIN_CONFIG_INPUT_DEBOUNCE 13
279 #define PIN_CONFIG_POWER_SOURCE 14
280 #define PIN_CONFIG_SLEW_RATE 15
281 #define PIN_CONFIG_LOW_POWER_MODE 16
282 #define PIN_CONFIG_OUTPUT 17
283 #define PIN_CONFIG_END 0x7FFF
284
285 #if CONFIG_IS_ENABLED(PINCTRL_GENERIC)
286 /**
287 * pinctrl_generic_set_state() - generic set_state operation
288 * Parse the DT node of @config and its children and handle generic properties
289 * such as "pins", "groups", "functions", and pin configuration parameters.
290 *
291 * @pctldev: pinctrl device
292 * @config: config device (pseudo device), pointing a config node in DTS
293 * @return: 0 on success, or negative error code on failure
294 */
295 int pinctrl_generic_set_state(struct udevice *pctldev, struct udevice *config);
296 #else
pinctrl_generic_set_state(struct udevice * pctldev,struct udevice * config)297 static inline int pinctrl_generic_set_state(struct udevice *pctldev,
298 struct udevice *config)
299 {
300 return -EINVAL;
301 }
302 #endif
303
304 #if CONFIG_IS_ENABLED(PINCTRL)
305 /**
306 * pinctrl_select_state() - set a device to a given state
307 *
308 * @dev: peripheral device
309 * @statename: state name, like "default"
310 * @return: 0 on success, or negative error code on failure
311 */
312 int pinctrl_select_state(struct udevice *dev, const char *statename);
313
314 /**
315 * pinctrl_request() - Request a particular pinctrl function
316 *
317 * @dev: Device to check (UCLASS_PINCTRL)
318 * @func: Function number (driver-specific)
319 * @flags: Flags (driver-specific)
320 * @return 0 if OK, -ve on error
321 */
322 int pinctrl_request(struct udevice *dev, int func, int flags);
323
324 /**
325 * pinctrl_request_noflags() - Request a particular pinctrl function
326 *
327 * This is similar to pinctrl_request() but uses 0 for @flags.
328 *
329 * @dev: Device to check (UCLASS_PINCTRL)
330 * @func: Function number (driver-specific)
331 * @return 0 if OK, -ve on error
332 */
333 int pinctrl_request_noflags(struct udevice *dev, int func);
334
335 /**
336 * pinctrl_get_periph_id() - get the peripheral ID for a device
337 *
338 * This generally looks at the peripheral's device tree node to work out the
339 * peripheral ID. The return value is normally interpreted as enum periph_id.
340 * so long as this is defined by the platform (which it should be).
341 *
342 * @dev: Pinctrl device to use for decoding
343 * @periph: Device to check
344 * @return peripheral ID of @periph, or -ENOENT on error
345 */
346 int pinctrl_get_periph_id(struct udevice *dev, struct udevice *periph);
347
348 /**
349 * pinctrl_decode_pin_config() - decode pin configuration flags
350 *
351 * This decodes some of the PIN_CONFIG values into flags, with each value
352 * being (1 << pin_cfg). This does not support things with values like the
353 * slew rate.
354 *
355 * @blob: Device tree blob
356 * @node: Node containing the PIN_CONFIG values
357 * @return decoded flag value, or -ve on error
358 */
359 int pinctrl_decode_pin_config(const void *blob, int node);
360
361 /**
362 * pinctrl_get_gpio_mux() - get the mux value for a particular GPIO
363 *
364 * This allows the raw mux value for a GPIO to be obtained. It is
365 * useful for displaying the function being used by that GPIO, such
366 * as with the 'gpio' command. This function is internal to the GPIO
367 * subsystem and should not be used by generic code. Typically it is
368 * used by a GPIO driver with knowledge of the SoC pinctrl setup.
369 *
370 * @dev: Pinctrl device to use
371 * @banknum: GPIO bank number
372 * @index: GPIO index within the bank
373 * @return mux value (SoC-specific, e.g. 0 for input, 1 for output)
374 */
375 int pinctrl_get_gpio_mux(struct udevice *dev, int banknum, int index);
376
377 /**
378 * pinctrl_get_pins_count() - get the total pins count for all GPIOs
379 *
380 * This allows the total pins count for all GPIO to be obtained.
381 *
382 * @dev: Pinctrl device to use
383 * @return pins count
384 */
385 int pinctrl_get_pins_count(struct udevice *dev);
386
387 /**
388 * pinctrl_get_pin_name() - Returns the pin's name
389 *
390 * This allows to display the pin's name for debug purpose
391 *
392 * @dev: Pinctrl device to use
393 * @selector Pin index within pin-controller
394 * @buf Pin's name
395 * @return 0 if OK, -ve on error
396 */
397 int pinctrl_get_pin_name(struct udevice *dev, int selector, char *buf,
398 int size);
399
400 /**
401 * pinctrl_get_pin_muxing() - Returns the muxing description
402 *
403 * This allows to display the muxing description of the given pin for
404 * debug purpose
405 *
406 * @dev: Pinctrl device to use
407 * @selector Pin index within pin-controller
408 * @buf Pin's muxing description
409 * @size Pin's muxing description length
410 * @return 0 if OK, -ve on error
411 */
412 int pinctrl_get_pin_muxing(struct udevice *dev, int selector, char *buf,
413 int size);
414
415 /**
416 * pinctrl_gpio_request() - request a single pin to be used as GPIO
417 *
418 * @dev: GPIO peripheral device
419 * @offset: the GPIO pin offset from the GPIO controller
420 * @return: 0 on success, or negative error code on failure
421 */
422 int pinctrl_gpio_request(struct udevice *dev, unsigned offset);
423
424 /**
425 * pinctrl_gpio_free() - free a single pin used as GPIO
426 *
427 * @dev: GPIO peripheral device
428 * @offset: the GPIO pin offset from the GPIO controller
429 * @return: 0 on success, or negative error code on failure
430 */
431 int pinctrl_gpio_free(struct udevice *dev, unsigned offset);
432
433 #else
pinctrl_select_state(struct udevice * dev,const char * statename)434 static inline int pinctrl_select_state(struct udevice *dev,
435 const char *statename)
436 {
437 return -EINVAL;
438 }
439
pinctrl_request(struct udevice * dev,int func,int flags)440 static inline int pinctrl_request(struct udevice *dev, int func, int flags)
441 {
442 return -EINVAL;
443 }
444
pinctrl_request_noflags(struct udevice * dev,int func)445 static inline int pinctrl_request_noflags(struct udevice *dev, int func)
446 {
447 return -EINVAL;
448 }
449
pinctrl_get_periph_id(struct udevice * dev,struct udevice * periph)450 static inline int pinctrl_get_periph_id(struct udevice *dev, struct udevice *periph)
451 {
452 return -EINVAL;
453 }
454
pinctrl_decode_pin_config(const void * blob,int node)455 static inline int pinctrl_decode_pin_config(const void *blob, int node)
456 {
457 return -EINVAL;
458 }
459
pinctrl_get_gpio_mux(struct udevice * dev,int banknum,int index)460 static inline int pinctrl_get_gpio_mux(struct udevice *dev, int banknum, int index)
461 {
462 return -EINVAL;
463 }
464
pinctrl_get_pins_count(struct udevice * dev)465 static inline int pinctrl_get_pins_count(struct udevice *dev)
466 {
467 return -EINVAL;
468 }
469
pinctrl_get_pin_name(struct udevice * dev,int selector,char * buf,int size)470 static inline int pinctrl_get_pin_name(struct udevice *dev, int selector, char *buf,
471 int size)
472 {
473 return -EINVAL;
474 }
475
pinctrl_get_pin_muxing(struct udevice * dev,int selector,char * buf,int size)476 static inline int pinctrl_get_pin_muxing(struct udevice *dev, int selector, char *buf,
477 int size)
478 {
479 return -EINVAL;
480 }
481
pinctrl_gpio_request(struct udevice * dev,unsigned offset)482 static inline int pinctrl_gpio_request(struct udevice *dev, unsigned offset)
483 {
484 return -EINVAL;
485 }
486
pinctrl_gpio_free(struct udevice * dev,unsigned offset)487 static inline int pinctrl_gpio_free(struct udevice *dev, unsigned offset)
488 {
489 return -EINVAL;
490 }
491
492 #endif
493
494 #endif /* __PINCTRL_H */
495