FDT_PINCTRL(4)         FreeBSD Kernel Interfaces Manual         FDT_PINCTRL(4)

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>.

FreeBSD 13.1-RELEASE-p6          March 3, 2018         FreeBSD 13.1-RELEASE-p6