[mirror_ubuntu-jammy-kernel.git] / include / linux / pwm.h

/* SPDX-License-Identifier: GPL-2.0 */
#ifndef __LINUX_PWM_H
#define __LINUX_PWM_H

#include <linux/err.h>
#include <linux/mutex.h>
#include <linux/of.h>

struct pwm_capture;
struct seq_file;

struct pwm_chip;

/**
 * enum pwm_polarity - polarity of a PWM signal
 * @PWM_POLARITY_NORMAL: a high signal for the duration of the duty-
 * cycle, followed by a low signal for the remainder of the pulse
 * period
 * @PWM_POLARITY_INVERSED: a low signal for the duration of the duty-
 * cycle, followed by a high signal for the remainder of the pulse
 * period
 */
enum pwm_polarity {
	PWM_POLARITY_NORMAL,
	PWM_POLARITY_INVERSED,
};

/**
 * struct pwm_args - board-dependent PWM arguments
 * @period: reference period
 * @polarity: reference polarity
 *
 * This structure describes board-dependent arguments attached to a PWM
 * device. These arguments are usually retrieved from the PWM lookup table or
 * device tree.
 *
 * Do not confuse this with the PWM state: PWM arguments represent the initial
 * configuration that users want to use on this PWM device rather than the
 * current PWM hardware state.
 */
struct pwm_args {
	u64 period;
	enum pwm_polarity polarity;
};

enum {
	PWMF_REQUESTED = 1 << 0,
	PWMF_EXPORTED = 1 << 1,
};

/*
 * struct pwm_state - state of a PWM channel
 * @period: PWM period (in nanoseconds)
 * @duty_cycle: PWM duty cycle (in nanoseconds)
 * @polarity: PWM polarity
 * @enabled: PWM enabled status
 */
struct pwm_state {
	u64 period;
	u64 duty_cycle;
	enum pwm_polarity polarity;
	bool enabled;
};

/**
 * 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
 * @args: PWM arguments
 * @state: last applied state
 * @last: last implemented state (for PWM_DEBUG)
 */
struct pwm_device {
	const char *label;
	unsigned long flags;
	unsigned int hwpwm;
	unsigned int pwm;
	struct pwm_chip *chip;
	void *chip_data;

	struct pwm_args args;
	struct pwm_state state;
	struct pwm_state last;
};

/**
 * pwm_get_state() - retrieve the current PWM state
 * @pwm: PWM device
 * @state: state to fill with the current PWM state
 *
 * The returned PWM state represents the state that was applied by a previous call to
 * pwm_apply_state(). Drivers may have to slightly tweak that state before programming it to
 * hardware. If pwm_apply_state() was never called, this returns either the current hardware
 * state (if supported) or the default settings.
 */
static inline void pwm_get_state(const struct pwm_device *pwm,
				 struct pwm_state *state)
{
	*state = pwm->state;
}

static inline bool pwm_is_enabled(const struct pwm_device *pwm)
{
	struct pwm_state state;

	pwm_get_state(pwm, &state);

	return state.enabled;
}

static inline void pwm_set_period(struct pwm_device *pwm, u64 period)
{
	if (pwm)
		pwm->state.period = period;
}

static inline u64 pwm_get_period(const struct pwm_device *pwm)
{
	struct pwm_state state;

	pwm_get_state(pwm, &state);

	return state.period;
}

static inline void pwm_set_duty_cycle(struct pwm_device *pwm, unsigned int duty)
{
	if (pwm)
		pwm->state.duty_cycle = duty;
}

static inline u64 pwm_get_duty_cycle(const struct pwm_device *pwm)
{
	struct pwm_state state;

	pwm_get_state(pwm, &state);

	return state.duty_cycle;
}

static inline enum pwm_polarity pwm_get_polarity(const struct pwm_device *pwm)
{
	struct pwm_state state;

	pwm_get_state(pwm, &state);

	return state.polarity;
}

static inline void pwm_get_args(const struct pwm_device *pwm,
				struct pwm_args *args)
{
	*args = pwm->args;
}

/**
 * pwm_init_state() - prepare a new state to be applied with pwm_apply_state()
 * @pwm: PWM device
 * @state: state to fill with the prepared PWM state
 *
 * This functions prepares a state that can later be tweaked and applied
 * to the PWM device with pwm_apply_state(). This is a convenient function
 * that first retrieves the current PWM state and the replaces the period
 * and polarity fields with the reference values defined in pwm->args.
 * Once the function returns, you can adjust the ->enabled and ->duty_cycle
 * fields according to your needs before calling pwm_apply_state().
 *
 * ->duty_cycle is initially set to zero to avoid cases where the current
 * ->duty_cycle value exceed the pwm_args->period one, which would trigger
 * an error if the user calls pwm_apply_state() without adjusting ->duty_cycle
 * first.
 */
static inline void pwm_init_state(const struct pwm_device *pwm,
				  struct pwm_state *state)
{
	struct pwm_args args;

	/* First get the current state. */
	pwm_get_state(pwm, state);

	/* Then fill it with the reference config */
	pwm_get_args(pwm, &args);

	state->period = args.period;
	state->polarity = args.polarity;
	state->duty_cycle = 0;
}

/**
 * pwm_get_relative_duty_cycle() - Get a relative duty cycle value
 * @state: PWM state to extract the duty cycle from
 * @scale: target scale of the relative duty cycle
 *
 * This functions converts the absolute duty cycle stored in @state (expressed
 * in nanosecond) into a value relative to the period.
 *
 * For example if you want to get the duty_cycle expressed in percent, call:
 *
 * pwm_get_state(pwm, &state);
 * duty = pwm_get_relative_duty_cycle(&state, 100);
 */
