dts: Bring in pinctrl device tree binding
Add this binding file since we now use it in U-Boot. Signed-off-by: Simon Glass <sjg@chromium.org>
This commit is contained in:
Simon Glass
parent
931b24c5a0
commit
61101e0583
236
doc/device-tree-bindings/pinctrl/pinctrl-bindings.txt
Normal file
236
doc/device-tree-bindings/pinctrl/pinctrl-bindings.txt
Normal file
@ -0,0 +1,236 @@
|
||||
== 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 ==
|
||||
|
||||
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 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";
|
||||
};
|
||||
|
||||
== 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 or "group" 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 or "pins" has 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
|
||||
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
|
||||
|
||||
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;
|
||||
};
|
||||
};
|
||||
|
||||
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.
|
||||
|
||||
- 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>
|
||||
Loading…
Reference in New Issue
Block a user