Lines Matching +full:part +full:- +full:1 +full:- +full:pins
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
23 can control PINs. It may be able to multiplex, bias, set load capacitance,
24 set drive strength, etc. for individual pins or groups of pins.
26 - PINS are equal to pads, fingers, balls or whatever packaging input or
30 be sparse - i.e. there may be gaps in the space with numbers where no
35 describing the pins handled by this specific pin controller.
55 1 o o o o o o o o
57 To register a pin controller and name all the pins on this package we can do
60 .. code-block:: c
66 PINCTRL_PIN(1, "B8"),
76 .pins = foo_pins,
97 See ``arch/arm/mach-ux500/Kconfig`` for an example.
99 Pins usually have fancier names than this. You can find these in the datasheet
101 called ``PINCTRL_PIN()`` to create the struct entries. As you can see the pins are
109 For a padding with 467 pads, as opposed to actual pins, the enumeration will
125 Many controllers need to deal with groups of pins, so the pin controller
126 subsystem has a mechanism for enumerating groups of pins and retrieving the
127 actual enumerated pins that are part of a certain group.
129 For example, say that we have a group of pins dealing with an SPI interface
130 on { 0, 8, 16, 24 }, and a group of pins dealing with an I2C interface on pins
136 .. code-block:: c
161 const unsigned int **pins,
164 *pins = foo_groups[selector].pins;
182 to retrieve the name and pins of the group. Maintaining the data structure of
183 the groups is up to the driver, this is just a simple example - in practice you
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
195 using a certain resistor value - pull up and pull down - so that the pin has a
208 .. code-block:: c
270 physical pins that are also registered as pin controller pins.
275 situations a cross-subsystem mapping between pins and GPIOs is needed.
280 may be muxing several GPIO ranges (typically SoCs that have one set of pins,
285 .. code-block:: c
322 GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and
335 - GPIO range : [32 .. 47]
336 - pin range : [32 .. 47]
338 - GPIO range : [48 .. 55]
339 - pin range : [64 .. 71]
341 The above examples assume the mapping between the GPIOs and pins is
345 .. code-block:: c
347 static const unsigned int range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 };
353 .pins = &range_pins,
359 group is known, the pins and npins elements of the above structure can be
363 .. code-block:: c
365 pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins, &gpio_range.npins);
367 When GPIO-specific functions in the pin control subsystem are called, these
370 pin controller handling the matching range is found, GPIO-specific functions
407 +---+
413 +---+---+
415 +---+---+ +---+
421 +-------+-------+-------+---+---+
422 1 | o o | o o | o o | o | o |
423 +-------+-------+-------+---+---+
426 are chessboard-like, big ones have "holes" in some arrangement according to
428 pins you see some will be taken by things like a few VCC and GND to feed power
430 memory interface. The remaining pins will often be subject to pin multiplexing.
433 to its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using
436 In this 8x8 BGA package the pins { A8, A7, A6, A5 } can be used as an SPI port
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
439 be used as an I2C port (these are just two pins: SCL, SDA). Needless to say,
442 out on pins { G4, G3, G2, G1 }.
445 special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will
446 consume 2, 4 or 8 pins respectively, so either { A1, B1 } are taken or
448 port on pins { G4, G3, G2, G1 } of course.
453 different pins by pinmux settings.
455 Since general-purpose I/O pins (GPIO) are typically always in shortage, it is
471 - FUNCTIONS can be switched in and out by a driver residing with the pin
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
483 function i2c is associated with the pins { A5, B5 }, enumerated as
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
507 - FUNCTIONS and GROUPS on a certain PIN CONTROLLER are MAPPED to a certain
511 the set of pins to be used by a certain device. (If only one possible group
512 of pins is available for the function, no group name need to be supplied -
520 .. code-block:: c
523 {"map-spi0", spi0, pinctrl0, fspi0, gspi0},
524 {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0},
528 function. The group is not compulsory - if it is omitted the first group
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
544 pads (or "fingers") rather than pins - these are the soldering surfaces on the
546 pins/balls underneath the capsule. Pick some enumeration that makes sense to
547 you. Define enumerators only for the pins you can control if that makes sense.
564 The pinmux core takes care of preventing conflicts on pins and calling
577 A simple driver for the above example will work by setting bits 0, 1, 2, 3, 4, or 5
579 group of pins would work something like this:
581 .. code-block:: c
614 const unsigned int **pins,
617 *pins = foo_groups[selector].pins;
683 the muxes 1 and 5, which have pin 62 in common.
686 pins and who is using them, it will already have denied an impossible
688 things - when it gets a selector passed in, the pinmux subsystem makes
690 pins. Thus bits 0 and 2, or 1 and 5 in the control register will never
708 gpiolib-based drivers as part of their ``.request()`` and ``.free()`` semantics.
713 NOTE that platforms and individual drivers shall *NOT* request GPIO pins to be
715 that driver request proper muxing and other control for its pins.
718 individual pin into a GPIO pin independent of any other pins, and then try
729 controller core, so you know which GPIO pins are being affected by the request
741 special GPIO-handler is registered.
757 software-control a few electrical properties of the pin that you would
769 | +- SPI
770 Physical pins --- pad --- pinmux -+- I2C
771 | +- mmc
772 | +- GPIO
799 | +- SPI
800 Physical pins --- pad --- pinmux -+- I2C
801 | | +- mmc
815 In some pin controllers, although the physical pins are designed in the same
823 - Registers (or fields within registers) that control electrical
827 - Registers (or fields within registers) that control muxing of signals
828 from various other HW blocks (e.g. I2C, MMC, or GPIO) onto pins should
831 - Registers (or fields within registers) that control GPIO functionality
845 may be placed at some pin-specific register in all cases or as part
852 If you make a 1-to-1 map to the GPIO subsystem for this pin, you may start
858 wake up and maybe even gpiod_get() / gpiod_put() as part of this cycle. This
863 a certain pin config setting. Look in e.g. ``<linux/pinctrl/pinconf-generic.h>``
868 1 to indicate high level, argument 0 to indicate low level.
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",
919 Here the pins we want to control are in the "u0_group" and there is some
920 function called "u0" that can be enabled on this group of pins, and then
922 named "gpio-mode" that can be mapped onto the same pins to move them into
929 by that UART device to control the pins that pertain to that very UART
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
935 pins is a question for the driver.
951 part of this.
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",
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"),
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),
1044 .. code-block:: c
1047 PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),
1054 As it is possible to map a function to different groups of pins an optional
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",
1082 groups of pins, say for example in the mmc0 example above, where you can
1083 additively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all
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
1168 of the type found below. However when doing fine-grained state selection
1172 So if you just want to put the pins for a certain device into the default
1183 A typical case is if a driver needs to switch bias of pins from normal
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
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
1265 the associated pins, whereas ``pinctrl_select_state()`` pass on to the pin controller
1269 The pins are allocated for your device when you issue the ``devm_pinctrl_get()``
1271 pins.
1273 NOTE: the pinctrl system will return ``-EPROBE_DEFER`` if it cannot find the
1287 .. code-block:: c
1303 mux in and bias pins in a certain way before the GPIO subsystems starts to
1307 setting up the config and muxing for the pins right before the device is
1312 back-end. This is when the GPIO driver may call out to the functions
1314 above. This only involves per-pin multiplexing, and will be completely
1318 If a pin control driver and a GPIO driver is dealing with the same pins
1320 as a back-end for the GPIO driver like this, unless your hardware design
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
1351 .. code-block:: c
1353 PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */,
1363 an SPI port from one set of pins to another set of pins. Say for example for
1364 spi0 in the example above, we expose two different groups of pins for the same
1367 "pos-A" and "pos-B".
1370 then muxes the function in the pins defined by group A, and finally muxes it in
1371 on the pins defined by group B:
1373 .. code-block:: c
1387 s1 = pinctrl_lookup_state(p, "pos-A");
1391 s2 = pinctrl_lookup_state(p, "pos-B");
1413 The above has to be done from process context. The reservation of the pins
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
1448 - ``pinmux-pins``: iterates through all pins and prints mux owner, gpio owner
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