NAME

     fdt_pinctrl — FDT I/O pin multiplexing support

SYNOPSIS

     device fdt_pinctrl

DESCRIPTION

     Pin multiplexing is a technology used to re-purpose a single physical connection (depending
     on chip packaging it may be pin, ball, or pad) by routing its signal to any one of several
     different SoC internal devices.  For example, based on the actual device design, a single
     SoC chip pin might perform any of these roles: SPI clock, I2C data, GPIO pin, or PWM signal.
     Function selection is performed by the pinmux controller, a SoC hardware block which is
     usually controlled by a set of registers.  Pinmux controller capabilities and register
     format depend on the actual hardware implementation.

     On fdt(4) based systems, the pinmux controller is represented by a node in the device tree.
     It may have any number of child nodes representing pin configuration groups.  Properties of
     such nodes are hardware-specific and handled by individual pinctrl drivers.

   Example 1
     Pinmux controller device tree node

     pinctrl@7e220000 {
         compatible = "vndr,soc1715-pinctrl";
         reg = <0x7e220000 0x100>

         spi0_pins: spi0 {
             vndr,pins = <11 12>
             vndr,functions = <ALT0 ALT5>
         }

         i2c0_pins: i2c0 {
             ...
         }
     }

     Client devices are hardware devices that require certain pin configurations to function
     properly.  Depending on the state the device is in (active, idle) it might require different
     pin configurations.  Each configuration is described by setting the pinctrl-N property to
     the list of phandles pointing to specific child nodes of the pinmux controller node.  N is
     an integer value starting with 0 and incremented by 1 for every new set of pin
     configurations.  pinctrl-0 is a default configuration that is applied in the
     fdt_pinctrl_configure_tree(9) call.  In addition to referring to pin configurations by
     index, they can be referred to by name if the pinctrl-names property is set.  The value of
     pinctrl-names is a list of strings with names for each pinctrl-N property.  Client devices
     can request specific configuration using fdt_pinctrl_configure(9) and
     fdt_pinctrl_configure_by_name(9).

   Example 2
     backlight@7f000000 {
         compatible = "vndr,vndr-bl"
         reg = <0x7f000000 0x20>
         ...
         pinctrl-name = "active", "idle"
         pinctrl-0 = <&backlight_active_pins>
         pinctrl-1 = <&backlight_idle_pins>
     }

     The pinctrl driver should implement the FDT_PINCTRL_CONFIGURE method, register itself as a
     pin configuration handler by calling fdt_pinctrl_register function, and call
     fdt_pinctrl_configure_tree(9) to configure pins for all enabled devices (devices where the
     "status" property is not set to "disabled").

SEE ALSO

     fdt_pinctrl(9)

HISTORY

     The fdt_pinctrl driver first appeared in FreeBSD 10.2.

AUTHORS

     The fdt_pinctrl device driver was developed by Ian Lepore <ian@FreeBSD.org>.  This manual
     page was written by Oleksandr Tymoshenko <gonzo@FreeBSD.org>.