svn commit: r349168 - head/share/man/man4
Ian Lepore
ian at FreeBSD.org
Tue Jun 18 04:32:20 UTC 2019
Author: ian
Date: Tue Jun 18 04:32:19 2019
New Revision: 349168
URL: https://svnweb.freebsd.org/changeset/base/349168
Log:
Add a pwmc(4) manpage.
Added:
head/share/man/man4/pwmc.4 (contents, props changed)
Modified:
head/share/man/man4/Makefile
Modified: head/share/man/man4/Makefile
==============================================================================
--- head/share/man/man4/Makefile Tue Jun 18 02:27:30 2019 (r349167)
+++ head/share/man/man4/Makefile Tue Jun 18 04:32:19 2019 (r349168)
@@ -418,6 +418,7 @@ MAN= aac.4 \
pts.4 \
pty.4 \
puc.4 \
+ pwmc.4 \
${_qlxge.4} \
${_qlxgb.4} \
${_qlxgbe.4} \
Added: head/share/man/man4/pwmc.4
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/share/man/man4/pwmc.4 Tue Jun 18 04:32:19 2019 (r349168)
@@ -0,0 +1,212 @@
+.\"
+.\" Copyright (c) 2019 Ian Lepore <ian at freebsd.org>
+.\"
+.\" 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 AUTHOR ``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 AUTHOR 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 June 17, 2019
+.Dt PWMC 4
+.Os
+.Sh NAME
+.Nm pwmc
+.Nd PWM (Pulse Width Modulation) control device driver
+.Sh SYNOPSIS
+To compile this driver into the kernel,
+place the following lines in your
+kernel configuration file:
+.Bd -ragged -offset indent
+.Cd "device pwmbus"
+.Cd "device pwmc"
+.Ed
+.Pp
+Alternatively, to load the driver as a
+module at boot time, place the following line in
+.Xr loader.conf 5 :
+.Bd -literal -offset indent
+pwmc_load="YES"
+.Ed
+.Sh DESCRIPTION
+The
+.Nm
+driver provides device-control access to a channel of PWM hardware.
+Each instance of a
+.Nm
+device is associated with a single PWM output channel.
+.Pp
+Some PWM hardware is organized with multiple channels sharing a
+common clock or other resources.
+In such cases, a separate
+.Nm
+instance will exist for each channel, but changing the period or
+duty cycle of any one channel may affect other channels within the
+hardware which share the same resources.
+Consult the documentation for the underlying PWM hardware device driver
+for details on channels that share resources.
+.Pp
+An instance of
+.Nm
+creates a character device named
+.Pa /dev/pwm/pwmcX.Y
+where
+.Va X
+is a sequential number assigned to each PWM hardware controller
+as it is discovered by the system, and
+.Va Y
+is the channel number within that hardware controller.
+The driver can be configured to create aliases that point to the
+.Pa pwmcX.Y
+entries, in effect creating named channels.
+.Pp
+The
+.Nm
+driver provides control of a PWM channel with the following
+.Xr ioctl 2
+calls and data structures, defined in
+.In dev/pwm/pwmc.h :
+.Bl -tag -width indent
+.It Dv PWMGETSTATE Pq Vt "struct pwm_state"
+Retrieve the current state of the channel.
+.It Dv PWMSETSTATE Pq Vt "struct pwm_state"
+Set the current state of the channel.
+All parameters are updated on every call.
+To change just one of the values, use
+.Dv PWMGETSTATE
+to get the current state and then submit the same data back with
+just the appropriate value changed.
+.El
+.Pp
+The
+.Va pwm_state
+structure is defined as follows:
+.Bd -literal
+struct pwm_state {
+ u_int period;
+ u_int duty;
+ uint32_t flags;
+ bool enable;
+};
+.Ed
+.Pp
+.Bl -tag -width period
+.It Va period
+The duration, in nanoseconds, of one complete on-off cycle.
+.It Va duty
+The duration, in nanoseconds, of the on portion of one cycle.
+.It Va flags
+Flags that affect the output signal can be bitwise-ORed together.
+The following flags are currently defined:
+.Pp
+.Bl -tag -width PWM_POLARITY_INVERTED -compact
+.It Dv PWM_POLARITY_INVERTED
+Invert the signal polarity.
+.El
+.It Va enable
+.Va
+False to disable the output signal or true to enable it.
+.El
+.Sh HINTS CONFIGURATION
+On a
+.Xr device.hints 5
+based system, such as
+.Li MIPS ,
+these values are configurable for
+.Nm :
+.Bl -tag -width indent
+.It Va hint.pwmc.%d.at
+The pwmbus instance the
+.Nm
+instance is attached to.
+.It Va hint.pwmc.%d.channel
+The hardware channel number the instance is attached to.
+Channel numbers count up from zero.
+.It Va hint.pwmc.%d.label
+If this optional hint is set, the driver creates an alias in
+.Pa /dev/pwm
+with the given name, which points to the instance.
+.El
+.Sh FDT CONFIGURATION
+On an
+.Xr fdt 4
+based system, a
+.Nm
+device is described with a child node of the pwm hardware controller node.
+When the hardware supports multiple channels within the controller, it is
+not necessary to include a
+.Nm
+child node for every channel the hardware supports.
+Define only the channels you need to control.
+.Pp
+The following properties are required for a
+.Nm
+device node:
+.Bl -tag -width indent
+.It Va compatible
+Must be the string "freebsd,pwmc".
+.It Va reg
+The hardware channel number.
+.El
+.Pp
+The following properties are optional for the
+.Nm
+device node:
+.Bl -tag -width indent
+.It Va label
+A string containing only characters legal in a file name.
+The driver creates an alias with the given name in
+.Pa /dev/pwm
+which points to the instance's
+.Pa /dev/pwm/pwmcX.Y
+device entry.
+.El
+.Pp
+Example of a PWM hardware node containing one
+.Nm
+child node:
+.Bd -literal
+&ehrpwm0 {
+ status = "okay";
+ pinctrl-names = "default";
+ pinctrl-0 = <&ehrpwm0_AB_pins>;
+
+ pwmcontrol at 0 {
+ compatible = "freebsd,pwmc";
+ reg = <0>;
+ label = "backlight";
+ };
+};
+.Ed
+.Sh FILES
+.Bl -tag -width -compact
+.It Pa /dev/pwm/pwmc*
+.El
+.Sh SEE ALSO
+.Xr fdt 4 ,
+.Xr device.hints 5 ,
+.Xr pwm 8 ,
+.Xr pwm 9
+.Sh HISTORY
+The
+.Nm
+driver
+appeared in
+.Fx 13.0 .
More information about the svn-src-head
mailing list