1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 2018 Oleksandr Tymoshenko 4.\" 5.\" All rights reserved. 6.\" 7.\" This program is free software. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 21.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 23.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 27.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.\" 29.\" $FreeBSD$ 30.\" 31.Dd March 2, 2018 32.Dt fdt_pinctrl 9 33.Os 34.Sh NAME 35.Nm fdt_pinctrl 36.Nd helper functions for FDT pinmux controller drivers 37.Sh SYNOPSIS 38.In dev/fdt/fdt_pinctrl.h 39.Ft int 40.Fn fdt_pinctrl_configure "device_t client" "u_int index" 41.Ft int 42.Fn fdt_pinctrl_configure_by_name "device_t client" "const char * name" 43.Ft int 44.Fn fdt_pinctrl_register "device_t pinctrl" "const char *pinprop" 45.Ft int 46.Fn fdt_pinctrl_configure_tree "device_t pinctrl" 47.Sh DESCRIPTION 48.Xr fdt_pinctrl 4 49provides an API for manipulating I/O pin configurations on 50pinmux controllers and pinmux clients. 51On the controller side, the standard newbus probe and 52attach methods are implemented. 53This driver also implements the 54.Fn fdt_pinctrl_configure 55method, in which it calls the 56.Fn fdt_pinctrl_register 57function to register itself as a pinmux controller. 58Then 59.Fn fdt_pinctrl_configure_tree 60is used to walk the device tree and configure pins specified by the pinctrl-0 61property for all active devices. 62If a client device requires a pin configuration change at some 63point of its lifecycle, it uses the 64.Fn fdt_pinctrl_configure 65or 66.Fn fdt_pinctrl_configure_by_name 67functions. 68.Pp 69.Fn fdt_pinctrl_configure 70is used by client device 71.Fa client 72to request a pin configuration 73described by the pinctrl-N property with index 74.Fa index . 75.Pp 76.Fn fdt_pinctrl_configure_by_name 77is used by client device 78.Fa client 79to request the pin configuration with name 80.Fa name . 81.Pp 82.Fn fdt_pinctrl_register 83registers a pinctrl driver so that it can be used by other devices which call 84.Fn fdt_pinctrl_configure 85or 86.Fn fdt_pinctrl_configure_by_name . 87The 88.Fa pinprop 89argument is the name of a property that 90identifies each descendant of the pinctrl 91node. 92The pinctrl node is a pin configuration 93node whose xref phandle can be passed to 94.Fn FDT_PINCTRL_CONFIGURE . 95If 96.Fa pinprop 97is 98.Dv NULL , 99every descendant node is registered. 100It is possible for the driver to register itself 101as a pinmux controller for more than one pin property type 102by calling 103.Fn fdt_pinctrl_register 104multiple types. 105.Pp 106.Fn fdt_pinctrl_configure_tree 107walks through enabled devices in the device tree. 108If the pinctrl-0 property contains references 109to child nodes of the specified pinctrl device, 110their pins are configured. 111.Sh EXAMPLES 112.Bd -literal 113static int 114foo_configure_pins(device_t dev, phandle_t cfgxref) 115{ 116 phandle_t cfgnode; 117 uint32_t *pins, *functions; 118 int npins, nfunctions; 119 120 cfgnode = OF_node_from_xref(cfgxref); 121 pins = NULL; 122 npins = OF_getencprop_alloc(cfgnode, "foo,pins", sizeof(*pins), 123 (void **)&pins); 124 functions = NULL; 125 nfunctions = OF_getencprop_alloc(cfgnode, "foo,functions", 126 sizeof(*functions), (void **)&functions); 127 ... 128} 129 130static int 131foo_attach(device_t dev) 132{ 133 ... 134 135 fdt_pinctrl_register(dev, "foo,pins"); 136 /* 137 * It is possible to register more than one pinprop handler 138 */ 139 fdt_pinctrl_register(dev, "bar,pins"); 140 fdt_pinctrl_configure_tree(dev); 141 142 return (0); 143} 144 145static device_method_t foo_methods[] = { 146 ... 147 148 /* fdt_pinctrl interface */ 149 DEVMETHOD(fdt_pinctrl_configure, foo_configure_pins), 150 151 /* Terminate method list */ 152 DEVMETHOD_END 153}; 154 155DRIVER_MODULE(foo, simplebus, foo_driver, foo_devclass, NULL, NULL); 156.Ed 157.Sh SEE ALSO 158.Xr fdt_pinctrl 4 , 159.Sh AUTHORS 160This manual page was written by 161.An Oleksandr Tymoshenko . 162