mirror of
https://github.com/AsahiLinux/u-boot
synced 2024-12-01 08:59:33 +00:00
9c08fbfc95
The pinmux property allows for smaller and more compact device trees, especially when there are many pins which need to be assigned individually. Instead of specifying an array of strings to be parsed as pins and a function property, the pinmux property contains an array of integers representing pinmux groups. A pinmux group consists of the pin identifier and mux settings represented as a single integer or an array of integers. Each individual pin controller driver specifies the exact format of a pinmux group. As specified in the Linux documentation, a pinmux group may be multiple integers long. However, no existing drivers use multi-integer pinmux groups, so I have chosen to omit this feature. This makes the implementation easier, since there is no need to allocate a buffer to do endian conversions. Support for the pinmux property is done differently than in Linux. As far as I can tell, inversion of control is used when implementing support for the pins and groups properties to avoid allocating. This results in some duplication of effort; every property in a config node is parsed once for each pin in that node. This is not such an overhead with pins and groups properties, since having multiple pins in one config node does not occur especially often. However, the semantics of the pinmux property make such a configuration much more appealing. A future patch could parse all config properties at once and store them in an array. This would make it easier to create drivers which do not function solely as callbacks from pinctrl-generic. This commit increases the size of the sandbox build by approximately 48 bytes. However, it also decreases the size of the K210 device tree by 2 KiB from the previous version of this series. The documentation has been updated from the last Linux commit before it was split off into yaml files. Signed-off-by: Sean Anderson <seanga2@gmail.com> Reviewed-by: Simon Glass <sjg@chromium.org>
289 lines
10 KiB
Text
289 lines
10 KiB
Text
== 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 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";
|
|
};
|
|
|
|
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 provided with mux configuration settings
|
|
in a pinmux group. A pinmux group consists of the pin identifier and mux
|
|
settings represented as a single integer or an array of integers.
|
|
|
|
The pinmux property accepts an array of pinmux groups, each of them describing
|
|
a single pin multiplexing configuration.
|
|
|
|
pincontroller {
|
|
state_0_node_a {
|
|
pinmux = <PINMUX_GROUP>, <PINMUX_GROUP>, ...;
|
|
};
|
|
};
|
|
|
|
Each individual pin controller driver bindings documentation shall specify
|
|
how pin IDs and pin multiplexing configuration are defined and assembled
|
|
together in a pinmux group.
|
|
|
|
== 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
|
|
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
|
|
drive-strength-microamp - sink or source at most X uA
|
|
input-enable - enable input on pin (no effect on output, such as
|
|
enabling an input buffer)
|
|
input-disable - disable input on pin (no effect on output, such as
|
|
disabling an input buffer)
|
|
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-disable - disable output on a pin (such as disable an output
|
|
buffer)
|
|
output-enable - enable output on a pin without actively driving it
|
|
(such as enabling an output buffer)
|
|
output-low - set the pin to output mode with low level
|
|
output-high - set the pin to output mode with high level
|
|
sleep-hardware-state - indicate this is sleep related state which will be programmed
|
|
into the registers for the sleep state.
|
|
slew-rate - set the slew rate
|
|
skew-delay - this affects the expected clock skew on input pins
|
|
and the delay before latching a value to an output
|
|
pin. Typically indicates how many double-inverters are
|
|
used to delay the signal.
|
|
|
|
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 or an array of integers.
|
|
|
|
- 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.
|
|
|
|
- drive-strength-microamp takes as argument the target strength in uA.
|
|
|
|
- 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>
|