linux-3.3/Documentation/pinctrl.txt

6 - Enumerating and naming controllable pins
8 - Multiplexing of pins, pads, fingers (etc) see below for details
10 - Configuration of pins, pads, fingers (etc), such as software-controlled
11   biasing and driving mode specific pins, such as pull-up/down, open drain,
14 Top-level interface
19 - A pin controller is a piece of hardware, usually a set of registers, that
25 - PINS are equal to pads, fingers, balls or whatever packaging input or
29   be sparse - i.e. there may be gaps in the space with numbers where no
91 See for example arch/arm/mach-u300/Kconfig for an example.
100 also consider matching of offsets to the GPIO ranges that may be handled by
158 		return -EINVAL;
190 beginning on 0 until it returns non-zero to determine legal selectors, then
193 just a simple example - in practice you may need more entries in your group
201 Pins can sometimes be software-configured in an various ways, mostly related
205 using a certain resistor value - pull up and pull down - so that the pin has a
211 ret = pin_config_set("foo-dev", "FOO_GPIO_PIN", PLATFORM_X_PULL_UP);
272 they can exploit the special whole-group pin control function. The
273 pin_config_group_set() callback is allowed to return the error code -EAGAIN,
275 group-level handling and then fall through to iterate over all pins, in which
280 Interaction with the GPIO subsystem
283 The GPIO drivers may want to perform operations of various types on the same
288 which pin controller handles control of a certain GPIO pin. Since a single
289 pin controller may be muxing several GPIO ranges (typically SoCs that have
290 one set of pins but internally several GPIO silicon blocks, each modeled as
291 a struct gpio_chip) any number of GPIO ranges can be added to a pin controller
323 GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and
325 GPIO range.
327 The GPIO range of "chip a" starts from the GPIO base of 32 and actual
329 offset for the GPIO range and pin range. The GPIO range of "chip b" starts
330 from GPIO number 48, while the pin range of "chip b" starts from 64.
332 We can convert a gpio number to actual pin number using this "pin_base".
333 They are mapped in the global GPIO pin space at:
336  - GPIO range : [32 .. 47]
337  - pin range  : [32 .. 47]
339  - GPIO range : [48 .. 55]
340  - pin range  : [64 .. 71]
342 When GPIO-specific functions in the pin control subsystem are called, these
345 pin controller handling the matching range is found, GPIO-specific functions
350 in gpio number, and add the ranges's .pin_base offset to retrive a pin number.
377       +---+
383       +---+---+
385       +---+---+               +---+
391       +-------+-------+-------+---+---+
393       +-------+-------+-------+---+---+
396 are chessboard-like, big ones have "holes" in some arrangement according to
408 some general-purpose GPIO pin. However, in another setting, pins { A5, B5 } can
415 special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will
425 Since general-purpose I/O pins (GPIO) are typically always in shortage, it is
426 common to be able to use almost any pin as a GPIO pin if it is not currently
435 in your machine configuration. It is inspired by the clk, GPIO and regulator
436 subsystems, so devices will request their mux setting, but it's also possible
437 to request a single pin for e.g. GPIO.
441 - FUNCTIONS can be switched in and out by a driver residing with the pin
446 - FUNCTIONS are assumed to be enumerable from zero in a one-dimensional array.
450 - FUNCTIONS have PIN GROUPS as defined on the generic level - so a certain
463 - The combination of a FUNCTION and a PIN GROUP determine a certain function
465   and their machine-specific particulars are kept inside the pinmux driver,
468   - Request the name of a function with a certain selector (>= 0)
469   - A list of groups associated with a certain function
470   - Request that a certain group in that list to be activated for a certain
473   As already described above, pin groups are in turn self-descriptive, so
477 - FUNCTIONS and GROUPS on a certain PIN CONTROLLER are MAPPED to a certain
482   of pins is available for the function, no group name need to be supplied -
491     {"map-spi0", spi0, pinctrl0, fspi0, gspi0},
492     {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0}
496   The group is not compulsory - if it is omitted the first group presented by
509 - PINS for a certain FUNCTION using a certain PIN GROUP on a certain
510   PIN CONTROLLER are provided on a first-come first-serve basis, so if some
511   other device mux setting or GPIO pin request has already taken your physical
516 pads (or "fingers") rather than pins - these are the soldering surfaces on the
542 is possible to perform the requested mux setting, poke the hardware so that
547 writing values into some certain registers to activate a certain mux setting
551 into some register named MUX to select a certain function with a certain
607 		return -EINVAL;
664 		return -EINVAL;
687 	writeb((readb(MUX)|regbit), MUX)
696 	writeb((readb(MUX) & ~(regbit)), MUX)
721 things - when it gets a selector passed in, the pinmux subsystem makes
722 sure no other device or GPIO assignment is already using the selected
729 Pinmux interaction with the GPIO subsystem
734 gpiolib-based drivers as part of their gpio_request() and
739 NOTE that platforms and individual drivers shall *NOT* request GPIO pins to be
744 individual pin into a GPIO pin independent of any other pins, and then try
747 In this case, the function array would become 64 entries for each GPIO
751 to enable only GPIO on an individual pin: .gpio_request_enable() and
754 This function will pass in the affected GPIO range identified by the pin
755 controller core, so you know which GPIO pins are being affected by the request
759 GPIO pin shall be used for input or output you can implement the
761 gpiolib driver and the affected GPIO range, pin offset and desired direction
765 named functions for each GPIO pin, the pinmux_request_gpio() will attempt to
766 obtain the function "gpioN" where "N" is the global GPIO pin number if no
767 special GPIO-handler is registered.
775 constrained and how the clock tree looks. Of course pinmux settings are also
786 		.ctrl_dev_name = "pinctrl-foo",
788 		.dev_name = "foo-spi.0",
791 		.ctrl_dev_name = "pinctrl-foo",
793 		.dev_name = "foo-i2c.0",
796 		.ctrl_dev_name = "pinctrl-foo",
798 		.dev_name = "foo-mmc.0",
818 it even more compact which assumes you want to use pinctrl-foo and position
822        PINMUX_MAP("I2CMAP", "pinctrl-foo", "i2c0", "foo-i2c.0"),
834 	.name = "spi0-pos-A",
835 	.ctrl_dev_name = "pinctrl-foo",
838 	.dev_name = "foo-spi.0",
841 	.name = "spi0-pos-B",
842 	.ctrl_dev_name = "pinctrl-foo",
845 	.dev_name = "foo-spi.0",
855 three groups for a total of 2+2+4 = 8 pins (for an 8-bit MMC bus as is the
861 	.ctrl_dev_name = "pinctrl-foo",
864 	.dev_name = "foo-mmc.0",
868 	.ctrl_dev_name = "pinctrl-foo",
871 	.dev_name = "foo-mmc.0",
875 	.ctrl_dev_name = "pinctrl-foo",
878 	.dev_name = "foo-mmc.0",
882 	.ctrl_dev_name = "pinctrl-foo",
884 	.dev_name = "foo-mmc.0",
888 	.ctrl_dev_name = "pinctrl-foo",
891 	.dev_name = "foo-mmc.0",
895 	.ctrl_dev_name = "pinctrl-foo",
898 	.dev_name = "foo-mmc.0",
920 where a driver needs to switch between different mux mappings at runtime
923 A driver may request a certain mux to be activated, usually just the default
924 mux like this:
943 	state->pmx = pmx;
948 	pinmux_disable(state->pmx);
949 	pinmux_put(state->pmx);
952 If you want to grab a specific mux mapping and not just the first one found for
954 example the second i2c0 setting: pinmux_get(&device, "spi0-pos-B");
962 - pinmux_get() is called in process context to reserve the pins affected with
966 - pinmux_enable()/pinmux_disable() is quick and can be called from fastpath
971 - pinmux_disable() is called in process context to tear down the pin requests
972   and release the state holder struct for the mux setting.
977 driver which takes care of activating and/or deactivating the mux setting by
998 	.ctrl_dev_name = "pinctrl-foo",
1003 Since it may be common to request the core to hog a few always-applicable
1004 mux settings on the primary pin controller, there is a convenience macro for
1015 It is possible to mux a certain function in and out at runtime, say to move
1019 "Advanced mapping" above. So we have two mappings named "spi0-pos-A" and
1020 "spi0-pos-B".
1030 	pmx = pinmux_get(&device, "spi0-pos-A");
1040 	pmx = pinmux_get(&device, "spi0-pos-B");