Date: Tue, 18 Jun 2019 04:32:19 +0000 (UTC) From: Ian Lepore <ian@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r349168 - head/share/man/man4 Message-ID: <201906180432.x5I4WJa9069890@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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@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 .
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201906180432.x5I4WJa9069890>