Merge tag 'pinctrl-v3.12-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-pinctrl

		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>;

		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.

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

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.

- 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>

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>;

				};

			};

		};

		....

	};

  - "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.

     - 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.

	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");

}

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.

    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",

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"),

};

	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),

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),

};