Date: Sat, 31 Mar 2018 00:03:00 +0000 (UTC) From: Oleksandr Tymoshenko <gonzo@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-11@freebsd.org Subject: svn commit: r331833 - in stable/11/share/man: man4 man9 Message-ID: <201803310003.w2V030Q1050998@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: gonzo Date: Sat Mar 31 00:03:00 2018 New Revision: 331833 URL: https://svnweb.freebsd.org/changeset/base/331833 Log: MFC r330309: [fdt_pinctrl] Add man pages for fdt_pinctrl driver - Add fdt_pinctrl(4) with general information for the driver - Add fdt_pinctrl(9) with fdt_pinctrl KPI description Reviewed by: ian, manu, wblock Differential Revision: https://reviews.freebsd.org/D14235 Added: stable/11/share/man/man4/fdt_pinctrl.4 - copied unchanged from r330309, head/share/man/man4/fdt_pinctrl.4 stable/11/share/man/man9/fdt_pinctrl.9 - copied unchanged from r330309, head/share/man/man9/fdt_pinctrl.9 Modified: stable/11/share/man/man4/Makefile stable/11/share/man/man9/Makefile Directory Properties: stable/11/ (props changed) Modified: stable/11/share/man/man4/Makefile ============================================================================== --- stable/11/share/man/man4/Makefile Fri Mar 30 23:31:08 2018 (r331832) +++ stable/11/share/man/man4/Makefile Sat Mar 31 00:03:00 2018 (r331833) @@ -161,6 +161,7 @@ MAN= aac.4 \ fd.4 \ fdc.4 \ fdt.4 \ + fdt_pinctrl.4 \ fdtbus.4 \ ffclock.4 \ filemon.4 \ Copied: stable/11/share/man/man4/fdt_pinctrl.4 (from r330309, head/share/man/man4/fdt_pinctrl.4) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ stable/11/share/man/man4/fdt_pinctrl.4 Sat Mar 31 00:03:00 2018 (r331833, copy of r330309, head/share/man/man4/fdt_pinctrl.4) @@ -0,0 +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 +.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. +For example, based on the actual device design, a single SoC chip +pin can 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. +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 = <ALT0 ALT5> + } + + 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 +calling fdt_pinctrl_register function, and call +.Xr fdt_pinctrl_configure_tree 9 +to configure pins for all enabled devices (device 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 . Modified: stable/11/share/man/man9/Makefile ============================================================================== --- stable/11/share/man/man9/Makefile Fri Mar 30 23:31:08 2018 (r331832) +++ stable/11/share/man/man9/Makefile Sat Mar 31 00:03:00 2018 (r331833) @@ -121,6 +121,7 @@ MAN= accept_filter.9 \ eventtimers.9 \ extattr.9 \ fail.9 \ + fdt_pinctrl.9 \ fetch.9 \ firmware.9 \ fpu_kern.9 \ @@ -768,6 +769,10 @@ MLINKS+=fail.9 KFAIL_POINT_CODE.9 \ fail.9 KFAIL_POINT_GOTO.9 \ fail.9 KFAIL_POINT_RETURN.9 \ fail.9 KFAIL_POINT_RETURN_VOID.9 +MLINKS+=fdt_pinctrl.9 fdt_pinctrl_configure.9 \ + fdt_pinctrl.9 fdt_pinctrl_configure_by_name.9 \ + fdt_pinctrl.9 fdt_pinctrl_configure_tree.9 \ + fdt_pinctrl.9 fdt_pinctrl_register.9 MLINKS+=fetch.9 fubyte.9 \ fetch.9 fuswintr.9 \ fetch.9 fuword.9 \ Copied: stable/11/share/man/man9/fdt_pinctrl.9 (from r330309, head/share/man/man9/fdt_pinctrl.9) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ stable/11/share/man/man9/fdt_pinctrl.9 Sat Mar 31 00:03:00 2018 (r331833, copy of r330309, head/share/man/man9/fdt_pinctrl.9) @@ -0,0 +1,161 @@ +.\" -*- 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 +.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 +.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. +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 . +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 .
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201803310003.w2V030Q1050998>