| == 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. |
| |
| pinctrl-assert-gpios: |
| List of phandles, each pointing at a GPIO which is used by some |
| board design to steer pins between two peripherals on the board. |
| It plays like a board level pin multiplexer to choose different |
| functions for given pins by pulling up/down the GPIOs. See |
| bindings/gpio/gpio.txt for details of how to specify GPIO. |
| |
| 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. |