xref: /freebsd/share/man/man9/fdt_pinctrl.9 (revision a1c11a0a7be38352d83738abedc1cf0ef3c7499a)
1.\" -*- nroff -*-
2.\"
3.\" Copyright (c) 2018 Oleksandr Tymoshenko
4.\"
5.\" All rights reserved.
6.\"
7.\" This program is free software.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
21.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
23.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
27.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28.\"
29.\" $FreeBSD$
30.\"
31.Dd March 2, 2018
32.Dt fdt_pinctrl 9
33.Os
34.Sh NAME
35.Nm fdt_pinctrl
36.Nd helper functions for FDT pinmux controller drivers
37.Sh SYNOPSIS
38.In dev/fdt/fdt_pinctrl.h
39.Ft int
40.Fn fdt_pinctrl_configure "device_t client" "u_int index"
41.Ft int
42.Fn fdt_pinctrl_configure_by_name "device_t client" "const char * name"
43.Ft int
44.Fn fdt_pinctrl_register "device_t pinctrl" "const char *pinprop"
45.Ft int
46.Fn fdt_pinctrl_configure_tree "device_t pinctrl"
47.Sh DESCRIPTION
48.Xr fdt_pinctrl 4
49provides an API for manipulating I/O pin configurations on
50pinmux controllers and pinmux clients.
51On the controller side, the standard newbus probe and
52attach methods are implemented.
53This driver also implements the
54.Fn fdt_pinctrl_configure
55method, in which it calls the
56.Fn fdt_pinctrl_register
57function to register itself as a pinmux controller.
58Then
59.Fn fdt_pinctrl_configure_tree
60is used to walk the device tree and configure pins specified by the pinctrl-0
61property for all active devices.
62If a client device requires a pin configuration change at some
63point of its lifecycle, it uses the
64.Fn fdt_pinctrl_configure
65or
66.Fn fdt_pinctrl_configure_by_name
67functions.
68.Pp
69.Fn fdt_pinctrl_configure
70is used by client device
71.Fa client
72to request a pin configuration
73described by the pinctrl-N property with index
74.Fa index .
75.Pp
76.Fn fdt_pinctrl_configure_by_name
77is used by client device
78.Fa client
79to request the pin configuration with name
80.Fa name .
81.Pp
82.Fn fdt_pinctrl_register
83registers a pinctrl driver so that it can be used by other devices which call
84.Fn fdt_pinctrl_configure
85or
86.Fn fdt_pinctrl_configure_by_name .
87The
88.Fa pinprop
89argument is the name of a property that
90identifies each descendant of the pinctrl
91node.
92The pinctrl node is a pin configuration
93node whose xref phandle can be passed to
94.Fn FDT_PINCTRL_CONFIGURE .
95If
96.Fa pinprop
97is
98.Dv NULL ,
99every descendant node is registered.
100It is possible for the driver to register itself
101as a pinmux controller for more than one pin property type
102by calling
103.Fn fdt_pinctrl_register
104multiple types.
105.Pp
106.Fn fdt_pinctrl_configure_tree
107walks through enabled devices in the device tree.
108If the pinctrl-0 property contains references
109to child nodes of the specified pinctrl device,
110their pins are configured.
111.Sh EXAMPLES
112.Bd -literal
113static int
114foo_configure_pins(device_t dev, phandle_t cfgxref)
115{
116	phandle_t cfgnode;
117	uint32_t *pins, *functions;
118	int npins, nfunctions;
119
120	cfgnode = OF_node_from_xref(cfgxref);
121	pins = NULL;
122	npins = OF_getencprop_alloc(cfgnode, "foo,pins", sizeof(*pins),
123	    (void **)&pins);
124	functions = NULL;
125	nfunctions = OF_getencprop_alloc(cfgnode, "foo,functions",
126	    sizeof(*functions), (void **)&functions);
127	...
128}
129
130static int
131foo_attach(device_t dev)
132{
133	...
134
135	fdt_pinctrl_register(dev, "foo,pins");
136	/*
137	 * It is possible to register more than one pinprop handler
138	 */
139	fdt_pinctrl_register(dev, "bar,pins");
140	fdt_pinctrl_configure_tree(dev);
141
142	return (0);
143}
144
145static device_method_t foo_methods[] = {
146	...
147
148	/* fdt_pinctrl interface */
149	DEVMETHOD(fdt_pinctrl_configure, foo_configure_pins),
150
151	/* Terminate method list */
152	DEVMETHOD_END
153};
154
155DRIVER_MODULE(foo, simplebus, foo_driver, foo_devclass, NULL, NULL);
156.Ed
157.Sh SEE ALSO
158.Xr fdt_pinctrl 4 ,
159.Sh AUTHORS
160This manual page was written by
161.An Oleksandr Tymoshenko .
162