Pinctrl-bindings.txt

Hardware modulesthat control pin multiplexing or configuration parameters

such aspull-up/down, tri-state, drive-strength etc are designated as pin

controllers. Eachpin controller must be represented as a node in device tree,

just like any otherhardware module.

 

Hardware moduleswhose signals are affected by pin configuration are

designated clientdevices. Again, each client device must be represented as a

node in device tree,just like any other hardware module.

 

For a client deviceto operate correctly, certain pin controllers must

set up certainspecific pin configurations. Some client devices need a

single static pinconfiguration, e.g. set up during initialization. Others

need to reconfigurepins 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 numberand names of those states is defined by the client device's

own binding.

 

The common pinctrlbindings defined in this file provide an infrastructure

for client devicedevice tree nodes to map those state names to the pin

configuration usedby those states.

 

Note that pincontrollers themselves may also be client devices of themselves.

For example, a pincontroller may set up its own "active" state when the

driver loads. Thiswould allow representing a board's static pin configuration

in a single place,rather than splitting it across multiple client device

nodes. The decisionto do this or not somewhat rests with the author of

individual boarddevice tree files, and any requirements imposed by the

bindings for theindividual client devices in use by that board, i.e. whether

they require certainspecific named states for dynamic pin configuration.

 

== Pinctrl clientdevices ==

 

For each clientdevice individually, every pin state is assigned an integer

ID. These numbersstart at 0, and are contiguous. For each state ID, a unique

property exists todefine the pin configuration. Each state may also be

assigned a name.When names are used, another property exists to map from

those names to theinteger IDs.

 

Each client device'sown binding determines the set of states the must be

defined in itsdevice tree node, and whether to define the set of state

IDs that must beprovided, or whether to define the set of state names that

must be provided.

 

Required properties:

pinctrl-0:      List of phandles, each pointingat a pin configuration

                node. These referencedpin configuration nodes must be child

                nodes of the pin controllerthat they configure. Multiple

                entries may exist in this listso that multiple pin

                controllers may be configured,or so that a state may be built

                from multiple nodes for asingle pin controller, each

                contributing part of theoverall configuration. See the next

                section of this document fordetails of the format of these

                pin configuration nodes.

 

                In some cases, it may be usefulto define a state, but for it

                to be empty. This may berequired when a common IP block is

                used in an SoC either without apin controller, or where the

                pin controller does not affectthe HW module in question. If

                the binding for that IP blockrequires certain pin states to

                exist, they must still bedefined, but may be left empty.

 

Optional properties:

pinctrl-1:      List of phandles, each pointing at a pinconfiguration

                node within a pin controller.

...

pinctrl-n:      List of phandles, each pointing at a pinconfiguration

                node within a pin controller.

pinctrl-names:  The list of names to assign states. Listentry 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 namedstates */

        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 stateIDs */

        device {

                pinctrl-0 =<&state_0_node_a>;

                pinctrl-1 =<&state_1_node_a &state_1_node_b>;

        };

 

        /*

         * For an IP block whose bindingsupports pin configuration,

         * but in use on an SoC that doesn'thave any pin control hardware

         */

        device {

                pinctrl-names ="active", "idle";

                pinctrl-0 = <>;

                pinctrl-1 = <>;

        };

 

== Pin controllerdevices ==

 

Pin controllerdevices should contain the pin configuration nodes that client

devices reference.

 

For example:

 

        pincontroller {

                ... /* Standard DT propertiesfor the device itself elided */

 

                state_0_node_a {

                        ...

                };

                state_1_node_a {

                        ...

                };

                state_1_node_b {

                        ...

                };

        }

 

The contents of eachof those pin configuration child nodes is defined

entirely by thebinding for the individual pin controller device. There

exists no commonstandard for this content.

 

The pinconfiguration nodes need not be direct children of the pin controller

device; they may begrandchildren, for example. Whether this is legal, and

whether there is anyinteraction between the child and intermediate parent

nodes, is againdefined entirely by the binding for the individual pin

controller device.

 

== Using genericpinconfig options ==

 

Generic pinconfigparameters can be used by defining a separate node containing

the applicableparameters (and optional values), like:

 

pcfg_pull_up:pcfg_pull_up {

        bias-pull-up;

        drive-strength = <20>;

};

 

This node shouldthen be referenced in the appropriate pinctrl node as a phandle

and parsed in thedriver using the pinconf_generic_parse_dt_config function.

 

Supportedconfiguration parameters are:

 

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-schmitt-enable    - enable schmitt-trigger mode

input-schmitt-disable   - disable schmitt-trigger mode

input-schmitt           - run in schmitt-trigger mode withhysteresis X

input-debounce          - debounce mode with debound time X

power-source            - select power source X

slew-rate               - use slew-rate X

low-power-enable        - enable low power mode

low-power-disable       - disable low power mode

output-low              - set the pin to output mode withlow level

output-high             - set the pin to output mode withhigh level

 

Arguments forparameters:

 

- bias-pull-up,-down and -pin-default take as optional argument 0 to disable

  the pull, on hardware supporting it the pullstrength in Ohm. bias-disable

  will also disable any active pull.

 

- drive-strengthtakes as argument the target strength in mA.

 

- input-schmitttakes as argument the adjustable hysteresis in a

  driver-specific format

 

- input-debouncetakes the debounce time as argument or 0 to disable debouncing

 

- power-sourceargument is the custom value describing the source to select

 

- slew-rate takes asargument the target rate in a driver-specific format

 

All parameters notlisted here, do not take an argument.

 

More in-depthdocumentation on these parameters can be found in

<include/linux/pinctrl/pinconfig-generic.h>