static inline unsigned int
pwm_get_relative_duty_cycle(const struct pwm_state *state, unsigned int scale)
{
	if (!state->period)
		return 0;

	return DIV_ROUND_CLOSEST_ULL((u64)state->duty_cycle * scale,
				     state->period);
}

/**
 * pwm_set_relative_duty_cycle() - Set a relative duty cycle value
 * @state: PWM state to fill
 * @duty_cycle: relative duty cycle value
 * @scale: scale in which @duty_cycle is expressed
 *
 * This functions converts a relative into an absolute duty cycle (expressed
 * in nanoseconds), and puts the result in state->duty_cycle.
 *
 * For example if you want to configure a 50% duty cycle, call:
 *
 * pwm_init_state(pwm, &state);
 * pwm_set_relative_duty_cycle(&state, 50, 100);
 * pwm_apply_state(pwm, &state);
 *
 * This functions returns -EINVAL if @duty_cycle and/or @scale are
 * inconsistent (@scale == 0 or @duty_cycle > @scale).
 */
static inline int
pwm_set_relative_duty_cycle(struct pwm_state *state, unsigned int duty_cycle,
			    unsigned int scale)
{
	if (!scale || duty_cycle > scale)
		return -EINVAL;

	state->duty_cycle = DIV_ROUND_CLOSEST_ULL((u64)duty_cycle *
						  state->period,
						  scale);

	return 0;
}

/**
 * struct pwm_ops - PWM controller operations
 * @request: optional hook for requesting a PWM
 * @free: optional hook for freeing a PWM
 * @capture: capture and report PWM signal
 * @apply: atomically apply a new PWM config
 * @get_state: get the current PWM state. This function is only
 *	       called once per PWM device when the PWM chip is
 *	       registered.
 * @owner: helps prevent removal of modules exporting active PWMs
 * @config: configure duty cycles and period length for this PWM
 * @set_polarity: configure the polarity of this PWM
 * @enable: enable PWM output toggling
 * @disable: disable PWM output toggling
 */
struct pwm_ops {
	int (*request)(struct pwm_chip *chip, struct pwm_device *pwm);
	void (*free)(struct pwm_chip *chip, struct pwm_device *pwm);
	int (*capture)(struct pwm_chip *chip, struct pwm_device *pwm,
		       struct pwm_capture *result, unsigned long timeout);
	int (*apply)(struct pwm_chip *chip, struct pwm_device *pwm,
		     const struct pwm_state *state);
	void (*get_state)(struct pwm_chip *chip, struct pwm_device *pwm,
			  struct pwm_state *state);
	struct module *owner;

	/* Only used by legacy drivers */
	int (*config)(struct pwm_chip *chip, struct pwm_device *pwm,
		      int duty_ns, int period_ns);
	int (*set_polarity)(struct pwm_chip *chip, struct pwm_device *pwm,
			    enum pwm_polarity polarity);
	int (*enable)(struct pwm_chip *chip, struct pwm_device *pwm);
	void (*disable)(struct pwm_chip *chip, struct pwm_device *pwm);
};

/**
 * struct pwm_chip - abstract a PWM controller
 * @dev: device providing the PWMs
 * @ops: callbacks for this PWM controller
 * @base: number of first PWM controlled by this chip
 * @npwm: number of PWMs controlled by this chip
 * @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
 * @list: list node for internal use
 * @pwms: array of PWM devices allocated by the framework
 */
struct pwm_chip {
	struct device *dev;
	const struct pwm_ops *ops;
	int base;
	unsigned int npwm;

	struct pwm_device * (*of_xlate)(struct pwm_chip *pc,
					const struct of_phandle_args *args);
	unsigned int of_pwm_n_cells;

	/* only used internally by the PWM framework */
	struct list_head list;
	struct pwm_device *pwms;
};

/**
 * struct pwm_capture - PWM capture data
 * @period: period of the PWM signal (in nanoseconds)
 * @duty_cycle: duty cycle of the PWM signal (in nanoseconds)
 */
struct pwm_capture {
	unsigned int period;
	unsigned int duty_cycle;
};

#if IS_ENABLED(CONFIG_PWM)
/* PWM user APIs */
struct pwm_device *pwm_request(int pwm_id, const char *label);
void pwm_free(struct pwm_device *pwm);
int pwm_apply_state(struct pwm_device *pwm, const struct pwm_state *state);
int pwm_adjust_config(struct pwm_device *pwm);

/**
 * pwm_config() - change a PWM device configuration
 * @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.
 */
static inline int pwm_config(struct pwm_device *pwm, int duty_ns,
			     int period_ns)
{
	struct pwm_state state;

	if (!pwm)
		return -EINVAL;

	if (duty_ns < 0 || period_ns < 0)
		return -EINVAL;

	pwm_get_state(pwm, &state);
	if (state.duty_cycle == duty_ns && state.period == period_ns)
		return 0;

	state.duty_cycle = duty_ns;
	state.period = period_ns;
	return pwm_apply_state(pwm, &state);
}

/**
 * pwm_enable() - start a PWM output toggling
 * @pwm: PWM device
 *
 * Returns: 0 on success or a negative error code on failure.
 */
static inline int pwm_enable(struct pwm_device *pwm)
{
	struct pwm_state state;

	if (!pwm)
		return -EINVAL;

	pwm_get_state(pwm, &state);
	if (state.enabled)
		return 0;

	state.enabled = true;
	return pwm_apply_state(pwm, &state);
}

