Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 04883802 authored by Thierry Reding's avatar Thierry Reding
Browse files

pwm: Clean up kerneldoc 



Clean up kerneldoc in preparation for including the PWM documentation in
DocBook.

Signed-off-by: default avatarThierry Reding <thierry.reding@gmail.com>
parent 6bc7064a

drivers/pwm/core.c

+38 −6
Original line number Diff line number Diff line
@@ -200,6 +200,8 @@ static void of_pwmchip_remove(struct pwm_chip *chip) 
 * pwm_set_chip_data() - set private chip data for a PWM

 * @pwm: PWM device

 * @data: pointer to chip-specific data

 *

 * Returns: 0 on success or a negative error code on failure.

 */

int pwm_set_chip_data(struct pwm_device *pwm, void *data)

{
@@ -215,6 +217,8 @@ EXPORT_SYMBOL_GPL(pwm_set_chip_data); 
/**

 * pwm_get_chip_data() - get private chip data for a PWM

 * @pwm: PWM device

 *

 * Returns: A pointer to the chip-private data for the PWM device.

 */

void *pwm_get_chip_data(struct pwm_device *pwm)

{
@@ -230,6 +234,8 @@ EXPORT_SYMBOL_GPL(pwm_get_chip_data); 
 * Register a new PWM chip. If chip->base < 0 then a dynamically assigned base

 * will be used. The initial polarity for all channels is specified by the

 * @polarity parameter.

 *

 * Returns: 0 on success or a negative error code on failure.

 */

int pwmchip_add_with_polarity(struct pwm_chip *chip,

			      enum pwm_polarity polarity)
@@ -291,6 +297,8 @@ EXPORT_SYMBOL_GPL(pwmchip_add_with_polarity); 
 *

 * Register a new PWM chip. If chip->base < 0 then a dynamically assigned base

 * will be used. The initial polarity for all channels is normal.

 *

 * Returns: 0 on success or a negative error code on failure.

 */

int pwmchip_add(struct pwm_chip *chip)

{
@@ -304,6 +312,8 @@ EXPORT_SYMBOL_GPL(pwmchip_add); 
 *

 * Removes a PWM chip. This function may return busy if the PWM chip provides

 * a PWM device that is still requested.

 *

 * Returns: 0 on success or a negative error code on failure.

 */

int pwmchip_remove(struct pwm_chip *chip)

{
@@ -338,10 +348,13 @@ EXPORT_SYMBOL_GPL(pwmchip_remove); 


/**

 * pwm_request() - request a PWM device

 * @pwm_id: global PWM device index

 * @pwm: global PWM device index

 * @label: PWM device label

 *

 * This function is deprecated, use pwm_get() instead.

 *

 * Returns: A pointer to a PWM device or an ERR_PTR()-encoded error code on

 * failure.

 */

struct pwm_device *pwm_request(int pwm, const char *label)

{
@@ -376,9 +389,9 @@ EXPORT_SYMBOL_GPL(pwm_request); 
 * @index: per-chip index of the PWM to request

 * @label: a literal description string of this PWM

 *

 * Returns the PWM at the given index of the given PWM chip. A negative error

 * code is returned if the index is not valid for the specified PWM chip or

 * if the PWM device cannot be requested.

 * Returns: A pointer to the PWM device at the given index of the given PWM

 * chip. A negative error code is returned if the index is not valid for the

 * specified PWM chip or if the PWM device cannot be requested.

 */

struct pwm_device *pwm_request_from_chip(struct pwm_chip *chip,

					 unsigned int index,
@@ -419,6 +432,8 @@ EXPORT_SYMBOL_GPL(pwm_free); 
 * @pwm: PWM device

 * @duty_ns: "on" time (in nanoseconds)

 * @period_ns: duration (in nanoseconds) of one cycle

 *

 * Returns: 0 on success or a negative error code on failure.

 */

int pwm_config(struct pwm_device *pwm, int duty_ns, int period_ns)

{
@@ -443,7 +458,10 @@ EXPORT_SYMBOL_GPL(pwm_config); 
 * @pwm: PWM device

 * @polarity: new polarity of the PWM signal

 *

 * Note that the polarity cannot be configured while the PWM device is enabled

 * Note that the polarity cannot be configured while the PWM device is

 * enabled.

 *

 * Returns: 0 on success or a negative error code on failure.

 */

int pwm_set_polarity(struct pwm_device *pwm, enum pwm_polarity polarity)

{
@@ -471,6 +489,8 @@ EXPORT_SYMBOL_GPL(pwm_set_polarity); 
/**

 * pwm_enable() - start a PWM output toggling

 * @pwm: PWM device

 *

 * Returns: 0 on success or a negative error code on failure.

 */

int pwm_enable(struct pwm_device *pwm)

{
@@ -524,6 +544,9 @@ static struct pwm_chip *of_node_to_pwmchip(struct device_node *np) 
 * lookup of the PWM index. This also means that the "pwm-names" property

 * becomes mandatory for devices that look up the PWM device via the con_id

 * parameter.

 *

 * Returns: A pointer to the requested PWM device or an ERR_PTR()-encoded

 * error code on failure.

 */

struct pwm_device *of_pwm_get(struct device_node *np, const char *con_id)

{
@@ -630,6 +653,9 @@ void pwm_remove_table(struct pwm_lookup *table, size_t num) 
 *

 * Once a PWM chip has been found the specified PWM device will be requested

 * and is ready to be used.

 *

 * Returns: A pointer to the requested PWM device or an ERR_PTR()-encoded

 * error code on failure.

 */

struct pwm_device *pwm_get(struct device *dev, const char *con_id)

{
@@ -752,6 +778,9 @@ static void devm_pwm_release(struct device *dev, void *res) 
 *

 * This function performs like pwm_get() but the acquired PWM device will

 * automatically be released on driver detach.

 *

 * Returns: A pointer to the requested PWM device or an ERR_PTR()-encoded

 * error code on failure.

 */

struct pwm_device *devm_pwm_get(struct device *dev, const char *con_id)

{
@@ -781,6 +810,9 @@ EXPORT_SYMBOL_GPL(devm_pwm_get); 
 *

 * This function performs like of_pwm_get() but the acquired PWM device will

 * automatically be released on driver detach.

 *

 * Returns: A pointer to the requested PWM device or an ERR_PTR()-encoded

 * error code on failure.

 */

struct pwm_device *devm_of_pwm_get(struct device *dev, struct device_node *np,

				   const char *con_id)
@@ -832,7 +864,7 @@ EXPORT_SYMBOL_GPL(devm_pwm_put); 
  * pwm_can_sleep() - report whether PWM access will sleep

  * @pwm: PWM device

  *

  * It returns true if accessing the PWM can sleep, false otherwise.

  * Returns: True if accessing the PWM can sleep, false otherwise.

  */

bool pwm_can_sleep(struct pwm_device *pwm)

{

include/linux/pwm.h

+14 −0
Original line number Diff line number Diff line
@@ -79,6 +79,18 @@ enum { 
	PWMF_EXPORTED = 1 << 2,

};



/**

 * struct pwm_device - PWM channel object

 * @label: name of the PWM device

 * @flags: flags associated with the PWM device

 * @hwpwm: per-chip relative index of the PWM device

 * @pwm: global index of the PWM device

 * @chip: PWM chip providing this PWM device

 * @chip_data: chip-private data associated with the PWM device

 * @period: period of the PWM signal (in nanoseconds)

 * @duty_cycle: duty cycle of the PWM signal (in nanoseconds)

 * @polarity: polarity of the PWM signal

 */

struct pwm_device {

	const char *label;

	unsigned long flags;
@@ -163,6 +175,8 @@ struct pwm_ops { 
 * @base: number of first PWM controlled by this chip

 * @npwm: number of PWMs controlled by this chip

 * @pwms: array of PWM devices allocated by the framework

 * @of_xlate: request a PWM device given a device tree PWM specifier

 * @of_pwm_n_cells: number of cells expected in the device tree PWM specifier

 * @can_sleep: must be true if the .config(), .enable() or .disable()

 *             operations may sleep

 */