110 lines · plain
1== Introduction ==2 3Hardware modules that control pin multiplexing or configuration parameters4such as pull-up/down, tri-state, drive-strength etc are designated as pin5controllers. Each pin controller must be represented as a node in device tree,6just like any other hardware module.7 8Hardware modules whose signals are affected by pin configuration are9designated client devices. Again, each client device must be represented as a10node in device tree, just like any other hardware module.11 12For a client device to operate correctly, certain pin controllers must13set up certain specific pin configurations. Some client devices need a14single static pin configuration, e.g. set up during initialization. Others15need to reconfigure pins at run-time, for example to tri-state pins when the16device is inactive. Hence, each client device can define a set of named17states. The number and names of those states is defined by the client device's18own binding.19 20The common pinctrl bindings defined in this file provide an infrastructure21for client device device tree nodes to map those state names to the pin22configuration used by those states.23 24Note that pin controllers themselves may also be client devices of themselves.25For example, a pin controller may set up its own "active" state when the26driver loads. This would allow representing a board's static pin configuration27in a single place, rather than splitting it across multiple client device28nodes. The decision to do this or not somewhat rests with the author of29individual board device tree files, and any requirements imposed by the30bindings for the individual client devices in use by that board, i.e. whether31they require certain specific named states for dynamic pin configuration.32 33== Pinctrl client devices ==34 35For each client device individually, every pin state is assigned an integer36ID. These numbers start at 0, and are contiguous. For each state ID, a unique37property exists to define the pin configuration. Each state may also be38assigned a name. When names are used, another property exists to map from39those names to the integer IDs.40 41Each client device's own binding determines the set of states that must be42defined in its device tree node, and whether to define the set of state43IDs that must be provided, or whether to define the set of state names that44must be provided.45 46Required properties:47pinctrl-0: List of phandles, each pointing at a pin configuration48 node. These referenced pin configuration nodes must be child49 nodes of the pin controller that they configure. Multiple50 entries may exist in this list so that multiple pin51 controllers may be configured, or so that a state may be built52 from multiple nodes for a single pin controller, each53 contributing part of the overall configuration. See the next54 section of this document for details of the format of these55 pin configuration nodes.56 57 In some cases, it may be useful to define a state, but for it58 to be empty. This may be required when a common IP block is59 used in an SoC either without a pin controller, or where the60 pin controller does not affect the HW module in question. If61 the binding for that IP block requires certain pin states to62 exist, they must still be defined, but may be left empty.63 64Optional properties:65pinctrl-1: List of phandles, each pointing at a pin configuration66 node within a pin controller.67...68pinctrl-n: List of phandles, each pointing at a pin configuration69 node within a pin controller.70pinctrl-names: The list of names to assign states. List entry 0 defines the71 name for integer state ID 0, list entry 1 for state ID 1, and72 so on.73 74For example:75 76 /* For a client device requiring named states */77 device {78 pinctrl-names = "active", "idle";79 pinctrl-0 = <&state_0_node_a>;80 pinctrl-1 = <&state_1_node_a>, <&state_1_node_b>;81 };82 83 /* For the same device if using state IDs */84 device {85 pinctrl-0 = <&state_0_node_a>;86 pinctrl-1 = <&state_1_node_a>, <&state_1_node_b>;87 };88 89 /*90 * For an IP block whose binding supports pin configuration,91 * but in use on an SoC that doesn't have any pin control hardware92 */93 device {94 pinctrl-names = "active", "idle";95 pinctrl-0 = <>;96 pinctrl-1 = <>;97 };98 99== Pin controller devices ==100 101See pinctrl.yaml102 103== Generic pin multiplexing node content ==104 105See pinmux-node.yaml106 107== Generic pin configuration node content ==108 109See pincfg-node.yaml110