summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2013-09-04 16:24:33 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2013-09-04 16:24:33 -0700
commitaa7054f5a5a9ff728ce291cb103afa19f4f849eb (patch)
tree83ddb460e2dca239f35d64a33054c100fe7f9e5d /Documentation
parent816434ec4a674fcdb3c2221a6dffdc8f34020550 (diff)
parentc9e3b2d8f75d84c7b333761471f6cef98ec4429a (diff)
Merge tag 'pinctrl-v3.12-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-pinctrl
Pull pin control changes from Linus Walleij: "Here is the bulk of pin control changes for the v3.12 series. Most of the relevant information is in the tag. I merged in v3.11-rc7 last week to get rid of a largeish conflict within the sunxi (AllWinner) driver in linux-next and fix up the non-trivial merge the right way. That driver had a rather large fix adding locking late in the release cycle. Overall the bulk changes this time is cleanups and refactorings and not much new features, which is nice. - Refactorings for generic pin config handling in the core. - Factor out a set of device tree utilities for use in all drivers, to parse and allocate maps from the device tree. - Some fixes to the core such as more nitpicky locking. - Pushed down config array iteration into the drivers. This patch is necessary for drivers that want to iterate over configs and pile up a stack of alterations to the same register(s), or if the driver wants to take a local spinlock when committing the configuration. - A new driver for the Texas Instruments Palmas PMIC by Laxman Dewangan. This is used on the Tegra systems. - A major cleanup and modernization of the PFC (Super Hitachi and ARM SHmobile) pin controller and subdrivers. - Support for the A20 and A31 sunxi (AllWinner) SoCs. - A huge pile of fixes and cleanups: Axel Lin, Jingoo Han Dan Carpenter, Julia Lawall and Sachin Kamat did an excellent job here" * tag 'pinctrl-v3.12-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-pinctrl: (124 commits) pinctrl: sunxi: Fix off-by-one for valid offset range checking pinctrl: sunxi: drop lock on error path pinctrl: pinconf-generic: Remove ti prefix in dev_err messages pinctrl: rockchip: Implement .request() and .free() callbacks pinctrl: at91: fix get_pullup/down function return pinctrl: sh-pfc: remove unnecessary platform_set_drvdata() pinctrl: Add s5pv210 support to pinctrl-exynos pinctrl: utils: include export.h to avoid warnings pinctrl: s3c24xx: off by one in s3c24xx_eint_init() pinctrl: mvebu: testing the wrong variable pinctrl: abx500: fix bitwise AND test pinctrl: mvebu: Convert to use devm_ioremap_resource pinctrl: Pass all configs to driver on pin_config_set() pinctrl: tz1090-pdc: Convert to devm_ioremap_resource pinctrl: tz1090: Convert to devm_ioremap_resource pinctrl: tegra: Convert to devm_ioremap_resource pinctrl: rockchip: Simplify pin_to_bank equation pinctrl: spear: Convert to devm_ioremap_resource pinctrl: rockchip: Remove of_match_ptr macro for DT only driver pinctrl: palmas: PINCTRL_PALMAS needs to select PINMUX ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio.txt55
-rw-r--r--Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt41
-rw-r--r--Documentation/devicetree/bindings/pinctrl/pinctrl-palmas.txt96
-rw-r--r--Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt3
-rw-r--r--Documentation/pinctrl.txt101
5 files changed, 244 insertions, 52 deletions
diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt
index d933af370697..6cec6ff20d2e 100644
--- a/Documentation/devicetree/bindings/gpio/gpio.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio.txt
@@ -75,23 +75,36 @@ Example of two SOC GPIO banks defined as gpio-controller nodes:
gpio-controller;
};
-2.1) gpio-controller and pinctrl subsystem
-------------------------------------------
+2.1) gpio- and pin-controller interaction
+-----------------------------------------
-gpio-controller on a SOC might be tightly coupled with the pinctrl
-subsystem, in the sense that the pins can be used by other functions
-together with optional gpio feature.
+Some or all of the GPIOs provided by a GPIO controller may be routed to pins
+on the package via a pin controller. This allows muxing those pins between
+GPIO and other functions.
-While the pin allocation is totally managed by the pin ctrl subsystem,
-gpio (under gpiolib) is still maintained by gpio drivers. It may happen
-that different pin ranges in a SoC is managed by different gpio drivers.
+It is useful to represent which GPIOs correspond to which pins on which pin
+controllers. The gpio-ranges property described below represents this, and
+contains information structures as follows:
-This makes it logical to let gpio drivers announce their pin ranges to
-the pin ctrl subsystem and call 'pinctrl_request_gpio' in order to
-request the corresponding pin before any gpio usage.
+ gpio-range-list ::= <single-gpio-range> [gpio-range-list]
+ single-gpio-range ::=
+ <pinctrl-phandle> <gpio-base> <pinctrl-base> <count>
+ gpio-phandle : phandle to pin controller node.
+ gpio-base : Base GPIO ID in the GPIO controller
+ pinctrl-base : Base pinctrl pin ID in the pin controller
+ count : The number of GPIOs/pins in this range
-For this, the gpio controller can use a pinctrl phandle and pins to
-announce the pinrange to the pin ctrl subsystem. For example,
+The "pin controller node" mentioned above must conform to the bindings
+described in ../pinctrl/pinctrl-bindings.txt.
+
+Previous versions of this binding required all pin controller nodes that
+were referenced by any gpio-ranges property to contain a property named
+#gpio-range-cells with value <3>. This requirement is now deprecated.
+However, that property may still exist in older device trees for
+compatibility reasons, and would still be required even in new device
+trees that need to be compatible with older software.
+
+Example:
qe_pio_e: gpio-controller@1460 {
#gpio-cells = <2>;
@@ -99,16 +112,8 @@ announce the pinrange to the pin ctrl subsystem. For example,
reg = <0x1460 0x18>;
gpio-controller;
gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>;
+ };
- }
-
-where,
- &pinctrl1 and &pinctrl2 is the phandle to the pinctrl DT node.
-
- Next values specify the base pin and number of pins for the range
- handled by 'qe_pio_e' gpio. In the given example from base pin 20 to
- pin 29 under pinctrl1 with gpio offset 0 and pin 50 to pin 69 under
- pinctrl2 with gpio offset 10 is handled by this gpio controller.
-
-The pinctrl node must have "#gpio-range-cells" property to show number of
-arguments to pass with phandle from gpio controllers node.
+Here, a single GPIO controller has GPIOs 0..9 routed to pin controller
+pinctrl1's pins 20..29, and GPIOs 10..19 routed to pin controller pinctrl2's
+pins 50..59.
diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
index aeb3c995cc04..1958ca9f9e5c 100644
--- a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
+++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
@@ -127,21 +127,20 @@ whether there is any interaction between the child and intermediate parent
nodes, is again defined entirely by the binding for the individual pin
controller device.
-== Using generic pinconfig options ==
+== Generic pin configuration node content ==
-Generic pinconfig parameters can be used by defining a separate node containing
-the applicable parameters (and optional values), like:
+Many data items that are represented in a pin configuration node are common
+and generic. Pin control bindings should use the properties defined below
+where they are applicable; not all of these properties are relevant or useful
+for all hardware or binding structures. Each individual binding document
+should state which of these generic properties, if any, are used, and the
+structure of the DT nodes that contain these properties.
-pcfg_pull_up: pcfg_pull_up {
- bias-pull-up;
- drive-strength = <20>;
-};
-
-This node should then be referenced in the appropriate pinctrl node as a phandle
-and parsed in the driver using the pinconf_generic_parse_dt_config function.
-
-Supported configuration parameters are:
+Supported generic properties are:
+pins - the list of pins that properties in the node
+ apply to
+function - the mux function to select
bias-disable - disable any pin bias
bias-high-impedance - high impedance mode ("third-state", "floating")
bias-bus-hold - latch weakly
@@ -160,7 +159,21 @@ low-power-disable - disable low power mode
output-low - set the pin to output mode with low level
output-high - set the pin to output mode with high level
-Arguments for parameters:
+Some of the generic properties take arguments. For those that do, the
+arguments are described below.
+
+- pins takes a list of pin names or IDs as a required argument. The specific
+ binding for the hardware defines:
+ - Whether the entries are integers or strings, and their meaning.
+
+- function takes a list of function names/IDs as a required argument. The
+ specific binding for the hardware defines:
+ - Whether the entries are integers or strings, and their meaning.
+ - Whether only a single entry is allowed (which is applied to all entries
+ in the pins property), or whether there may alternatively be one entry per
+ entry in the pins property, in which case the list lengths must match, and
+ for each list index i, the function at list index i is applied to the pin
+ at list index i.
- bias-pull-up, -down and -pin-default take as optional argument on hardware
supporting it the pull strength in Ohm. bias-disable will disable the pull.
@@ -170,7 +183,5 @@ Arguments for parameters:
- input-debounce takes the debounce time in usec as argument
or 0 to disable debouncing
-All parameters not listed here, do not take an argument.
-
More in-depth documentation on these parameters can be found in
<include/linux/pinctrl/pinconfig-generic.h>
diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-palmas.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-palmas.txt
new file mode 100644
index 000000000000..734d9b04d533
--- /dev/null
+++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-palmas.txt
@@ -0,0 +1,96 @@
+Palmas Pincontrol bindings
+
+The pins of Palmas device can be set on different option and provides
+the configuration for Pull UP/DOWN, open drain etc.
+
+Required properties:
+- compatible: It must be one of following:
+ - "ti,palmas-pinctrl" for Palma series of the pincontrol.
+ - "ti,tps65913-pinctrl" for Palma series device TPS65913.
+ - "ti,tps80036-pinctrl" for Palma series device TPS80036.
+
+Please refer to pinctrl-bindings.txt in this directory for details of the
+common pinctrl bindings used by client devices, including the meaning of the
+phrase "pin configuration node".
+
+Palmas's pin configuration nodes act as a container for an arbitrary number of
+subnodes. Each of these subnodes represents some desired configuration for a
+list of pins. This configuration can include the mux function to select on
+those pin(s), and various pin configuration parameters, such as pull-up,
+open drain.
+
+The name of each subnode is not important; all subnodes should be enumerated
+and processed purely based on their content.
+
+Each subnode only affects those parameters that are explicitly listed. In
+other words, a subnode that lists a mux function but no pin configuration
+parameters implies no information about any pin configuration parameters.
+Similarly, a pin subnode that describes a pullup parameter implies no
+information about e.g. the mux function.
+
+Optional properties:
+- ti,palmas-enable-dvfs1: Enable DVFS1. Configure pins for DVFS1 mode.
+ Selection primary or secondary function associated to I2C2_SCL_SCE,
+ I2C2_SDA_SDO pin/pad for DVFS1 interface
+- ti,palmas-enable-dvfs2: Enable DVFS2. Configure pins for DVFS2 mode.
+ Selection primary or secondary function associated to GPADC_START
+ and SYSEN2 pin/pad for DVFS2 interface
+
+This binding uses the following generic properties as defined in
+pinctrl-bindings.txt:
+
+Required: pins
+Options: function, bias-disable, bias-pull-up, bias-pull-down,
+ bias-pin-default, drive-open-drain.
+
+Note that many of these properties are only valid for certain specific pins.
+See the Palmas device datasheet for complete details regarding which pins
+support which functionality.
+
+Valid values for pin names are:
+ gpio0, gpio1, gpio2, gpio3, gpio4, gpio5, gpio6, gpio7, gpio8, gpio9,
+ gpio10, gpio11, gpio12, gpio13, gpio14, gpio15, vac, powergood,
+ nreswarm, pwrdown, gpadc_start, reset_in, nsleep, enable1, enable2,
+ int.
+
+Valid value of function names are:
+ gpio, led, pwm, regen, sysen, clk32kgaudio, id, vbus_det, chrg_det,
+ vac, vacok, powergood, usb_psel, msecure, pwrhold, int, nreswarm,
+ simrsto, simrsti, low_vbat, wireless_chrg1, rcm, pwrdown, gpadc_start,
+ reset_in, nsleep, enable.
+
+There are 4 special functions: opt0, opt1, opt2 and opt3. If any of these
+functions is selected then directly pins register will be written with 0, 1, 2
+or 3 respectively if it is valid for that pins or list of pins.
+
+Example:
+ palmas: tps65913 {
+ ....
+ pinctrl {
+ compatible = "ti,tps65913-pinctrl";
+ ti,palmas-enable-dvfs1;
+ pinctrl-names = "default";
+ pinctrl-0 = <&palmas_pins_state>;
+
+ palmas_pins_state: pinmux {
+ gpio0 {
+ pins = "gpio0";
+ function = "id";
+ bias-pull-up;
+ };
+
+ vac {
+ pins = "vac";
+ function = "vacok";
+ bias-pull-down;
+ };
+
+ gpio5 {
+ pins = "gpio5";
+ function = "opt0";
+ drive-open-drain = <1>;
+ };
+ };
+ };
+ ....
+ };
diff --git a/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt
index 36281e7a2a46..257677de3e6b 100644
--- a/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt
+++ b/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt
@@ -12,6 +12,7 @@ Required Properties:
- "samsung,s3c2440-pinctrl": for S3C2440-compatible pin-controller,
- "samsung,s3c2450-pinctrl": for S3C2450-compatible pin-controller,
- "samsung,s3c64xx-pinctrl": for S3C64xx-compatible pin-controller,
+ - "samsung,s5pv210-pinctrl": for S5PV210-compatible pin-controller,
- "samsung,exynos4210-pinctrl": for Exynos4210 compatible pin-controller.
- "samsung,exynos4x12-pinctrl": for Exynos4x12 compatible pin-controller.
- "samsung,exynos5250-pinctrl": for Exynos5250 compatible pin-controller.
@@ -128,7 +129,7 @@ B. External Wakeup Interrupts: For supporting external wakeup interrupts, a
- samsung,s3c64xx-wakeup-eint: represents wakeup interrupt controller
found on Samsung S3C64xx SoCs,
- samsung,exynos4210-wakeup-eint: represents wakeup interrupt controller
- found on Samsung Exynos4210 SoC.
+ found on Samsung Exynos4210 and S5PC110/S5PV210 SoCs.
- interrupt-parent: phandle of the interrupt parent to which the external
wakeup interrupts are forwarded to.
- interrupts: interrupt used by multiplexed wakeup interrupts.
diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt
index 052e13af2d38..c0ffd30eb55e 100644
--- a/Documentation/pinctrl.txt
+++ b/Documentation/pinctrl.txt
@@ -81,7 +81,7 @@ int __init foo_probe(void)
struct pinctrl_dev *pctl;
pctl = pinctrl_register(&foo_desc, <PARENT>, NULL);
- if (IS_ERR(pctl))
+ if (!pctl)
pr_err("could not register foo pin driver\n");
}
@@ -795,18 +795,97 @@ special GPIO-handler is registered.
GPIO mode pitfalls
==================
-Sometime 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.
+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.
+
+(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.
+
+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 subssytem, 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.
@@ -856,7 +935,7 @@ static unsigned long uart_sleep_mode[] = {
PIN_CONF_PACKED(PIN_CONFIG_OUTPUT, 0),
};
-static struct pinctrl_map __initdata pinmap[] = {
+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",
@@ -951,7 +1030,7 @@ 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 __initdata mapping[] = {
+static struct pinctrl_map mapping[] __initdata = {
PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT, "pinctrl-foo", NULL, "i2c0"),
};
@@ -970,7 +1049,7 @@ static unsigned long i2c_pin_configs[] = {
FOO_SLEW_RATE_SLOW,
};
-static struct pinctrl_map __initdata mapping[] = {
+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),
@@ -984,7 +1063,7 @@ 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 __initdata mapping[] = {
+static struct pinctrl_map mapping[] __initdata = {
PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),
};