FreeBSD/Linux Kernel Cross Reference
sys/contrib/device-tree/Bindings/pinctrl/pinctrl-bindings.txt

     == 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 ==
   
   See pinctrl.yaml
   
   == Generic pin multiplexing node content ==
   
   See pinmux-node.yaml
   
   == Generic pin configuration node content ==
   
   See pincfg-node.yaml

Cache object: c5602ca41d316211787e48f5030905ad