From 679b7ef604dd6ee109a5a09abd2a01ba31a2d4ee Mon Sep 17 00:00:00 2001 From: ian Date: Fri, 21 Jun 2019 15:12:17 +0000 Subject: [PATCH] Do some general cleanup and light wordsmithing. Sort methods alphabetically. Wrap long lines. Start sentences on a new line. Remove contractions (not because it's a good idea, just to silence igor). Add some explanation of the units for the period and duty arguments and the convention for channel numbers. --- share/man/man9/pwmbus.9 | 72 ++++++++++++++++++++++++++--------------- 1 file changed, 46 insertions(+), 26 deletions(-) diff --git a/share/man/man9/pwmbus.9 b/share/man/man9/pwmbus.9 index 74397afb1042..5b0915c10812 100644 --- a/share/man/man9/pwmbus.9 +++ b/share/man/man9/pwmbus.9 @@ -27,14 +27,14 @@ .Os .Sh NAME .Nm pwmbus , -.Nm PWMBUS_GET_BUS , .Nm PWMBUS_CHANNEL_CONFIG , -.Nm PWMBUS_CHANNEL_GET_CONFIG , -.Nm PWMBUS_CHANNEL_SET_FLAGS , -.Nm PWMBUS_CHANNEL_GET_FLAGS , +.Nm PWMBUS_CHANNEL_COUNT , .Nm PWMBUS_CHANNEL_ENABLE , +.Nm PWMBUS_CHANNEL_GET_CONFIG , +.Nm PWMBUS_CHANNEL_GET_FLAGS , .Nm PWMBUS_CHANNEL_IS_ENABLED , -.Nm PWMBUS_CHANNEL_MAX +.Nm PWMBUS_CHANNEL_SET_FLAGS , +.Nm PWMBUS_GET_BUS .Nd PWMBUS methods .Sh SYNOPSIS .Cd "device pwm" @@ -42,45 +42,65 @@ .Ft int .Fn PWMBUS_CHANNEL_CONFIG "device_t bus" "int channel" "uint64_t period" "uint64_t duty" .Ft int -.Fn PWMBUS_CHANNEL_GET_CONFIG "device_t bus" "int channel" "uint64_t *period" "uint64_t *duty" -.Ft int -.Fn PWMBUS_CHANNEL_SET_FLAGS "device_t bus" "int channel" "uint32_t flags" -.Ft int -.Fn PWMBUS_CHANNEL_GET_FLAGS "device_t bus" "int channel" "uint32_t *flags" +.Fn PWMBUS_CHANNEL_COUNT "device_t bus" "int channel" "int *nchannel" .Ft int .Fn PWMBUS_CHANNEL_ENABLE "device_t bus" "int channel" "bool enable" .Ft int +.Fn PWMBUS_CHANNEL_GET_CONFIG "device_t bus" "int channel" "uint64_t *period" "uint64_t *duty" +.Ft int +.Fn PWMBUS_CHANNEL_GET_FLAGS "device_t bus" "int channel" "uint32_t *flags" +.Ft int .Fn PWMBUS_CHANNEL_IS_ENABLED "device_t bus" "int channel" "bool *enabled" .Ft int -.Fn PWMBUS_CHANNEL_COUNT "device_t bus" "int channel" "int *nchannel" +.Fn PWMBUS_CHANNEL_SET_FLAGS "device_t bus" "int channel" "uint32_t flags" .Sh DESCRIPTION -The PWMBUS (Pulse-Width Modulation) interface allows the device driver to register to a global -bus so other devices in the kernel can use them in a generic way. +The PWMBUS (Pulse-Width Modulation) interface allows a device driver to +register to a global bus so other devices in the kernel can use them in a +generic way. +.Pp +For all +.Nm +methods, the +.Va period +argument is the duration in nanoseconds of one complete on-off cycle, and the +.Va duty +argument is the duration in nanoseconds of the on portion of that cycle. +.Pp +Some PWM hardware is organized as a single controller with multiple channels. +Channel numbers count up from zero. +When multiple channels are present, they sometimes share a common clock or +other resources. +In such cases, 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. .Sh INTERFACE .Bl -tag -width indent .It Fn PWMBUS_CHANNEL_CONFIG "device_t bus" "int channel" "uint64_t period" "uint64_t duty" -Configure the period and duty (in nanoseconds) in the PWM controller on the bus for the specified channel. +Configure the period and duty (in nanoseconds) in the PWM controller on the bus +for the specified channel. Returns 0 on success or .Er EINVAL if the values are not supported by the controller or .Er EBUSY -if the PWMBUS controller is in use and doesn't support changing the value on the fly. +if the PWMBUS controller is in use and does not support changing the value on +the fly. +.It Fn PWMBUS_CHANNEL_COUNT "device_t bus" "int *nchannel" +Get the number of channels supported by the controller. +.It Fn PWMBUS_CHANNEL_ENABLE "device_t bus" "int channel" "bool enable" +Enable the PWM channel. .It Fn PWMBUS_CHANNEL_GET_CONFIG "device_t bus" "int channel" "uint64_t *period" "uint64_t *duty" Get the current configuration of the period and duty for the specified channel. -.It Fn PWMBUS_CHANNEL_SET_FLAGS "device_t bus" "int channel" "uint32_t flags" -Set the flags of the channel (such as inverted polarity), if the driver or controller -doesn't support this a do-nothing default method is used. .It Fn PWMBUS_CHANNEL_GET_FLAGS "device_t bus" "int channel" "uint32_t *flags" Get the current flags for the channel. If the driver or controller -doesn't support this, a default method returns a flags value of zero. -.It Fn PWMBUS_CHANNEL_ENABLE "device_t bus" "int channel" "bool enable" -Enable the PWM channel. -.It Fn PWMBUS_CHANNEL_ISENABLED "device_t bus" "int channel" "bool *enable" -Test if the PWM channel is enabled. -.It PWMBUS_CHANNEL_COUNT "device_t bus" "int channel" "int *nchannel" -Get the number of channels supported by the controller. -Channel numbers count up from zero. +does not support this, a default method returns a flags value of zero. +.It Fn PWMBUS_CHANNEL_IS_ENABLED "device_t bus" "int channel" "bool *enable" +Test whether the PWM channel is enabled. +.It Fn PWMBUS_CHANNEL_SET_FLAGS "device_t bus" "int channel" "uint32_t flags" +Set the flags of the channel (such as inverted polarity). +If the driver or controller does not support this a do-nothing default method +is used. .El .Sh HISTORY The