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.Dd June 23, 2018 30.Dt fdt_pinctrl 9 31.Os 32.Sh NAME 33.Nm fdt_pinctrl 34.Nd helper functions for FDT pinmux controller drivers 35.Sh SYNOPSIS 36.In dev/fdt/fdt_pinctrl.h 37.Ft int 38.Fn fdt_pinctrl_configure "device_t client" "u_int index" 39.Ft int 40.Fn fdt_pinctrl_configure_by_name "device_t client" "const char * name" 41.Ft int 42.Fn fdt_pinctrl_register "device_t pinctrl" "const char *pinprop" 43.Ft int 44.Fn fdt_pinctrl_configure_tree "device_t pinctrl" 45.Sh DESCRIPTION 46.Xr fdt_pinctrl 4 47provides an API for manipulating I/O pin configurations on 48pinmux controllers and pinmux clients. 49On the controller side, the standard newbus probe and 50attach methods are implemented. 51As part of handling attach, it calls the 52.Fn fdt_pinctrl_register 53function to register itself as a pinmux controller. 54Then 55.Fn fdt_pinctrl_configure_tree 56is used to walk the device tree and configure pins specified by the pinctrl-0 57property for all active devices. 58The driver also implements the 59.Fn fdt_pinctrl_configure 60method, which allows client devices to change their 61pin configurations after startup. 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 . 87It also registers each child node of the pinctrl driver's node which contains 88a property with the name given in 89.Fa pinprop . 90If 91.Fa pinprop 92is 93.Dv NULL , 94every descendant node is registered. 95It is possible for the driver to register itself 96as a pinmux controller for more than one pin property type 97by calling 98.Fn fdt_pinctrl_register 99multiple types. 100.Pp 101.Fn fdt_pinctrl_configure_tree 102walks through enabled devices in the device tree. 103If the pinctrl-0 property contains references 104to child nodes of the specified pinctrl device, 105their pins are configured. 106.Sh EXAMPLES 107.Bd -literal 108static int 109foo_configure_pins(device_t dev, phandle_t cfgxref) 110{ 111 phandle_t cfgnode; 112 uint32_t *pins, *functions; 113 int npins, nfunctions; 114 115 cfgnode = OF_node_from_xref(cfgxref); 116 pins = NULL; 117 npins = OF_getencprop_alloc_multi(cfgnode, "foo,pins", sizeof(*pins), 118 (void **)&pins); 119 functions = NULL; 120 nfunctions = OF_getencprop_alloc_multi(cfgnode, "foo,functions", 121 sizeof(*functions), (void **)&functions); 122 ... 123} 124 125static int 126foo_is_gpio(device_t dev, device_t gpiodev, bool *is_gpio) 127{ 128 return (foo_is_pin_func_gpio(is_gpio)); 129} 130 131static int 132foo_set_flags(device_t dev, device_t gpiodev, uint32_t pin, uint32_t flags) 133{ 134 int rv; 135 136 rv = foo_is_pin_func_gpio(is_gpio); 137 if (rv != 0) 138 return (rv); 139 foo_set_flags(pin, flags); 140 return (0); 141} 142 143static int 144foo_get_flags(device_t dev, device_t gpiodev, uint32_t pin, uint32_t *flags) 145{ 146 int rv; 147 148 rv = foo_is_pin_func_gpio(is_gpio); 149 if (rv != 0) 150 return (rv); 151 foo_get_flags(pin, flags); 152 return (0); 153} 154 155static int 156foo_attach(device_t dev) 157{ 158 ... 159 160 fdt_pinctrl_register(dev, "foo,pins"); 161 /* 162 * It is possible to register more than one pinprop handler 163 */ 164 fdt_pinctrl_register(dev, "bar,pins"); 165 fdt_pinctrl_configure_tree(dev); 166 167 return (0); 168} 169 170static device_method_t foo_methods[] = { 171 ... 172 173 /* fdt_pinctrl interface */ 174 DEVMETHOD(fdt_pinctrl_configure, foo_configure_pins), 175 DEVMETHOD(fdt_pinctrl_is_gpio, foo_is_gpio), 176 DEVMETHOD(fdt_pinctrl_set_flags, foo_set_flags), 177 DEVMETHOD(fdt_pinctrl_get_flags, foo_get_flags), 178 179 /* Terminate method list */ 180 DEVMETHOD_END 181}; 182 183DRIVER_MODULE(foo, simplebus, foo_driver, foo_devclass, NULL, NULL); 184.Ed 185.Sh SEE ALSO 186.Xr fdt_pinctrl 4 187.Sh AUTHORS 188This manual page was written by 189.An Oleksandr Tymoshenko . 190