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