share/man/man4/fdt_pinctrl.4

   1 .\" Copyright (c) 2018 Oleksandr Tymoshenko
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd March 3, 2018
  28 .Dt "FDT_PINCTRL" 4
  29 .Os
  30 .Sh NAME
  31 .Nm fdt_pinctrl
  32 .Nd FDT I/O pin multiplexing support
  33 .Sh SYNOPSIS
  34 .Cd "device fdt_pinctrl"
  35 .Sh DESCRIPTION
  36 .Pp
  37 Pin multiplexing is a technology used to re-purpose a single
  38 physical connection (depending on chip packaging it may be
  39 pin, ball, or pad) by routing its signal to any one of several
  40 different SoC internal devices.
  41 For example, based on the actual device design, a single SoC chip
  42 pin might perform any of these roles: SPI clock, I2C
  43 data, GPIO pin, or PWM signal.
  44 Function selection is performed by the pinmux controller, a SoC
  45 hardware block which is usually controlled by a set of registers.
  46 Pinmux controller capabilities and register format depend
  47 on the actual hardware implementation.
  48 .Pp
  49 On
  50 .Xr fdt 4
  51 based systems, the pinmux controller is represented by a node in
  52 the device tree.
  53 It may have any number of child nodes representing pin
  54 configuration groups.
  55 Properties of such nodes are hardware-specific and handled
  56 by individual pinctrl drivers.
  57 .Ss Example 1
  58 Pinmux controller device tree node
  59 .Bd -literal
  60 pinctrl@7e220000 {
  61     compatible = "vndr,soc1715-pinctrl";
  62     reg = <0x7e220000 0x100>
  63
  64     spi0_pins: spi0 {
  65         vndr,pins = <11 12>
  66         vndr,functions = <ALT0 ALT5>
  67     }
  68
  69     i2c0_pins: i2c0 {
  70         ...
  71     }
  72 }
  73 .Ed
  74 .Pp
  75 Client devices are hardware devices that require certain pin
  76 configurations to function properly.
  77 Depending on the state the device is in (active, idle) it might
  78 require different pin configurations.
  79 Each configuration is described by setting the pinctrl-N
  80 property to the list of phandles pointing to specific child
  81 nodes of the pinmux controller node.
  82 N is an integer value starting with 0 and incremented by 1
  83 for every new set of pin configurations.
  84 pinctrl-0 is a default configuration that is applied in the
  85 .Xr fdt_pinctrl_configure_tree 9
  86 call.
  87 In addition to referring to pin configurations by index, they
  88 can be referred to by name if the pinctrl-names property is set.
  89 The value of pinctrl-names is a list of strings with names for
  90 each pinctrl-N property.
  91 Client devices can request specific configuration using
  92 .Xr fdt_pinctrl_configure 9
  93 and
  94 .Xr fdt_pinctrl_configure_by_name 9 .
  95 .Ss Example 2
  96 .Bd -literal
  97 backlight@7f000000 {
  98     compatible = "vndr,vndr-bl"
  99     reg = <0x7f000000 0x20>
 100     ...
 101     pinctrl-name = "active", "idle"
 102     pinctrl-0 = <&backlight_active_pins>
 103     pinctrl-1 = <&backlight_idle_pins>
 104 }
 105 .Ed
 106 .Pp
 107 The pinctrl driver should implement the FDT_PINCTRL_CONFIGURE
 108 method, register itself as a pin configuration handler by
 109 calling fdt_pinctrl_register function, and call
 110 .Xr fdt_pinctrl_configure_tree 9
 111 to configure pins for all enabled devices (devices where
 112 the "status" property is not set to "disabled").
 113 .Sh SEE ALSO
 114 .Xr fdt_pinctrl 9
 115 .Sh HISTORY
 116 The
 117 .Nm
 118 driver first appeared in
 119 .Fx 10.2 .
 120 .Sh AUTHORS
 121 .An -nosplit
 122 The
 123 .Nm
 124 device driver was developed by
 125 .An \&Ian Lepore Aq Mt ian@FreeBSD.org .
 126 This manual page was written by
 127 .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .