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 June 23, 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. 53As part of handling attach, it calls the 54.Fn fdt_pinctrl_register 55function to register itself as a pinmux controller. 56Then 57.Fn fdt_pinctrl_configure_tree 58is used to walk the device tree and configure pins specified by the pinctrl-0 59property for all active devices. 60The driver also implements the 61.Fn fdt_pinctrl_configure 62method, which allows client devices to change their 63pin configurations after startup. 64If a client device requires a pin configuration change at some 65point of its lifecycle, it uses the 66.Fn fdt_pinctrl_configure 67or 68.Fn fdt_pinctrl_configure_by_name 69functions. 70.Pp 71.Fn fdt_pinctrl_configure 72is used by client device 73.Fa client 74to request a pin configuration 75described by the pinctrl-N property with index 76.Fa index . 77.Pp 78.Fn fdt_pinctrl_configure_by_name 79is used by client device 80.Fa client 81to request the pin configuration with name 82.Fa name . 83.Pp 84.Fn fdt_pinctrl_register 85registers a pinctrl driver so that it can be used by other devices which call 86.Fn fdt_pinctrl_configure 87or 88.Fn fdt_pinctrl_configure_by_name . 89It also registers each child node of the pinctrl driver's node which contains 90a property with the name given in 91.Fa pinprop . 92If 93.Fa pinprop 94is 95.Dv NULL , 96every descendant node is registered. 97It is possible for the driver to register itself 98as a pinmux controller for more than one pin property type 99by calling 100.Fn fdt_pinctrl_register 101multiple types. 102.Pp 103.Fn fdt_pinctrl_configure_tree 104walks through enabled devices in the device tree. 105If the pinctrl-0 property contains references 106to child nodes of the specified pinctrl device, 107their pins are configured. 108.Sh EXAMPLES 109.Bd -literal 110static int 111foo_configure_pins(device_t dev, phandle_t cfgxref) 112{ 113 phandle_t cfgnode; 114 uint32_t *pins, *functions; 115 int npins, nfunctions; 116 117 cfgnode = OF_node_from_xref(cfgxref); 118 pins = NULL; 119 npins = OF_getencprop_alloc_multi(cfgnode, "foo,pins", sizeof(*pins), 120 (void **)&pins); 121 functions = NULL; 122 nfunctions = OF_getencprop_alloc_multi(cfgnode, "foo,functions", 123 sizeof(*functions), (void **)&functions); 124 ... 125} 126 127static int 128foo_is_gpio(device_t dev, device_t gpiodev, bool *is_gpio) 129{ 130 return (foo_is_pin_func_gpio(is_gpio)); 131} 132 133static int 134foo_set_flags(device_t dev, device_t gpiodev, uint32_t pin, uint32_t flags) 135{ 136 int rv; 137 138 rv = foo_is_pin_func_gpio(is_gpio); 139 if (rv != 0) 140 return (rv); 141 foo_set_flags(pin, flags); 142 return (0); 143} 144 145static int 146foo_get_flags(device_t dev, device_t gpiodev, uint32_t pin, uint32_t *flags) 147{ 148 int rv; 149 150 rv = foo_is_pin_func_gpio(is_gpio); 151 if (rv != 0) 152 return (rv); 153 foo_get_flags(pin, flags); 154 return (0); 155} 156 157static int 158foo_attach(device_t dev) 159{ 160 ... 161 162 fdt_pinctrl_register(dev, "foo,pins"); 163 /* 164 * It is possible to register more than one pinprop handler 165 */ 166 fdt_pinctrl_register(dev, "bar,pins"); 167 fdt_pinctrl_configure_tree(dev); 168 169 return (0); 170} 171 172static device_method_t foo_methods[] = { 173 ... 174 175 /* fdt_pinctrl interface */ 176 DEVMETHOD(fdt_pinctrl_configure, foo_configure_pins), 177 DEVMETHOD(fdt_pinctrl_is_gpio, foo_is_gpio), 178 DEVMETHOD(fdt_pinctrl_set_flags, foo_set_flags), 179 DEVMETHOD(fdt_pinctrl_get_flags, foo_get_flags), 180 181 /* Terminate method list */ 182 DEVMETHOD_END 183}; 184 185DRIVER_MODULE(foo, simplebus, foo_driver, foo_devclass, NULL, NULL); 186.Ed 187.Sh SEE ALSO 188.Xr fdt_pinctrl 4 189.Sh AUTHORS 190This manual page was written by 191.An Oleksandr Tymoshenko . 192