share/man/man4/pwmc.4

   1 .\"
   2 .\" Copyright (c) 2019 Ian Lepore <ian@freebsd.org>
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\"
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  15 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  16 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  17 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  18 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  19 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  20 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  21 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  23 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd June 17, 2019
  28 .Dt PWMC 4
  29 .Os
  30 .Sh NAME
  31 .Nm pwmc
  32 .Nd PWM (Pulse Width Modulation) control device driver
  33 .Sh SYNOPSIS
  34 To compile this driver into the kernel,
  35 place the following lines in your
  36 kernel configuration file:
  37 .Bd -ragged -offset indent
  38 .Cd "device pwmbus"
  39 .Cd "device pwmc"
  40 .Ed
  41 .Pp
  42 Alternatively, to load the driver as a
  43 module at boot time, place the following line in
  44 .Xr loader.conf 5 :
  45 .Bd -literal -offset indent
  46 pwmc_load="YES"
  47 .Ed
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 driver provides device-control access to a channel of PWM hardware.
  52 Each instance of a
  53 .Nm
  54 device is associated with a single PWM output channel.
  55 .Pp
  56 Some PWM hardware is organized with multiple channels sharing a
  57 common clock or other resources.
  58 In such cases, a separate
  59 .Nm
  60 instance will exist for each channel, but changing the period or
  61 duty cycle of any one channel may affect other channels within the
  62 hardware which share the same resources.
  63 Consult the documentation for the underlying PWM hardware device driver
  64 for details on channels that share resources.
  65 .Pp
  66 An instance of
  67 .Nm
  68 creates a character device named
  69 .Pa /dev/pwm/pwmcX.Y
  70 where
  71 .Va X
  72 is a sequential number assigned to each PWM hardware controller
  73 as it is discovered by the system, and
  74 .Va Y
  75 is the channel number within that hardware controller.
  76 The driver can be configured to create aliases that point to the
  77 .Pa pwmcX.Y
  78 entries, in effect creating named channels.
  79 .Pp
  80 The
  81 .Nm
  82 driver provides control of a PWM channel with the following
  83 .Xr ioctl 2
  84 calls and data structures, defined in
  85 .In dev/pwm/pwmc.h :
  86 .Bl -tag -width indent
  87 .It Dv PWMGETSTATE Pq Vt "struct pwm_state"
  88 Retrieve the current state of the channel.
  89 .It Dv PWMSETSTATE Pq Vt "struct pwm_state"
  90 Set the current state of the channel.
  91 All parameters are updated on every call.
  92 To change just one of the values, use
  93 .Dv PWMGETSTATE
  94 to get the current state and then submit the same data back with
  95 just the appropriate value changed.
  96 .El
  97 .Pp
  98 The
  99 .Va pwm_state
 100 structure is defined as follows:
 101 .Bd -literal
 102 struct pwm_state {
 103         u_int           period;
 104         u_int           duty;
 105         uint32_t        flags;
 106         bool            enable;
 107 };
 108 .Ed
 109 .Pp
 110 .Bl -tag -width period
 111 .It Va period
 112 The duration, in nanoseconds, of one complete on-off cycle.
 113 .It Va duty
 114 The duration, in nanoseconds, of the on portion of one cycle.
 115 .It Va flags
 116 Flags that affect the output signal can be bitwise-ORed together.
 117 The following flags are currently defined:
 118 .Pp
 119 .Bl -tag -width PWM_POLARITY_INVERTED -compact
 120 .It Dv PWM_POLARITY_INVERTED
 121 Invert the signal polarity.
 122 .El
 123 .It Va enable
 124 .Va
 125 False to disable the output signal or true to enable it.
 126 .El
 127 .Sh HINTS CONFIGURATION
 128 On a
 129 .Xr device.hints 5
 130 based system, such as
 131 .Li MIPS ,
 132 these values are configurable for
 133 .Nm :
 134 .Bl -tag -width indent
 135 .It Va hint.pwmc.%d.at
 136 The pwmbus instance the
 137 .Nm
 138 instance is attached to.
 139 .It Va hint.pwmc.%d.channel
 140 The hardware channel number the instance is attached to.
 141 Channel numbers count up from zero.
 142 .It Va hint.pwmc.%d.label
 143 If this optional hint is set, the driver creates an alias in
 144 .Pa /dev/pwm
 145 with the given name, which points to the instance.
 146 .El
 147 .Sh FDT CONFIGURATION
 148 On an
 149 .Xr fdt 4
 150 based system, a
 151 .Nm
 152 device is described with a child node of the pwm hardware controller node.
 153 When the hardware supports multiple channels within the controller, it is
 154 not necessary to include a
 155 .Nm
 156 child node for every channel the hardware supports.
 157 Define only the channels you need to control.
 158 .Pp
 159 The following properties are required for a
 160 .Nm
 161 device node:
 162 .Bl -tag -width indent
 163 .It Va compatible
 164 Must be the string "freebsd,pwmc".
 165 .It Va reg
 166 The hardware channel number.
 167 .El
 168 .Pp
 169 The following properties are optional for the
 170 .Nm
 171 device node:
 172 .Bl -tag -width indent
 173 .It Va label
 174 A string containing only characters legal in a file name.
 175 The driver creates an alias with the given name in
 176 .Pa /dev/pwm
 177 which points to the instance's
 178 .Pa /dev/pwm/pwmcX.Y
 179 device entry.
 180 .El
 181 .Pp
 182 Example of a PWM hardware node containing one
 183 .Nm
 184 child node:
 185 .Bd -literal
 186 &ehrpwm0 {
 187     status = "okay";
 188     pinctrl-names = "default";
 189     pinctrl-0 = <&ehrpwm0_AB_pins>;
 190
 191     pwmcontrol@0 {
 192         compatible = "freebsd,pwmc";
 193         reg = <0>;
 194         label = "backlight";
 195     };
 196 };
 197 .Ed
 198 .Sh FILES
 199 .Bl -tag -width -compact
 200 .It Pa /dev/pwm/pwmc*
 201 .El
 202 .Sh SEE ALSO
 203 .Xr fdt 4 ,
 204 .Xr device.hints 5 ,
 205 .Xr pwm 8 ,
 206 .Xr pwm 9
 207 .Sh HISTORY
 208 The
 209 .Nm
 210 driver
 211 appeared in
 212 .Fx 13.0 .