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
26   output line you want to control and these are denoted by unsigned integers
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.
93 Pins usually have fancier names than this. You can find these in the dataheet
105 standard too (all these pads had names, too):
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
203 may be able to make an output pin high impedance, or "tristate" meaning it is
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
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
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
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
460   Group names must be unique per pin controller, no two groups on the same
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
501   without device names are referred to as SYSTEM pinmuxes, such as can be taken
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
516 pads (or "fingers") rather than pins - these are the soldering surfaces on the
607 		return -EINVAL;
664 		return -EINVAL;
721 things - when it gets a selector passed in, the pinmux subsystem makes
734 gpiolib-based drivers as part of their gpio_request() and
735 gpio_free() semantics. Likewise the pinmux_gpio_direction_[input|output]
736 shall only be called from within respective gpio_direction_[input|output]
759 GPIO pin shall be used for input or output you can implement the
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",
943 	state->pmx = pmx;
948 	pinmux_disable(state->pmx);
949 	pinmux_put(state->pmx);
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
998 	.ctrl_dev_name = "pinctrl-foo",
1003 Since it may be common to request the core to hog a few always-applicable
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");