pinctrl 文档

== 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 multiplexing node content ==
pin multiplexing nodes:
function        - the mux function to select groups            - the list of groups to select with this function
Example:
state_0_node_a { function = "uart0";
    groups = "u0rxtx", "u0rtscts"; }; state_1_node_a { function = "spi0";
    groups = "spi0pins"; };
== 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 { pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */
    bias-pull-up; }; state_1_node_a { pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */
    output-high; }; state_2_node_a { 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/pinconfig-generic.h>