/**
 * pwm_disable() - stop a PWM output toggling
 * @pwm: PWM device
 */
static inline void pwm_disable(struct pwm_device *pwm)
{
	struct pwm_state state;

	if (!pwm)
		return;

	pwm_get_state(pwm, &state);
	if (!state.enabled)
		return;

	state.enabled = false;
	pwm_apply_state(pwm, &state);
}

/* PWM provider APIs */
int pwm_capture(struct pwm_device *pwm, struct pwm_capture *result,
		unsigned long timeout);
int pwm_set_chip_data(struct pwm_device *pwm, void *data);
void *pwm_get_chip_data(struct pwm_device *pwm);

int pwmchip_add(struct pwm_chip *chip);
int pwmchip_remove(struct pwm_chip *chip);
struct pwm_device *pwm_request_from_chip(struct pwm_chip *chip,
					 unsigned int index,
					 const char *label);

struct pwm_device *of_pwm_xlate_with_flags(struct pwm_chip *pc,
		const struct of_phandle_args *args);

struct pwm_device *pwm_get(struct device *dev, const char *con_id);
struct pwm_device *of_pwm_get(struct device *dev, struct device_node *np,
			      const char *con_id);
void pwm_put(struct pwm_device *pwm);

struct pwm_device *devm_pwm_get(struct device *dev, const char *con_id);
struct pwm_device *devm_of_pwm_get(struct device *dev, struct device_node *np,
				   const char *con_id);
struct pwm_device *devm_fwnode_pwm_get(struct device *dev,
				       struct fwnode_handle *fwnode,
				       const char *con_id);
void devm_pwm_put(struct device *dev, struct pwm_device *pwm);
#else
static inline struct pwm_device *pwm_request(int pwm_id, const char *label)
{
	return ERR_PTR(-ENODEV);
}

static inline void pwm_free(struct pwm_device *pwm)
{
}

static inline int pwm_apply_state(struct pwm_device *pwm,
				  const struct pwm_state *state)
{
	return -ENOTSUPP;
}

static inline int pwm_adjust_config(struct pwm_device *pwm)
{
	return -ENOTSUPP;
}

static inline int pwm_config(struct pwm_device *pwm, int duty_ns,
			     int period_ns)
{
	return -EINVAL;
}

static inline int pwm_capture(struct pwm_device *pwm,
			      struct pwm_capture *result,
			      unsigned long timeout)
{
	return -EINVAL;
}

static inline int pwm_enable(struct pwm_device *pwm)
{
	return -EINVAL;
}

static inline void pwm_disable(struct pwm_device *pwm)
{
}

static inline int pwm_set_chip_data(struct pwm_device *pwm, void *data)
{
	return -EINVAL;
}

static inline void *pwm_get_chip_data(struct pwm_device *pwm)
{
	return NULL;
}

static inline int pwmchip_add(struct pwm_chip *chip)
{
	return -EINVAL;
}

static inline int pwmchip_remove(struct pwm_chip *chip)
{
	return -EINVAL;
}

static inline struct pwm_device *pwm_request_from_chip(struct pwm_chip *chip,
						       unsigned int index,
						       const char *label)
{
	return ERR_PTR(-ENODEV);
}

static inline struct pwm_device *pwm_get(struct device *dev,
					 const char *consumer)
{
	return ERR_PTR(-ENODEV);
}

static inline struct pwm_device *of_pwm_get(struct device *dev,
					    struct device_node *np,
					    const char *con_id)
{
	return ERR_PTR(-ENODEV);
}

static inline void pwm_put(struct pwm_device *pwm)
{
}

static inline struct pwm_device *devm_pwm_get(struct device *dev,
					      const char *consumer)
{
	return ERR_PTR(-ENODEV);
}

static inline struct pwm_device *devm_of_pwm_get(struct device *dev,
						 struct device_node *np,
						 const char *con_id)
{
	return ERR_PTR(-ENODEV);
}

static inline struct pwm_device *
devm_fwnode_pwm_get(struct device *dev, struct fwnode_handle *fwnode,
		    const char *con_id)
{
	return ERR_PTR(-ENODEV);
}

static inline void devm_pwm_put(struct device *dev, struct pwm_device *pwm)
{
}
#endif

static inline void pwm_apply_args(struct pwm_device *pwm)
{
	struct pwm_state state = { };

	/*
	 * PWM users calling pwm_apply_args() expect to have a fresh config
	 * where the polarity and period are set according to pwm_args info.
	 * The problem is, polarity can only be changed when the PWM is
	 * disabled.
	 *
	 * PWM drivers supporting hardware readout may declare the PWM device
	 * as enabled, and prevent polarity setting, which changes from the
	 * existing behavior, where all PWM devices are declared as disabled
	 * at startup (even if they are actually enabled), thus authorizing
	 * polarity setting.
	 *
	 * To fulfill this requirement, we apply a new state which disables
	 * the PWM device and set the reference period and polarity config.
	 *
	 * Note that PWM users requiring a smooth handover between the
	 * bootloader and the kernel (like critical regulators controlled by
	 * PWM devices) will have to switch to the atomic API and avoid calling
	 * pwm_apply_args().
	 */

	state.enabled = false;
	state.polarity = pwm->args.polarity;
	state.period = pwm->args.period;

	pwm_apply_state(pwm, &state);
}

