== Introduction ==

Hardware modules that control pin multiplexing or configuration parameters
such as pull-up/down, tri-state, drive-strength etc are designated as pin
controllers. Each pin controller must be represented as a node in device tree,
just like any other hardware module.

Hardware modules whose signals are affected by pin configuration are
designated client devices. Again, each client device must be represented as a
node in device tree, just like any other hardware module.

For a client device to operate correctly, certain pin controllers must
set up certain specific pin configurations. Some client devices need a
single static pin configuration, e.g. set up during initialization. Others
need to reconfigure pins at run-time, for example to tri-state pins when the
device is inactive. Hence, each client device can define a set of named
states. The number and names of those states is defined by the client device's
own binding.

The common pinctrl bindings defined in this file provide an infrastructure
for client device device tree nodes to map those state names to the pin
configuration used by those states.

Note that pin controllers themselves may also be client devices of themselves.
For example, a pin controller may set up its own "active" state when the
driver loads. This would allow representing a board's static pin configuration
in a single place, rather than splitting it across multiple client device
nodes. The decision to do this or not somewhat rests with the author of
individual board device tree files, and any requirements imposed by the
bindings for the individual client devices in use by that board, i.e. whether
they require certain specific named states for dynamic pin configuration.

== Pinctrl client devices ==

For each client device individually, every pin state is assigned an integer
ID. These numbers start at 0, and are contiguous. For each state ID, a unique
property exists to define the pin configuration. Each state may also be
assigned a name. When names are used, another property exists to map from
those names to the integer IDs.

Each client device's own binding determines the set of states that must be
defined in its device tree node, and whether to define the set of state
IDs that must be provided, or whether to define the set of state names that
must be provided.

Required properties:
pinctrl-0:	List of phandles, each pointing at a pin configuration
		node. These referenced pin configuration nodes must be child
		nodes of the pin controller that they configure. Multiple
		entries may exist in this list so that multiple pin
		controllers may be configured, or so that a state may be built
		from multiple nodes for a single pin controller, each
		contributing part of the overall configuration. See the next
		section of this document for details of the format of these
		pin configuration nodes.

		In some cases, it may be useful to define a state, but for it
		to be empty. This may be required when a common IP block is
		used in an SoC either without a pin controller, or where the
		pin controller does not affect the HW module in question. If
		the binding for that IP block requires certain pin states to
		exist, they must still be defined, but may be left empty.

Optional properties:
pinctrl-1:	List of phandles, each pointing at a pin configuration
		node within a pin controller.
...
pinctrl-n:	List of phandles, each pointing at a pin configuration
		node within a pin controller.
pinctrl-names:	The list of names to assign states. List entry 0 defines the
		name for integer state ID 0, list entry 1 for state ID 1, and
		so on.

For example:

	/* For a client device requiring named states */
	device {
		pinctrl-names = "active", "idle";
		pinctrl-0 = <&state_0_node_a>;
		pinctrl-1 = <&state_1_node_a &state_1_node_b>;
	};

	/* For the same device if using state IDs */
	device {
		pinctrl-0 = <&state_0_node_a>;
		pinctrl-1 = <&state_1_node_a &state_1_node_b>;
	};

	/*
	 * For an IP block whose binding supports pin configuration,
	 * but in use on an SoC that doesn't have any pin control hardware
	 */
	device {
		pinctrl-names = "active", "idle";
		pinctrl-0 = <>;
		pinctrl-1 = <>;
	};

== Pin controller devices ==
Required properties: See the pin controller driver specific documentation

Optional properties:
#pinctrl-cells:	Number of pin control cells in addition to the index within the
		pin controller device instance

Pin controller devices should contain the pin configuration nodes that client
devices reference.

For example:

	pincontroller {
		... /* Standard DT properties for the device itself elided */

		state_0_node_a {
			...
		};
		state_1_node_a {
			...
		};
		state_1_node_b {
			...
		};
	}

The contents of each of those pin configuration child nodes is defined
entirely by the binding for the individual pin controller device. There
exists no common standard for this content. The pinctrl framework only
provides generic helper bindings that the pin controller driver can use.

The pin configuration nodes need not be direct children of the pin controller
device; they may be grandchildren, for example. Whether this is legal, and
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.

== Generic pin multiplexing node content ==

pin multiplexing nodes:

function		- the mux function to select
groups			- the list of groups to select with this function
			  (either this or "pins" must be specified)
pins			- the list of pins to select with this function (either
			  this or "groups" must be specified)

Example:

