Lines Matching +full:gpio +full:- +full:range
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
30 be sparse - i.e. there may be gaps in the space with numbers where no
60 .. code-block:: c
97 See ``arch/arm/mach-ux500/Kconfig`` for an example.
106 also consider matching of offsets to the GPIO ranges that may be handled by
136 .. code-block:: c
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
266 Interaction with the GPIO subsystem
269 The GPIO drivers may want to perform operations of various types on the same
275 situations a cross-subsystem mapping between pins and GPIOs is needed.
279 controller handles control of a certain GPIO pin. Since a single pin controller
280 may be muxing several GPIO ranges (typically SoCs that have one set of pins,
281 but internally several GPIO silicon blocks, each modelled as a struct
282 gpio_chip) any number of GPIO ranges can be added to a pin controller instance
285 .. code-block:: c
287 #include <linux/gpio/driver.h>
322 GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and
324 GPIO range.
326 The GPIO range of "chip a" starts from the GPIO base of 32 and actual
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]
343 numbers can be encoded in the range like this:
345 .. code-block:: c
363 .. code-block:: c
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
375 in gpio number, and use the range's internals to retrieve a pin number. After
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
382 section 2.1 of ``Documentation/devicetree/bindings/gpio/gpio.txt`` on how to bind
383 pinctrl and gpio drivers.
407 +---+
413 +---+---+
415 +---+---+ +---+
421 +-------+-------+-------+---+---+
423 +-------+-------+-------+---+---+
426 are chessboard-like, big ones have "holes" in some arrangement according to
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
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
465 in your machine configuration. It is inspired by the clk, GPIO and regulator
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
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
493 - The combination of a FUNCTION and a PIN GROUP determine a certain function
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
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
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
544 pads (or "fingers") rather than pins - these are the soldering surfaces on the
581 .. code-block:: c
688 things - when it gets a selector passed in, the pinmux subsystem makes
689 sure no other device or GPIO assignment is already using the selected
696 Pin control interaction with the GPIO subsystem
700 from the Linux kernel using the API in ``<linux/gpio/consumer.h>`` with gpiod_get()
702 that your datasheet calls "GPIO mode", but actually is just an electrical
704 `GPIO mode pitfalls`_ for more details on this scenario.
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
718 individual pin into a GPIO pin independent of any other pins, and then try
721 In this case, the function array would become 64 entries for each GPIO
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
729 controller core, so you know which GPIO pins are being affected by the request
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.
744 GPIO mode pitfalls
747 Due to the naming conventions used by hardware engineers, where "GPIO"
750 into "GPIO mode". It appears that what hardware engineers mean with
751 "GPIO mode" is not necessarily the use case that is implied in the kernel
752 interface ``<linux/gpio/consumer.h>``: a pin that you grab from kernel code and then
756 Rather hardware engineers think that "GPIO mode" means that you can
757 software-control a few electrical properties of the pin that you would
761 The GPIO portions of a pin and its relation to a certain pin controller
769 | +- SPI
770 Physical pins --- pad --- pinmux -+- I2C
771 | +- mmc
772 | +- GPIO
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.
781 still applying desired pin config properties. GPIO functionality is thus
784 In this arrangement the registers for the GPIO portions of the pin controller,
785 or the registers for the GPIO hardware module are likely to reside in a
786 separate memory range only intended for GPIO driving, and the register
787 range dealing with pin config and pin multiplexing get placed into a
788 different memory range and a separate section of the data sheet.
791 simultaneous access to the same pin from GPIO and pin multiplexing
799 | +- SPI
800 Physical pins --- pad --- pinmux -+- I2C
801 | | +- mmc
803 GPIO pin
807 In this arrangement, the GPIO functionality can always be enabled, such that
808 e.g. a GPIO input can be used to "spy" on the SPI/I2C/MMC signal while it is
810 wrong things on the GPIO block, as it is never really disconnected. It is
811 possible that the GPIO, pin config and pin multiplex registers are placed into
812 the same memory range and the same section of the data sheet, although that
816 way as (B), the GPIO function still can't be enabled at the same time as the
818 simultaneous activation by GPIO and other muxed in devices.
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
832 such as setting a GPIO's output value, reading a GPIO's input value, or
833 setting GPIO pin direction should be exposed through the GPIO subsystem,
838 GPIO subsystem may call into the pinctrl subsystem in order to
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
842 module rather than the GPIO HW module.
845 may be placed at some pin-specific register in all cases or as part
846 of the GPIO register in case (B) especially. This doesn't mean that such
847 properties necessarily pertain to what the Linux kernel calls "GPIO".
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
856 muxed in, then twist it over to GPIO mode and use gpiod_direction_output()
861 The solution is to not think that what the datasheet calls "GPIO mode"
862 has to be handled by the ``<linux/gpio/consumer.h>`` interface. Instead view this as
863 a certain pin config setting. Look in e.g. ``<linux/pinctrl/pinconf-generic.h>``
870 So it is perfectly possible to push a pin into "GPIO mode" and drive the
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
923 GPIO mode.
926 GPIO subsystem. It is just an electrical configuration used by that device
928 datasheet calls "GPIO mode", but that is not the point: it is still used
930 driver, putting them into modes needed by the UART. GPIO in the Linux
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
937 Some datasheets will be more helpful and refer to the "GPIO mode" as
938 "low power mode" rather than anything to do with GPIO. This often means
941 specific muxing or configuration rather than anything related to the GPIO
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.
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),
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
1168 of the type found below. However when doing fine-grained state selection
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
1273 NOTE: the pinctrl system will return ``-EPROBE_DEFER`` if it cannot find the
1287 .. code-block:: c
1290 #include <linux/gpio/consumer.h>
1293 struct gpio_desc *gpio;
1296 gpio = devm_gpiod_get(&dev, "foo");
1298 Here we first request a certain pin state and then request GPIO "foo" to be
1301 state BEFORE requesting the GPIO. This is a semantic convention to avoid
1303 mux in and bias pins in a certain way before the GPIO subsystems starts to
1308 probing, nevertheless orthogonal to the GPIO subsystem.
1310 But there are also situations where it makes sense for the GPIO subsystem
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
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
1321 is such that the GPIO controller can override the pin controller's
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 */,
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");
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