struct pwm_lookup {
	struct list_head list;
	const char *provider;
	unsigned int index;
	const char *dev_id;
	const char *con_id;
	unsigned int period;
	enum pwm_polarity polarity;
	const char *module; /* optional, may be NULL */
};

#define PWM_LOOKUP_WITH_MODULE(_provider, _index, _dev_id, _con_id,	\
			       _period, _polarity, _module)		\
	{								\
		.provider = _provider,					\
		.index = _index,					\
		.dev_id = _dev_id,					\
		.con_id = _con_id,					\
		.period = _period,					\
		.polarity = _polarity,					\
		.module = _module,					\
	}

#define PWM_LOOKUP(_provider, _index, _dev_id, _con_id, _period, _polarity) \
	PWM_LOOKUP_WITH_MODULE(_provider, _index, _dev_id, _con_id, _period, \
			       _polarity, NULL)

#if IS_ENABLED(CONFIG_PWM)
void pwm_add_table(struct pwm_lookup *table, size_t num);
void pwm_remove_table(struct pwm_lookup *table, size_t num);
#else
static inline void pwm_add_table(struct pwm_lookup *table, size_t num)
{
}

static inline void pwm_remove_table(struct pwm_lookup *table, size_t num)
{
}
#endif

#ifdef CONFIG_PWM_SYSFS
void pwmchip_sysfs_export(struct pwm_chip *chip);
void pwmchip_sysfs_unexport(struct pwm_chip *chip);
#else
static inline void pwmchip_sysfs_export(struct pwm_chip *chip)
{
}

static inline void pwmchip_sysfs_unexport(struct pwm_chip *chip)
{
}
#endif /* CONFIG_PWM_SYSFS */

#endif /* __LINUX_PWM_H */
Commit	Line	Data
b2441318	1	/* SPDX-License-Identifier: GPL-2.0 */
1a189b97 RK	2	#ifndef __LINUX_PWM_H
	3	#define __LINUX_PWM_H
	4
0bcf168b	5	#include <linux/err.h>
d1cd2142	6	#include <linux/mutex.h>
7299ab70 TR	7	#include <linux/of.h>
7299ab70 TR	8
3a3d1a4e	9	struct pwm_capture;
62099abf	10	struct seq_file;
3a3d1a4e	11
0c2498f1 SH	12	struct pwm_chip;
0c2498f1 SH	13
0aa0869c PA	14	/**
	15	* enum pwm_polarity - polarity of a PWM signal
	16	* @PWM_POLARITY_NORMAL: a high signal for the duration of the duty-
	17	* cycle, followed by a low signal for the remainder of the pulse
	18	* period
	19	* @PWM_POLARITY_INVERSED: a low signal for the duration of the duty-
	20	* cycle, followed by a high signal for the remainder of the pulse
	21	* period
	22	*/
	23	enum pwm_polarity {
	24	PWM_POLARITY_NORMAL,
	25	PWM_POLARITY_INVERSED,
	26	};
	27
e39c0df1 BB	28	/**
	29	* struct pwm_args - board-dependent PWM arguments
	30	* @period: reference period
	31	* @polarity: reference polarity
	32	*
	33	* This structure describes board-dependent arguments attached to a PWM
	34	* device. These arguments are usually retrieved from the PWM lookup table or
	35	* device tree.
	36	*
	37	* Do not confuse this with the PWM state: PWM arguments represent the initial
	38	* configuration that users want to use on this PWM device rather than the
	39	* current PWM hardware state.
	40	*/
	41	struct pwm_args {
a9d887dc	42	u64 period;
e39c0df1 BB	43	enum pwm_polarity polarity;
	44	};
	45
f051c466 TR	46	enum {
f051c466 TR	47	PWMF_REQUESTED = 1 << 0,
09a7e4a3	48	PWMF_EXPORTED = 1 << 1,
f051c466 TR	49	};
f051c466 TR	50
43a276b0 BB	51	/*
	52	* struct pwm_state - state of a PWM channel
	53	* @period: PWM period (in nanoseconds)
	54	* @duty_cycle: PWM duty cycle (in nanoseconds)
	55	* @polarity: PWM polarity
09a7e4a3	56	* @enabled: PWM enabled status
43a276b0 BB	57	*/
43a276b0 BB	58	struct pwm_state {
a9d887dc GDS	59	u64 period;
a9d887dc GDS	60	u64 duty_cycle;
43a276b0	61	enum pwm_polarity polarity;
09a7e4a3	62	bool enabled;
43a276b0 BB	63	};
43a276b0 BB	64
04883802 TR	65	/**
	66	* struct pwm_device - PWM channel object
	67	* @label: name of the PWM device
	68	* @flags: flags associated with the PWM device
	69	* @hwpwm: per-chip relative index of the PWM device
	70	* @pwm: global index of the PWM device
	71	* @chip: PWM chip providing this PWM device
	72	* @chip_data: chip-private data associated with the PWM device
e39c0df1	73	* @args: PWM arguments
3ad1f3a3 UKK	74	* @state: last applied state
3ad1f3a3 UKK	75	* @last: last implemented state (for PWM_DEBUG)
04883802	76	*/
f051c466	77	struct pwm_device {
6bc7064a TR	78	const char *label;
	79	unsigned long flags;
	80	unsigned int hwpwm;
	81	unsigned int pwm;
	82	struct pwm_chip *chip;
	83	void *chip_data;
	84
e39c0df1	85	struct pwm_args args;
43a276b0	86	struct pwm_state state;
3ad1f3a3	87	struct pwm_state last;
f051c466 TR	88	};
f051c466 TR	89
43a276b0 BB	90	/**
	91	* pwm_get_state() - retrieve the current PWM state
	92	* @pwm: PWM device
	93	* @state: state to fill with the current PWM state
1a7a6e80 UKK	94	*
	95	* The returned PWM state represents the state that was applied by a previous call to
	96	* pwm_apply_state(). Drivers may have to slightly tweak that state before programming it to
	97	* hardware. If pwm_apply_state() was never called, this returns either the current hardware
	98	* state (if supported) or the default settings.
43a276b0 BB	99	*/
	100	static inline void pwm_get_state(const struct pwm_device *pwm,
	101	struct pwm_state *state)
	102	{
	103	*state = pwm->state;
	104	}
	105
