Hardware modulesthat control pin multiplexing or configuration parameters
such aspull-up/down, tri-state, drive-strength etc are designated as pin
controllers. Eachpin controller must be represented as a node in device tree,
just like any otherhardware module.
Hardware moduleswhose signals are affected by pin configuration are
designated clientdevices. Again, each client device must be represented as a
node in device tree,just like any other hardware module.
For a client deviceto operate correctly, certain pin controllers must
set up certainspecific pin configurations. Some client devices need a
single static pinconfiguration, e.g. set up during initialization. Others
need to reconfigurepins 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 numberand names of those states is defined by the client device's
own binding.
The common pinctrlbindings defined in this file provide an infrastructure
for client devicedevice tree nodes to map those state names to the pin
configuration usedby those states.
Note that pincontrollers themselves may also be client devices of themselves.
For example, a pincontroller may set up its own "active" state when the
driver loads. Thiswould allow representing a board's static pin configuration
in a single place,rather than splitting it across multiple client device
nodes. The decisionto do this or not somewhat rests with the author of
individual boarddevice tree files, and any requirements imposed by the
bindings for theindividual client devices in use by that board, i.e. whether
they require certainspecific named states for dynamic pin configuration.
== Pinctrl clientdevices ==
For each clientdevice individually, every pin state is assigned an integer
ID. These numbersstart at 0, and are contiguous. For each state ID, a unique
property exists todefine the pin configuration. Each state may also be
assigned a name.When names are used, another property exists to map from
those names to theinteger IDs.
Each client device'sown binding determines the set of states the must be
defined in itsdevice tree node, and whether to define the set of state
IDs that must beprovided, or whether to define the set of state names that
must be provided.
Required properties:
pinctrl-0: List of phandles, each pointingat a pin configuration
node. These referencedpin configuration nodes must be child
nodes of the pin controllerthat they configure. Multiple
entries may exist in this listso that multiple pin
controllers may be configured,or so that a state may be built
from multiple nodes for asingle pin controller, each
contributing part of theoverall configuration. See the next
section of this document fordetails of the format of these
pin configuration nodes.
In some cases, it may be usefulto define a state, but for it
to be empty. This may berequired when a common IP block is
used in an SoC either without apin controller, or where the
pin controller does not affectthe HW module in question. If
the binding for that IP blockrequires certain pin states to
exist, they must still bedefined, but may be left empty.
Optional properties:
pinctrl-1: List of phandles, each pointing at a pinconfiguration
node within a pin controller.
...
pinctrl-n: List of phandles, each pointing at a pinconfiguration
node within a pin controller.
pinctrl-names: The list of names to assign states. Listentry 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 namedstates */
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 stateIDs */
device {
pinctrl-0 =<&state_0_node_a>;
pinctrl-1 =<&state_1_node_a &state_1_node_b>;
};
/*
* For an IP block whose bindingsupports pin configuration,
* but in use on an SoC that doesn'thave any pin control hardware
*/
device {
pinctrl-names ="active", "idle";
pinctrl-0 = <>;
pinctrl-1 = <>;
};
== Pin controllerdevices ==
Pin controllerdevices should contain the pin configuration nodes that client
devices reference.
For example:
pincontroller {
... /* Standard DT propertiesfor the device itself elided */
state_0_node_a {
...
};
state_1_node_a {
...
};
state_1_node_b {
...
};
}
The contents of eachof those pin configuration child nodes is defined
entirely by thebinding for the individual pin controller device. There
exists no commonstandard for this content.
The pinconfiguration nodes need not be direct children of the pin controller
device; they may begrandchildren, for example. Whether this is legal, and
whether there is anyinteraction between the child and intermediate parent
nodes, is againdefined entirely by the binding for the individual pin
controller device.
== Using genericpinconfig options ==
Generic pinconfigparameters can be used by defining a separate node containing
the applicableparameters (and optional values), like:
pcfg_pull_up:pcfg_pull_up {
bias-pull-up;
drive-strength = <20>;
};
This node shouldthen be referenced in the appropriate pinctrl node as a phandle
and parsed in thedriver using the pinconf_generic_parse_dt_config function.
Supportedconfiguration parameters are:
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
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-schmitt-enable - enable schmitt-trigger mode
input-schmitt-disable - disable schmitt-trigger mode
input-schmitt - run in schmitt-trigger mode withhysteresis X
input-debounce - debounce mode with debound time X
power-source - select power source X
slew-rate - use slew-rate X
low-power-enable - enable low power mode
low-power-disable - disable low power mode
output-low - set the pin to output mode withlow level
output-high - set the pin to output mode withhigh level
Arguments forparameters:
- bias-pull-up,-down and -pin-default take as optional argument 0 to disable
the pull, on hardware supporting it the pullstrength in Ohm. bias-disable
will also disable any active pull.
- drive-strengthtakes as argument the target strength in mA.
- input-schmitttakes as argument the adjustable hysteresis in a
driver-specific format
- input-debouncetakes the debounce time as argument or 0 to disable debouncing
- power-sourceargument is the custom value describing the source to select
- slew-rate takes asargument the target rate in a driver-specific format
All parameters notlisted here, do not take an argument.
More in-depthdocumentation on these parameters can be found in
<include/linux/pinctrl/pinconfig-generic.h>