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

Broadcom BCM2835 GPIO (and pinmux) controller

The BCM2835 GPIO module is a combined GPIO controller, (GPIO) interrupt

controller, and pinmux/control device.

Required properties:

- compatible: "brcm,bcm2835-gpio"

- reg: Should contain the physical address of the GPIO module's registes.

- gpio-controller: Marks the device node as a GPIO controller.

- #gpio-cells : Should be two. The first cell is the pin number and the

  second cell is used to specify optional parameters:

  - bit 0 specifies polarity (0 for normal, 1 for inverted)

- interrupts : The interrupt outputs from the controller. One interrupt per

  individual bank followed by the "all banks" interrupt.

- interrupt-controller: Marks the device node as an interrupt controller.

- #interrupt-cells : Should be 2.

  The first cell is the GPIO number.

  The second cell is used to specify flags:

    bits[3:0] trigger type and level flags:

      1 = low-to-high edge triggered.

      2 = high-to-low edge triggered.

      4 = active high level-sensitive.

      8 = active low level-sensitive.

    Valid combinations are 1, 2, 3, 4, 8.

Please refer to ../gpio/gpio.txt for a general description of GPIO bindings.

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

Each pin configuration node lists the pin(s) to which it applies, and one or

more of the mux function to select on those pin(s), and pull-up/down

configuration. Each subnode only affects those parameters that are explicitly

listed. In other words, a subnode that lists only a mux function implies no

information about any pull configuration. Similarly, a subnode that lists only

a pul parameter implies no information about the mux function.

Required subnode-properties:

- brcm,pins: An array of cells. Each cell contains the ID of a pin. Valid IDs

  are the integer GPIO IDs; 0==GPIO0, 1==GPIO1, ... 53==GPIO53.

Optional subnode-properties:

- brcm,function: Integer, containing the function to mux to the pin(s):

  0: GPIO in

  1: GPIO out

  2: alt5

  3: alt4

  4: alt0

  5: alt1

  6: alt2

  7: alt3

- brcm,pull: Integer, representing the pull-down/up to apply to the pin(s):

  0: none

  1: down

  2: up

Each of brcm,function and brcm,pull may contain either a single value which

will be applied to all pins in brcm,pins, or 1 value for each entry in

brcm,pins.

Example:

	gpio: gpio {

		compatible = "brcm,bcm2835-gpio";

		reg = <0x2200000 0xb4>;

		interrupts = <2 17>, <2 19>, <2 18>, <2 20>;

		gpio-controller;

		#gpio-cells = <2>;

		interrupt-controller;

		#interrupt-cells = <2>;

	};

- pinctrl-single,function-off : function off mode for disabled state if

  available and same for all registers; if not specified, disabling of

  pin functions is ignored

- pinctrl-single,bit-per-mux : boolean to indicate that one register controls

  more than one pin

This driver assumes that there is only one register for each pin,

and uses the common pinctrl bindings as specified in the pinctrl-bindings.txt

document in this directory.

This driver assumes that there is only one register for each pin (unless the

pinctrl-single,bit-per-mux is set), and uses the common pinctrl bindings as

specified in the pinctrl-bindings.txt document in this directory.

The pin configuration nodes for pinctrl-single are specified as pinctrl

register offset and value pairs using pinctrl-single,pins. Only the bits

pinctrl register. See the device example and static board pins example

below for more information.

In case when one register changes more than one pin's mux the

pinctrl-single,bits need to be used which takes three parameters:

	pinctrl-single,bits = <0xdc 0x18, 0xff>;

Where 0xdc is the offset from the pinctrl register base address for the

device pinctrl register, 0x18 is the desired value, and 0xff is the sub mask to

be used when applying this change to the register.

Example:

/* SoC common file */

	pinctrl-single,function-mask = <0xffff>;

};

control_devconf0: pinmux@48002274 {

	compatible = "pinctrl-single";

	reg = <0x48002274 4>;	/* Single register */

	#address-cells = <1>;

	#size-cells = <0>;

	pinctrl-single,bit-per-mux;

	pinctrl-single,register-width = <32>;

	pinctrl-single,function-mask = <0x5F>;

};

/* board specific .dts file */

	};

};

&control_devconf0 {

	mcbsp1_pins: pinmux_mcbsp1_pins {

		pinctrl-single,bits = <

			0x00 0x18 0x18 /* FSR/CLKR signal from FSX/CLKX pin */

		>;

	};

	mcbsp2_clks_pins: pinmux_mcbsp2_clks_pins {

		pinctrl-single,bits = <

			0x00 0x40 0x40 /* McBSP2 CLKS from McBSP_CLKS pin */

		>;

	};

};

&uart2 {

       pinctrl-names = "default";

       pinctrl-0 = <&uart2_pins>;

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

the range ID value, so that the pin controller knows which range it should

deal with.

PINMUX interfaces

=================

pinmux core.

Pinmux requests from drivers

============================

Pin control requests from drivers

=================================

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

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:

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 pinctrl hogs, the pin control driver may be

setting up the config and muxing for the pins when it 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 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

==========================

	select COMMON_CLK

	select GENERIC_CLOCKEVENTS

	select PINCTRL

	select PINCTRL_STN8815

	select MIGHT_HAVE_CACHE_L2X0

	select ARCH_REQUIRE_GPIOLIB

	help