5c31252c BB	106	static inline bool pwm_is_enabled(const struct pwm_device *pwm)
5c31252c BB	107	{
09a7e4a3 BB	108	struct pwm_state state;
	109
	110	pwm_get_state(pwm, &state);
	111
	112	return state.enabled;
5c31252c BB	113	}
5c31252c BB	114
a9d887dc	115	static inline void pwm_set_period(struct pwm_device *pwm, u64 period)
f051c466 TR	116	{
f051c466 TR	117	if (pwm)
43a276b0	118	pwm->state.period = period;
f051c466 TR	119	}
f051c466 TR	120
a9d887dc	121	static inline u64 pwm_get_period(const struct pwm_device *pwm)
f051c466	122	{
43a276b0 BB	123	struct pwm_state state;
	124
	125	pwm_get_state(pwm, &state);
	126
	127	return state.period;
f051c466 TR	128	}
f051c466 TR	129
76abbdde HS	130	static inline void pwm_set_duty_cycle(struct pwm_device *pwm, unsigned int duty)
	131	{
	132	if (pwm)
43a276b0	133	pwm->state.duty_cycle = duty;
76abbdde HS	134	}
76abbdde HS	135
a9d887dc	136	static inline u64 pwm_get_duty_cycle(const struct pwm_device *pwm)
76abbdde	137	{
43a276b0 BB	138	struct pwm_state state;
	139
	140	pwm_get_state(pwm, &state);
	141
	142	return state.duty_cycle;
76abbdde HS	143	}
76abbdde HS	144
011e7631 BB	145	static inline enum pwm_polarity pwm_get_polarity(const struct pwm_device *pwm)
011e7631 BB	146	{
43a276b0 BB	147	struct pwm_state state;
	148
	149	pwm_get_state(pwm, &state);
	150
	151	return state.polarity;
011e7631 BB	152	}
011e7631 BB	153
e39c0df1 BB	154	static inline void pwm_get_args(const struct pwm_device *pwm,
	155	struct pwm_args *args)
	156	{
	157	*args = pwm->args;
	158	}
	159
a6a0dbbc BB	160	/**
	161	* pwm_init_state() - prepare a new state to be applied with pwm_apply_state()
	162	* @pwm: PWM device
	163	* @state: state to fill with the prepared PWM state
	164	*
	165	* This functions prepares a state that can later be tweaked and applied
	166	* to the PWM device with pwm_apply_state(). This is a convenient function
	167	* that first retrieves the current PWM state and the replaces the period
	168	* and polarity fields with the reference values defined in pwm->args.
	169	* Once the function returns, you can adjust the ->enabled and ->duty_cycle
	170	* fields according to your needs before calling pwm_apply_state().
	171	*
	172	* ->duty_cycle is initially set to zero to avoid cases where the current
	173	* ->duty_cycle value exceed the pwm_args->period one, which would trigger
	174	* an error if the user calls pwm_apply_state() without adjusting ->duty_cycle
	175	* first.
	176	*/
	177	static inline void pwm_init_state(const struct pwm_device *pwm,
	178	struct pwm_state *state)
	179	{
	180	struct pwm_args args;
	181
	182	/* First get the current state. */
	183	pwm_get_state(pwm, state);
	184
	185	/* Then fill it with the reference config */
	186	pwm_get_args(pwm, &args);
	187
	188	state->period = args.period;
	189	state->polarity = args.polarity;
	190	state->duty_cycle = 0;
	191	}
	192
f6f3bddf BB	193	/**
	194	* pwm_get_relative_duty_cycle() - Get a relative duty cycle value
	195	* @state: PWM state to extract the duty cycle from
	196	* @scale: target scale of the relative duty cycle
	197	*
	198	* This functions converts the absolute duty cycle stored in @state (expressed
	199	* in nanosecond) into a value relative to the period.
	200	*
	201	* For example if you want to get the duty_cycle expressed in percent, call:
	202	*
	203	* pwm_get_state(pwm, &state);
	204	* duty = pwm_get_relative_duty_cycle(&state, 100);
	205	*/
	206	static inline unsigned int
	207	pwm_get_relative_duty_cycle(const struct pwm_state *state, unsigned int scale)
	208	{
	209	if (!state->period)
	210	return 0;
	211
	212	return DIV_ROUND_CLOSEST_ULL((u64)state->duty_cycle * scale,
	213	state->period);
	214	}
	215
	216	/**
	217	* pwm_set_relative_duty_cycle() - Set a relative duty cycle value
	218	* @state: PWM state to fill
	219	* @duty_cycle: relative duty cycle value
	220	* @scale: scale in which @duty_cycle is expressed
	221	*
	222	* This functions converts a relative into an absolute duty cycle (expressed
	223	* in nanoseconds), and puts the result in state->duty_cycle.
	224	*
	225	* For example if you want to configure a 50% duty cycle, call:
	226	*
	227	* pwm_init_state(pwm, &state);
	228	* pwm_set_relative_duty_cycle(&state, 50, 100);
	229	* pwm_apply_state(pwm, &state);
	230	*
	231	* This functions returns -EINVAL if @duty_cycle and/or @scale are
	232	* inconsistent (@scale == 0 or @duty_cycle > @scale).
	233	*/
	234	static inline int
	235	pwm_set_relative_duty_cycle(struct pwm_state *state, unsigned int duty_cycle,
	236	unsigned int scale)
	237	{
	238	if (!scale \|\| duty_cycle > scale)
	239	return -EINVAL;
	240
	241	state->duty_cycle = DIV_ROUND_CLOSEST_ULL((u64)duty_cycle *
	242	state->period,
	243	scale);
	244
	245	return 0;
	246	}
	247
