share/man/man9/fdt_pinctrl.9

   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 3, 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
  49 provides an API for manipulating I/O pin configurations on
  50 pinmux controllers and pinmux clients.
  51 On the controller side, the standard newbus probe and
  52 attach methods are implemented.
  53 As part of handling attach, it calls the
  54 .Fn fdt_pinctrl_register
  55 function to register itself as a pinmux controller.
  56 Then
  57 .Fn fdt_pinctrl_configure_tree
  58 is used to walk the device tree and configure pins specified by the pinctrl-0
  59 property for all active devices.
  60 The driver also implements the
  61 .Fn fdt_pinctrl_configure
  62 method, which allows client devices to change their
  63 pin configurations after startup.
  64 If a client device requires a pin configuration change at some
  65 point of its lifecycle, it uses the
  66 .Fn fdt_pinctrl_configure
  67 or
  68 .Fn fdt_pinctrl_configure_by_name
  69 functions.
  70 .Pp
  71 .Fn fdt_pinctrl_configure
  72 is used by client device
  73 .Fa client
  74 to request a pin configuration
  75 described by the pinctrl-N property with index
  76 .Fa index .
  77 .Pp
  78 .Fn fdt_pinctrl_configure_by_name
  79 is used by client device
  80 .Fa client
  81 to request the pin configuration with name
  82 .Fa name .
  83 .Pp
  84 .Fn fdt_pinctrl_register
  85 registers a pinctrl driver so that it can be used by other devices which call
  86 .Fn fdt_pinctrl_configure
  87 or
  88 .Fn fdt_pinctrl_configure_by_name .
  89 It also registers each child node of the pinctrl driver's node which contains
  90 a property with the name given in
  91 .Fa pinprop .
  92 If
  93 .Fa pinprop
  94 is
  95 .Dv NULL ,
  96 every descendant node is registered.
  97 It is possible for the driver to register itself
  98 as a pinmux controller for more than one pin property type
  99 by calling
 100 .Fn fdt_pinctrl_register
 101 multiple types.
 102 .Pp
 103 .Fn fdt_pinctrl_configure_tree
 104 walks through enabled devices in the device tree.
 105 If the pinctrl-0 property contains references
 106 to child nodes of the specified pinctrl device,
 107 their pins are configured.
 108 .Sh EXAMPLES
 109 .Bd -literal
 110 static int
 111 foo_configure_pins(device_t dev, phandle_t cfgxref)
 112 {
 113         phandle_t cfgnode;
 114         uint32_t *pins, *functions;
 115         int npins, nfunctions;
 116
 117         cfgnode = OF_node_from_xref(cfgxref);
 118         pins = NULL;
 119         npins = OF_getencprop_alloc(cfgnode, "foo,pins", sizeof(*pins),
 120             (void **)&pins);
 121         functions = NULL;
 122         nfunctions = OF_getencprop_alloc(cfgnode, "foo,functions",
 123             sizeof(*functions), (void **)&functions);
 124         ...
 125 }
 126
 127 static int
 128 foo_attach(device_t dev)
 129 {
 130         ...
 131
 132         fdt_pinctrl_register(dev, "foo,pins");
 133         /*
 134          * It is possible to register more than one pinprop handler
 135          */
 136         fdt_pinctrl_register(dev, "bar,pins");
 137         fdt_pinctrl_configure_tree(dev);
 138
 139         return (0);
 140 }
 141
 142 static device_method_t foo_methods[] = {
 143         ...
 144
 145         /* fdt_pinctrl interface */
 146         DEVMETHOD(fdt_pinctrl_configure, foo_configure_pins),
 147
 148         /* Terminate method list */
 149         DEVMETHOD_END
 150 };
 151
 152 DRIVER_MODULE(foo, simplebus, foo_driver, foo_devclass, NULL, NULL);
 153 .Ed
 154 .Sh SEE ALSO
 155 .Xr fdt_pinctrl 4 ,
 156 .Sh AUTHORS
 157 This manual page was written by
 158 .An Oleksandr Tymoshenko .