Lines Matching +full:a +full:- +full:gpio
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
22 - A pin controller is a piece of hardware, usually a set of registers, that
28 - PINS are equal to pads, fingers, balls or whatever packaging input or
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
35 When a PIN CONTROLLER is instantiated, it will register a descriptor to the
39 Here is an example of a PGA (Pin Grid Array) chip seen from underneath::
41 A B C D E F G H
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.
101 for your chip. Notice that the core pinctrl.h file provides a fancy macro
107 also consider matching of offsets to the GPIO ranges that may be handled by
110 For a padring with 467 pads, as opposed to actual pins, I used an enumeration
127 subsystem has a mechanism for enumerating groups of pins and retrieving the
128 actual enumerated pins that are part of a certain group.
130 For example, say that we have a group of pins dealing with an SPI interface
131 on { 0, 8, 16, 24 }, and a group of pins dealing with an I2C interface on pins
197 the groups is up to the driver, this is just a simple example - in practice you
205 Pins can sometimes be software-configured in various ways, mostly related
209 using a certain resistor value - pull up and pull down - so that the pin has a
277 Interaction with the GPIO subsystem
280 The GPIO drivers may want to perform operations of various types on the same
286 situations a cross-subsystem mapping between pins and GPIOs is needed.
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
291 may be muxing several GPIO ranges (typically SoCs that have one set of pins,
292 but internally several GPIO silicon blocks, each modelled as a struct
293 gpio_chip) any number of GPIO ranges can be added to a pin controller instance
300 .name = "chip a",
325 GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and
326 "chip b" have different .pin_base, which means a start pin number of the
327 GPIO range.
329 The GPIO range of "chip a" starts from the GPIO base of 32 and actual
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:
337 chip a:
338 - GPIO range : [32 .. 47]
339 - pin range : [32 .. 47]
341 - GPIO range : [48 .. 55]
342 - pin range : [64 .. 71]
359 In this case the pin_base property will be ignored. If the name of a pin
367 When GPIO-specific functions in the pin control subsystem are called, these
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
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
382 section 2.1 of Documentation/devicetree/bindings/gpio/gpio.txt on how to bind
383 pinctrl and gpio drivers.
397 is a way for chip vendors producing some kind of electrical packages to use
398 a certain physical pin (ball, pad, finger, etc) for multiple mutually exclusive
400 we usually mean a way of soldering or wiring the package into an electronic
404 Here is an example of a PGA (Pin Grid Array) chip seen from underneath::
406 A B C D E F G H
407 +---+
413 +---+---+
415 +---+---+ +---+
421 +-------+-------+-------+---+---+
423 +-------+-------+-------+---+---+
426 are chessboard-like, big ones have "holes" in some arrangement according to
427 different design patterns, but we're using this as a simple example. Of the
428 pins you see some will be taken by things like a few VCC and GND to feed power
429 to the chip, and quite a few will be taken by large ports like an external
434 pinctrl_register_pins() and a suitable data set as shown earlier.
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
481 function is *always* associated with a certain set of pin groups, could
482 be just a single one, but could also be many. In the example above the
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
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 -
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
551 mapped to any pin, like in a phone exchange. So the available pin groups for
552 a certain function will be limited to a few choices (say up to eight or so),
554 by inspecting available pinmux hardware, and a necessary assumption since we
571 Pinmux drivers are required to supply a few callback functions, some are
573 some certain registers to activate a certain mux setting for a certain pin.
575 A simple driver for the above example will work by setting bits 0, 1, 2, 3 or 4
576 into some register named MUX to select a certain function with a certain
733 things - when it gets a selector passed in, the pinmux subsystem makes
734 sure no other device or GPIO assignment is already using the selected
738 All the above functions are mandatory to implement for a pinmux driver.
741 Pin control interaction with the GPIO subsystem
744 Note that the following implies that the use case is to use a certain pin
745 from the Linux kernel using the API in <linux/gpio.h> with gpio_request()
747 that your datasheet calls "GPIO mode", but actually is just an electrical
748 configuration for a certain device. See the section below named
749 "GPIO mode pitfalls" for more details on this scenario.
753 gpiolib-based drivers as part of their gpio_request() and
758 NOTE that platforms and individual drivers shall *NOT* request GPIO pins to be
759 controlled e.g. muxed in. Instead, implement a proper gpiolib driver and have
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.
766 In this case, the function array would become 64 entries for each GPIO
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
774 controller core, so you know which GPIO pins are being affected by the request
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.
789 GPIO mode pitfalls
792 Due to the naming conventions used by hardware engineers, where "GPIO"
794 may be confused by a datasheet talking about a pin being possible to set
795 into "GPIO mode". It appears that what hardware engineers mean with
796 "GPIO mode" is not necessarily the use case that is implied in the kernel
797 interface <linux/gpio.h>: a pin that you grab from kernel code and then
801 Rather hardware engineers think that "GPIO mode" means that you can
802 software-control a few electrical properties of the pin that you would
804 for a device.
806 The GPIO portions of a pin and its relation to a certain pin controller
810 (A)
813 | +- SPI
814 Physical pins --- pad --- pinmux -+- I2C
815 | +- mmc
816 | +- GPIO
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
828 In this arrangement the registers for the GPIO portions of the pin controller,
829 or the registers for the GPIO hardware module are likely to reside in a
830 separate memory range only intended for GPIO driving, and the register
831 range dealing with pin config and pin multiplexing get placed into a
832 different memory range and a separate section of the data sheet.
834 A flag "strict" in struct pinmux_ops is available to check and deny
835 simultaneous access to the same pin from GPIO and pin multiplexing
845 | +- SPI
846 Physical pins --- pad --- pinmux -+- I2C
847 | | +- mmc
849 GPIO pin
853 In this arrangement, the GPIO functionality can always be enabled, such that
854 e.g. a GPIO input can be used to "spy" on the SPI/I2C/MMC signal while it is
856 wrong things on the GPIO block, as it is never really disconnected. It is
857 possible that the GPIO, pin config and pin multiplex registers are placed into
862 way as (B), the GPIO function still can't be enabled at the same time as the
864 simultaneous activation by GPIO and other muxed in devices.
866 From a kernel point of view, however, these are different aspects of the
869 - Registers (or fields within registers) that control electrical
873 - Registers (or fields within registers) that control muxing of signals
874 from various other HW blocks (e.g. I2C, MMC, or GPIO) onto pins should
877 - Registers (or fields within registers) that control GPIO functionality
878 such as setting a GPIO's output value, reading a GPIO's input value, or
879 setting GPIO pin direction should be exposed through the GPIO subsystem,
884 GPIO subsystem may call into the pinctrl subsystem in order to
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
888 module rather than the GPIO HW module.
891 may be placed at some pin-specific register in all cases or as part
892 of the GPIO register in case (B) especially. This doesn't mean that such
893 properties necessarily pertain to what the Linux kernel calls "GPIO".
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
902 muxed in, then twist it over to GPIO mode and use gpio_direction_output()
907 The solution is to not think that what the datasheet calls "GPIO mode"
908 has to be handled by the <linux/gpio.h> interface. Instead view this as
909 a certain pin config setting. Look in e.g. <linux/pinctrl/pinconf-generic.h>
916 So it is perfectly possible to push a pin into "GPIO mode" and drive the
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
966 GPIO mode.
969 GPIO subsystem. It is just an electrical configuration used by that device
971 datasheet calls "GPIO mode", but that is not the point: it is still used
973 driver, putting them into modes needed by the UART. GPIO in the Linux
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
978 pins is a question for the driver.
980 Some datasheets will be more helpful and refer to the "GPIO mode" as
981 "low power mode" rather than anything to do with GPIO. This often means
984 specific muxing or configuration rather than anything related to the GPIO
991 Boards and machines define how a certain complete running system is put
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.
1037 Since the above construct is pretty common there is a helper macro to make
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"),
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),
1077 a named state without causing any pin controller to be programmed::
1080 PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),
1087 As it is possible to map a function to different groups of pins an optional
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
1116 case), we define a mapping like this::
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",
1182 device, and since we allow multiple groups to match to a single device, they
1190 When a device driver is about to probe the device core will automatically
1193 of the type found below. However when doing fine-grained state selection
1197 So if you just want to put the pins for a certain device into the default
1205 some cases where a driver needs to e.g. switch between different mux mappings
1208 A typical case is if a driver needs to switch bias of pins from normal
1210 PINCTRL_STATE_SLEEP at runtime, re-biasing or even re-muxing pins to save
1213 A driver may request a certain control state to be activated, usually just the
1226 /* Allocate a state holder named "foo" etc */
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
1255 information for a given client device. It will allocate a struct from the
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
1265 specific state for a client device. This operation may be slow, too.
1267 - pinctrl_select_state() programs pin controller hardware according to the
1268 definition of the state as given by the mapping table. In theory, this is a
1269 fast-path operation, since it only involved blasting some register settings
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
1277 explicitly destroy a pinctrl object returned by devm_pinctrl_get().
1281 pinctrl_get() must be paired with a plain pinctrl_put().
1296 NOTE: the pinctrl system will return -EPROBE_DEFER if it cannot find the
1311 #include <linux/gpio.h>
1314 int gpio;
1317 gpio = devm_gpio_request(&dev, 14, "foo");
1319 Here we first request a certain pin state and then request GPIO 14 to be
1322 state BEFORE requesting the GPIO. This is a semantic convention to avoid
1324 mux in and bias pins in a certain way before the GPIO subsystems starts to
1329 probing, nevertheless orthogonal to the GPIO subsystem.
1331 But there are also situations where it makes sense for the GPIO subsystem
1332 to communicate directly with the pinctrl subsystem, using the latter as a
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
1339 If a pin control driver and a GPIO driver is dealing with the same pins
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
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 */,
1379 It is possible to mux a certain function in and out at runtime, say to move
1384 "pos-A" and "pos-B".
1386 This snippet first initializes a state object for both groups (in foo_probe()),
1387 then muxes the function in the pins defined by group A, and finally muxes it in
1402 s1 = pinctrl_lookup_state(foo->p, "pos-A");
1406 s2 = pinctrl_lookup_state(foo->p, "pos-B");
1413 /* Enable on position A */
1430 can be used by different functions at different times on a running system.