0c2498f1 SH	248	/**
	249	* struct pwm_ops - PWM controller operations
	250	* @request: optional hook for requesting a PWM
	251	* @free: optional hook for freeing a PWM
3a3d1a4e	252	* @capture: capture and report PWM signal
27938fd8	253	* @apply: atomically apply a new PWM config
15fa8a43 BB	254	* @get_state: get the current PWM state. This function is only
	255	* called once per PWM device when the PWM chip is
	256	* registered.
0c2498f1	257	* @owner: helps prevent removal of modules exporting active PWMs
5d0a4c11 UKK	258	* @config: configure duty cycles and period length for this PWM
	259	* @set_polarity: configure the polarity of this PWM
	260	* @enable: enable PWM output toggling
	261	* @disable: disable PWM output toggling
0c2498f1 SH	262	*/
0c2498f1 SH	263	struct pwm_ops {
6bc7064a TR	264	int (request)(struct pwm_chip chip, struct pwm_device *pwm);
6bc7064a TR	265	void (free)(struct pwm_chip chip, struct pwm_device *pwm);
3a3d1a4e LJ	266	int (capture)(struct pwm_chip chip, struct pwm_device *pwm,
3a3d1a4e LJ	267	struct pwm_capture *result, unsigned long timeout);
5ec803ed	268	int (apply)(struct pwm_chip chip, struct pwm_device *pwm,
71523d18	269	const struct pwm_state *state);
15fa8a43 BB	270	void (get_state)(struct pwm_chip chip, struct pwm_device *pwm,
15fa8a43 BB	271	struct pwm_state *state);
6bc7064a	272	struct module *owner;
5d0a4c11 UKK	273
	274	/* Only used by legacy drivers */
	275	int (config)(struct pwm_chip chip, struct pwm_device *pwm,
	276	int duty_ns, int period_ns);
	277	int (set_polarity)(struct pwm_chip chip, struct pwm_device *pwm,
	278	enum pwm_polarity polarity);
	279	int (enable)(struct pwm_chip chip, struct pwm_device *pwm);
	280	void (disable)(struct pwm_chip chip, struct pwm_device *pwm);
0c2498f1 SH	281	};
	282
	283	/**
f051c466 TR	284	* struct pwm_chip - abstract a PWM controller
f051c466 TR	285	* @dev: device providing the PWMs
f051c466 TR	286	* @ops: callbacks for this PWM controller
	287	* @base: number of first PWM controlled by this chip
	288	* @npwm: number of PWMs controlled by this chip
04883802 TR	289	* @of_xlate: request a PWM device given a device tree PWM specifier
04883802 TR	290	* @of_pwm_n_cells: number of cells expected in the device tree PWM specifier
5d0a4c11 UKK	291	* @list: list node for internal use
5d0a4c11 UKK	292	* @pwms: array of PWM devices allocated by the framework
0c2498f1 SH	293	*/
0c2498f1 SH	294	struct pwm_chip {
6bc7064a	295	struct device *dev;
6bc7064a TR	296	const struct pwm_ops *ops;
	297	int base;
	298	unsigned int npwm;
	299
6bc7064a TR	300	struct pwm_device * (of_xlate)(struct pwm_chip pc,
	301	const struct of_phandle_args *args);
	302	unsigned int of_pwm_n_cells;
5d0a4c11 UKK	303
	304	/* only used internally by the PWM framework */
	305	struct list_head list;
	306	struct pwm_device *pwms;
0c2498f1 SH	307	};
0c2498f1 SH	308
3a3d1a4e LJ	309	/**
	310	* struct pwm_capture - PWM capture data
	311	* @period: period of the PWM signal (in nanoseconds)
	312	* @duty_cycle: duty cycle of the PWM signal (in nanoseconds)
	313	*/
	314	struct pwm_capture {
	315	unsigned int period;
	316	unsigned int duty_cycle;
	317	};
	318
0bcf168b	319	#if IS_ENABLED(CONFIG_PWM)
5ec803ed BB	320	/* PWM user APIs */
	321	struct pwm_device pwm_request(int pwm_id, const char label);
	322	void pwm_free(struct pwm_device *pwm);
