Skip site navigation (1)Skip section navigation (2)
Date:      Sat, 3 Mar 2018 02:49:49 +0000 (UTC)
From:      Oleksandr Tymoshenko <gonzo@FreeBSD.org>
To:        src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org
Subject:   svn commit: r330309 - in head/share/man: man4 man9
Message-ID:  <201803030249.w232nnXM095284@repo.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: gonzo
Date: Sat Mar  3 02:49:49 2018
New Revision: 330309
URL: https://svnweb.freebsd.org/changeset/base/330309

Log:
  [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
  MFC after:	2 weeks
  Differential Revision:	https://reviews.freebsd.org/D14235

Added:
  head/share/man/man4/fdt_pinctrl.4   (contents, props changed)
  head/share/man/man9/fdt_pinctrl.9   (contents, props changed)
Modified:
  head/share/man/man4/Makefile
  head/share/man/man9/Makefile

Modified: head/share/man/man4/Makefile
==============================================================================
--- head/share/man/man4/Makefile	Sat Mar  3 02:39:54 2018	(r330308)
+++ head/share/man/man4/Makefile	Sat Mar  3 02:49:49 2018	(r330309)
@@ -165,6 +165,7 @@ MAN=	aac.4 \
 	fd.4 \
 	fdc.4 \
 	fdt.4 \
+	fdt_pinctrl.4 \
 	fdtbus.4 \
 	ffclock.4 \
 	filemon.4 \

Added: head/share/man/man4/fdt_pinctrl.4
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ head/share/man/man4/fdt_pinctrl.4	Sat Mar  3 02:49:49 2018	(r330309)
@@ -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: head/share/man/man9/Makefile
==============================================================================
--- head/share/man/man9/Makefile	Sat Mar  3 02:39:54 2018	(r330308)
+++ head/share/man/man9/Makefile	Sat Mar  3 02:49:49 2018	(r330309)
@@ -126,6 +126,7 @@ MAN=	accept_filter.9 \
 	eventtimers.9 \
 	extattr.9 \
 	fail.9 \
+	fdt_pinctrl.9 \
 	fetch.9 \
 	firmware.9 \
 	fpu_kern.9 \
@@ -945,6 +946,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 \

Added: head/share/man/man9/fdt_pinctrl.9
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ head/share/man/man9/fdt_pinctrl.9	Sat Mar  3 02:49:49 2018	(r330309)
@@ -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?201803030249.w232nnXM095284>