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