forked from Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
148 lines
5.6 KiB
148 lines
5.6 KiB
== 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 |
|
|
|
pinctrl-use-default: Boolean. Indicates that the OS can use the boot default |
|
pin configuration. This allows using an OS that does not have a |
|
driver for the pin controller. This property can be set either |
|
globally for the pin controller or in child nodes for individual |
|
pin group control. |
|
|
|
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 == |
|
|
|
See pinmux-node.yaml |
|
|
|
== Generic pin configuration node content == |
|
|
|
See pincfg-node.yaml
|
|
|