state_0_node_a {
	uart0 {
		function = "uart0";
		groups = "u0rxtx", "u0rtscts";
	};
};
state_1_node_a {
	spi0 {
		function = "spi0";
		groups = "spi0pins";
	};
};
state_2_node_a {
	function = "i2c0";
	pins = "mfio29", "mfio30";
};

Optionally an alternative binding can be used if more suitable depending on the
pin controller hardware. For hardware where there is a large number of identical
pin controller instances, naming each pin and function can easily become
unmaintainable. This is especially the case if the same controller is used for
different pins and functions depending on the SoC revision and packaging.

For cases like this, the pin controller driver may use pinctrl-pin-array helper
binding with a hardware based index and a number of pin configuration values:

pincontroller {
	... /* Standard DT properties for the device itself elided */
	#pinctrl-cells = <2>;

	state_0_node_a {
		pinctrl-pin-array = <
			0 A_DELAY_PS(0) G_DELAY_PS(120)
			4 A_DELAY_PS(0) G_DELAY_PS(360)
			...
		>;
	};
	...
};

Above #pinctrl-cells specifies the number of value cells in addition to the
index of the registers. This is similar to the interrupts-extended binding with
one exception. There is no need to specify the phandle for each entry as that
is already known as the defined pins are always children of the pin controller
node. Further having the phandle pointing to another pin controller would not
currently work as the pinctrl framework uses named modes to group pins for each
pin control device.

The index for pinctrl-pin-array must relate to the hardware for the pinctrl
registers, and must not be a virtual index of pin instances. The reason for
this is to avoid mapping of the index in the dts files and the pin controller
driver as it can change.

For hardware where pin multiplexing configurations have to be specified for
each single pin the number of required sub-nodes containing "pin" and
"function" properties can quickly escalate and become hard to write and
maintain.

For cases like this, the pin controller driver may use the pinmux helper
property, where the pin identifier is packed with mux configuration settings
in a single integer.

The pinmux property accepts an array of integers, each of them describing
a single pin multiplexing configuration.

pincontroller {
	state_0_node_a {
		pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ...;
	};
};

Each individual pin controller driver bindings documentation shall specify
how those values (pin IDs and pin multiplexing configuration) are defined and
assembled together.

== Generic pin configuration node content ==

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.

Supported generic properties are:

pins			- the list of pins that properties in the node
			  apply to (either this, "group" or "pinmux" has to be
			  specified)
group			- the group to apply the properties to, if the driver
			  supports configuration of whole groups rather than
			  individual pins (either this, "pins" or "pinmux" has
			  to be specified)
pinmux			- the list of numeric pin ids and their mux settings
			  that properties in the node apply to (either this,
			  "pins" or "groups" have to be specified)
bias-disable		- disable any pin bias
bias-high-impedance	- high impedance mode ("third-state", "floating")
bias-bus-hold		- latch weakly
bias-pull-up		- pull up the pin
bias-pull-down		- pull down the pin
bias-pull-pin-default	- use pin-default pull state
bi-directional		- pin supports simultaneous input/output operations
drive-push-pull		- drive actively high and low
drive-open-drain	- drive with open drain
drive-open-source	- drive with open source
drive-strength		- sink or source at most X mA
input-enable		- enable input on pin (no effect on output)
input-disable		- disable input on pin (no effect on output)
input-schmitt-enable	- enable schmitt-trigger mode
input-schmitt-disable	- disable schmitt-trigger mode
input-debounce		- debounce mode with debound time X
power-source		- select between different power supplies
low-power-enable	- enable low power mode
low-power-disable	- disable low power mode
output-enable		- enable output on pin regardless of output value
output-low		- set the pin to output mode with low level
output-high		- set the pin to output mode with high level
slew-rate		- set the slew rate

For example:

state_0_node_a {
	cts_rxd {
		pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */
		bias-pull-up;
	};
};
state_1_node_a {
	rts_txd {
		pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */
		output-high;
	};
};
state_2_node_a {
	foo {
		group = "foo-group";
		bias-pull-up;
	};
};
state_3_node_a {
	mux {
		pinmux = <GPIOx_PINm_MUXn>, <GPIOx_PINj_MUXk)>;
		input-enable;
	};
};

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.

- pinmux takes a list of pin IDs and mux settings as required argument. The
  specific bindings for the hardware defines:
  - How pin IDs and mux settings are defined and assembled together in a single
    integer.

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

- drive-strength takes as argument the target strength in mA.

- input-debounce takes the debounce time in usec as argument
  or 0 to disable debouncing

More in-depth documentation on these parameters can be found in
<include/linux/pinctrl/pinconf-generic.h>