--- /dev/null
+===============================
+PINCTRL (PIN CONTROL) subsystem
+===============================
+
+This document outlines the pin control subsystem in Linux
+
+This subsystem deals with:
+
+- Enumerating and naming controllable pins
+
+- Multiplexing of pins, pads, fingers (etc) see below for details
+
+- Configuration of pins, pads, fingers (etc), such as software-controlled
+ biasing and driving mode specific pins, such as pull-up/down, open drain,
+ load capacitance etc.
+
+Top-level interface
+===================
+
+Definition of PIN CONTROLLER:
+
+- A pin controller is a piece of hardware, usually a set of registers, that
+ can control PINs. It may be able to multiplex, bias, set load capacitance,
+ set drive strength, etc. for individual pins or groups of pins.
+
+Definition of PIN:
+
+- PINS are equal to pads, fingers, balls or whatever packaging input or
+ output line you want to control and these are denoted by unsigned integers
+ in the range 0..maxpin. This numberspace is local to each PIN CONTROLLER, so
+ there may be several such number spaces in a system. This pin space may
+ be sparse - i.e. there may be gaps in the space with numbers where no
+ pin exists.
+
+When a PIN CONTROLLER is instantiated, it will register a descriptor to the
+pin control framework, and this descriptor contains an array of pin descriptors
+describing the pins handled by this specific pin controller.
+
+Here is an example of a PGA (Pin Grid Array) chip seen from underneath::
+
+ A B C D E F G H
+
+ 8 o o o o o o o o
+
+ 7 o o o o o o o o
+
+ 6 o o o o o o o o
+
+ 5 o o o o o o o o
+
+ 4 o o o o o o o o
+
+ 3 o o o o o o o o
+
+ 2 o o o o o o o o
+
+ 1 o o o o o o o o
+
+To register a pin controller and name all the pins on this package we can do
+this in our driver::
+
+ #include <linux/pinctrl/pinctrl.h>
+
+ const struct pinctrl_pin_desc foo_pins[] = {
+ PINCTRL_PIN(0, "A8"),
+ PINCTRL_PIN(1, "B8"),
+ PINCTRL_PIN(2, "C8"),
+ ...
+ PINCTRL_PIN(61, "F1"),
+ PINCTRL_PIN(62, "G1"),
+ PINCTRL_PIN(63, "H1"),
+ };
+
+ static struct pinctrl_desc foo_desc = {
+ .name = "foo",
+ .pins = foo_pins,
+ .npins = ARRAY_SIZE(foo_pins),
+ .owner = THIS_MODULE,
+ };
+
+ int __init foo_probe(void)
+ {
+ int error;
+
+ struct pinctrl_dev *pctl;
+
+ error = pinctrl_register_and_init(&foo_desc, <PARENT>,
+ NULL, &pctl);
+ if (error)
+ return error;
+
+ return pinctrl_enable(pctl);
+ }
+
+To enable the pinctrl subsystem and the subgroups for PINMUX and PINCONF and
+selected drivers, you need to select them from your machine's Kconfig entry,
+since these are so tightly integrated with the machines they are used on.
+See for example arch/arm/mach-u300/Kconfig for an example.
+
+Pins usually have fancier names than this. You can find these in the datasheet
+for your chip. Notice that the core pinctrl.h file provides a fancy macro
+called PINCTRL_PIN() to create the struct entries. As you can see I enumerated
+the pins from 0 in the upper left corner to 63 in the lower right corner.
+This enumeration was arbitrarily chosen, in practice you need to think
+through your numbering system so that it matches the layout of registers
+and such things in your driver, or the code may become complicated. You must
+also consider matching of offsets to the GPIO ranges that may be handled by
+the pin controller.
+
+For a padring with 467 pads, as opposed to actual pins, I used an enumeration
+like this, walking around the edge of the chip, which seems to be industry
+standard too (all these pads had names, too)::
+
+
+ 0 ..... 104
+ 466 105
+ . .
+ . .
+ 358 224
+ 357 .... 225
+
+
+Pin groups
+==========
+
+Many controllers need to deal with groups of pins, so the pin controller
+subsystem has a mechanism for enumerating groups of pins and retrieving the
+actual enumerated pins that are part of a certain group.
+
+For example, say that we have a group of pins dealing with an SPI interface
+on { 0, 8, 16, 24 }, and a group of pins dealing with an I2C interface on pins
+on { 24, 25 }.
+
+These two groups are presented to the pin control subsystem by implementing
+some generic pinctrl_ops like this::
+
+ #include <linux/pinctrl/pinctrl.h>
+
+ struct foo_group {
+ const char *name;
+ const unsigned int *pins;
+ const unsigned num_pins;
+ };
+
+ static const unsigned int spi0_pins[] = { 0, 8, 16, 24 };
+ static const unsigned int i2c0_pins[] = { 24, 25 };
+
+ static const struct foo_group foo_groups[] = {
+ {
+ .name = "spi0_grp",
+ .pins = spi0_pins,
+ .num_pins = ARRAY_SIZE(spi0_pins),
+ },
+ {
+ .name = "i2c0_grp",
+ .pins = i2c0_pins,
+ .num_pins = ARRAY_SIZE(i2c0_pins),
+ },
+ };
+
+
+ static int foo_get_groups_count(struct pinctrl_dev *pctldev)
+ {
+ return ARRAY_SIZE(foo_groups);
+ }
+
+ static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
+ unsigned selector)
+ {
+ return foo_groups[selector].name;
+ }
+
+ static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
+ const unsigned **pins,
+ unsigned *num_pins)
+ {
+ *pins = (unsigned *) foo_groups[selector].pins;
+ *num_pins = foo_groups[selector].num_pins;
+ return 0;
+ }
+
+ static struct pinctrl_ops foo_pctrl_ops = {
+ .get_groups_count = foo_get_groups_count,
+ .get_group_name = foo_get_group_name,
+ .get_group_pins = foo_get_group_pins,
+ };
+
+
+ static struct pinctrl_desc foo_desc = {
+ ...
+ .pctlops = &foo_pctrl_ops,
+ };
+
+The pin control subsystem will call the .get_groups_count() function to
+determine the total number of legal selectors, then it will call the other functions
+to retrieve the name and pins of the group. Maintaining the data structure of
+the groups is up to the driver, this is just a simple example - in practice you
+may need more entries in your group structure, for example specific register
+ranges associated with each group and so on.
+
+
+Pin configuration
+=================
+
+Pins can sometimes be software-configured in various ways, mostly related
+to their electronic properties when used as inputs or outputs. For example you
+may be able to make an output pin high impedance, or "tristate" meaning it is
+effectively disconnected. You may be able to connect an input pin to VDD or GND
+using a certain resistor value - pull up and pull down - so that the pin has a
+stable value when nothing is driving the rail it is connected to, or when it's
+unconnected.
+
+Pin configuration can be programmed by adding configuration entries into the
+mapping table; see section "Board/machine configuration" below.
+
+The format and meaning of the configuration parameter, PLATFORM_X_PULL_UP
+above, is entirely defined by the pin controller driver.
+
+The pin configuration driver implements callbacks for changing pin
+configuration in the pin controller ops like this::
+
+ #include <linux/pinctrl/pinctrl.h>
+ #include <linux/pinctrl/pinconf.h>
+ #include "platform_x_pindefs.h"
+
+ static int foo_pin_config_get(struct pinctrl_dev *pctldev,
+ unsigned offset,
+ unsigned long *config)
+ {
+ struct my_conftype conf;
+
+ ... Find setting for pin @ offset ...
+
+ *config = (unsigned long) conf;
+ }
+
+ static int foo_pin_config_set(struct pinctrl_dev *pctldev,
+ unsigned offset,
+ unsigned long config)
+ {
+ struct my_conftype *conf = (struct my_conftype *) config;
+
+ switch (conf) {
+ case PLATFORM_X_PULL_UP:
+ ...
+ }
+ }
+ }
+
+ static int foo_pin_config_group_get (struct pinctrl_dev *pctldev,
+ unsigned selector,
+ unsigned long *config)
+ {
+ ...
+ }
+
+ static int foo_pin_config_group_set (struct pinctrl_dev *pctldev,
+ unsigned selector,
+ unsigned long config)
+ {
+ ...
+ }
+
+ static struct pinconf_ops foo_pconf_ops = {
+ .pin_config_get = foo_pin_config_get,
+ .pin_config_set = foo_pin_config_set,
+ .pin_config_group_get = foo_pin_config_group_get,
+ .pin_config_group_set = foo_pin_config_group_set,
+ };
+
+ /* Pin config operations are handled by some pin controller */
+ static struct pinctrl_desc foo_desc = {
+ ...
+ .confops = &foo_pconf_ops,
+ };
+
+Since some controllers have special logic for handling entire groups of pins
+they can exploit the special whole-group pin control function. The
+pin_config_group_set() callback is allowed to return the error code -EAGAIN,
+for groups it does not want to handle, or if it just wants to do some
+group-level handling and then fall through to iterate over all pins, in which
+case each individual pin will be treated by separate pin_config_set() calls as
+well.
+
+
+Interaction with the GPIO subsystem
+===================================
+
+The GPIO drivers may want to perform operations of various types on the same
+physical pins that are also registered as pin controller pins.
+
+First and foremost, the two subsystems can be used as completely orthogonal,
+see the section named "pin control requests from drivers" and
+"drivers needing both pin control and GPIOs" below for details. But in some
+situations a cross-subsystem mapping between pins and GPIOs is needed.
+
+Since the pin controller subsystem has its pinspace local to the pin controller
+we need a mapping so that the pin control subsystem can figure out which pin
+controller handles control of a certain GPIO pin. Since a single pin controller
+may be muxing several GPIO ranges (typically SoCs that have one set of pins,
+but internally several GPIO silicon blocks, each modelled as a struct
+gpio_chip) any number of GPIO ranges can be added to a pin controller instance
+like this::
+
+ struct gpio_chip chip_a;
+ struct gpio_chip chip_b;
+
+ static struct pinctrl_gpio_range gpio_range_a = {
+ .name = "chip a",
+ .id = 0,
+ .base = 32,
+ .pin_base = 32,
+ .npins = 16,
+ .gc = &chip_a;
+ };
+
+ static struct pinctrl_gpio_range gpio_range_b = {
+ .name = "chip b",
+ .id = 0,
+ .base = 48,
+ .pin_base = 64,
+ .npins = 8,
+ .gc = &chip_b;
+ };
+
+ {
+ struct pinctrl_dev *pctl;
+ ...
+ pinctrl_add_gpio_range(pctl, &gpio_range_a);
+ pinctrl_add_gpio_range(pctl, &gpio_range_b);
+ }
+
+So this complex system has one pin controller handling two different
+GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and
+"chip b" have different .pin_base, which means a start pin number of the
+GPIO range.
+
+The GPIO range of "chip a" starts from the GPIO base of 32 and actual
+pin range also starts from 32. However "chip b" has different starting
+offset for the GPIO range and pin range. The GPIO range of "chip b" starts
+from GPIO number 48, while the pin range of "chip b" starts from 64.
+
+We can convert a gpio number to actual pin number using this "pin_base".
+They are mapped in the global GPIO pin space at:
+
+chip a:
+ - GPIO range : [32 .. 47]
+ - pin range : [32 .. 47]
+chip b:
+ - GPIO range : [48 .. 55]
+ - pin range : [64 .. 71]
+
+The above examples assume the mapping between the GPIOs and pins is
+linear. If the mapping is sparse or haphazard, an array of arbitrary pin
+numbers can be encoded in the range like this::
+
+ static const unsigned range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 };
+
+ static struct pinctrl_gpio_range gpio_range = {
+ .name = "chip",
+ .id = 0,
+ .base = 32,
+ .pins = &range_pins,
+ .npins = ARRAY_SIZE(range_pins),
+ .gc = &chip;
+ };
+
+In this case the pin_base property will be ignored. If the name of a pin
+group is known, the pins and npins elements of the above structure can be
+initialised using the function pinctrl_get_group_pins(), e.g. for pin
+group "foo"::
+
+ pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins,
+ &gpio_range.npins);
+
+When GPIO-specific functions in the pin control subsystem are called, these
+ranges will be used to look up the appropriate pin controller by inspecting
+and matching the pin to the pin ranges across all controllers. When a
+pin controller handling the matching range is found, GPIO-specific functions
+will be called on that specific pin controller.
+
+For all functionalities dealing with pin biasing, pin muxing etc, the pin
+controller subsystem will look up the corresponding pin number from the passed
+in gpio number, and use the range's internals to retrieve a pin number. After
+that, the subsystem passes it on to the pin control driver, so the driver
+will get a pin number into its handled number range. Further it is also passed
+the range ID value, so that the pin controller knows which range it should
+deal with.
+
+Calling pinctrl_add_gpio_range from pinctrl driver is DEPRECATED. Please see
+section 2.1 of Documentation/devicetree/bindings/gpio/gpio.txt on how to bind
+pinctrl and gpio drivers.
+
+
+PINMUX interfaces
+=================
+
+These calls use the pinmux_* naming prefix. No other calls should use that
+prefix.
+
+
+What is pinmuxing?
+==================
+
+PINMUX, also known as padmux, ballmux, alternate functions or mission modes
+is a way for chip vendors producing some kind of electrical packages to use
+a certain physical pin (ball, pad, finger, etc) for multiple mutually exclusive
+functions, depending on the application. By "application" in this context
+we usually mean a way of soldering or wiring the package into an electronic
+system, even though the framework makes it possible to also change the function
+at runtime.
+
+Here is an example of a PGA (Pin Grid Array) chip seen from underneath::
+
+ A B C D E F G H
+ +---+
+ 8 | o | o o o o o o o
+ | |
+ 7 | o | o o o o o o o
+ | |
+ 6 | o | o o o o o o o
+ +---+---+
+ 5 | o | o | o o o o o o
+ +---+---+ +---+
+ 4 o o o o o o | o | o
+ | |
+ 3 o o o o o o | o | o
+ | |
+ 2 o o o o o o | o | o
+ +-------+-------+-------+---+---+
+ 1 | o o | o o | o o | o | o |
+ +-------+-------+-------+---+---+
+
+This is not tetris. The game to think of is chess. Not all PGA/BGA packages
+are chessboard-like, big ones have "holes" in some arrangement according to
+different design patterns, but we're using this as a simple example. Of the
+pins you see some will be taken by things like a few VCC and GND to feed power
+to the chip, and quite a few will be taken by large ports like an external
+memory interface. The remaining pins will often be subject to pin multiplexing.
+
+The example 8x8 PGA package above will have pin numbers 0 through 63 assigned
+to its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using
+pinctrl_register_pins() and a suitable data set as shown earlier.
+
+In this 8x8 BGA package the pins { A8, A7, A6, A5 } can be used as an SPI port
+(these are four pins: CLK, RXD, TXD, FRM). In that case, pin B5 can be used as
+some general-purpose GPIO pin. However, in another setting, pins { A5, B5 } can
+be used as an I2C port (these are just two pins: SCL, SDA). Needless to say,
+we cannot use the SPI port and I2C port at the same time. However in the inside
+of the package the silicon performing the SPI logic can alternatively be routed
+out on pins { G4, G3, G2, G1 }.
+
+On the bottom row at { A1, B1, C1, D1, E1, F1, G1, H1 } we have something
+special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will
+consume 2, 4 or 8 pins respectively, so either { A1, B1 } are taken or
+{ A1, B1, C1, D1 } or all of them. If we use all 8 bits, we cannot use the SPI
+port on pins { G4, G3, G2, G1 } of course.
+
+This way the silicon blocks present inside the chip can be multiplexed "muxed"
+out on different pin ranges. Often contemporary SoC (systems on chip) will
+contain several I2C, SPI, SDIO/MMC, etc silicon blocks that can be routed to
+different pins by pinmux settings.
+
+Since general-purpose I/O pins (GPIO) are typically always in shortage, it is
+common to be able to use almost any pin as a GPIO pin if it is not currently
+in use by some other I/O port.
+
+
+Pinmux conventions
+==================
+
+The purpose of the pinmux functionality in the pin controller subsystem is to
+abstract and provide pinmux settings to the devices you choose to instantiate
+in your machine configuration. It is inspired by the clk, GPIO and regulator
+subsystems, so devices will request their mux setting, but it's also possible
+to request a single pin for e.g. GPIO.
+
+Definitions:
+
+- FUNCTIONS can be switched in and out by a driver residing with the pin
+ control subsystem in the drivers/pinctrl/* directory of the kernel. The
+ pin control driver knows the possible functions. In the example above you can
+ identify three pinmux functions, one for spi, one for i2c and one for mmc.
+
+- FUNCTIONS are assumed to be enumerable from zero in a one-dimensional array.
+ In this case the array could be something like: { spi0, i2c0, mmc0 }
+ for the three available functions.
+
+- FUNCTIONS have PIN GROUPS as defined on the generic level - so a certain
+ function is *always* associated with a certain set of pin groups, could
+ be just a single one, but could also be many. In the example above the
+ function i2c is associated with the pins { A5, B5 }, enumerated as
+ { 24, 25 } in the controller pin space.
+
+ The Function spi is associated with pin groups { A8, A7, A6, A5 }
+ and { G4, G3, G2, G1 }, which are enumerated as { 0, 8, 16, 24 } and
+ { 38, 46, 54, 62 } respectively.
+
+ Group names must be unique per pin controller, no two groups on the same
+ controller may have the same name.
+
+- The combination of a FUNCTION and a PIN GROUP determine a certain function
+ for a certain set of pins. The knowledge of the functions and pin groups
+ and their machine-specific particulars are kept inside the pinmux driver,
+ from the outside only the enumerators are known, and the driver core can
+ request:
+
+ - The name of a function with a certain selector (>= 0)
+ - A list of groups associated with a certain function
+ - That a certain group in that list to be activated for a certain function
+
+ As already described above, pin groups are in turn self-descriptive, so
+ the core will retrieve the actual pin range in a certain group from the
+ driver.
+
+- FUNCTIONS and GROUPS on a certain PIN CONTROLLER are MAPPED to a certain
+ device by the board file, device tree or similar machine setup configuration
+ mechanism, similar to how regulators are connected to devices, usually by
+ name. Defining a pin controller, function and group thus uniquely identify
+ the set of pins to be used by a certain device. (If only one possible group
+ of pins is available for the function, no group name need to be supplied -
+ the core will simply select the first and only group available.)
+
+ In the example case we can define that this particular machine shall
+ use device spi0 with pinmux function fspi0 group gspi0 and i2c0 on function
+ fi2c0 group gi2c0, on the primary pin controller, we get mappings
+ like these::
+
+ {
+ {"map-spi0", spi0, pinctrl0, fspi0, gspi0},
+ {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0}
+ }
+
+ Every map must be assigned a state name, pin controller, device and
+ function. The group is not compulsory - if it is omitted the first group
+ presented by the driver as applicable for the function will be selected,
+ which is useful for simple cases.
+
+ It is possible to map several groups to the same combination of device,
+ pin controller and function. This is for cases where a certain function on
+ a certain pin controller may use different sets of pins in different
+ configurations.
+
+- PINS for a certain FUNCTION using a certain PIN GROUP on a certain
+ PIN CONTROLLER are provided on a first-come first-serve basis, so if some
+ other device mux setting or GPIO pin request has already taken your physical
+ pin, you will be denied the use of it. To get (activate) a new setting, the
+ old one has to be put (deactivated) first.
+
+Sometimes the documentation and hardware registers will be oriented around
+pads (or "fingers") rather than pins - these are the soldering surfaces on the
+silicon inside the package, and may or may not match the actual number of
+pins/balls underneath the capsule. Pick some enumeration that makes sense to
+you. Define enumerators only for the pins you can control if that makes sense.
+
+Assumptions:
+
+We assume that the number of possible function maps to pin groups is limited by
+the hardware. I.e. we assume that there is no system where any function can be
+mapped to any pin, like in a phone exchange. So the available pin groups for
+a certain function will be limited to a few choices (say up to eight or so),
+not hundreds or any amount of choices. This is the characteristic we have found
+by inspecting available pinmux hardware, and a necessary assumption since we
+expect pinmux drivers to present *all* possible function vs pin group mappings
+to the subsystem.
+
+
+Pinmux drivers
+==============
+
+The pinmux core takes care of preventing conflicts on pins and calling
+the pin controller driver to execute different settings.
+
+It is the responsibility of the pinmux driver to impose further restrictions
+(say for example infer electronic limitations due to load, etc.) to determine
+whether or not the requested function can actually be allowed, and in case it
+is possible to perform the requested mux setting, poke the hardware so that
+this happens.
+
+Pinmux drivers are required to supply a few callback functions, some are
+optional. Usually the set_mux() function is implemented, writing values into
+some certain registers to activate a certain mux setting for a certain pin.
+
+A simple driver for the above example will work by setting bits 0, 1, 2, 3 or 4
+into some register named MUX to select a certain function with a certain
+group of pins would work something like this::
+
+ #include <linux/pinctrl/pinctrl.h>
+ #include <linux/pinctrl/pinmux.h>
+
+ struct foo_group {
+ const char *name;
+ const unsigned int *pins;
+ const unsigned num_pins;
+ };
+
+ static const unsigned spi0_0_pins[] = { 0, 8, 16, 24 };
+ static const unsigned spi0_1_pins[] = { 38, 46, 54, 62 };
+ static const unsigned i2c0_pins[] = { 24, 25 };
+ static const unsigned mmc0_1_pins[] = { 56, 57 };
+ static const unsigned mmc0_2_pins[] = { 58, 59 };
+ static const unsigned mmc0_3_pins[] = { 60, 61, 62, 63 };
+
+ static const struct foo_group foo_groups[] = {
+ {
+ .name = "spi0_0_grp",
+ .pins = spi0_0_pins,
+ .num_pins = ARRAY_SIZE(spi0_0_pins),
+ },
+ {
+ .name = "spi0_1_grp",
+ .pins = spi0_1_pins,
+ .num_pins = ARRAY_SIZE(spi0_1_pins),
+ },
+ {
+ .name = "i2c0_grp",
+ .pins = i2c0_pins,
+ .num_pins = ARRAY_SIZE(i2c0_pins),
+ },
+ {
+ .name = "mmc0_1_grp",
+ .pins = mmc0_1_pins,
+ .num_pins = ARRAY_SIZE(mmc0_1_pins),
+ },
+ {
+ .name = "mmc0_2_grp",
+ .pins = mmc0_2_pins,
+ .num_pins = ARRAY_SIZE(mmc0_2_pins),
+ },
+ {
+ .name = "mmc0_3_grp",
+ .pins = mmc0_3_pins,
+ .num_pins = ARRAY_SIZE(mmc0_3_pins),
+ },
+ };
+
+
+ static int foo_get_groups_count(struct pinctrl_dev *pctldev)
+ {
+ return ARRAY_SIZE(foo_groups);
+ }
+
+ static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
+ unsigned selector)
+ {
+ return foo_groups[selector].name;
+ }
+
+ static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
+ unsigned ** const pins,
+ unsigned * const num_pins)
+ {
+ *pins = (unsigned *) foo_groups[selector].pins;
+ *num_pins = foo_groups[selector].num_pins;
+ return 0;
+ }
+
+ static struct pinctrl_ops foo_pctrl_ops = {
+ .get_groups_count = foo_get_groups_count,
+ .get_group_name = foo_get_group_name,
+ .get_group_pins = foo_get_group_pins,
+ };
+
+ struct foo_pmx_func {
+ const char *name;
+ const char * const *groups;
+ const unsigned num_groups;
+ };
+
+ static const char * const spi0_groups[] = { "spi0_0_grp", "spi0_1_grp" };
+ static const char * const i2c0_groups[] = { "i2c0_grp" };
+ static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp",
+ "mmc0_3_grp" };
+
+ static const struct foo_pmx_func foo_functions[] = {
+ {
+ .name = "spi0",
+ .groups = spi0_groups,
+ .num_groups = ARRAY_SIZE(spi0_groups),
+ },
+ {
+ .name = "i2c0",
+ .groups = i2c0_groups,
+ .num_groups = ARRAY_SIZE(i2c0_groups),
+ },
+ {
+ .name = "mmc0",
+ .groups = mmc0_groups,
+ .num_groups = ARRAY_SIZE(mmc0_groups),
+ },
+ };
+
+ static int foo_get_functions_count(struct pinctrl_dev *pctldev)
+ {
+ return ARRAY_SIZE(foo_functions);
+ }
+
+ static const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector)
+ {
+ return foo_functions[selector].name;
+ }
+
+ static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector,
+ const char * const **groups,
+ unsigned * const num_groups)
+ {
+ *groups = foo_functions[selector].groups;
+ *num_groups = foo_functions[selector].num_groups;
+ return 0;
+ }
+
+ static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned selector,
+ unsigned group)
+ {
+ u8 regbit = (1 << selector + group);
+
+ writeb((readb(MUX)|regbit), MUX)
+ return 0;
+ }
+
+ static struct pinmux_ops foo_pmxops = {
+ .get_functions_count = foo_get_functions_count,
+ .get_function_name = foo_get_fname,
+ .get_function_groups = foo_get_groups,
+ .set_mux = foo_set_mux,
+ .strict = true,
+ };
+
+ /* Pinmux operations are handled by some pin controller */
+ static struct pinctrl_desc foo_desc = {
+ ...
+ .pctlops = &foo_pctrl_ops,
+ .pmxops = &foo_pmxops,
+ };
+
+In the example activating muxing 0 and 1 at the same time setting bits
+0 and 1, uses one pin in common so they would collide.
+
+The beauty of the pinmux subsystem is that since it keeps track of all
+pins and who is using them, it will already have denied an impossible
+request like that, so the driver does not need to worry about such
+things - when it gets a selector passed in, the pinmux subsystem makes
+sure no other device or GPIO assignment is already using the selected
+pins. Thus bits 0 and 1 in the control register will never be set at the
+same time.
+
+All the above functions are mandatory to implement for a pinmux driver.
+
+
+Pin control interaction with the GPIO subsystem
+===============================================
+
+Note that the following implies that the use case is to use a certain pin
+from the Linux kernel using the API in <linux/gpio.h> with gpio_request()
+and similar functions. There are cases where you may be using something
+that your datasheet calls "GPIO mode", but actually is just an electrical
+configuration for a certain device. See the section below named
+"GPIO mode pitfalls" for more details on this scenario.
+
+The public pinmux API contains two functions named pinctrl_request_gpio()
+and pinctrl_free_gpio(). These two functions shall *ONLY* be called from
+gpiolib-based drivers as part of their gpio_request() and
+gpio_free() semantics. Likewise the pinctrl_gpio_direction_[input|output]
+shall only be called from within respective gpio_direction_[input|output]
+gpiolib implementation.
+
+NOTE that platforms and individual drivers shall *NOT* request GPIO pins to be
+controlled e.g. muxed in. Instead, implement a proper gpiolib driver and have
+that driver request proper muxing and other control for its pins.
+
+The function list could become long, especially if you can convert every
+individual pin into a GPIO pin independent of any other pins, and then try
+the approach to define every pin as a function.
+
+In this case, the function array would become 64 entries for each GPIO
+setting and then the device functions.
+
+For this reason there are two functions a pin control driver can implement
+to enable only GPIO on an individual pin: .gpio_request_enable() and
+.gpio_disable_free().
+
+This function will pass in the affected GPIO range identified by the pin
+controller core, so you know which GPIO pins are being affected by the request
+operation.
+
+If your driver needs to have an indication from the framework of whether the
+GPIO pin shall be used for input or output you can implement the
+.gpio_set_direction() function. As described this shall be called from the
+gpiolib driver and the affected GPIO range, pin offset and desired direction
+will be passed along to this function.
+
+Alternatively to using these special functions, it is fully allowed to use
+named functions for each GPIO pin, the pinctrl_request_gpio() will attempt to
+obtain the function "gpioN" where "N" is the global GPIO pin number if no
+special GPIO-handler is registered.
+
+
+GPIO mode pitfalls
+==================
+
+Due to the naming conventions used by hardware engineers, where "GPIO"
+is taken to mean different things than what the kernel does, the developer
+may be confused by a datasheet talking about a pin being possible to set
+into "GPIO mode". It appears that what hardware engineers mean with
+"GPIO mode" is not necessarily the use case that is implied in the kernel
+interface <linux/gpio.h>: a pin that you grab from kernel code and then
+either listen for input or drive high/low to assert/deassert some
+external line.
+
+Rather hardware engineers think that "GPIO mode" means that you can
+software-control a few electrical properties of the pin that you would
+not be able to control if the pin was in some other mode, such as muxed in
+for a device.
+
+The GPIO portions of a pin and its relation to a certain pin controller
+configuration and muxing logic can be constructed in several ways. Here
+are two examples::
+
+ (A)
+ pin config
+ logic regs
+ | +- SPI
+ Physical pins --- pad --- pinmux -+- I2C
+ | +- mmc
+ | +- GPIO
+ pin
+ multiplex
+ logic regs
+
+Here some electrical properties of the pin can be configured no matter
+whether the pin is used for GPIO or not. If you multiplex a GPIO onto a
+pin, you can also drive it high/low from "GPIO" registers.
+Alternatively, the pin can be controlled by a certain peripheral, while
+still applying desired pin config properties. GPIO functionality is thus
+orthogonal to any other device using the pin.
+
+In this arrangement the registers for the GPIO portions of the pin controller,
+or the registers for the GPIO hardware module are likely to reside in a
+separate memory range only intended for GPIO driving, and the register
+range dealing with pin config and pin multiplexing get placed into a
+different memory range and a separate section of the data sheet.
+
+A flag "strict" in struct pinmux_ops is available to check and deny
+simultaneous access to the same pin from GPIO and pin multiplexing
+consumers on hardware of this type. The pinctrl driver should set this flag
+accordingly.
+
+::
+
+ (B)
+
+ pin config
+ logic regs
+ | +- SPI
+ Physical pins --- pad --- pinmux -+- I2C
+ | | +- mmc
+ | |
+ GPIO pin
+ multiplex
+ logic regs
+
+In this arrangement, the GPIO functionality can always be enabled, such that
+e.g. a GPIO input can be used to "spy" on the SPI/I2C/MMC signal while it is
+pulsed out. It is likely possible to disrupt the traffic on the pin by doing
+wrong things on the GPIO block, as it is never really disconnected. It is
+possible that the GPIO, pin config and pin multiplex registers are placed into
+the same memory range and the same section of the data sheet, although that
+need not be the case.
+
+In some pin controllers, although the physical pins are designed in the same
+way as (B), the GPIO function still can't be enabled at the same time as the
+peripheral functions. So again the "strict" flag should be set, denying
+simultaneous activation by GPIO and other muxed in devices.
+
+From a kernel point of view, however, these are different aspects of the
+hardware and shall be put into different subsystems:
+
+- Registers (or fields within registers) that control electrical
+ properties of the pin such as biasing and drive strength should be
+ exposed through the pinctrl subsystem, as "pin configuration" settings.
+
+- Registers (or fields within registers) that control muxing of signals
+ from various other HW blocks (e.g. I2C, MMC, or GPIO) onto pins should
+ be exposed through the pinctrl subsystem, as mux functions.
+
+- Registers (or fields within registers) that control GPIO functionality
+ such as setting a GPIO's output value, reading a GPIO's input value, or
+ setting GPIO pin direction should be exposed through the GPIO subsystem,
+ and if they also support interrupt capabilities, through the irqchip
+ abstraction.
+
+Depending on the exact HW register design, some functions exposed by the
+GPIO subsystem may call into the pinctrl subsystem in order to
+co-ordinate register settings across HW modules. In particular, this may
+be needed for HW with separate GPIO and pin controller HW modules, where
+e.g. GPIO direction is determined by a register in the pin controller HW
+module rather than the GPIO HW module.
+
+Electrical properties of the pin such as biasing and drive strength
+may be placed at some pin-specific register in all cases or as part
+of the GPIO register in case (B) especially. This doesn't mean that such
+properties necessarily pertain to what the Linux kernel calls "GPIO".
+
+Example: a pin is usually muxed in to be used as a UART TX line. But during
+system sleep, we need to put this pin into "GPIO mode" and ground it.
+
+If you make a 1-to-1 map to the GPIO subsystem for this pin, you may start
+to think that you need to come up with something really complex, that the
+pin shall be used for UART TX and GPIO at the same time, that you will grab
+a pin control handle and set it to a certain state to enable UART TX to be
+muxed in, then twist it over to GPIO mode and use gpio_direction_output()
+to drive it low during sleep, then mux it over to UART TX again when you
+wake up and maybe even gpio_request/gpio_free as part of this cycle. This
+all gets very complicated.
+
+The solution is to not think that what the datasheet calls "GPIO mode"
+has to be handled by the <linux/gpio.h> interface. Instead view this as
+a certain pin config setting. Look in e.g. <linux/pinctrl/pinconf-generic.h>
+and you find this in the documentation:
+
+ PIN_CONFIG_OUTPUT:
+ this will configure the pin in output, use argument
+ 1 to indicate high level, argument 0 to indicate low level.
+
+So it is perfectly possible to push a pin into "GPIO mode" and drive the
+line low as part of the usual pin control map. So for example your UART
+driver may look like this::
+
+ #include <linux/pinctrl/consumer.h>
+
+ struct pinctrl *pinctrl;
+ struct pinctrl_state *pins_default;
+ struct pinctrl_state *pins_sleep;
+
+ pins_default = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_DEFAULT);
+ pins_sleep = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_SLEEP);
+
+ /* Normal mode */
+ retval = pinctrl_select_state(pinctrl, pins_default);
+ /* Sleep mode */
+ retval = pinctrl_select_state(pinctrl, pins_sleep);
+
+And your machine configuration may look like this:
+--------------------------------------------------
+
+::
+
+ static unsigned long uart_default_mode[] = {
+ PIN_CONF_PACKED(PIN_CONFIG_DRIVE_PUSH_PULL, 0),
+ };
+
+ static unsigned long uart_sleep_mode[] = {
+ PIN_CONF_PACKED(PIN_CONFIG_OUTPUT, 0),
+ };
+
+ static struct pinctrl_map pinmap[] __initdata = {
+ PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
+ "u0_group", "u0"),
+ PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
+ "UART_TX_PIN", uart_default_mode),
+ PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
+ "u0_group", "gpio-mode"),
+ PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
+ "UART_TX_PIN", uart_sleep_mode),
+ };
+
+ foo_init(void) {
+ pinctrl_register_mappings(pinmap, ARRAY_SIZE(pinmap));
+ }
+
+Here the pins we want to control are in the "u0_group" and there is some
+function called "u0" that can be enabled on this group of pins, and then
+everything is UART business as usual. But there is also some function
+named "gpio-mode" that can be mapped onto the same pins to move them into
+GPIO mode.
+
+This will give the desired effect without any bogus interaction with the
+GPIO subsystem. It is just an electrical configuration used by that device
+when going to sleep, it might imply that the pin is set into something the
+datasheet calls "GPIO mode", but that is not the point: it is still used
+by that UART device to control the pins that pertain to that very UART
+driver, putting them into modes needed by the UART. GPIO in the Linux
+kernel sense are just some 1-bit line, and is a different use case.
+
+How the registers are poked to attain the push or pull, and output low
+configuration and the muxing of the "u0" or "gpio-mode" group onto these
+pins is a question for the driver.
+
+Some datasheets will be more helpful and refer to the "GPIO mode" as
+"low power mode" rather than anything to do with GPIO. This often means
+the same thing electrically speaking, but in this latter case the
+software engineers will usually quickly identify that this is some
+specific muxing or configuration rather than anything related to the GPIO
+API.
+
+
+Board/machine configuration
+===========================
+
+Boards and machines define how a certain complete running system is put
+together, including how GPIOs and devices are muxed, how regulators are
+constrained and how the clock tree looks. Of course pinmux settings are also
+part of this.
+
+A pin controller configuration for a machine looks pretty much like a simple
+regulator configuration, so for the example array above we want to enable i2c
+and spi on the second function mapping::
+
+ #include <linux/pinctrl/machine.h>
+
+ static const struct pinctrl_map mapping[] __initconst = {
+ {
+ .dev_name = "foo-spi.0",
+ .name = PINCTRL_STATE_DEFAULT,
+ .type = PIN_MAP_TYPE_MUX_GROUP,
+ .ctrl_dev_name = "pinctrl-foo",
+ .data.mux.function = "spi0",
+ },
+ {
+ .dev_name = "foo-i2c.0",
+ .name = PINCTRL_STATE_DEFAULT,
+ .type = PIN_MAP_TYPE_MUX_GROUP,
+ .ctrl_dev_name = "pinctrl-foo",
+ .data.mux.function = "i2c0",
+ },
+ {
+ .dev_name = "foo-mmc.0",
+ .name = PINCTRL_STATE_DEFAULT,
+ .type = PIN_MAP_TYPE_MUX_GROUP,
+ .ctrl_dev_name = "pinctrl-foo",
+ .data.mux.function = "mmc0",
+ },
+ };
+
+The dev_name here matches to the unique device name that can be used to look
+up the device struct (just like with clockdev or regulators). The function name
+must match a function provided by the pinmux driver handling this pin range.
+
+As you can see we may have several pin controllers on the system and thus
+we need to specify which one of them contains the functions we wish to map.
+
+You register this pinmux mapping to the pinmux subsystem by simply::
+
+ ret = pinctrl_register_mappings(mapping, ARRAY_SIZE(mapping));
+
+Since the above construct is pretty common there is a helper macro to make
+it even more compact which assumes you want to use pinctrl-foo and position
+0 for mapping, for example::
+
+ static struct pinctrl_map mapping[] __initdata = {
+ PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT,
+ "pinctrl-foo", NULL, "i2c0"),
+ };
+
+The mapping table may also contain pin configuration entries. It's common for
+each pin/group to have a number of configuration entries that affect it, so
+the table entries for configuration reference an array of config parameters
+and values. An example using the convenience macros is shown below::
+
+ static unsigned long i2c_grp_configs[] = {
+ FOO_PIN_DRIVEN,
+ FOO_PIN_PULLUP,
+ };
+
+ static unsigned long i2c_pin_configs[] = {
+ FOO_OPEN_COLLECTOR,
+ FOO_SLEW_RATE_SLOW,
+ };
+
+ static struct pinctrl_map mapping[] __initdata = {
+ PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
+ "pinctrl-foo", "i2c0", "i2c0"),
+ PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
+ "pinctrl-foo", "i2c0", i2c_grp_configs),
+ PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,
+ "pinctrl-foo", "i2c0scl", i2c_pin_configs),
+ PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,
+ "pinctrl-foo", "i2c0sda", i2c_pin_configs),
+ };
+
+Finally, some devices expect the mapping table to contain certain specific
+named states. When running on hardware that doesn't need any pin controller
+configuration, the mapping table must still contain those named states, in
+order to explicitly indicate that the states were provided and intended to
+be empty. Table entry macro PIN_MAP_DUMMY_STATE serves the purpose of defining
+a named state without causing any pin controller to be programmed::
+
+ static struct pinctrl_map mapping[] __initdata = {
+ PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),
+ };
+
+
+Complex mappings
+================
+
+As it is possible to map a function to different groups of pins an optional
+.group can be specified like this::
+
+ ...
+ {
+ .dev_name = "foo-spi.0",
+ .name = "spi0-pos-A",
+ .type = PIN_MAP_TYPE_MUX_GROUP,
+ .ctrl_dev_name = "pinctrl-foo",
+ .function = "spi0",
+ .group = "spi0_0_grp",
+ },
+ {
+ .dev_name = "foo-spi.0",
+ .name = "spi0-pos-B",
+ .type = PIN_MAP_TYPE_MUX_GROUP,
+ .ctrl_dev_name = "pinctrl-foo",
+ .function = "spi0",
+ .group = "spi0_1_grp",
+ },
+ ...
+
+This example mapping is used to switch between two positions for spi0 at
+runtime, as described further below under the heading "Runtime pinmuxing".
+
+Further it is possible for one named state to affect the muxing of several
+groups of pins, say for example in the mmc0 example above, where you can
+additively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all
+three groups for a total of 2+2+4 = 8 pins (for an 8-bit MMC bus as is the
+case), we define a mapping like this::
+
+ ...
+ {
+ .dev_name = "foo-mmc.0",
+ .name = "2bit"
+ .type = PIN_MAP_TYPE_MUX_GROUP,
+ .ctrl_dev_name = "pinctrl-foo",
+ .function = "mmc0",
+ .group = "mmc0_1_grp",
+ },
+ {
+ .dev_name = "foo-mmc.0",
+ .name = "4bit"
+ .type = PIN_MAP_TYPE_MUX_GROUP,
+ .ctrl_dev_name = "pinctrl-foo",
+ .function = "mmc0",
+ .group = "mmc0_1_grp",
+ },
+ {
+ .dev_name = "foo-mmc.0",
+ .name = "4bit"
+ .type = PIN_MAP_TYPE_MUX_GROUP,
+ .ctrl_dev_name = "pinctrl-foo",
+ .function = "mmc0",
+ .group = "mmc0_2_grp",
+ },
+ {
+ .dev_name = "foo-mmc.0",
+ .name = "8bit"
+ .type = PIN_MAP_TYPE_MUX_GROUP,
+ .ctrl_dev_name = "pinctrl-foo",
+ .function = "mmc0",
+ .group = "mmc0_1_grp",
+ },
+ {
+ .dev_name = "foo-mmc.0",
+ .name = "8bit"
+ .type = PIN_MAP_TYPE_MUX_GROUP,
+ .ctrl_dev_name = "pinctrl-foo",
+ .function = "mmc0",
+ .group = "mmc0_2_grp",
+ },
+ {
+ .dev_name = "foo-mmc.0",
+ .name = "8bit"
+ .type = PIN_MAP_TYPE_MUX_GROUP,
+ .ctrl_dev_name = "pinctrl-foo",
+ .function = "mmc0",
+ .group = "mmc0_3_grp",
+ },
+ ...
+
+The result of grabbing this mapping from the device with something like
+this (see next paragraph)::
+
+ p = devm_pinctrl_get(dev);
+ s = pinctrl_lookup_state(p, "8bit");
+ ret = pinctrl_select_state(p, s);
+
+or more simply::
+
+ p = devm_pinctrl_get_select(dev, "8bit");
+
+Will be that you activate all the three bottom records in the mapping at
+once. Since they share the same name, pin controller device, function and
+device, and since we allow multiple groups to match to a single device, they
+all get selected, and they all get enabled and disable simultaneously by the
+pinmux core.
+
+
+Pin control requests from drivers
+=================================
+
+When a device driver is about to probe the device core will automatically
+attempt to issue pinctrl_get_select_default() on these devices.
+This way driver writers do not need to add any of the boilerplate code
+of the type found below. However when doing fine-grained state selection
+and not using the "default" state, you may have to do some device driver
+handling of the pinctrl handles and states.
+
+So if you just want to put the pins for a certain device into the default
+state and be done with it, there is nothing you need to do besides
+providing the proper mapping table. The device core will take care of
+the rest.
+
+Generally it is discouraged to let individual drivers get and enable pin
+control. So if possible, handle the pin control in platform code or some other
+place where you have access to all the affected struct device * pointers. In
+some cases where a driver needs to e.g. switch between different mux mappings
+at runtime this is not possible.
+
+A typical case is if a driver needs to switch bias of pins from normal
+operation and going to sleep, moving from the PINCTRL_STATE_DEFAULT to
+PINCTRL_STATE_SLEEP at runtime, re-biasing or even re-muxing pins to save
+current in sleep mode.
+
+A driver may request a certain control state to be activated, usually just the
+default state like this::
+
+ #include <linux/pinctrl/consumer.h>
+
+ struct foo_state {
+ struct pinctrl *p;
+ struct pinctrl_state *s;
+ ...
+ };
+
+ foo_probe()
+ {
+ /* Allocate a state holder named "foo" etc */
+ struct foo_state *foo = ...;
+
+ foo->p = devm_pinctrl_get(&device);
+ if (IS_ERR(foo->p)) {
+ /* FIXME: clean up "foo" here */
+ return PTR_ERR(foo->p);
+ }
+
+ foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT);
+ if (IS_ERR(foo->s)) {
+ /* FIXME: clean up "foo" here */
+ return PTR_ERR(s);
+ }
+
+ ret = pinctrl_select_state(foo->s);
+ if (ret < 0) {
+ /* FIXME: clean up "foo" here */
+ return ret;
+ }
+ }
+
+This get/lookup/select/put sequence can just as well be handled by bus drivers
+if you don't want each and every driver to handle it and you know the
+arrangement on your bus.
+
+The semantics of the pinctrl APIs are:
+
+- pinctrl_get() is called in process context to obtain a handle to all pinctrl
+ information for a given client device. It will allocate a struct from the
+ kernel memory to hold the pinmux state. All mapping table parsing or similar
+ slow operations take place within this API.
+
+- devm_pinctrl_get() is a variant of pinctrl_get() that causes pinctrl_put()
+ to be called automatically on the retrieved pointer when the associated
+ device is removed. It is recommended to use this function over plain
+ pinctrl_get().
+
+- pinctrl_lookup_state() is called in process context to obtain a handle to a
+ specific state for a client device. This operation may be slow, too.
+
+- pinctrl_select_state() programs pin controller hardware according to the
+ definition of the state as given by the mapping table. In theory, this is a
+ fast-path operation, since it only involved blasting some register settings
+ into hardware. However, note that some pin controllers may have their
+ registers on a slow/IRQ-based bus, so client devices should not assume they
+ can call pinctrl_select_state() from non-blocking contexts.
+
+- pinctrl_put() frees all information associated with a pinctrl handle.
+
+- devm_pinctrl_put() is a variant of pinctrl_put() that may be used to
+ explicitly destroy a pinctrl object returned by devm_pinctrl_get().
+ However, use of this function will be rare, due to the automatic cleanup
+ that will occur even without calling it.
+
+ pinctrl_get() must be paired with a plain pinctrl_put().
+ pinctrl_get() may not be paired with devm_pinctrl_put().
+ devm_pinctrl_get() can optionally be paired with devm_pinctrl_put().
+ devm_pinctrl_get() may not be paired with plain pinctrl_put().
+
+Usually the pin control core handled the get/put pair and call out to the
+device drivers bookkeeping operations, like checking available functions and
+the associated pins, whereas select_state pass on to the pin controller
+driver which takes care of activating and/or deactivating the mux setting by
+quickly poking some registers.
+
+The pins are allocated for your device when you issue the devm_pinctrl_get()
+call, after this you should be able to see this in the debugfs listing of all
+pins.
+
+NOTE: the pinctrl system will return -EPROBE_DEFER if it cannot find the
+requested pinctrl handles, for example if the pinctrl driver has not yet
+registered. Thus make sure that the error path in your driver gracefully
+cleans up and is ready to retry the probing later in the startup process.
+
+
+Drivers needing both pin control and GPIOs
+==========================================
+
+Again, it is discouraged to let drivers lookup and select pin control states
+themselves, but again sometimes this is unavoidable.
+
+So say that your driver is fetching its resources like this::
+
+ #include <linux/pinctrl/consumer.h>
+ #include <linux/gpio.h>
+
+ struct pinctrl *pinctrl;
+ int gpio;
+
+ pinctrl = devm_pinctrl_get_select_default(&dev);
+ gpio = devm_gpio_request(&dev, 14, "foo");
+
+Here we first request a certain pin state and then request GPIO 14 to be
+used. If you're using the subsystems orthogonally like this, you should
+nominally always get your pinctrl handle and select the desired pinctrl
+state BEFORE requesting the GPIO. This is a semantic convention to avoid
+situations that can be electrically unpleasant, you will certainly want to
+mux in and bias pins in a certain way before the GPIO subsystems starts to
+deal with them.
+
+The above can be hidden: using the device core, the pinctrl core may be
+setting up the config and muxing for the pins right before the device is
+probing, nevertheless orthogonal to the GPIO subsystem.
+
+But there are also situations where it makes sense for the GPIO subsystem
+to communicate directly with the pinctrl subsystem, using the latter as a
+back-end. This is when the GPIO driver may call out to the functions
+described in the section "Pin control interaction with the GPIO subsystem"
+above. This only involves per-pin multiplexing, and will be completely
+hidden behind the gpio_*() function namespace. In this case, the driver
+need not interact with the pin control subsystem at all.
+
+If a pin control driver and a GPIO driver is dealing with the same pins
+and the use cases involve multiplexing, you MUST implement the pin controller
+as a back-end for the GPIO driver like this, unless your hardware design
+is such that the GPIO controller can override the pin controller's
+multiplexing state through hardware without the need to interact with the
+pin control system.
+
+
+System pin control hogging
+==========================
+
+Pin control map entries can be hogged by the core when the pin controller
+is registered. This means that the core will attempt to call pinctrl_get(),
+lookup_state() and select_state() on it immediately after the pin control
+device has been registered.
+
+This occurs for mapping table entries where the client device name is equal
+to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT::
+
+ {
+ .dev_name = "pinctrl-foo",
+ .name = PINCTRL_STATE_DEFAULT,
+ .type = PIN_MAP_TYPE_MUX_GROUP,
+ .ctrl_dev_name = "pinctrl-foo",
+ .function = "power_func",
+ },
+
+Since it may be common to request the core to hog a few always-applicable
+mux settings on the primary pin controller, there is a convenience macro for
+this::
+
+ PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */,
+ "power_func")
+
+This gives the exact same result as the above construction.
+
+
+Runtime pinmuxing
+=================
+
+It is possible to mux a certain function in and out at runtime, say to move
+an SPI port from one set of pins to another set of pins. Say for example for
+spi0 in the example above, we expose two different groups of pins for the same
+function, but with different named in the mapping as described under
+"Advanced mapping" above. So that for an SPI device, we have two states named
+"pos-A" and "pos-B".
+
+This snippet first initializes a state object for both groups (in foo_probe()),
+then muxes the function in the pins defined by group A, and finally muxes it in
+on the pins defined by group B::
+
+ #include <linux/pinctrl/consumer.h>
+
+ struct pinctrl *p;
+ struct pinctrl_state *s1, *s2;
+
+ foo_probe()
+ {
+ /* Setup */
+ p = devm_pinctrl_get(&device);
+ if (IS_ERR(p))
+ ...
+
+ s1 = pinctrl_lookup_state(foo->p, "pos-A");
+ if (IS_ERR(s1))
+ ...
+
+ s2 = pinctrl_lookup_state(foo->p, "pos-B");
+ if (IS_ERR(s2))
+ ...
+ }
+
+ foo_switch()
+ {
+ /* Enable on position A */
+ ret = pinctrl_select_state(s1);
+ if (ret < 0)
+ ...
+
+ ...
+
+ /* Enable on position B */
+ ret = pinctrl_select_state(s2);
+ if (ret < 0)
+ ...
+
+ ...
+ }
+
+The above has to be done from process context. The reservation of the pins
+will be done when the state is activated, so in effect one specific pin
+can be used by different functions at different times on a running system.
+++ /dev/null
-===============================
-PINCTRL (PIN CONTROL) subsystem
-===============================
-
-This document outlines the pin control subsystem in Linux
-
-This subsystem deals with:
-
-- Enumerating and naming controllable pins
-
-- Multiplexing of pins, pads, fingers (etc) see below for details
-
-- Configuration of pins, pads, fingers (etc), such as software-controlled
- biasing and driving mode specific pins, such as pull-up/down, open drain,
- load capacitance etc.
-
-Top-level interface
-===================
-
-Definition of PIN CONTROLLER:
-
-- A pin controller is a piece of hardware, usually a set of registers, that
- can control PINs. It may be able to multiplex, bias, set load capacitance,
- set drive strength, etc. for individual pins or groups of pins.
-
-Definition of PIN:
-
-- PINS are equal to pads, fingers, balls or whatever packaging input or
- output line you want to control and these are denoted by unsigned integers
- in the range 0..maxpin. This numberspace is local to each PIN CONTROLLER, so
- there may be several such number spaces in a system. This pin space may
- be sparse - i.e. there may be gaps in the space with numbers where no
- pin exists.
-
-When a PIN CONTROLLER is instantiated, it will register a descriptor to the
-pin control framework, and this descriptor contains an array of pin descriptors
-describing the pins handled by this specific pin controller.
-
-Here is an example of a PGA (Pin Grid Array) chip seen from underneath::
-
- A B C D E F G H
-
- 8 o o o o o o o o
-
- 7 o o o o o o o o
-
- 6 o o o o o o o o
-
- 5 o o o o o o o o
-
- 4 o o o o o o o o
-
- 3 o o o o o o o o
-
- 2 o o o o o o o o
-
- 1 o o o o o o o o
-
-To register a pin controller and name all the pins on this package we can do
-this in our driver::
-
- #include <linux/pinctrl/pinctrl.h>
-
- const struct pinctrl_pin_desc foo_pins[] = {
- PINCTRL_PIN(0, "A8"),
- PINCTRL_PIN(1, "B8"),
- PINCTRL_PIN(2, "C8"),
- ...
- PINCTRL_PIN(61, "F1"),
- PINCTRL_PIN(62, "G1"),
- PINCTRL_PIN(63, "H1"),
- };
-
- static struct pinctrl_desc foo_desc = {
- .name = "foo",
- .pins = foo_pins,
- .npins = ARRAY_SIZE(foo_pins),
- .owner = THIS_MODULE,
- };
-
- int __init foo_probe(void)
- {
- int error;
-
- struct pinctrl_dev *pctl;
-
- error = pinctrl_register_and_init(&foo_desc, <PARENT>,
- NULL, &pctl);
- if (error)
- return error;
-
- return pinctrl_enable(pctl);
- }
-
-To enable the pinctrl subsystem and the subgroups for PINMUX and PINCONF and
-selected drivers, you need to select them from your machine's Kconfig entry,
-since these are so tightly integrated with the machines they are used on.
-See for example arch/arm/mach-u300/Kconfig for an example.
-
-Pins usually have fancier names than this. You can find these in the datasheet
-for your chip. Notice that the core pinctrl.h file provides a fancy macro
-called PINCTRL_PIN() to create the struct entries. As you can see I enumerated
-the pins from 0 in the upper left corner to 63 in the lower right corner.
-This enumeration was arbitrarily chosen, in practice you need to think
-through your numbering system so that it matches the layout of registers
-and such things in your driver, or the code may become complicated. You must
-also consider matching of offsets to the GPIO ranges that may be handled by
-the pin controller.
-
-For a padring with 467 pads, as opposed to actual pins, I used an enumeration
-like this, walking around the edge of the chip, which seems to be industry
-standard too (all these pads had names, too)::
-
-
- 0 ..... 104
- 466 105
- . .
- . .
- 358 224
- 357 .... 225
-
-
-Pin groups
-==========
-
-Many controllers need to deal with groups of pins, so the pin controller
-subsystem has a mechanism for enumerating groups of pins and retrieving the
-actual enumerated pins that are part of a certain group.
-
-For example, say that we have a group of pins dealing with an SPI interface
-on { 0, 8, 16, 24 }, and a group of pins dealing with an I2C interface on pins
-on { 24, 25 }.
-
-These two groups are presented to the pin control subsystem by implementing
-some generic pinctrl_ops like this::
-
- #include <linux/pinctrl/pinctrl.h>
-
- struct foo_group {
- const char *name;
- const unsigned int *pins;
- const unsigned num_pins;
- };
-
- static const unsigned int spi0_pins[] = { 0, 8, 16, 24 };
- static const unsigned int i2c0_pins[] = { 24, 25 };
-
- static const struct foo_group foo_groups[] = {
- {
- .name = "spi0_grp",
- .pins = spi0_pins,
- .num_pins = ARRAY_SIZE(spi0_pins),
- },
- {
- .name = "i2c0_grp",
- .pins = i2c0_pins,
- .num_pins = ARRAY_SIZE(i2c0_pins),
- },
- };
-
-
- static int foo_get_groups_count(struct pinctrl_dev *pctldev)
- {
- return ARRAY_SIZE(foo_groups);
- }
-
- static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
- unsigned selector)
- {
- return foo_groups[selector].name;
- }
-
- static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
- const unsigned **pins,
- unsigned *num_pins)
- {
- *pins = (unsigned *) foo_groups[selector].pins;
- *num_pins = foo_groups[selector].num_pins;
- return 0;
- }
-
- static struct pinctrl_ops foo_pctrl_ops = {
- .get_groups_count = foo_get_groups_count,
- .get_group_name = foo_get_group_name,
- .get_group_pins = foo_get_group_pins,
- };
-
-
- static struct pinctrl_desc foo_desc = {
- ...
- .pctlops = &foo_pctrl_ops,
- };
-
-The pin control subsystem will call the .get_groups_count() function to
-determine the total number of legal selectors, then it will call the other functions
-to retrieve the name and pins of the group. Maintaining the data structure of
-the groups is up to the driver, this is just a simple example - in practice you
-may need more entries in your group structure, for example specific register
-ranges associated with each group and so on.
-
-
-Pin configuration
-=================
-
-Pins can sometimes be software-configured in various ways, mostly related
-to their electronic properties when used as inputs or outputs. For example you
-may be able to make an output pin high impedance, or "tristate" meaning it is
-effectively disconnected. You may be able to connect an input pin to VDD or GND
-using a certain resistor value - pull up and pull down - so that the pin has a
-stable value when nothing is driving the rail it is connected to, or when it's
-unconnected.
-
-Pin configuration can be programmed by adding configuration entries into the
-mapping table; see section "Board/machine configuration" below.
-
-The format and meaning of the configuration parameter, PLATFORM_X_PULL_UP
-above, is entirely defined by the pin controller driver.
-
-The pin configuration driver implements callbacks for changing pin
-configuration in the pin controller ops like this::
-
- #include <linux/pinctrl/pinctrl.h>
- #include <linux/pinctrl/pinconf.h>
- #include "platform_x_pindefs.h"
-
- static int foo_pin_config_get(struct pinctrl_dev *pctldev,
- unsigned offset,
- unsigned long *config)
- {
- struct my_conftype conf;
-
- ... Find setting for pin @ offset ...
-
- *config = (unsigned long) conf;
- }
-
- static int foo_pin_config_set(struct pinctrl_dev *pctldev,
- unsigned offset,
- unsigned long config)
- {
- struct my_conftype *conf = (struct my_conftype *) config;
-
- switch (conf) {
- case PLATFORM_X_PULL_UP:
- ...
- }
- }
- }
-
- static int foo_pin_config_group_get (struct pinctrl_dev *pctldev,
- unsigned selector,
- unsigned long *config)
- {
- ...
- }
-
- static int foo_pin_config_group_set (struct pinctrl_dev *pctldev,
- unsigned selector,
- unsigned long config)
- {
- ...
- }
-
- static struct pinconf_ops foo_pconf_ops = {
- .pin_config_get = foo_pin_config_get,
- .pin_config_set = foo_pin_config_set,
- .pin_config_group_get = foo_pin_config_group_get,
- .pin_config_group_set = foo_pin_config_group_set,
- };
-
- /* Pin config operations are handled by some pin controller */
- static struct pinctrl_desc foo_desc = {
- ...
- .confops = &foo_pconf_ops,
- };
-
-Since some controllers have special logic for handling entire groups of pins
-they can exploit the special whole-group pin control function. The
-pin_config_group_set() callback is allowed to return the error code -EAGAIN,
-for groups it does not want to handle, or if it just wants to do some
-group-level handling and then fall through to iterate over all pins, in which
-case each individual pin will be treated by separate pin_config_set() calls as
-well.
-
-
-Interaction with the GPIO subsystem
-===================================
-
-The GPIO drivers may want to perform operations of various types on the same
-physical pins that are also registered as pin controller pins.
-
-First and foremost, the two subsystems can be used as completely orthogonal,
-see the section named "pin control requests from drivers" and
-"drivers needing both pin control and GPIOs" below for details. But in some
-situations a cross-subsystem mapping between pins and GPIOs is needed.
-
-Since the pin controller subsystem has its pinspace local to the pin controller
-we need a mapping so that the pin control subsystem can figure out which pin
-controller handles control of a certain GPIO pin. Since a single pin controller
-may be muxing several GPIO ranges (typically SoCs that have one set of pins,
-but internally several GPIO silicon blocks, each modelled as a struct
-gpio_chip) any number of GPIO ranges can be added to a pin controller instance
-like this::
-
- struct gpio_chip chip_a;
- struct gpio_chip chip_b;
-
- static struct pinctrl_gpio_range gpio_range_a = {
- .name = "chip a",
- .id = 0,
- .base = 32,
- .pin_base = 32,
- .npins = 16,
- .gc = &chip_a;
- };
-
- static struct pinctrl_gpio_range gpio_range_b = {
- .name = "chip b",
- .id = 0,
- .base = 48,
- .pin_base = 64,
- .npins = 8,
- .gc = &chip_b;
- };
-
- {
- struct pinctrl_dev *pctl;
- ...
- pinctrl_add_gpio_range(pctl, &gpio_range_a);
- pinctrl_add_gpio_range(pctl, &gpio_range_b);
- }
-
-So this complex system has one pin controller handling two different
-GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and
-"chip b" have different .pin_base, which means a start pin number of the
-GPIO range.
-
-The GPIO range of "chip a" starts from the GPIO base of 32 and actual
-pin range also starts from 32. However "chip b" has different starting
-offset for the GPIO range and pin range. The GPIO range of "chip b" starts
-from GPIO number 48, while the pin range of "chip b" starts from 64.
-
-We can convert a gpio number to actual pin number using this "pin_base".
-They are mapped in the global GPIO pin space at:
-
-chip a:
- - GPIO range : [32 .. 47]
- - pin range : [32 .. 47]
-chip b:
- - GPIO range : [48 .. 55]
- - pin range : [64 .. 71]
-
-The above examples assume the mapping between the GPIOs and pins is
-linear. If the mapping is sparse or haphazard, an array of arbitrary pin
-numbers can be encoded in the range like this::
-
- static const unsigned range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 };
-
- static struct pinctrl_gpio_range gpio_range = {
- .name = "chip",
- .id = 0,
- .base = 32,
- .pins = &range_pins,
- .npins = ARRAY_SIZE(range_pins),
- .gc = &chip;
- };
-
-In this case the pin_base property will be ignored. If the name of a pin
-group is known, the pins and npins elements of the above structure can be
-initialised using the function pinctrl_get_group_pins(), e.g. for pin
-group "foo"::
-
- pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins,
- &gpio_range.npins);
-
-When GPIO-specific functions in the pin control subsystem are called, these
-ranges will be used to look up the appropriate pin controller by inspecting
-and matching the pin to the pin ranges across all controllers. When a
-pin controller handling the matching range is found, GPIO-specific functions
-will be called on that specific pin controller.
-
-For all functionalities dealing with pin biasing, pin muxing etc, the pin
-controller subsystem will look up the corresponding pin number from the passed
-in gpio number, and use the range's internals to retrieve a pin number. After
-that, the subsystem passes it on to the pin control driver, so the driver
-will get a pin number into its handled number range. Further it is also passed
-the range ID value, so that the pin controller knows which range it should
-deal with.
-
-Calling pinctrl_add_gpio_range from pinctrl driver is DEPRECATED. Please see
-section 2.1 of Documentation/devicetree/bindings/gpio/gpio.txt on how to bind
-pinctrl and gpio drivers.
-
-
-PINMUX interfaces
-=================
-
-These calls use the pinmux_* naming prefix. No other calls should use that
-prefix.
-
-
-What is pinmuxing?
-==================
-
-PINMUX, also known as padmux, ballmux, alternate functions or mission modes
-is a way for chip vendors producing some kind of electrical packages to use
-a certain physical pin (ball, pad, finger, etc) for multiple mutually exclusive
-functions, depending on the application. By "application" in this context
-we usually mean a way of soldering or wiring the package into an electronic
-system, even though the framework makes it possible to also change the function
-at runtime.
-
-Here is an example of a PGA (Pin Grid Array) chip seen from underneath::
-
- A B C D E F G H
- +---+
- 8 | o | o o o o o o o
- | |
- 7 | o | o o o o o o o
- | |
- 6 | o | o o o o o o o
- +---+---+
- 5 | o | o | o o o o o o
- +---+---+ +---+
- 4 o o o o o o | o | o
- | |
- 3 o o o o o o | o | o
- | |
- 2 o o o o o o | o | o
- +-------+-------+-------+---+---+
- 1 | o o | o o | o o | o | o |
- +-------+-------+-------+---+---+
-
-This is not tetris. The game to think of is chess. Not all PGA/BGA packages
-are chessboard-like, big ones have "holes" in some arrangement according to
-different design patterns, but we're using this as a simple example. Of the
-pins you see some will be taken by things like a few VCC and GND to feed power
-to the chip, and quite a few will be taken by large ports like an external
-memory interface. The remaining pins will often be subject to pin multiplexing.
-
-The example 8x8 PGA package above will have pin numbers 0 through 63 assigned
-to its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using
-pinctrl_register_pins() and a suitable data set as shown earlier.
-
-In this 8x8 BGA package the pins { A8, A7, A6, A5 } can be used as an SPI port
-(these are four pins: CLK, RXD, TXD, FRM). In that case, pin B5 can be used as
-some general-purpose GPIO pin. However, in another setting, pins { A5, B5 } can
-be used as an I2C port (these are just two pins: SCL, SDA). Needless to say,
-we cannot use the SPI port and I2C port at the same time. However in the inside
-of the package the silicon performing the SPI logic can alternatively be routed
-out on pins { G4, G3, G2, G1 }.
-
-On the bottom row at { A1, B1, C1, D1, E1, F1, G1, H1 } we have something
-special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will
-consume 2, 4 or 8 pins respectively, so either { A1, B1 } are taken or
-{ A1, B1, C1, D1 } or all of them. If we use all 8 bits, we cannot use the SPI
-port on pins { G4, G3, G2, G1 } of course.
-
-This way the silicon blocks present inside the chip can be multiplexed "muxed"
-out on different pin ranges. Often contemporary SoC (systems on chip) will
-contain several I2C, SPI, SDIO/MMC, etc silicon blocks that can be routed to
-different pins by pinmux settings.
-
-Since general-purpose I/O pins (GPIO) are typically always in shortage, it is
-common to be able to use almost any pin as a GPIO pin if it is not currently
-in use by some other I/O port.
-
-
-Pinmux conventions
-==================
-
-The purpose of the pinmux functionality in the pin controller subsystem is to
-abstract and provide pinmux settings to the devices you choose to instantiate
-in your machine configuration. It is inspired by the clk, GPIO and regulator
-subsystems, so devices will request their mux setting, but it's also possible
-to request a single pin for e.g. GPIO.
-
-Definitions:
-
-- FUNCTIONS can be switched in and out by a driver residing with the pin
- control subsystem in the drivers/pinctrl/* directory of the kernel. The
- pin control driver knows the possible functions. In the example above you can
- identify three pinmux functions, one for spi, one for i2c and one for mmc.
-
-- FUNCTIONS are assumed to be enumerable from zero in a one-dimensional array.
- In this case the array could be something like: { spi0, i2c0, mmc0 }
- for the three available functions.
-
-- FUNCTIONS have PIN GROUPS as defined on the generic level - so a certain
- function is *always* associated with a certain set of pin groups, could
- be just a single one, but could also be many. In the example above the
- function i2c is associated with the pins { A5, B5 }, enumerated as
- { 24, 25 } in the controller pin space.
-
- The Function spi is associated with pin groups { A8, A7, A6, A5 }
- and { G4, G3, G2, G1 }, which are enumerated as { 0, 8, 16, 24 } and
- { 38, 46, 54, 62 } respectively.
-
- Group names must be unique per pin controller, no two groups on the same
- controller may have the same name.
-
-- The combination of a FUNCTION and a PIN GROUP determine a certain function
- for a certain set of pins. The knowledge of the functions and pin groups
- and their machine-specific particulars are kept inside the pinmux driver,
- from the outside only the enumerators are known, and the driver core can
- request:
-
- - The name of a function with a certain selector (>= 0)
- - A list of groups associated with a certain function
- - That a certain group in that list to be activated for a certain function
-
- As already described above, pin groups are in turn self-descriptive, so
- the core will retrieve the actual pin range in a certain group from the
- driver.
-
-- FUNCTIONS and GROUPS on a certain PIN CONTROLLER are MAPPED to a certain
- device by the board file, device tree or similar machine setup configuration
- mechanism, similar to how regulators are connected to devices, usually by
- name. Defining a pin controller, function and group thus uniquely identify
- the set of pins to be used by a certain device. (If only one possible group
- of pins is available for the function, no group name need to be supplied -
- the core will simply select the first and only group available.)
-
- In the example case we can define that this particular machine shall
- use device spi0 with pinmux function fspi0 group gspi0 and i2c0 on function
- fi2c0 group gi2c0, on the primary pin controller, we get mappings
- like these::
-
- {
- {"map-spi0", spi0, pinctrl0, fspi0, gspi0},
- {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0}
- }
-
- Every map must be assigned a state name, pin controller, device and
- function. The group is not compulsory - if it is omitted the first group
- presented by the driver as applicable for the function will be selected,
- which is useful for simple cases.
-
- It is possible to map several groups to the same combination of device,
- pin controller and function. This is for cases where a certain function on
- a certain pin controller may use different sets of pins in different
- configurations.
-
-- PINS for a certain FUNCTION using a certain PIN GROUP on a certain
- PIN CONTROLLER are provided on a first-come first-serve basis, so if some
- other device mux setting or GPIO pin request has already taken your physical
- pin, you will be denied the use of it. To get (activate) a new setting, the
- old one has to be put (deactivated) first.
-
-Sometimes the documentation and hardware registers will be oriented around
-pads (or "fingers") rather than pins - these are the soldering surfaces on the
-silicon inside the package, and may or may not match the actual number of
-pins/balls underneath the capsule. Pick some enumeration that makes sense to
-you. Define enumerators only for the pins you can control if that makes sense.
-
-Assumptions:
-
-We assume that the number of possible function maps to pin groups is limited by
-the hardware. I.e. we assume that there is no system where any function can be
-mapped to any pin, like in a phone exchange. So the available pin groups for
-a certain function will be limited to a few choices (say up to eight or so),
-not hundreds or any amount of choices. This is the characteristic we have found
-by inspecting available pinmux hardware, and a necessary assumption since we
-expect pinmux drivers to present *all* possible function vs pin group mappings
-to the subsystem.
-
-
-Pinmux drivers
-==============
-
-The pinmux core takes care of preventing conflicts on pins and calling
-the pin controller driver to execute different settings.
-
-It is the responsibility of the pinmux driver to impose further restrictions
-(say for example infer electronic limitations due to load, etc.) to determine
-whether or not the requested function can actually be allowed, and in case it
-is possible to perform the requested mux setting, poke the hardware so that
-this happens.
-
-Pinmux drivers are required to supply a few callback functions, some are
-optional. Usually the set_mux() function is implemented, writing values into
-some certain registers to activate a certain mux setting for a certain pin.
-
-A simple driver for the above example will work by setting bits 0, 1, 2, 3 or 4
-into some register named MUX to select a certain function with a certain
-group of pins would work something like this::
-
- #include <linux/pinctrl/pinctrl.h>
- #include <linux/pinctrl/pinmux.h>
-
- struct foo_group {
- const char *name;
- const unsigned int *pins;
- const unsigned num_pins;
- };
-
- static const unsigned spi0_0_pins[] = { 0, 8, 16, 24 };
- static const unsigned spi0_1_pins[] = { 38, 46, 54, 62 };
- static const unsigned i2c0_pins[] = { 24, 25 };
- static const unsigned mmc0_1_pins[] = { 56, 57 };
- static const unsigned mmc0_2_pins[] = { 58, 59 };
- static const unsigned mmc0_3_pins[] = { 60, 61, 62, 63 };
-
- static const struct foo_group foo_groups[] = {
- {
- .name = "spi0_0_grp",
- .pins = spi0_0_pins,
- .num_pins = ARRAY_SIZE(spi0_0_pins),
- },
- {
- .name = "spi0_1_grp",
- .pins = spi0_1_pins,
- .num_pins = ARRAY_SIZE(spi0_1_pins),
- },
- {
- .name = "i2c0_grp",
- .pins = i2c0_pins,
- .num_pins = ARRAY_SIZE(i2c0_pins),
- },
- {
- .name = "mmc0_1_grp",
- .pins = mmc0_1_pins,
- .num_pins = ARRAY_SIZE(mmc0_1_pins),
- },
- {
- .name = "mmc0_2_grp",
- .pins = mmc0_2_pins,
- .num_pins = ARRAY_SIZE(mmc0_2_pins),
- },
- {
- .name = "mmc0_3_grp",
- .pins = mmc0_3_pins,
- .num_pins = ARRAY_SIZE(mmc0_3_pins),
- },
- };
-
-
- static int foo_get_groups_count(struct pinctrl_dev *pctldev)
- {
- return ARRAY_SIZE(foo_groups);
- }
-
- static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
- unsigned selector)
- {
- return foo_groups[selector].name;
- }
-
- static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
- unsigned ** const pins,
- unsigned * const num_pins)
- {
- *pins = (unsigned *) foo_groups[selector].pins;
- *num_pins = foo_groups[selector].num_pins;
- return 0;
- }
-
- static struct pinctrl_ops foo_pctrl_ops = {
- .get_groups_count = foo_get_groups_count,
- .get_group_name = foo_get_group_name,
- .get_group_pins = foo_get_group_pins,
- };
-
- struct foo_pmx_func {
- const char *name;
- const char * const *groups;
- const unsigned num_groups;
- };
-
- static const char * const spi0_groups[] = { "spi0_0_grp", "spi0_1_grp" };
- static const char * const i2c0_groups[] = { "i2c0_grp" };
- static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp",
- "mmc0_3_grp" };
-
- static const struct foo_pmx_func foo_functions[] = {
- {
- .name = "spi0",
- .groups = spi0_groups,
- .num_groups = ARRAY_SIZE(spi0_groups),
- },
- {
- .name = "i2c0",
- .groups = i2c0_groups,
- .num_groups = ARRAY_SIZE(i2c0_groups),
- },
- {
- .name = "mmc0",
- .groups = mmc0_groups,
- .num_groups = ARRAY_SIZE(mmc0_groups),
- },
- };
-
- static int foo_get_functions_count(struct pinctrl_dev *pctldev)
- {
- return ARRAY_SIZE(foo_functions);
- }
-
- static const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector)
- {
- return foo_functions[selector].name;
- }
-
- static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector,
- const char * const **groups,
- unsigned * const num_groups)
- {
- *groups = foo_functions[selector].groups;
- *num_groups = foo_functions[selector].num_groups;
- return 0;
- }
-
- static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned selector,
- unsigned group)
- {
- u8 regbit = (1 << selector + group);
-
- writeb((readb(MUX)|regbit), MUX)
- return 0;
- }
-
- static struct pinmux_ops foo_pmxops = {
- .get_functions_count = foo_get_functions_count,
- .get_function_name = foo_get_fname,
- .get_function_groups = foo_get_groups,
- .set_mux = foo_set_mux,
- .strict = true,
- };
-
- /* Pinmux operations are handled by some pin controller */
- static struct pinctrl_desc foo_desc = {
- ...
- .pctlops = &foo_pctrl_ops,
- .pmxops = &foo_pmxops,
- };
-
-In the example activating muxing 0 and 1 at the same time setting bits
-0 and 1, uses one pin in common so they would collide.
-
-The beauty of the pinmux subsystem is that since it keeps track of all
-pins and who is using them, it will already have denied an impossible
-request like that, so the driver does not need to worry about such
-things - when it gets a selector passed in, the pinmux subsystem makes
-sure no other device or GPIO assignment is already using the selected
-pins. Thus bits 0 and 1 in the control register will never be set at the
-same time.
-
-All the above functions are mandatory to implement for a pinmux driver.
-
-
-Pin control interaction with the GPIO subsystem
-===============================================
-
-Note that the following implies that the use case is to use a certain pin
-from the Linux kernel using the API in <linux/gpio.h> with gpio_request()
-and similar functions. There are cases where you may be using something
-that your datasheet calls "GPIO mode", but actually is just an electrical
-configuration for a certain device. See the section below named
-"GPIO mode pitfalls" for more details on this scenario.
-
-The public pinmux API contains two functions named pinctrl_request_gpio()
-and pinctrl_free_gpio(). These two functions shall *ONLY* be called from
-gpiolib-based drivers as part of their gpio_request() and
-gpio_free() semantics. Likewise the pinctrl_gpio_direction_[input|output]
-shall only be called from within respective gpio_direction_[input|output]
-gpiolib implementation.
-
-NOTE that platforms and individual drivers shall *NOT* request GPIO pins to be
-controlled e.g. muxed in. Instead, implement a proper gpiolib driver and have
-that driver request proper muxing and other control for its pins.
-
-The function list could become long, especially if you can convert every
-individual pin into a GPIO pin independent of any other pins, and then try
-the approach to define every pin as a function.
-
-In this case, the function array would become 64 entries for each GPIO
-setting and then the device functions.
-
-For this reason there are two functions a pin control driver can implement
-to enable only GPIO on an individual pin: .gpio_request_enable() and
-.gpio_disable_free().
-
-This function will pass in the affected GPIO range identified by the pin
-controller core, so you know which GPIO pins are being affected by the request
-operation.
-
-If your driver needs to have an indication from the framework of whether the
-GPIO pin shall be used for input or output you can implement the
-.gpio_set_direction() function. As described this shall be called from the
-gpiolib driver and the affected GPIO range, pin offset and desired direction
-will be passed along to this function.
-
-Alternatively to using these special functions, it is fully allowed to use
-named functions for each GPIO pin, the pinctrl_request_gpio() will attempt to
-obtain the function "gpioN" where "N" is the global GPIO pin number if no
-special GPIO-handler is registered.
-
-
-GPIO mode pitfalls
-==================
-
-Due to the naming conventions used by hardware engineers, where "GPIO"
-is taken to mean different things than what the kernel does, the developer
-may be confused by a datasheet talking about a pin being possible to set
-into "GPIO mode". It appears that what hardware engineers mean with
-"GPIO mode" is not necessarily the use case that is implied in the kernel
-interface <linux/gpio.h>: a pin that you grab from kernel code and then
-either listen for input or drive high/low to assert/deassert some
-external line.
-
-Rather hardware engineers think that "GPIO mode" means that you can
-software-control a few electrical properties of the pin that you would
-not be able to control if the pin was in some other mode, such as muxed in
-for a device.
-
-The GPIO portions of a pin and its relation to a certain pin controller
-configuration and muxing logic can be constructed in several ways. Here
-are two examples::
-
- (A)
- pin config
- logic regs
- | +- SPI
- Physical pins --- pad --- pinmux -+- I2C
- | +- mmc
- | +- GPIO
- pin
- multiplex
- logic regs
-
-Here some electrical properties of the pin can be configured no matter
-whether the pin is used for GPIO or not. If you multiplex a GPIO onto a
-pin, you can also drive it high/low from "GPIO" registers.
-Alternatively, the pin can be controlled by a certain peripheral, while
-still applying desired pin config properties. GPIO functionality is thus
-orthogonal to any other device using the pin.
-
-In this arrangement the registers for the GPIO portions of the pin controller,
-or the registers for the GPIO hardware module are likely to reside in a
-separate memory range only intended for GPIO driving, and the register
-range dealing with pin config and pin multiplexing get placed into a
-different memory range and a separate section of the data sheet.
-
-A flag "strict" in struct pinmux_ops is available to check and deny
-simultaneous access to the same pin from GPIO and pin multiplexing
-consumers on hardware of this type. The pinctrl driver should set this flag
-accordingly.
-
-::
-
- (B)
-
- pin config
- logic regs
- | +- SPI
- Physical pins --- pad --- pinmux -+- I2C
- | | +- mmc
- | |
- GPIO pin
- multiplex
- logic regs
-
-In this arrangement, the GPIO functionality can always be enabled, such that
-e.g. a GPIO input can be used to "spy" on the SPI/I2C/MMC signal while it is
-pulsed out. It is likely possible to disrupt the traffic on the pin by doing
-wrong things on the GPIO block, as it is never really disconnected. It is
-possible that the GPIO, pin config and pin multiplex registers are placed into
-the same memory range and the same section of the data sheet, although that
-need not be the case.
-
-In some pin controllers, although the physical pins are designed in the same
-way as (B), the GPIO function still can't be enabled at the same time as the
-peripheral functions. So again the "strict" flag should be set, denying
-simultaneous activation by GPIO and other muxed in devices.
-
-From a kernel point of view, however, these are different aspects of the
-hardware and shall be put into different subsystems:
-
-- Registers (or fields within registers) that control electrical
- properties of the pin such as biasing and drive strength should be
- exposed through the pinctrl subsystem, as "pin configuration" settings.
-
-- Registers (or fields within registers) that control muxing of signals
- from various other HW blocks (e.g. I2C, MMC, or GPIO) onto pins should
- be exposed through the pinctrl subsystem, as mux functions.
-
-- Registers (or fields within registers) that control GPIO functionality
- such as setting a GPIO's output value, reading a GPIO's input value, or
- setting GPIO pin direction should be exposed through the GPIO subsystem,
- and if they also support interrupt capabilities, through the irqchip
- abstraction.
-
-Depending on the exact HW register design, some functions exposed by the
-GPIO subsystem may call into the pinctrl subsystem in order to
-co-ordinate register settings across HW modules. In particular, this may
-be needed for HW with separate GPIO and pin controller HW modules, where
-e.g. GPIO direction is determined by a register in the pin controller HW
-module rather than the GPIO HW module.
-
-Electrical properties of the pin such as biasing and drive strength
-may be placed at some pin-specific register in all cases or as part
-of the GPIO register in case (B) especially. This doesn't mean that such
-properties necessarily pertain to what the Linux kernel calls "GPIO".
-
-Example: a pin is usually muxed in to be used as a UART TX line. But during
-system sleep, we need to put this pin into "GPIO mode" and ground it.
-
-If you make a 1-to-1 map to the GPIO subsystem for this pin, you may start
-to think that you need to come up with something really complex, that the
-pin shall be used for UART TX and GPIO at the same time, that you will grab
-a pin control handle and set it to a certain state to enable UART TX to be
-muxed in, then twist it over to GPIO mode and use gpio_direction_output()
-to drive it low during sleep, then mux it over to UART TX again when you
-wake up and maybe even gpio_request/gpio_free as part of this cycle. This
-all gets very complicated.
-
-The solution is to not think that what the datasheet calls "GPIO mode"
-has to be handled by the <linux/gpio.h> interface. Instead view this as
-a certain pin config setting. Look in e.g. <linux/pinctrl/pinconf-generic.h>
-and you find this in the documentation:
-
- PIN_CONFIG_OUTPUT:
- this will configure the pin in output, use argument
- 1 to indicate high level, argument 0 to indicate low level.
-
-So it is perfectly possible to push a pin into "GPIO mode" and drive the
-line low as part of the usual pin control map. So for example your UART
-driver may look like this::
-
- #include <linux/pinctrl/consumer.h>
-
- struct pinctrl *pinctrl;
- struct pinctrl_state *pins_default;
- struct pinctrl_state *pins_sleep;
-
- pins_default = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_DEFAULT);
- pins_sleep = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_SLEEP);
-
- /* Normal mode */
- retval = pinctrl_select_state(pinctrl, pins_default);
- /* Sleep mode */
- retval = pinctrl_select_state(pinctrl, pins_sleep);
-
-And your machine configuration may look like this:
---------------------------------------------------
-
-::
-
- static unsigned long uart_default_mode[] = {
- PIN_CONF_PACKED(PIN_CONFIG_DRIVE_PUSH_PULL, 0),
- };
-
- static unsigned long uart_sleep_mode[] = {
- PIN_CONF_PACKED(PIN_CONFIG_OUTPUT, 0),
- };
-
- static struct pinctrl_map pinmap[] __initdata = {
- PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
- "u0_group", "u0"),
- PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
- "UART_TX_PIN", uart_default_mode),
- PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
- "u0_group", "gpio-mode"),
- PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
- "UART_TX_PIN", uart_sleep_mode),
- };
-
- foo_init(void) {
- pinctrl_register_mappings(pinmap, ARRAY_SIZE(pinmap));
- }
-
-Here the pins we want to control are in the "u0_group" and there is some
-function called "u0" that can be enabled on this group of pins, and then
-everything is UART business as usual. But there is also some function
-named "gpio-mode" that can be mapped onto the same pins to move them into
-GPIO mode.
-
-This will give the desired effect without any bogus interaction with the
-GPIO subsystem. It is just an electrical configuration used by that device
-when going to sleep, it might imply that the pin is set into something the
-datasheet calls "GPIO mode", but that is not the point: it is still used
-by that UART device to control the pins that pertain to that very UART
-driver, putting them into modes needed by the UART. GPIO in the Linux
-kernel sense are just some 1-bit line, and is a different use case.
-
-How the registers are poked to attain the push or pull, and output low
-configuration and the muxing of the "u0" or "gpio-mode" group onto these
-pins is a question for the driver.
-
-Some datasheets will be more helpful and refer to the "GPIO mode" as
-"low power mode" rather than anything to do with GPIO. This often means
-the same thing electrically speaking, but in this latter case the
-software engineers will usually quickly identify that this is some
-specific muxing or configuration rather than anything related to the GPIO
-API.
-
-
-Board/machine configuration
-===========================
-
-Boards and machines define how a certain complete running system is put
-together, including how GPIOs and devices are muxed, how regulators are
-constrained and how the clock tree looks. Of course pinmux settings are also
-part of this.
-
-A pin controller configuration for a machine looks pretty much like a simple
-regulator configuration, so for the example array above we want to enable i2c
-and spi on the second function mapping::
-
- #include <linux/pinctrl/machine.h>
-
- static const struct pinctrl_map mapping[] __initconst = {
- {
- .dev_name = "foo-spi.0",
- .name = PINCTRL_STATE_DEFAULT,
- .type = PIN_MAP_TYPE_MUX_GROUP,
- .ctrl_dev_name = "pinctrl-foo",
- .data.mux.function = "spi0",
- },
- {
- .dev_name = "foo-i2c.0",
- .name = PINCTRL_STATE_DEFAULT,
- .type = PIN_MAP_TYPE_MUX_GROUP,
- .ctrl_dev_name = "pinctrl-foo",
- .data.mux.function = "i2c0",
- },
- {
- .dev_name = "foo-mmc.0",
- .name = PINCTRL_STATE_DEFAULT,
- .type = PIN_MAP_TYPE_MUX_GROUP,
- .ctrl_dev_name = "pinctrl-foo",
- .data.mux.function = "mmc0",
- },
- };
-
-The dev_name here matches to the unique device name that can be used to look
-up the device struct (just like with clockdev or regulators). The function name
-must match a function provided by the pinmux driver handling this pin range.
-
-As you can see we may have several pin controllers on the system and thus
-we need to specify which one of them contains the functions we wish to map.
-
-You register this pinmux mapping to the pinmux subsystem by simply::
-
- ret = pinctrl_register_mappings(mapping, ARRAY_SIZE(mapping));
-
-Since the above construct is pretty common there is a helper macro to make
-it even more compact which assumes you want to use pinctrl-foo and position
-0 for mapping, for example::
-
- static struct pinctrl_map mapping[] __initdata = {
- PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT,
- "pinctrl-foo", NULL, "i2c0"),
- };
-
-The mapping table may also contain pin configuration entries. It's common for
-each pin/group to have a number of configuration entries that affect it, so
-the table entries for configuration reference an array of config parameters
-and values. An example using the convenience macros is shown below::
-
- static unsigned long i2c_grp_configs[] = {
- FOO_PIN_DRIVEN,
- FOO_PIN_PULLUP,
- };
-
- static unsigned long i2c_pin_configs[] = {
- FOO_OPEN_COLLECTOR,
- FOO_SLEW_RATE_SLOW,
- };
-
- static struct pinctrl_map mapping[] __initdata = {
- PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
- "pinctrl-foo", "i2c0", "i2c0"),
- PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
- "pinctrl-foo", "i2c0", i2c_grp_configs),
- PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,
- "pinctrl-foo", "i2c0scl", i2c_pin_configs),
- PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,
- "pinctrl-foo", "i2c0sda", i2c_pin_configs),
- };
-
-Finally, some devices expect the mapping table to contain certain specific
-named states. When running on hardware that doesn't need any pin controller
-configuration, the mapping table must still contain those named states, in
-order to explicitly indicate that the states were provided and intended to
-be empty. Table entry macro PIN_MAP_DUMMY_STATE serves the purpose of defining
-a named state without causing any pin controller to be programmed::
-
- static struct pinctrl_map mapping[] __initdata = {
- PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),
- };
-
-
-Complex mappings
-================
-
-As it is possible to map a function to different groups of pins an optional
-.group can be specified like this::
-
- ...
- {
- .dev_name = "foo-spi.0",
- .name = "spi0-pos-A",
- .type = PIN_MAP_TYPE_MUX_GROUP,
- .ctrl_dev_name = "pinctrl-foo",
- .function = "spi0",
- .group = "spi0_0_grp",
- },
- {
- .dev_name = "foo-spi.0",
- .name = "spi0-pos-B",
- .type = PIN_MAP_TYPE_MUX_GROUP,
- .ctrl_dev_name = "pinctrl-foo",
- .function = "spi0",
- .group = "spi0_1_grp",
- },
- ...
-
-This example mapping is used to switch between two positions for spi0 at
-runtime, as described further below under the heading "Runtime pinmuxing".
-
-Further it is possible for one named state to affect the muxing of several
-groups of pins, say for example in the mmc0 example above, where you can
-additively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all
-three groups for a total of 2+2+4 = 8 pins (for an 8-bit MMC bus as is the
-case), we define a mapping like this::
-
- ...
- {
- .dev_name = "foo-mmc.0",
- .name = "2bit"
- .type = PIN_MAP_TYPE_MUX_GROUP,
- .ctrl_dev_name = "pinctrl-foo",
- .function = "mmc0",
- .group = "mmc0_1_grp",
- },
- {
- .dev_name = "foo-mmc.0",
- .name = "4bit"
- .type = PIN_MAP_TYPE_MUX_GROUP,
- .ctrl_dev_name = "pinctrl-foo",
- .function = "mmc0",
- .group = "mmc0_1_grp",
- },
- {
- .dev_name = "foo-mmc.0",
- .name = "4bit"
- .type = PIN_MAP_TYPE_MUX_GROUP,
- .ctrl_dev_name = "pinctrl-foo",
- .function = "mmc0",
- .group = "mmc0_2_grp",
- },
- {
- .dev_name = "foo-mmc.0",
- .name = "8bit"
- .type = PIN_MAP_TYPE_MUX_GROUP,
- .ctrl_dev_name = "pinctrl-foo",
- .function = "mmc0",
- .group = "mmc0_1_grp",
- },
- {
- .dev_name = "foo-mmc.0",
- .name = "8bit"
- .type = PIN_MAP_TYPE_MUX_GROUP,
- .ctrl_dev_name = "pinctrl-foo",
- .function = "mmc0",
- .group = "mmc0_2_grp",
- },
- {
- .dev_name = "foo-mmc.0",
- .name = "8bit"
- .type = PIN_MAP_TYPE_MUX_GROUP,
- .ctrl_dev_name = "pinctrl-foo",
- .function = "mmc0",
- .group = "mmc0_3_grp",
- },
- ...
-
-The result of grabbing this mapping from the device with something like
-this (see next paragraph)::
-
- p = devm_pinctrl_get(dev);
- s = pinctrl_lookup_state(p, "8bit");
- ret = pinctrl_select_state(p, s);
-
-or more simply::
-
- p = devm_pinctrl_get_select(dev, "8bit");
-
-Will be that you activate all the three bottom records in the mapping at
-once. Since they share the same name, pin controller device, function and
-device, and since we allow multiple groups to match to a single device, they
-all get selected, and they all get enabled and disable simultaneously by the
-pinmux core.
-
-
-Pin control requests from drivers
-=================================
-
-When a device driver is about to probe the device core will automatically
-attempt to issue pinctrl_get_select_default() on these devices.
-This way driver writers do not need to add any of the boilerplate code
-of the type found below. However when doing fine-grained state selection
-and not using the "default" state, you may have to do some device driver
-handling of the pinctrl handles and states.
-
-So if you just want to put the pins for a certain device into the default
-state and be done with it, there is nothing you need to do besides
-providing the proper mapping table. The device core will take care of
-the rest.
-
-Generally it is discouraged to let individual drivers get and enable pin
-control. So if possible, handle the pin control in platform code or some other
-place where you have access to all the affected struct device * pointers. In
-some cases where a driver needs to e.g. switch between different mux mappings
-at runtime this is not possible.
-
-A typical case is if a driver needs to switch bias of pins from normal
-operation and going to sleep, moving from the PINCTRL_STATE_DEFAULT to
-PINCTRL_STATE_SLEEP at runtime, re-biasing or even re-muxing pins to save
-current in sleep mode.
-
-A driver may request a certain control state to be activated, usually just the
-default state like this::
-
- #include <linux/pinctrl/consumer.h>
-
- struct foo_state {
- struct pinctrl *p;
- struct pinctrl_state *s;
- ...
- };
-
- foo_probe()
- {
- /* Allocate a state holder named "foo" etc */
- struct foo_state *foo = ...;
-
- foo->p = devm_pinctrl_get(&device);
- if (IS_ERR(foo->p)) {
- /* FIXME: clean up "foo" here */
- return PTR_ERR(foo->p);
- }
-
- foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT);
- if (IS_ERR(foo->s)) {
- /* FIXME: clean up "foo" here */
- return PTR_ERR(s);
- }
-
- ret = pinctrl_select_state(foo->s);
- if (ret < 0) {
- /* FIXME: clean up "foo" here */
- return ret;
- }
- }
-
-This get/lookup/select/put sequence can just as well be handled by bus drivers
-if you don't want each and every driver to handle it and you know the
-arrangement on your bus.
-
-The semantics of the pinctrl APIs are:
-
-- pinctrl_get() is called in process context to obtain a handle to all pinctrl
- information for a given client device. It will allocate a struct from the
- kernel memory to hold the pinmux state. All mapping table parsing or similar
- slow operations take place within this API.
-
-- devm_pinctrl_get() is a variant of pinctrl_get() that causes pinctrl_put()
- to be called automatically on the retrieved pointer when the associated
- device is removed. It is recommended to use this function over plain
- pinctrl_get().
-
-- pinctrl_lookup_state() is called in process context to obtain a handle to a
- specific state for a client device. This operation may be slow, too.
-
-- pinctrl_select_state() programs pin controller hardware according to the
- definition of the state as given by the mapping table. In theory, this is a
- fast-path operation, since it only involved blasting some register settings
- into hardware. However, note that some pin controllers may have their
- registers on a slow/IRQ-based bus, so client devices should not assume they
- can call pinctrl_select_state() from non-blocking contexts.
-
-- pinctrl_put() frees all information associated with a pinctrl handle.
-
-- devm_pinctrl_put() is a variant of pinctrl_put() that may be used to
- explicitly destroy a pinctrl object returned by devm_pinctrl_get().
- However, use of this function will be rare, due to the automatic cleanup
- that will occur even without calling it.
-
- pinctrl_get() must be paired with a plain pinctrl_put().
- pinctrl_get() may not be paired with devm_pinctrl_put().
- devm_pinctrl_get() can optionally be paired with devm_pinctrl_put().
- devm_pinctrl_get() may not be paired with plain pinctrl_put().
-
-Usually the pin control core handled the get/put pair and call out to the
-device drivers bookkeeping operations, like checking available functions and
-the associated pins, whereas select_state pass on to the pin controller
-driver which takes care of activating and/or deactivating the mux setting by
-quickly poking some registers.
-
-The pins are allocated for your device when you issue the devm_pinctrl_get()
-call, after this you should be able to see this in the debugfs listing of all
-pins.
-
-NOTE: the pinctrl system will return -EPROBE_DEFER if it cannot find the
-requested pinctrl handles, for example if the pinctrl driver has not yet
-registered. Thus make sure that the error path in your driver gracefully
-cleans up and is ready to retry the probing later in the startup process.
-
-
-Drivers needing both pin control and GPIOs
-==========================================
-
-Again, it is discouraged to let drivers lookup and select pin control states
-themselves, but again sometimes this is unavoidable.
-
-So say that your driver is fetching its resources like this::
-
- #include <linux/pinctrl/consumer.h>
- #include <linux/gpio.h>
-
- struct pinctrl *pinctrl;
- int gpio;
-
- pinctrl = devm_pinctrl_get_select_default(&dev);
- gpio = devm_gpio_request(&dev, 14, "foo");
-
-Here we first request a certain pin state and then request GPIO 14 to be
-used. If you're using the subsystems orthogonally like this, you should
-nominally always get your pinctrl handle and select the desired pinctrl
-state BEFORE requesting the GPIO. This is a semantic convention to avoid
-situations that can be electrically unpleasant, you will certainly want to
-mux in and bias pins in a certain way before the GPIO subsystems starts to
-deal with them.
-
-The above can be hidden: using the device core, the pinctrl core may be
-setting up the config and muxing for the pins right before the device is
-probing, nevertheless orthogonal to the GPIO subsystem.
-
-But there are also situations where it makes sense for the GPIO subsystem
-to communicate directly with the pinctrl subsystem, using the latter as a
-back-end. This is when the GPIO driver may call out to the functions
-described in the section "Pin control interaction with the GPIO subsystem"
-above. This only involves per-pin multiplexing, and will be completely
-hidden behind the gpio_*() function namespace. In this case, the driver
-need not interact with the pin control subsystem at all.
-
-If a pin control driver and a GPIO driver is dealing with the same pins
-and the use cases involve multiplexing, you MUST implement the pin controller
-as a back-end for the GPIO driver like this, unless your hardware design
-is such that the GPIO controller can override the pin controller's
-multiplexing state through hardware without the need to interact with the
-pin control system.
-
-
-System pin control hogging
-==========================
-
-Pin control map entries can be hogged by the core when the pin controller
-is registered. This means that the core will attempt to call pinctrl_get(),
-lookup_state() and select_state() on it immediately after the pin control
-device has been registered.
-
-This occurs for mapping table entries where the client device name is equal
-to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT::
-
- {
- .dev_name = "pinctrl-foo",
- .name = PINCTRL_STATE_DEFAULT,
- .type = PIN_MAP_TYPE_MUX_GROUP,
- .ctrl_dev_name = "pinctrl-foo",
- .function = "power_func",
- },
-
-Since it may be common to request the core to hog a few always-applicable
-mux settings on the primary pin controller, there is a convenience macro for
-this::
-
- PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */,
- "power_func")
-
-This gives the exact same result as the above construction.
-
-
-Runtime pinmuxing
-=================
-
-It is possible to mux a certain function in and out at runtime, say to move
-an SPI port from one set of pins to another set of pins. Say for example for
-spi0 in the example above, we expose two different groups of pins for the same
-function, but with different named in the mapping as described under
-"Advanced mapping" above. So that for an SPI device, we have two states named
-"pos-A" and "pos-B".
-
-This snippet first initializes a state object for both groups (in foo_probe()),
-then muxes the function in the pins defined by group A, and finally muxes it in
-on the pins defined by group B::
-
- #include <linux/pinctrl/consumer.h>
-
- struct pinctrl *p;
- struct pinctrl_state *s1, *s2;
-
- foo_probe()
- {
- /* Setup */
- p = devm_pinctrl_get(&device);
- if (IS_ERR(p))
- ...
-
- s1 = pinctrl_lookup_state(foo->p, "pos-A");
- if (IS_ERR(s1))
- ...
-
- s2 = pinctrl_lookup_state(foo->p, "pos-B");
- if (IS_ERR(s2))
- ...
- }
-
- foo_switch()
- {
- /* Enable on position A */
- ret = pinctrl_select_state(s1);
- if (ret < 0)
- ...
-
- ...
-
- /* Enable on position B */
- ret = pinctrl_select_state(s2);
- if (ret < 0)
- ...
-
- ...
- }
-
-The above has to be done from process context. The reservation of the pins
-will be done when the state is activated, so in effect one specific pin
-can be used by different functions at different times on a running system.
projects / GitHub / moto-9609 / android_kernel_motorola_exynos9610.git / commitdiff