71523d18	323	int pwm_apply_state(struct pwm_device pwm, const struct pwm_state state);
5ec803ed BB	324	int pwm_adjust_config(struct pwm_device *pwm);
	325
	326	/**
	327	* pwm_config() - change a PWM device configuration
	328	* @pwm: PWM device
	329	* @duty_ns: "on" time (in nanoseconds)
	330	* @period_ns: duration (in nanoseconds) of one cycle
	331	*
	332	* Returns: 0 on success or a negative error code on failure.
	333	*/
	334	static inline int pwm_config(struct pwm_device *pwm, int duty_ns,
	335	int period_ns)
	336	{
	337	struct pwm_state state;
	338
	339	if (!pwm)
	340	return -EINVAL;
	341
ef2bf499 BN	342	if (duty_ns < 0 \|\| period_ns < 0)
	343	return -EINVAL;
	344
5ec803ed BB	345	pwm_get_state(pwm, &state);
	346	if (state.duty_cycle == duty_ns && state.period == period_ns)
	347	return 0;
	348
	349	state.duty_cycle = duty_ns;
	350	state.period = period_ns;
	351	return pwm_apply_state(pwm, &state);
	352	}
	353
5ec803ed BB	354	/**
	355	* pwm_enable() - start a PWM output toggling
	356	* @pwm: PWM device
	357	*
	358	* Returns: 0 on success or a negative error code on failure.
	359	*/
	360	static inline int pwm_enable(struct pwm_device *pwm)
	361	{
	362	struct pwm_state state;
	363
	364	if (!pwm)
	365	return -EINVAL;
	366
	367	pwm_get_state(pwm, &state);
	368	if (state.enabled)
	369	return 0;
	370
	371	state.enabled = true;
	372	return pwm_apply_state(pwm, &state);
	373	}
	374
	375	/**
	376	* pwm_disable() - stop a PWM output toggling
	377	* @pwm: PWM device
	378	*/
	379	static inline void pwm_disable(struct pwm_device *pwm)
	380	{
	381	struct pwm_state state;
	382
	383	if (!pwm)
	384	return;
	385
	386	pwm_get_state(pwm, &state);
	387	if (!state.enabled)
	388	return;
	389
	390	state.enabled = false;
	391	pwm_apply_state(pwm, &state);
	392	}
	393
5ec803ed	394	/* PWM provider APIs */
3a3d1a4e LJ	395	int pwm_capture(struct pwm_device pwm, struct pwm_capture result,
3a3d1a4e LJ	396	unsigned long timeout);
f051c466 TR	397	int pwm_set_chip_data(struct pwm_device pwm, void data);
	398	void pwm_get_chip_data(struct pwm_device pwm);
	399
0c2498f1 SH	400	int pwmchip_add(struct pwm_chip *chip);
0c2498f1 SH	401	int pwmchip_remove(struct pwm_chip *chip);
f051c466 TR	402	struct pwm_device pwm_request_from_chip(struct pwm_chip chip,
	403	unsigned int index,
	404	const char *label);
8138d2dd	405
83af2402 PA	406	struct pwm_device of_pwm_xlate_with_flags(struct pwm_chip pc,
	407	const struct of_phandle_args *args);
	408
d4c0c470	409	struct pwm_device pwm_get(struct device dev, const char *con_id);
b2c200e3 FG	410	struct pwm_device of_pwm_get(struct device dev, struct device_node *np,
b2c200e3 FG	411	const char *con_id);
8138d2dd TR	412	void pwm_put(struct pwm_device *pwm);
8138d2dd TR	413
d4c0c470	414	struct pwm_device devm_pwm_get(struct device dev, const char *con_id);
261a5edd PU	415	struct pwm_device devm_of_pwm_get(struct device dev, struct device_node *np,
261a5edd PU	416	const char *con_id);
4a6ef8e3 NV	417	struct pwm_device devm_fwnode_pwm_get(struct device dev,
	418	struct fwnode_handle *fwnode,
	419	const char *con_id);
6354316d	420	void devm_pwm_put(struct device dev, struct pwm_device pwm);
0bcf168b	421	#else
5ec803ed BB	422	static inline struct pwm_device pwm_request(int pwm_id, const char label)
	423	{
	424	return ERR_PTR(-ENODEV);
	425	}
	426
	427	static inline void pwm_free(struct pwm_device *pwm)
	428	{
	429	}
	430
	431	static inline int pwm_apply_state(struct pwm_device *pwm,
	432	const struct pwm_state *state)
	433	{
	434	return -ENOTSUPP;
	435	}
	436
	437	static inline int pwm_adjust_config(struct pwm_device *pwm)
	438	{
	439	return -ENOTSUPP;
	440	}
	441
	442	static inline int pwm_config(struct pwm_device *pwm, int duty_ns,
	443	int period_ns)
	444	{
	445	return -EINVAL;
	446	}
	447
3a3d1a4e LJ	448	static inline int pwm_capture(struct pwm_device *pwm,
	449	struct pwm_capture *result,
	450	unsigned long timeout)
	451	{
	452	return -EINVAL;
	453	}
	454
5ec803ed BB	455	static inline int pwm_enable(struct pwm_device *pwm)
	456	{
	457	return -EINVAL;
	458	}
	459
	460	static inline void pwm_disable(struct pwm_device *pwm)
	461	{
	462	}
	463
0bcf168b TB	464	static inline int pwm_set_chip_data(struct pwm_device pwm, void data)
	465	{
	466	return -EINVAL;
	467	}
	468
	469	static inline void pwm_get_chip_data(struct pwm_device pwm)
	470	{
	471	return NULL;
	472	}
	473
	474	static inline int pwmchip_add(struct pwm_chip *chip)
	475	{
	476	return -EINVAL;
	477	}
	478
	479	static inline int pwmchip_remove(struct pwm_chip *chip)
	480	{
	481	return -EINVAL;
	482	}
	483
	484	static inline struct pwm_device pwm_request_from_chip(struct pwm_chip chip,
	485	unsigned int index,
	486	const char *label)
	487	{
	488	return ERR_PTR(-ENODEV);
	489	}
	490
	491	static inline struct pwm_device pwm_get(struct device dev,
	492	const char *consumer)
	493	{
	494	return ERR_PTR(-ENODEV);
	495	}
	496
