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