Lines Matching +full:port +full:- +full:mapping +full:- +full:mode
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
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.
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
200 mapping table; see section `Board/machine configuration`_ below.
208 .. code-block:: c
275 situations a cross-subsystem mapping between pins and GPIOs is needed.
278 we need a mapping so that the pin control subsystem can figure out which pin
285 .. code-block:: c
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
342 linear. If the mapping is sparse or haphazard, an array of arbitrary pin
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
407 +---+
413 +---+---+
415 +---+---+ +---+
421 +-------+-------+-------+---+---+
423 +-------+-------+-------+---+---+
426 are chessboard-like, big ones have "holes" in some arrangement according to
436 In this 8x8 BGA package the pins { A8, A7, A6, A5 } can be used as an SPI port
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,
440 we cannot use the SPI port and I2C port at the same time. However in the inside
445 special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will
448 port on pins { G4, G3, G2, G1 } of course.
455 Since general-purpose I/O pins (GPIO) are typically always in shortage, it is
457 in use by some other I/O port.
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
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
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
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.
741 special GPIO-handler is registered.
744 GPIO mode pitfalls
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
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
758 not be able to control if the pin was in some other mode, such as muxed in
769 | +- SPI
770 Physical pins --- pad --- pinmux -+- I2C
771 | +- mmc
772 | +- GPIO
799 | +- SPI
800 Physical pins --- pad --- pinmux -+- I2C
801 | | +- mmc
823 - Registers (or fields within registers) that control electrical
827 - Registers (or fields within registers) that control muxing of signals
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
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
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"
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);
885 /* Normal mode */
888 /* Sleep mode */
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.
928 datasheet calls "GPIO mode", but that is not the point: it is still used
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
955 and spi on the second function mapping:
957 .. code-block:: c
961 static const struct pinctrl_map mapping[] __initconst = {
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",
992 You register this pinmux mapping to the pinmux subsystem by simply:
994 .. code-block:: c
996 ret = pinctrl_register_mappings(mapping, ARRAY_SIZE(mapping));
999 it even more compact which assumes you want to use pinctrl-foo and position
1000 0 for mapping, for example:
1002 .. code-block:: c
1004 static struct pinctrl_map mapping[] __initdata = {
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
1014 .. code-block:: c
1026 static struct pinctrl_map mapping[] __initdata = {
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),
1037 Finally, some devices expect the mapping table to contain certain specific
1039 configuration, the mapping table must still contain those named states, in
1044 .. code-block:: c
1046 static struct pinctrl_map mapping[] __initdata = {
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",
1078 This example mapping is used to switch between two positions for spi0 at
1084 three groups for a total of 2 + 2 + 4 = 8 pins (for an 8-bit MMC bus as is the
1085 case), we define a mapping like this:
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",
1140 The result of grabbing this mapping from the device with something like
1143 .. code-block:: c
1151 .. code-block:: c
1155 Will be that you activate all the three bottom records in the mapping at
1168 of the type found below. However when doing fine-grained state selection
1174 providing the proper mapping table. The device core will take care of
1185 ``PINCTRL_STATE_SLEEP`` at runtime, re-biasing or even re-muxing pins to save
1186 current in sleep mode.
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
1233 kernel memory to hold the pinmux state. All mapping table parsing or similar
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
1245 definition of the state as given by the mapping table. In theory, this is a
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
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
1320 as a back-end for the GPIO driver like this, unless your hardware design
1334 This occurs for mapping table entries where the client device name is equal
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
1365 function, but with different named in the mapping as described under
1366 "Advanced mapping" above. So that for an SPI device, we have two states named
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