192 lines
7.7 KiB
Plaintext
192 lines
7.7 KiB
Plaintext
== 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 the 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 ==
|
|
|
|
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 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 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
|
|
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
|
|
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-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-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
|
|
|
|
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.
|
|
|
|
- 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/pinconfig-generic.h>
|