Page MenuHomeFreeBSD
Files F147363305

D14235.id38987.diff
No OneTemporary
Actions

D14235.id38987.diff
View Options

Index: share/man/man4/Makefile
===================================================================
--- share/man/man4/Makefile
+++ share/man/man4/Makefile
@@ -164,6 +164,7 @@
fd.4 \
fdc.4 \
fdt.4 \
+ fdt_pinctrl.4 \
fdtbus.4 \
ffclock.4 \
filemon.4 \
Index: share/man/man4/fdt_pinctrl.4
===================================================================
--- /dev/null
+++ share/man/man4/fdt_pinctrl.4
@@ -0,0 +1,128 @@
+.\" 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 February 6, 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 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 same SoC chip
+pin can perform one of the following roles: SPI clock, I2C
+data, GPIO ping or PWM signal.
+Function selection is performed by pinmux controller, SoC
+hardware block, usually a set of registers.
+Pinmux controller capabilities and registers format depend
+on actual hardware implementation.
+.Pp
+On
+.Xr fdt 4
+based systems pinmux controller is represented by a node in
+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 device is in (active, idle) it may
+require different pin configurations.
+Each configuration is described by setting pinctrl-N
+property to the list of phandles pointing to specific child
+nodes of 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
+.Xr fdt_pinctrl_configure_tree 9
+call.
+In addition to referring to pin configurations by index they
+can be refered to by name if pinctrl-names property is set.
+Its value 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
+names.
+.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
+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 that don't
+have "status" property 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: share/man/man9/Makefile
===================================================================
--- share/man/man9/Makefile
+++ share/man/man9/Makefile
@@ -126,6 +126,7 @@
eventtimers.9 \
extattr.9 \
fail.9 \
+ fdt_pinctrl.9 \
fetch.9 \
firmware.9 \
fpu_kern.9 \
@@ -941,6 +942,10 @@
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 \
Index: share/man/man9/fdt_pinctrl.9
===================================================================
--- /dev/null
+++ share/man/man9/fdt_pinctrl.9
@@ -0,0 +1,153 @@
+.\" -*- 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 February 4, 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 API for manipulating I/O pins configurations by
+pinmux controllers and pinmux clients.
+On the controller side in addition to standard newbus
+probe, attach methods driver also implements
+.Fn fdt_pinctrl_configure
+method in which it calls
+.Fn fdt_pinctrl_register
+function to register itself as a pinmux controller and then
+.Fn fdt_pinctrl_configure_tree
+to walk the device tree and configure pins specified by pinctrl-0
+property for all active devices.
+If client device requires pin configuration change at some
+point of its lifecycle it uses
+.Fn fdt_pinctrl_configure
+or
+.Fn fdt_pinctrl_configure_by_name
+functions.
+.Pp
+The function
+.Fn fdt_pinctrl_configure
+is used by client device
+.Fa client
+to request pin configuration
+described by its "pinctrl-N" property with index
+.Fa index .
+.Pp
+The function
+.Fn fdt_pinctrl_configure_by_name
+is used by client device
+.Fa client
+to request pin configuration with name
+.Fa name .
+.Pp
+The function
+.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 descendent of the pinctrl
+node which 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.
+.Pp
+The function
+.Fn fdt_pinctrl_configure_tree
+walks the device tree and configures pins for each
+enabled device whose pinctrl-0 property contains
+references to nodes which are children of the
+given pinctrl device.
+.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");
+ 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 .

File Metadata

Mime Type
text/plain
Expires
Wed, Mar 11, 8:30 AM (1 h, 16 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
29533339
Default Alt Text
D14235.id38987.diff (10 KB)

Event Timeline