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/down, open drain,
17 Top-level interface
20 Definition of PIN CONTROLLER:
22 - A pin controller is a piece of hardware, usually a set of registers, that
26 Definition of PIN:
28 - PINS are equal to pads, fingers, balls or whatever packaging input or
30 in the range 0..maxpin. This numberspace is local to each PIN CONTROLLER, so
31 there may be several such number spaces in a system. This pin space may
32 be sparse - i.e. there may be gaps in the space with numbers where no
33 pin exists.
35 When a PIN CONTROLLER is instantiated, it will register a descriptor to the
36 pin control framework, and this descriptor contains an array of pin descriptors
37 describing the pins handled by this specific pin controller.
39 Here is an example of a PGA (Pin Grid Array) chip seen from underneath::
59 To register a pin controller and name all the pins on this package we can do
98 See for example arch/arm/mach-u300/Kconfig for an example.
108 the pin controller.
123 Pin groups
126 Many controllers need to deal with groups of pins, so the pin controller
134 These two groups are presented to the pin control subsystem by implementing
194 The pin control subsystem will call the .get_groups_count() function to
197 the groups is up to the driver, this is just a simple example - in practice you
202 Pin configuration
205 Pins can sometimes be software-configured in various ways, mostly related
207 may be able to make an output pin high impedance, or "tristate" meaning it is
208 effectively disconnected. You may be able to connect an input pin to VDD or GND
209 using a certain resistor value - pull up and pull down - so that the pin has a
213 Pin configuration can be programmed by adding configuration entries into the
217 above, is entirely defined by the pin controller driver.
219 The pin configuration driver implements callbacks for changing pin
220 configuration in the pin controller ops like this::
232 ... Find setting for pin @ offset ...
271 /* Pin config operations are handled by some pin controller */
281 physical pins that are also registered as pin controller pins.
284 see the section named "pin control requests from drivers" and
285 "drivers needing both pin control and GPIOs" below for details. But in some
286 situations a cross-subsystem mapping between pins and GPIOs is needed.
288 Since the pin controller subsystem has its pinspace local to the pin controller
289 we need a mapping so that the pin control subsystem can figure out which pin
290 controller handles control of a certain GPIO pin. Since a single pin controller
293 gpio_chip) any number of GPIO ranges can be added to a pin controller instance
324 So this complex system has one pin controller handling two different
326 "chip b" have different .pin_base, which means a start pin number of the
330 pin range also starts from 32. However "chip b" has different starting
331 offset for the GPIO range and pin range. The GPIO range of "chip b" starts
332 from GPIO number 48, while the pin range of "chip b" starts from 64.
334 We can convert a gpio number to actual pin number using this "pin_base".
335 They are mapped in the global GPIO pin space at:
338 - GPIO range : [32 .. 47]
339 - pin range : [32 .. 47]
341 - GPIO range : [48 .. 55]
342 - pin range : [64 .. 71]
345 linear. If the mapping is sparse or haphazard, an array of arbitrary pin
359 In this case the pin_base property will be ignored. If the name of a pin
361 initialised using the function pinctrl_get_group_pins(), e.g. for pin
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
521 {"map-spi0", spi0, pinctrl0, fspi0, gspi0},
522 {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0}
525 Every map must be assigned a state name, pin controller, device and
526 function. The group is not compulsory - if it is omitted the first group
531 pin controller and function. This is for cases where a certain function on
532 a certain pin controller may use different sets of pins in different
535 - PINS for a certain FUNCTION using a certain PIN GROUP on a certain
536 PIN CONTROLLER are provided on a first-come first-serve basis, so if some
537 other device mux setting or GPIO pin request has already taken your physical
538 pin, you will be denied the use of it. To get (activate) a new setting, the
542 pads (or "fingers") rather than pins - these are the soldering surfaces on the
549 We assume that the number of possible function maps to pin groups is limited by
551 mapped to any pin, like in a phone exchange. So the available pin groups for
555 expect pinmux drivers to present *all* possible function vs pin group mappings
563 the pin controller driver to execute different settings.
573 some certain registers to activate a certain mux setting for a certain pin.
720 /* Pinmux operations are handled by some pin controller */
728 0 and 1, uses one pin in common so they would collide.
733 things - when it gets a selector passed in, the pinmux subsystem makes
741 Pin control interaction with the GPIO subsystem
744 Note that the following implies that the use case is to use a certain pin
753 gpiolib-based drivers as part of their gpio_request() and
763 individual pin into a GPIO pin independent of any other pins, and then try
764 the approach to define every pin as a function.
769 For this reason there are two functions a pin control driver can implement
770 to enable only GPIO on an individual pin: .gpio_request_enable() and
773 This function will pass in the affected GPIO range identified by the pin
778 GPIO pin shall be used for input or output you can implement the
780 gpiolib driver and the affected GPIO range, pin offset and desired direction
784 named functions for each GPIO pin, the pinctrl_gpio_request() will attempt to
785 obtain the function "gpioN" where "N" is the global GPIO pin number if no
786 special GPIO-handler is registered.
794 may be confused by a datasheet talking about a pin being possible to set
797 interface <linux/gpio.h>: a pin that you grab from kernel code and then
802 software-control a few electrical properties of the pin that you would
803 not be able to control if the pin was in some other mode, such as muxed in
806 The GPIO portions of a pin and its relation to a certain pin controller
811 pin config
813 | +- SPI
814 Physical pins --- pad --- pinmux -+- I2C
815 | +- mmc
816 | +- GPIO
817 pin
821 Here some electrical properties of the pin can be configured no matter
822 whether the pin is used for GPIO or not. If you multiplex a GPIO onto a
823 pin, you can also drive it high/low from "GPIO" registers.
824 Alternatively, the pin can be controlled by a certain peripheral, while
825 still applying desired pin config properties. GPIO functionality is thus
826 orthogonal to any other device using the pin.
828 In this arrangement the registers for the GPIO portions of the pin controller,
831 range dealing with pin config and pin multiplexing get placed into a
835 simultaneous access to the same pin from GPIO and pin multiplexing
843 pin config
845 | +- SPI
846 Physical pins --- pad --- pinmux -+- I2C
847 | | +- mmc
849 GPIO pin
855 pulsed out. It is likely possible to disrupt the traffic on the pin by doing
857 possible that the GPIO, pin config and pin multiplex registers are placed into
861 In some pin controllers, although the physical pins are designed in the same
869 - Registers (or fields within registers) that control electrical
870 properties of the pin such as biasing and drive strength should be
871 exposed through the pinctrl subsystem, as "pin configuration" settings.
873 - Registers (or fields within registers) that control muxing of signals
877 - Registers (or fields within registers) that control GPIO functionality
879 setting GPIO pin direction should be exposed through the GPIO subsystem,
885 co-ordinate register settings across HW modules. In particular, this may
886 be needed for HW with separate GPIO and pin controller HW modules, where
887 e.g. GPIO direction is determined by a register in the pin controller HW
890 Electrical properties of the pin such as biasing and drive strength
891 may be placed at some pin-specific register in all cases or as part
895 Example: a pin is usually muxed in to be used as a UART TX line. But during
896 system sleep, we need to put this pin into "GPIO mode" and ground it.
898 If you make a 1-to-1 map to the GPIO subsystem for this pin, you may start
900 pin shall be used for UART TX and GPIO at the same time, that you will grab
901 a pin control handle and set it to a certain state to enable UART TX to be
909 a certain pin config setting. Look in e.g. <linux/pinctrl/pinconf-generic.h>
913 this will configure the pin in output, use argument
916 So it is perfectly possible to push a pin into "GPIO mode" and drive the
917 line low as part of the usual pin control map. So for example your UART
926 pins_default = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_DEFAULT);
927 pins_sleep = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_SLEEP);
935 --------------------------------------------------
948 PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
950 PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
952 PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
953 "u0_group", "gpio-mode"),
954 PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
965 named "gpio-mode" that can be mapped onto the same pins to move them into
970 when going to sleep, it might imply that the pin is set into something the
974 kernel sense are just some 1-bit line, and is a different use case.
977 configuration and the muxing of the "u0" or "gpio-mode" group onto these
993 constrained and how the clock tree looks. Of course pinmux settings are also
996 A pin controller configuration for a machine looks pretty much like a simple
1004 .dev_name = "foo-spi.0",
1007 .ctrl_dev_name = "pinctrl-foo",
1011 .dev_name = "foo-i2c.0",
1014 .ctrl_dev_name = "pinctrl-foo",
1018 .dev_name = "foo-mmc.0",
1021 .ctrl_dev_name = "pinctrl-foo",
1028 must match a function provided by the pinmux driver handling this pin range.
1030 As you can see we may have several pin controllers on the system and thus
1038 it even more compact which assumes you want to use pinctrl-foo and position
1042 PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT,
1043 "pinctrl-foo", NULL, "i2c0"),
1046 The mapping table may also contain pin configuration entries. It's common for
1047 each pin/group to have a number of configuration entries that affect it, so
1062 PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
1063 "pinctrl-foo", "i2c0", "i2c0"),
1064 PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
1065 "pinctrl-foo", "i2c0", i2c_grp_configs),
1066 PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,
1067 "pinctrl-foo", "i2c0scl", i2c_pin_configs),
1068 PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,
1069 "pinctrl-foo", "i2c0sda", i2c_pin_configs),
1073 named states. When running on hardware that doesn't need any pin controller
1077 a named state without causing any pin controller to be programmed::
1080 PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),
1092 .dev_name = "foo-spi.0",
1093 .name = "spi0-pos-A",
1095 .ctrl_dev_name = "pinctrl-foo",
1100 .dev_name = "foo-spi.0",
1101 .name = "spi0-pos-B",
1103 .ctrl_dev_name = "pinctrl-foo",
1115 three groups for a total of 2+2+4 = 8 pins (for an 8-bit MMC bus as is the
1120 .dev_name = "foo-mmc.0",
1123 .ctrl_dev_name = "pinctrl-foo",
1128 .dev_name = "foo-mmc.0",
1131 .ctrl_dev_name = "pinctrl-foo",
1136 .dev_name = "foo-mmc.0",
1139 .ctrl_dev_name = "pinctrl-foo",
1144 .dev_name = "foo-mmc.0",
1147 .ctrl_dev_name = "pinctrl-foo",
1152 .dev_name = "foo-mmc.0",
1155 .ctrl_dev_name = "pinctrl-foo",
1160 .dev_name = "foo-mmc.0",
1163 .ctrl_dev_name = "pinctrl-foo",
1181 once. Since they share the same name, pin controller device, function and
1187 Pin control requests from drivers
1193 of the type found below. However when doing fine-grained state selection
1202 Generally it is discouraged to let individual drivers get and enable pin
1203 control. So if possible, handle the pin control in platform code or some other
1210 PINCTRL_STATE_SLEEP at runtime, re-biasing or even re-muxing pins to save
1229 foo->p = devm_pinctrl_get(&device);
1230 if (IS_ERR(foo->p)) {
1232 return PTR_ERR(foo->p);
1235 foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT);
1236 if (IS_ERR(foo->s)) {
1241 ret = pinctrl_select_state(foo->s);
1254 - pinctrl_get() is called in process context to obtain a handle to all pinctrl
1259 - devm_pinctrl_get() is a variant of pinctrl_get() that causes pinctrl_put()
1264 - pinctrl_lookup_state() is called in process context to obtain a handle to a
1267 - pinctrl_select_state() programs pin controller hardware according to the
1269 fast-path operation, since it only involved blasting some register settings
1270 into hardware. However, note that some pin controllers may have their
1271 registers on a slow/IRQ-based bus, so client devices should not assume they
1272 can call pinctrl_select_state() from non-blocking contexts.
1274 - pinctrl_put() frees all information associated with a pinctrl handle.
1276 - devm_pinctrl_put() is a variant of pinctrl_put() that may be used to
1286 Usually the pin control core handled the get/put pair and call out to the
1288 the associated pins, whereas select_state pass on to the pin controller
1296 NOTE: the pinctrl system will return -EPROBE_DEFER if it cannot find the
1302 Drivers needing both pin control and GPIOs
1305 Again, it is discouraged to let drivers lookup and select pin control states
1319 Here we first request a certain pin state and then request GPIO 14 to be
1333 back-end. This is when the GPIO driver may call out to the functions
1334 described in the section "Pin control interaction with the GPIO subsystem"
1335 above. This only involves per-pin multiplexing, and will be completely
1337 need not interact with the pin control subsystem at all.
1339 If a pin control driver and a GPIO driver is dealing with the same pins
1340 and the use cases involve multiplexing, you MUST implement the pin controller
1341 as a back-end for the GPIO driver like this, unless your hardware design
1342 is such that the GPIO controller can override the pin controller's
1344 pin control system.
1347 System pin control hogging
1350 Pin control map entries can be hogged by the core when the pin controller
1352 lookup_state() and select_state() on it immediately after the pin control
1356 to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT::
1359 .dev_name = "pinctrl-foo",
1362 .ctrl_dev_name = "pinctrl-foo",
1366 Since it may be common to request the core to hog a few always-applicable
1367 mux settings on the primary pin controller, there is a convenience macro for
1370 PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */,
1384 "pos-A" and "pos-B".
1402 s1 = pinctrl_lookup_state(foo->p, "pos-A");
1406 s2 = pinctrl_lookup_state(foo->p, "pos-B");
1429 will be done when the state is activated, so in effect one specific pin