d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[fdt_pinctrl] Add man pages for fdt_pinctrl driver

Browse Source 
- 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
This commit is contained in:
Oleksandr Tymoshenko 2018-03-03 02:49:49 +00:00
parent c1d6f6ebe8
commit a1c11a0a7b
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=330309
4 changed files with 294 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
share/man/man4/Makefile
View File

@ -165,6 +165,7 @@ MAN= aac.4 \
fd.4 \
fdc.4 \
fdt.4 \
fdt_pinctrl.4 \
fdtbus.4 \
ffclock.4 \
filemon.4 \

127
share/man/man4/fdt_pinctrl.4 Normal file
View File

@ -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 .

5
share/man/man9/Makefile
View File

@ -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 \

161
share/man/man9/fdt_pinctrl.9 Normal file
View File

@ -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 .