From 123570fb927a53008531d08e5a86e60f78c5720d Mon Sep 17 00:00:00 2001
From: Ian Lepore <ian@FreeBSD.org>
Date: Tue, 18 Jun 2019 00:17:10 +0000
Subject: [PATCH] Explain the relationship between PWM hardware channels being
 controlled and pwmc(4) device filenames.  Also, use uppercase PWM when the
 term is being used as an acronym, and expand the acronym where it's first
 used.

---
 usr.sbin/pwm/pwm.8 | 35 ++++++++++++++++++++++++++---------
 1 file changed, 26 insertions(+), 9 deletions(-)

diff --git a/usr.sbin/pwm/pwm.8 b/usr.sbin/pwm/pwm.8
index ec204547dc5e..179f3c9b285d 100644
--- a/usr.sbin/pwm/pwm.8
+++ b/usr.sbin/pwm/pwm.8
@@ -27,7 +27,7 @@
 .Os
 .Sh NAME
 .Nm pwm
-.Nd configure pwm controller
+.Nd configure PWM (Pulse Width Modulation) hardware
 .Sh SYNOPSIS
 .Nm
 .Op Fl f Ar device
@@ -47,9 +47,26 @@
 .Sh DESCRIPTION
 The
 .Nm
-utility can be used to configure pwm controllers.
+utility can be used to configure pwm hardware.
+.Nm
+uses a
+.Xr pwmc 4
+device to communicate with the hardware.
+Some PWM hardware supports multiple output channels within a single
+controller block; each
+.Xr pwmc 4
+instance controls a single PWM channel.
 .Pp
-The options are as follow:
+.Xr pwmc 4
+devices are named
+.Pa /dev/pwm/pwmcX.Y ,
+where
+.Va X
+is the controller unit number and
+.Va Y
+is the channel number within that unit.
+.Pp
+The options are as follows:
 .Bl -tag -width "-f device"
 .It Fl f Ar device
 Device to operate on.
@@ -60,15 +77,15 @@ If an unqualified name is provided,
 .Pa /dev/pwm
 is automatically prepended.
 .It Fl E
-Enable the pwm channel.
+Enable the PWM channel.
 .It Fl D
-Disable the pwm channel.
+Disable the PWM channel.
 .It Fl C
-Show the configuration of the pwm channel.
+Show the configuration of the PWM channel.
 .It Fl p Ar period
-Configure the period (in nanoseconds) of the pwm channel
+Configure the period (in nanoseconds) of the PWM channel
 .It Fl d Ar duty
-Configure the duty (in nanoseconds or percentage) of the pwm channel.
+Configure the duty (in nanoseconds or percentage) of the PWM channel.
 Duty is the portion of the
 .Ar period
 during which the signal is asserted.
@@ -76,7 +93,7 @@ during which the signal is asserted.
 .Sh EXAMPLES
 .Bl -bullet
 .It
-Show the configuration of the pwm channel:
+Show the configuration of the PWM channel:
 .Bd -literal
 pwm -f /dev/pwm/pwmc0.1 -C
 .Ed