hwmon: (w83627ehf) Fix temp2 source for W83627UHG
[linux-2.6.git] / Documentation / pinctrl.txt
index 43ba411..150fd38 100644 (file)
@@ -7,12 +7,9 @@ This subsystem deals with:
 
 - Multiplexing of pins, pads, fingers (etc) see below for details
 
-The intention is to also deal with:
-
-- Software-controlled biasing and driving mode specific pins, such as
-  pull-up/down, open drain etc, load capacitance configuration when controlled
-  by software, etc.
-
+- 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
 ===================
@@ -88,6 +85,11 @@ int __init foo_probe(void)
                pr_err("could not register foo pin driver\n");
 }
 
+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 dataheet
 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
@@ -193,6 +195,88 @@ structure, for example specific register ranges associated with each group
 and so on.
 
 
+Pin configuration
+=================
+
+Pins can sometimes be software-configured in an 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.
+
+For example, a platform may do this:
+
+ret = pin_config_set("foo-dev", "FOO_GPIO_PIN", PLATFORM_X_PULL_UP);
+
+To pull up a pin to VDD. 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
 ===================================
 
@@ -645,6 +729,17 @@ All the above functions are mandatory to implement for a pinmux driver.
 Pinmux interaction with the GPIO subsystem
 ==========================================
 
+The public pinmux API contains two functions named pinmux_request_gpio()
+and pinmux_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 pinmux_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
+muxed in. Instead, implement a proper gpiolib driver and have that driver
+request proper muxing 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.
@@ -652,19 +747,24 @@ 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 is an additional function a pinmux driver can implement
-to enable only GPIO on an individual pin: .gpio_request_enable(). The same
-.free() function as for other functions is assumed to be usable also for
-GPIO pins.
+For this reason there are two functions a pinmux 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.
 
-Alternatively it is fully allowed to use named functions for each GPIO
-pin, the pinmux_request_gpio() will attempt to obtain the function "gpioN"
-where "N" is the global GPIO pin number if no special GPIO-handler is
-registered.
+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 pinmux_request_gpio() will attempt to
+obtain the function "gpioN" where "N" is the global GPIO pin number if no
+special GPIO-handler is registered.
 
 
 Pinmux board/machine configuration
@@ -681,19 +781,19 @@ spi on the second function mapping:
 
 #include <linux/pinctrl/machine.h>
 
-static const struct pinmux_map pmx_mapping[] = {
+static const struct pinmux_map __initdata pmx_mapping[] = {
        {
-               .ctrl_dev_name = "pinctrl.0",
+               .ctrl_dev_name = "pinctrl-foo",
                .function = "spi0",
                .dev_name = "foo-spi.0",
        },
        {
-               .ctrl_dev_name = "pinctrl.0",
+               .ctrl_dev_name = "pinctrl-foo",
                .function = "i2c0",
                .dev_name = "foo-i2c.0",
        },
        {
-               .ctrl_dev_name = "pinctrl.0",
+               .ctrl_dev_name = "pinctrl-foo",
                .function = "mmc0",
                .dev_name = "foo-mmc.0",
        },
@@ -715,11 +815,11 @@ You register this pinmux mapping to the pinmux subsystem by simply:
        ret = pinmux_register_mappings(pmx_mapping, ARRAY_SIZE(pmx_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.0 and position
+it even more compact which assumes you want to use pinctrl-foo and position
 0 for mapping, for example:
 
-static struct pinmux_map pmx_mapping[] = {
-       PINMUX_MAP_PRIMARY("I2CMAP", "i2c0", "foo-i2c.0"),
+static struct pinmux_map __initdata pmx_mapping[] = {
+       PINMUX_MAP("I2CMAP", "pinctrl-foo", "i2c0", "foo-i2c.0"),
 };
 
 
@@ -732,14 +832,14 @@ As it is possible to map a function to different groups of pins an optional
 ...
 {
        .name = "spi0-pos-A",
-       .ctrl_dev_name = "pinctrl.0",
+       .ctrl_dev_name = "pinctrl-foo",
        .function = "spi0",
        .group = "spi0_0_grp",
        .dev_name = "foo-spi.0",
 },
 {
        .name = "spi0-pos-B",
-       .ctrl_dev_name = "pinctrl.0",
+       .ctrl_dev_name = "pinctrl-foo",
        .function = "spi0",
        .group = "spi0_1_grp",
        .dev_name = "foo-spi.0",
@@ -757,43 +857,42 @@ case), we define a mapping like this:
 
 ...
 {
-       .name "2bit"
-       .ctrl_dev_name = "pinctrl.0",
+       .name = "2bit"
+       .ctrl_dev_name = "pinctrl-foo",
        .function = "mmc0",
        .group = "mmc0_1_grp",
        .dev_name = "foo-mmc.0",
 },
 {
-       .name "4bit"
-       .ctrl_dev_name = "pinctrl.0",
+       .name = "4bit"
+       .ctrl_dev_name = "pinctrl-foo",
        .function = "mmc0",
        .group = "mmc0_1_grp",
        .dev_name = "foo-mmc.0",
 },
 {
-       .name "4bit"
-       .ctrl_dev_name = "pinctrl.0",
+       .name = "4bit"
+       .ctrl_dev_name = "pinctrl-foo",
        .function = "mmc0",
        .group = "mmc0_2_grp",
        .dev_name = "foo-mmc.0",
 },
 {
-       .name "8bit"
-       .ctrl_dev_name = "pinctrl.0",
-       .function = "mmc0",
+       .name = "8bit"
+       .ctrl_dev_name = "pinctrl-foo",
        .group = "mmc0_1_grp",
        .dev_name = "foo-mmc.0",
 },
 {
-       .name "8bit"
-       .ctrl_dev_name = "pinctrl.0",
+       .name = "8bit"
+       .ctrl_dev_name = "pinctrl-foo",
        .function = "mmc0",
        .group = "mmc0_2_grp",
        .dev_name = "foo-mmc.0",
 },
 {
-       .name "8bit"
-       .ctrl_dev_name = "pinctrl.0",
+       .name = "8bit"
+       .ctrl_dev_name = "pinctrl-foo",
        .function = "mmc0",
        .group = "mmc0_3_grp",
        .dev_name = "foo-mmc.0",
@@ -895,8 +994,8 @@ This is enabled by simply setting the .hog_on_boot field in the map to true,
 like this:
 
 {
-       .name "POWERMAP"
-       .ctrl_dev_name = "pinctrl.0",
+       .name = "POWERMAP"
+       .ctrl_dev_name = "pinctrl-foo",
        .function = "power_func",
        .hog_on_boot = true,
 },
@@ -925,7 +1024,7 @@ it, disables and releases it, and muxes it in on the pins defined by group B:
 
 foo_switch()
 {
-       struct pinmux pmx;
+       struct pinmux *pmx;
 
        /* Enable on position A */
        pmx = pinmux_get(&device, "spi0-pos-A");