[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
This commit is contained in:
parent
c1d6f6ebe8
commit
a1c11a0a7b
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=330309
@ -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
127
share/man/man4/fdt_pinctrl.4
Normal 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 .
|
@ -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
161
share/man/man9/fdt_pinctrl.9
Normal 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 .
|
Loading…
Reference in New Issue
Block a user