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 Pin multiplexing is a technology used to re-purpose a single
  37 physical connection (depending on chip packaging it may be
  38 pin, ball, or pad) by routing its signal to any one of several
  39 different SoC internal devices.
  40 For example, based on the actual device design, a single SoC chip
  41 pin might perform any of these roles: SPI clock, I2C
  42 data, GPIO pin, or PWM signal.
  43 Function selection is performed by the pinmux controller, a SoC
  44 hardware block which is usually controlled by a set of registers.
  45 Pinmux controller capabilities and register format depend
  46 on the actual hardware implementation.
  47 .Pp
  48 On
  49 .Xr fdt 4
  50 based systems, the pinmux controller is represented by a node in
  51 the device tree.
  52 It may have any number of child nodes representing pin
  53 configuration groups.
  54 Properties of such nodes are hardware-specific and handled
  55 by individual pinctrl drivers.
  56 .Ss Example 1
  57 Pinmux controller device tree node
  58 .Bd -literal
  59 pinctrl@7e220000 {
  60     compatible = "vndr,soc1715-pinctrl";
  61     reg = <0x7e220000 0x100>
  62
  63     spi0_pins: spi0 {
  64         vndr,pins = <11 12>
  65         vndr,functions = <ALT0 ALT5>
  66     }
  67
  68     i2c0_pins: i2c0 {
  69         ...
  70     }
  71 }
  72 .Ed
  73 .Pp
  74 Client devices are hardware devices that require certain pin
  75 configurations to function properly.
  76 Depending on the state the device is in (active, idle) it might
  77 require different pin configurations.
  78 Each configuration is described by setting the pinctrl-N
  79 property to the list of phandles pointing to specific child
  80 nodes of the pinmux controller node.
  81 N is an integer value starting with 0 and incremented by 1
  82 for every new set of pin configurations.
  83 pinctrl-0 is a default configuration that is applied in the
  84 .Xr fdt_pinctrl_configure_tree 9
  85 call.
  86 In addition to referring to pin configurations by index, they
  87 can be referred to by name if the pinctrl-names property is set.
  88 The value of pinctrl-names is a list of strings with names for
  89 each pinctrl-N property.
  90 Client devices can request specific configuration using
  91 .Xr fdt_pinctrl_configure 9
  92 and
  93 .Xr fdt_pinctrl_configure_by_name 9 .
  94 .Ss Example 2
  95 .Bd -literal
  96 backlight@7f000000 {
  97     compatible = "vndr,vndr-bl"
  98     reg = <0x7f000000 0x20>
  99     ...
 100     pinctrl-name = "active", "idle"
 101     pinctrl-0 = <&backlight_active_pins>
 102     pinctrl-1 = <&backlight_idle_pins>
 103 }
 104 .Ed
 105 .Pp
 106 The pinctrl driver should implement the FDT_PINCTRL_CONFIGURE
 107 method, register itself as a pin configuration handler by
 108 calling fdt_pinctrl_register function, and call
 109 .Xr fdt_pinctrl_configure_tree 9
 110 to configure pins for all enabled devices (devices where
 111 the "status" property is not set to "disabled").
 112 .Sh SEE ALSO
 113 .Xr fdt_pinctrl 9
 114 .Sh HISTORY
 115 The
 116 .Nm
 117 driver first appeared in
 118 .Fx 10.2 .
 119 .Sh AUTHORS
 120 .An -nosplit
 121 The
 122 .Nm
 123 device driver was developed by
 124 .An \&Ian Lepore Aq Mt ian@FreeBSD.org .
 125 This manual page was written by
 126 .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .