Page MenuHomeFreeBSD
Files F131358402

D14235.id.diff
No OneTemporary
Actions

D14235.id.diff
View Options

Index: head/share/man/man4/Makefile
===================================================================
--- head/share/man/man4/Makefile
+++ head/share/man/man4/Makefile
@@ -165,6 +165,7 @@
fd.4 \
fdc.4 \
fdt.4 \
+ fdt_pinctrl.4 \
fdtbus.4 \
ffclock.4 \
filemon.4 \
Index: head/share/man/man4/fdt_pinctrl.4
===================================================================
--- head/share/man/man4/fdt_pinctrl.4
+++ 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 .
Index: head/share/man/man9/Makefile
===================================================================
--- head/share/man/man9/Makefile
+++ head/share/man/man9/Makefile
@@ -126,6 +126,7 @@
eventtimers.9 \
extattr.9 \
fail.9 \
+ fdt_pinctrl.9 \
fetch.9 \
firmware.9 \
fpu_kern.9 \
@@ -945,6 +946,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: head/share/man/man9/fdt_pinctrl.9
===================================================================
--- head/share/man/man9/fdt_pinctrl.9
+++ 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 .

File Metadata

Mime Type
text/plain
Expires
Wed, Oct 8, 5:40 AM (9 h, 6 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
23454871
Default Alt Text
D14235.id.diff (10 KB)

Event Timeline