Lines Matching +full:pin +full:- +full:settings
2 PINCTRL (PIN CONTROL) subsystem
5 This document outlines the pin control subsystem in Linux
9 - Enumerating and naming controllable pins
11 - Multiplexing of pins, pads, fingers (etc) see below for details
13 - Configuration of pins, pads, fingers (etc), such as software-controlled
14 biasing and driving mode specific pins, such as pull-up, pull-down, open drain,
17 Top-level interface
22 - A PIN CONTROLLER is a piece of hardware, usually a set of registers, that
26 - PINS are equal to pads, fingers, balls or whatever packaging input or
28 in the range 0..maxpin. This numberspace is local to each PIN CONTROLLER, so
29 there may be several such number spaces in a system. This pin space may
30 be sparse - i.e. there may be gaps in the space with numbers where no
31 pin exists.
33 When a PIN CONTROLLER is instantiated, it will register a descriptor to the
34 pin control framework, and this descriptor contains an array of pin descriptors
35 describing the pins handled by this specific pin controller.
37 Here is an example of a PGA (Pin Grid Array) chip seen from underneath::
57 To register a pin controller and name all the pins on this package we can do
60 .. code-block:: c
97 See ``arch/arm/mach-ux500/Kconfig`` for an example.
107 the pin controller.
122 Pin groups
125 Many controllers need to deal with groups of pins, so the pin controller
133 These two groups are presented to the pin control subsystem by implementing
136 .. code-block:: c
180 The pin control subsystem will call the ``.get_groups_count()`` function to
183 the groups is up to the driver, this is just a simple example - in practice you
188 Pin configuration
191 Pins can sometimes be software-configured in various ways, mostly related
193 may be able to make an output pin high impedance (Hi-Z), or "tristate" meaning it is
194 effectively disconnected. You may be able to connect an input pin to VDD or GND
195 using a certain resistor value - pull up and pull down - so that the pin has a
199 Pin configuration can be programmed by adding configuration entries into the
203 above, is entirely defined by the pin controller driver.
205 The pin configuration driver implements callbacks for changing pin
206 configuration in the pin controller ops like this:
208 .. code-block:: c
221 /* ... Find setting for pin @ offset ... */
260 /* Pin config operations are handled by some pin controller */
270 physical pins that are also registered as pin controller pins.
273 see the section named `Pin control requests from drivers`_ and
274 `Drivers needing both pin control and GPIOs`_ below for details. But in some
275 situations a cross-subsystem mapping between pins and GPIOs is needed.
277 Since the pin controller subsystem has its pinspace local to the pin controller
278 we need a mapping so that the pin control subsystem can figure out which pin
279 controller handles control of a certain GPIO pin. Since a single pin controller
282 gpio_chip) any number of GPIO ranges can be added to a pin controller instance
285 .. code-block:: c
321 So this complex system has one pin controller handling two different
323 "chip b" have different ``pin_base``, which means a start pin number of the
327 pin range also starts from 32. However "chip b" has different starting
328 offset for the GPIO range and pin range. The GPIO range of "chip b" starts
329 from GPIO number 48, while the pin range of "chip b" starts from 64.
331 We can convert a gpio number to actual pin number using this ``pin_base``.
332 They are mapped in the global GPIO pin space at:
335 - GPIO range : [32 .. 47]
336 - pin range : [32 .. 47]
338 - GPIO range : [48 .. 55]
339 - pin range : [64 .. 71]
342 linear. If the mapping is sparse or haphazard, an array of arbitrary pin
345 .. code-block:: c
358 In this case the ``pin_base`` property will be ignored. If the name of a pin
360 initialised using the function ``pinctrl_get_group_pins()``, e.g. for pin
363 .. code-block:: c
367 When GPIO-specific functions in the pin control subsystem are called, these
368 ranges will be used to look up the appropriate pin controller by inspecting
369 and matching the pin to the pin ranges across all controllers. When a
370 pin controller handling the matching range is found, GPIO-specific functions
371 will be called on that specific pin controller.
373 For all functionalities dealing with pin biasing, pin muxing etc, the pin
374 controller subsystem will look up the corresponding pin number from the passed
375 in gpio number, and use the range's internals to retrieve a pin number. After
376 that, the subsystem passes it on to the pin control driver, so the driver
377 will get a pin number into its handled number range. Further it is also passed
378 the range ID value, so that the pin controller knows which range it should
398 a certain physical pin (ball, pad, finger, etc) for multiple mutually exclusive
404 Here is an example of a PGA (Pin Grid Array) chip seen from underneath::
407 +---+
413 +---+---+
415 +---+---+ +---+
421 +-------+-------+-------+---+---+
423 +-------+-------+-------+---+---+
426 are chessboard-like, big ones have "holes" in some arrangement according to
430 memory interface. The remaining pins will often be subject to pin multiplexing.
432 The example 8x8 PGA package above will have pin numbers 0 through 63 assigned
437 (these are four pins: CLK, RXD, TXD, FRM). In that case, pin B5 can be used as
438 some general-purpose GPIO pin. However, in another setting, pins { A5, B5 } can
445 special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will
451 out on different pin ranges. Often contemporary SoC (systems on chip) will
453 different pins by pinmux settings.
455 Since general-purpose I/O pins (GPIO) are typically always in shortage, it is
456 common to be able to use almost any pin as a GPIO pin if it is not currently
463 The purpose of the pinmux functionality in the pin controller subsystem is to
464 abstract and provide pinmux settings to the devices you choose to instantiate
467 to request a single pin for e.g. GPIO.
471 - FUNCTIONS can be switched in and out by a driver residing with the pin
473 pin control driver knows the possible functions. In the example above you can
476 - FUNCTIONS are assumed to be enumerable from zero in a one-dimensional array.
480 - FUNCTIONS have PIN GROUPS as defined on the generic level - so a certain
481 function is *always* associated with a certain set of pin groups, could
484 { 24, 25 } in the controller pin space.
486 The Function spi is associated with pin groups { A8, A7, A6, A5 }
490 Group names must be unique per pin controller, no two groups on the same
493 - The combination of a FUNCTION and a PIN GROUP determine a certain function
494 for a certain set of pins. The knowledge of the functions and pin groups
495 and their machine-specific particulars are kept inside the pinmux driver,
499 - The name of a function with a certain selector (>= 0)
500 - A list of groups associated with a certain function
501 - That a certain group in that list to be activated for a certain function
503 As already described above, pin groups are in turn self-descriptive, so
504 the core will retrieve the actual pin range in a certain group from the
507 - FUNCTIONS and GROUPS on a certain PIN CONTROLLER are MAPPED to a certain
510 name. Defining a pin controller, function and group thus uniquely identify
512 of pins is available for the function, no group name need to be supplied -
517 fi2c0 group gi2c0, on the primary pin controller, we get mappings
520 .. code-block:: c
523 {"map-spi0", spi0, pinctrl0, fspi0, gspi0},
524 {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0},
527 Every map must be assigned a state name, pin controller, device and
528 function. The group is not compulsory - if it is omitted the first group
533 pin controller and function. This is for cases where a certain function on
534 a certain pin controller may use different sets of pins in different
537 - PINS for a certain FUNCTION using a certain PIN GROUP on a certain
538 PIN CONTROLLER are provided on a first-come first-serve basis, so if some
539 other device mux setting or GPIO pin request has already taken your physical
540 pin, you will be denied the use of it. To get (activate) a new setting, the
544 pads (or "fingers") rather than pins - these are the soldering surfaces on the
551 We assume that the number of possible function maps to pin groups is limited by
553 mapped to any pin, like in a phone exchange. So the available pin groups for
557 expect pinmux drivers to present *all* possible function vs pin group mappings
565 the pin controller driver to execute different settings.
575 some certain registers to activate a certain mux setting for a certain pin.
581 .. code-block:: c
674 /* Pinmux operations are handled by some pin controller */
682 0 and 2, uses pin 24 in common so they would collide. All the same for
683 the muxes 1 and 5, which have pin 62 in common.
688 things - when it gets a selector passed in, the pinmux subsystem makes
696 Pin control interaction with the GPIO subsystem
699 Note that the following implies that the use case is to use a certain pin
708 gpiolib-based drivers as part of their ``.request()`` and ``.free()`` semantics.
718 individual pin into a GPIO pin independent of any other pins, and then try
719 the approach to define every pin as a function.
724 For this reason there are two functions a pin control driver can implement
725 to enable only GPIO on an individual pin: ``.gpio_request_enable()`` and
728 This function will pass in the affected GPIO range identified by the pin
733 GPIO pin shall be used for input or output you can implement the
735 gpiolib driver and the affected GPIO range, pin offset and desired direction
739 named functions for each GPIO pin, the ``pinctrl_gpio_request()`` will attempt to
740 obtain the function "gpioN" where "N" is the global GPIO pin number if no
741 special GPIO-handler is registered.
749 may be confused by a datasheet talking about a pin being possible to set
752 interface ``<linux/gpio/consumer.h>``: a pin that you grab from kernel code and then
757 software-control a few electrical properties of the pin that you would
758 not be able to control if the pin was in some other mode, such as muxed in
761 The GPIO portions of a pin and its relation to a certain pin controller
767 pin config
769 | +- SPI
770 Physical pins --- pad --- pinmux -+- I2C
771 | +- mmc
772 | +- GPIO
773 pin
777 Here some electrical properties of the pin can be configured no matter
778 whether the pin is used for GPIO or not. If you multiplex a GPIO onto a
779 pin, you can also drive it high/low from "GPIO" registers.
780 Alternatively, the pin can be controlled by a certain peripheral, while
781 still applying desired pin config properties. GPIO functionality is thus
782 orthogonal to any other device using the pin.
784 In this arrangement the registers for the GPIO portions of the pin controller,
787 range dealing with pin config and pin multiplexing get placed into a
791 simultaneous access to the same pin from GPIO and pin multiplexing
797 pin config
799 | +- SPI
800 Physical pins --- pad --- pinmux -+- I2C
801 | | +- mmc
803 GPIO pin
809 pulsed out. It is likely possible to disrupt the traffic on the pin by doing
811 possible that the GPIO, pin config and pin multiplex registers are placed into
815 In some pin controllers, although the physical pins are designed in the same
823 - Registers (or fields within registers) that control electrical
824 properties of the pin such as biasing and drive strength should be
825 exposed through the pinctrl subsystem, as "pin configuration" settings.
827 - Registers (or fields within registers) that control muxing of signals
831 - Registers (or fields within registers) that control GPIO functionality
833 setting GPIO pin direction should be exposed through the GPIO subsystem,
839 coordinate register settings across HW modules. In particular, this may
840 be needed for HW with separate GPIO and pin controller HW modules, where
841 e.g. GPIO direction is determined by a register in the pin controller HW
844 Electrical properties of the pin such as biasing and drive strength
845 may be placed at some pin-specific register in all cases or as part
849 Example: a pin is usually muxed in to be used as a UART TX line. But during
850 system sleep, we need to put this pin into "GPIO mode" and ground it.
852 If you make a 1-to-1 map to the GPIO subsystem for this pin, you may start
854 pin shall be used for UART TX and GPIO at the same time, that you will grab
855 a pin control handle and set it to a certain state to enable UART TX to be
863 a certain pin config setting. Look in e.g. ``<linux/pinctrl/pinconf-generic.h>``
867 this will configure the pin in output, use argument
870 So it is perfectly possible to push a pin into "GPIO mode" and drive the
871 line low as part of the usual pin control map. So for example your UART
874 .. code-block:: c
882 pins_default = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_DEFAULT);
883 pins_sleep = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_SLEEP);
893 .. code-block:: c
904 PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
906 PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
908 PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
909 "u0_group", "gpio-mode"),
910 PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
922 named "gpio-mode" that can be mapped onto the same pins to move them into
927 when going to sleep, it might imply that the pin is set into something the
931 kernel sense are just some 1-bit line, and is a different use case.
934 configuration and the muxing of the "u0" or "gpio-mode" group onto these
950 constrained and how the clock tree looks. Of course pinmux settings are also
953 A pin controller configuration for a machine looks pretty much like a simple
957 .. code-block:: c
963 .dev_name = "foo-spi.0",
966 .ctrl_dev_name = "pinctrl-foo",
970 .dev_name = "foo-i2c.0",
973 .ctrl_dev_name = "pinctrl-foo",
977 .dev_name = "foo-mmc.0",
980 .ctrl_dev_name = "pinctrl-foo",
987 must match a function provided by the pinmux driver handling this pin range.
989 As you can see we may have several pin controllers on the system and thus
994 .. code-block:: c
999 it even more compact which assumes you want to use pinctrl-foo and position
1002 .. code-block:: c
1005 PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
1006 "pinctrl-foo", NULL, "i2c0"),
1009 The mapping table may also contain pin configuration entries. It's common for
1010 each pin/group to have a number of configuration entries that affect it, so
1014 .. code-block:: c
1027 PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
1028 "pinctrl-foo", "i2c0", "i2c0"),
1029 PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
1030 "pinctrl-foo", "i2c0", i2c_grp_configs),
1031 PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,
1032 "pinctrl-foo", "i2c0scl", i2c_pin_configs),
1033 PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,
1034 "pinctrl-foo", "i2c0sda", i2c_pin_configs),
1038 named states. When running on hardware that doesn't need any pin controller
1042 a named state without causing any pin controller to be programmed:
1044 .. code-block:: c
1047 PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),
1057 .. code-block:: c
1061 .dev_name = "foo-spi.0",
1062 .name = "spi0-pos-A",
1064 .ctrl_dev_name = "pinctrl-foo",
1069 .dev_name = "foo-spi.0",
1070 .name = "spi0-pos-B",
1072 .ctrl_dev_name = "pinctrl-foo",
1084 three groups for a total of 2 + 2 + 4 = 8 pins (for an 8-bit MMC bus as is the
1087 .. code-block:: c
1091 .dev_name = "foo-mmc.0",
1094 .ctrl_dev_name = "pinctrl-foo",
1099 .dev_name = "foo-mmc.0",
1102 .ctrl_dev_name = "pinctrl-foo",
1107 .dev_name = "foo-mmc.0",
1110 .ctrl_dev_name = "pinctrl-foo",
1115 .dev_name = "foo-mmc.0",
1118 .ctrl_dev_name = "pinctrl-foo",
1123 .dev_name = "foo-mmc.0",
1126 .ctrl_dev_name = "pinctrl-foo",
1131 .dev_name = "foo-mmc.0",
1134 .ctrl_dev_name = "pinctrl-foo",
1143 .. code-block:: c
1151 .. code-block:: c
1156 once. Since they share the same name, pin controller device, function and
1162 Pin control requests from drivers
1168 of the type found below. However when doing fine-grained state selection
1177 Generally it is discouraged to let individual drivers get and enable pin
1178 control. So if possible, handle the pin control in platform code or some other
1185 ``PINCTRL_STATE_SLEEP`` at runtime, re-biasing or even re-muxing pins to save
1191 .. code-block:: c
1206 foo->p = devm_pinctrl_get(&device);
1207 if (IS_ERR(foo->p)) {
1209 return PTR_ERR(foo->p);
1212 foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT);
1213 if (IS_ERR(foo->s)) {
1215 return PTR_ERR(foo->s);
1218 ret = pinctrl_select_state(foo->p, foo->s);
1231 - ``pinctrl_get()`` is called in process context to obtain a handle to all pinctrl
1236 - ``devm_pinctrl_get()`` is a variant of pinctrl_get() that causes ``pinctrl_put()``
1241 - ``pinctrl_lookup_state()`` is called in process context to obtain a handle to a
1244 - ``pinctrl_select_state()`` programs pin controller hardware according to the
1246 fast-path operation, since it only involved blasting some register settings
1247 into hardware. However, note that some pin controllers may have their
1248 registers on a slow/IRQ-based bus, so client devices should not assume they
1249 can call ``pinctrl_select_state()`` from non-blocking contexts.
1251 - ``pinctrl_put()`` frees all information associated with a pinctrl handle.
1253 - ``devm_pinctrl_put()`` is a variant of ``pinctrl_put()`` that may be used to
1263 Usually the pin control core handled the get/put pair and call out to the
1265 the associated pins, whereas ``pinctrl_select_state()`` pass on to the pin controller
1273 NOTE: the pinctrl system will return ``-EPROBE_DEFER`` if it cannot find the
1279 Drivers needing both pin control and GPIOs
1282 Again, it is discouraged to let drivers lookup and select pin control states
1287 .. code-block:: c
1298 Here we first request a certain pin state and then request GPIO "foo" to be
1312 back-end. This is when the GPIO driver may call out to the functions
1313 described in the section `Pin control interaction with the GPIO subsystem`_
1314 above. This only involves per-pin multiplexing, and will be completely
1316 need not interact with the pin control subsystem at all.
1318 If a pin control driver and a GPIO driver is dealing with the same pins
1319 and the use cases involve multiplexing, you MUST implement the pin controller
1320 as a back-end for the GPIO driver like this, unless your hardware design
1321 is such that the GPIO controller can override the pin controller's
1323 pin control system.
1326 System pin control hogging
1329 Pin control map entries can be hogged by the core when the pin controller
1332 the pin control device has been registered.
1335 to the pin controller device name, and the state name is ``PINCTRL_STATE_DEFAULT``:
1337 .. code-block:: c
1340 .dev_name = "pinctrl-foo",
1343 .ctrl_dev_name = "pinctrl-foo",
1347 Since it may be common to request the core to hog a few always-applicable
1348 mux settings on the primary pin controller, there is a convenience macro for
1351 .. code-block:: c
1353 PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */,
1367 "pos-A" and "pos-B".
1373 .. code-block:: c
1387 s1 = pinctrl_lookup_state(p, "pos-A");
1391 s2 = pinctrl_lookup_state(p, "pos-B");
1414 will be done when the state is activated, so in effect one specific pin
1423 - ``pinctrl-devices``: prints each pin controller device along with columns to
1426 - ``pinctrl-handles``: prints each configured pin controller handle and the
1429 - ``pinctrl-maps``: prints all pinctrl maps
1431 A sub-directory is created inside of ``/sys/kernel/debug/pinctrl`` for each pin
1434 - ``pins``: prints a line for each pin registered on the pin controller. The
1437 - ``gpio-ranges``: prints ranges that map gpio lines to pins on the controller
1439 - ``pingroups``: prints all pin groups registered on the pin controller
1441 - ``pinconf-pins``: prints pin config settings for each pin
1443 - ``pinconf-groups``: prints pin config settings per pin group
1445 - ``pinmux-functions``: prints each pin function along with the pin groups that
1446 map to the pin function
1448 - ``pinmux-pins``: iterates through all pins and prints mux owner, gpio owner
1449 and if the pin is a hog
1451 - ``pinmux-select``: write to this file to activate a pin function for a group:
1453 .. code-block:: sh
1455 echo "<group-name function-name>" > pinmux-select