b2c200e3 FG	497	static inline struct pwm_device of_pwm_get(struct device dev,
b2c200e3 FG	498	struct device_node *np,
8eb96127 PU	499	const char *con_id)
	500	{
	501	return ERR_PTR(-ENODEV);
	502	}
	503
0bcf168b TB	504	static inline void pwm_put(struct pwm_device *pwm)
	505	{
	506	}
	507
	508	static inline struct pwm_device devm_pwm_get(struct device dev,
	509	const char *consumer)
	510	{
	511	return ERR_PTR(-ENODEV);
	512	}
	513
261a5edd PU	514	static inline struct pwm_device devm_of_pwm_get(struct device dev,
	515	struct device_node *np,
	516	const char *con_id)
	517	{
	518	return ERR_PTR(-ENODEV);
	519	}
	520
4a6ef8e3 NV	521	static inline struct pwm_device *
	522	devm_fwnode_pwm_get(struct device dev, struct fwnode_handle fwnode,
	523	const char *con_id)
	524	{
	525	return ERR_PTR(-ENODEV);
	526	}
	527
0bcf168b TB	528	static inline void devm_pwm_put(struct device dev, struct pwm_device pwm)
	529	{
	530	}
	531	#endif
6354316d	532
5ec803ed BB	533	static inline void pwm_apply_args(struct pwm_device *pwm)
5ec803ed BB	534	{
33cdcee0 BB	535	struct pwm_state state = { };
33cdcee0 BB	536
5ec803ed BB	537	/*
	538	* PWM users calling pwm_apply_args() expect to have a fresh config
	539	* where the polarity and period are set according to pwm_args info.
	540	* The problem is, polarity can only be changed when the PWM is
	541	* disabled.
	542	*
	543	* PWM drivers supporting hardware readout may declare the PWM device
	544	* as enabled, and prevent polarity setting, which changes from the
	545	* existing behavior, where all PWM devices are declared as disabled
	546	* at startup (even if they are actually enabled), thus authorizing
	547	* polarity setting.
	548	*
33cdcee0 BB	549	* To fulfill this requirement, we apply a new state which disables
33cdcee0 BB	550	* the PWM device and set the reference period and polarity config.
5ec803ed BB	551	*
	552	* Note that PWM users requiring a smooth handover between the
	553	* bootloader and the kernel (like critical regulators controlled by
	554	* PWM devices) will have to switch to the atomic API and avoid calling
	555	* pwm_apply_args().
	556	*/
33cdcee0 BB	557
	558	state.enabled = false;
	559	state.polarity = pwm->args.polarity;
	560	state.period = pwm->args.period;
	561
	562	pwm_apply_state(pwm, &state);
5ec803ed BB	563	}
5ec803ed BB	564
8138d2dd TR	565	struct pwm_lookup {
	566	struct list_head list;
	567	const char *provider;
	568	unsigned int index;
	569	const char *dev_id;
	570	const char *con_id;
3796ce1d AB	571	unsigned int period;
3796ce1d AB	572	enum pwm_polarity polarity;
b526a314	573	const char module; / optional, may be NULL */
8138d2dd TR	574	};
8138d2dd TR	575
b526a314 HG	576	#define PWM_LOOKUP_WITH_MODULE(_provider, _index, _dev_id, _con_id, \
	577	_period, _polarity, _module) \
	578	{ \
	579	.provider = _provider, \
	580	.index = _index, \
	581	.dev_id = _dev_id, \
	582	.con_id = _con_id, \
	583	.period = _period, \
	584	.polarity = _polarity, \
	585	.module = _module, \
8138d2dd TR	586	}
8138d2dd TR	587
b526a314 HG	588	#define PWM_LOOKUP(_provider, _index, _dev_id, _con_id, _period, _polarity) \
	589	PWM_LOOKUP_WITH_MODULE(_provider, _index, _dev_id, _con_id, _period, \
	590	_polarity, NULL)
	591
0bcf168b	592	#if IS_ENABLED(CONFIG_PWM)
8138d2dd	593	void pwm_add_table(struct pwm_lookup *table, size_t num);
efb0de55	594	void pwm_remove_table(struct pwm_lookup *table, size_t num);
0bcf168b TB	595	#else
	596	static inline void pwm_add_table(struct pwm_lookup *table, size_t num)
	597	{
	598	}
efb0de55 SK	599
	600	static inline void pwm_remove_table(struct pwm_lookup *table, size_t num)
	601	{
	602	}
0c2498f1 SH	603	#endif
0c2498f1 SH	604
76abbdde HS	605	#ifdef CONFIG_PWM_SYSFS
	606	void pwmchip_sysfs_export(struct pwm_chip *chip);
	607	void pwmchip_sysfs_unexport(struct pwm_chip *chip);
	608	#else
	609	static inline void pwmchip_sysfs_export(struct pwm_chip *chip)
	610	{
	611	}
	612
	613	static inline void pwmchip_sysfs_unexport(struct pwm_chip *chip)
	614	{
	615	}
	616	#endif /* CONFIG_PWM_SYSFS */
	617
5243ef8b	618	#endif /* __LINUX_PWM_H */