Index: stable/11/share/man/man4/fdt_pinctrl.4 =================================================================== --- stable/11/share/man/man4/fdt_pinctrl.4 (revision 346511) +++ stable/11/share/man/man4/fdt_pinctrl.4 (revision 346512) @@ -1,127 +1,127 @@ .\" Copyright (c) 2018 Oleksandr Tymoshenko .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd March 2, 2018 +.Dd March 3, 2018 .Dt "FDT_PINCTRL" 4 .Os .Sh NAME .Nm fdt_pinctrl .Nd FDT I/O pin multiplexing support .Sh SYNOPSIS .Cd "device fdt_pinctrl" .Sh DESCRIPTION .Pp Pin multiplexing is a technology used to re-purpose a single physical connection (depending on chip packaging it may be -pin, ball, or pad) to pull signal from one of SoC internal -controllers to peripheral devices. +pin, ball, or pad) by routing its signal to any one of several +different SoC internal devices. For example, based on the actual device design, a single SoC chip -pin can perform any of these roles: SPI clock, I2C +pin might perform any of these roles: SPI clock, I2C data, GPIO pin, or PWM signal. Function selection is performed by the pinmux controller, a SoC -hardware block, usually controlled a set of registers. +hardware block which is usually controlled by a set of registers. Pinmux controller capabilities and register format depend on the actual hardware implementation. .Pp On .Xr fdt 4 based systems, the pinmux controller is represented by a node in the device tree. It may have any number of child nodes representing pin configuration groups. Properties of such nodes are hardware-specific and handled by individual pinctrl drivers. .Ss Example 1 Pinmux controller device tree node .Bd -literal pinctrl@7e220000 { compatible = "vndr,soc1715-pinctrl"; reg = <0x7e220000 0x100> spi0_pins: spi0 { vndr,pins = <11 12> vndr,functions = } i2c0_pins: i2c0 { ... } } .Ed .Pp Client devices are hardware devices that require certain pin configurations to function properly. Depending on the state the device is in (active, idle) it might require different pin configurations. Each configuration is described by setting the pinctrl-N property to the list of phandles pointing to specific child nodes of the pinmux controller node. N is an integer value starting with 0 and incremented by 1 for every new set of pin configurations. pinctrl-0 is a default configuration that is applied in the .Xr fdt_pinctrl_configure_tree 9 call. In addition to referring to pin configurations by index, they can be referred to by name if the pinctrl-names property is set. The value of pinctrl-names is a list of strings with names for each pinctrl-N property. Client devices can request specific configuration using .Xr fdt_pinctrl_configure 9 and .Xr fdt_pinctrl_configure_by_name 9 . .Ss Example 2 .Bd -literal backlight@7f000000 { compatible = "vndr,vndr-bl" reg = <0x7f000000 0x20> ... pinctrl-name = "active", "idle" pinctrl-0 = <&backlight_active_pins> pinctrl-1 = <&backlight_idle_pins> } .Ed .Pp -The pinctrl driver should implement FDT_PINCTRL_CONFIGURE -method, register itself as pin configuration handler by +The pinctrl driver should implement the FDT_PINCTRL_CONFIGURE +method, register itself as a pin configuration handler by calling fdt_pinctrl_register function, and call .Xr fdt_pinctrl_configure_tree 9 -to configure pins for all enabled devices (device where +to configure pins for all enabled devices (devices where the "status" property is not set to "disabled"). .Sh SEE ALSO .Xr fdt_pinctrl 9 .Sh HISTORY The .Nm driver first appeared in .Fx 10.2 . .Sh AUTHORS .An -nosplit The .Nm device driver was developed by .An \&Ian Lepore Aq Mt ian@FreeBSD.org . This manual page was written by .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . Index: stable/11/share/man/man9/fdt_pinctrl.9 =================================================================== --- stable/11/share/man/man9/fdt_pinctrl.9 (revision 346511) +++ stable/11/share/man/man9/fdt_pinctrl.9 (revision 346512) @@ -1,161 +1,158 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2018 Oleksandr Tymoshenko .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd March 2, 2018 +.Dd March 3, 2018 .Dt fdt_pinctrl 9 .Os .Sh NAME .Nm fdt_pinctrl .Nd helper functions for FDT pinmux controller drivers .Sh SYNOPSIS .In dev/fdt/fdt_pinctrl.h .Ft int .Fn fdt_pinctrl_configure "device_t client" "u_int index" .Ft int .Fn fdt_pinctrl_configure_by_name "device_t client" "const char * name" .Ft int .Fn fdt_pinctrl_register "device_t pinctrl" "const char *pinprop" .Ft int .Fn fdt_pinctrl_configure_tree "device_t pinctrl" .Sh DESCRIPTION .Xr fdt_pinctrl 4 provides an API for manipulating I/O pin configurations on pinmux controllers and pinmux clients. On the controller side, the standard newbus probe and attach methods are implemented. -This driver also implements the -.Fn fdt_pinctrl_configure -method, in which it calls the +As part of handling attach, it calls the .Fn fdt_pinctrl_register function to register itself as a pinmux controller. Then .Fn fdt_pinctrl_configure_tree is used to walk the device tree and configure pins specified by the pinctrl-0 property for all active devices. +The driver also implements the +.Fn fdt_pinctrl_configure +method, which allows client devices to change their +pin configurations after startup. If a client device requires a pin configuration change at some point of its lifecycle, it uses the .Fn fdt_pinctrl_configure or .Fn fdt_pinctrl_configure_by_name functions. .Pp .Fn fdt_pinctrl_configure is used by client device .Fa client to request a pin configuration described by the pinctrl-N property with index .Fa index . .Pp .Fn fdt_pinctrl_configure_by_name is used by client device .Fa client to request the pin configuration with name .Fa name . .Pp .Fn fdt_pinctrl_register registers a pinctrl driver so that it can be used by other devices which call .Fn fdt_pinctrl_configure or .Fn fdt_pinctrl_configure_by_name . -The -.Fa pinprop -argument is the name of a property that -identifies each descendant of the pinctrl -node. -The pinctrl node is a pin configuration -node whose xref phandle can be passed to -.Fn FDT_PINCTRL_CONFIGURE . +It also registers each child node of the pinctrl driver's node which contains +a property with the name given in +.Fa pinprop . If .Fa pinprop is .Dv NULL , every descendant node is registered. It is possible for the driver to register itself as a pinmux controller for more than one pin property type by calling .Fn fdt_pinctrl_register multiple types. .Pp .Fn fdt_pinctrl_configure_tree walks through enabled devices in the device tree. If the pinctrl-0 property contains references to child nodes of the specified pinctrl device, their pins are configured. .Sh EXAMPLES .Bd -literal static int foo_configure_pins(device_t dev, phandle_t cfgxref) { phandle_t cfgnode; uint32_t *pins, *functions; int npins, nfunctions; cfgnode = OF_node_from_xref(cfgxref); pins = NULL; npins = OF_getencprop_alloc(cfgnode, "foo,pins", sizeof(*pins), (void **)&pins); functions = NULL; nfunctions = OF_getencprop_alloc(cfgnode, "foo,functions", sizeof(*functions), (void **)&functions); ... } static int foo_attach(device_t dev) { ... fdt_pinctrl_register(dev, "foo,pins"); /* * It is possible to register more than one pinprop handler */ fdt_pinctrl_register(dev, "bar,pins"); fdt_pinctrl_configure_tree(dev); return (0); } static device_method_t foo_methods[] = { ... /* fdt_pinctrl interface */ DEVMETHOD(fdt_pinctrl_configure, foo_configure_pins), /* Terminate method list */ DEVMETHOD_END }; DRIVER_MODULE(foo, simplebus, foo_driver, foo_devclass, NULL, NULL); .Ed .Sh SEE ALSO .Xr fdt_pinctrl 4 , .Sh AUTHORS This manual page was written by .An Oleksandr Tymoshenko . Index: stable/11 =================================================================== --- stable/11 (revision 346511) +++ stable/11 (revision 346512) Property changes on: stable/11 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head:r330358,330360