1 /* SPDX-License-Identifier: GPL-2.0 */
11 MODULE_IMPORT_NS("PWM");
16  * enum pwm_polarity - polarity of a PWM signal
17  * @PWM_POLARITY_NORMAL: a high signal for the duration of the duty-
19  * period
20  * @PWM_POLARITY_INVERSED: a low signal for the duration of the duty-
22  * period
30  * struct pwm_args - board-dependent PWM arguments
31  * @period: reference period
34  * This structure describes board-dependent arguments attached to a PWM
35  * device. These arguments are usually retrieved from the PWM lookup table or
38  * Do not confuse this with the PWM state: PWM arguments represent the initial
39  * configuration that users want to use on this PWM device rather than the
40  * current PWM hardware state.
43 	u64 period;  member
53  * struct pwm_waveform - description of a PWM waveform
54  * @period_length_ns: PWM period
55  * @duty_length_ns: PWM duty cycle
56  * @duty_offset_ns: offset of the rising edge from the period's start
58  * This is a representation of a PWM waveform alternative to struct pwm_state
61  * PWM_POLARITY_NORMAL) and period - duty_cycle (.polarity =
64  * Note there is no explicit bool for enabled. A "disabled" PWM is represented
65  * by .period_length_ns = 0. Note further that the behaviour of a "disabled" PWM
67  * active or inactive level, go high-z or even continue to toggle.
78  * struct pwm_state - state of a PWM channel
79  * @period: PWM period (in nanoseconds)
80  * @duty_cycle: PWM duty cycle (in nanoseconds)
81  * @polarity: PWM polarity
82  * @enabled: PWM enabled status
83  * @usage_power: If set, the PWM driver is only required to maintain the power
89 	u64 period;  member
97  * struct pwm_device - PWM channel object
98  * @label: name of the PWM device
99  * @flags: flags associated with the PWM device
100  * @hwpwm: per-chip relative index of the PWM device
101  * @chip: PWM chip providing this PWM device
102  * @args: PWM arguments
118  * pwm_get_state() - retrieve the current PWM state
119  * @pwm: PWM device
120  * @state: state to fill with the current PWM state
122  * The returned PWM state represents the state that was applied by a previous call to
127 static inline void pwm_get_state(const struct pwm_device *pwm,  in pwm_get_state()  argument
130 	*state = pwm->state;  in pwm_get_state()
133 static inline bool pwm_is_enabled(const struct pwm_device *pwm)  in pwm_is_enabled()  argument
137 	pwm_get_state(pwm, &state);  in pwm_is_enabled()
142 static inline u64 pwm_get_period(const struct pwm_device *pwm)  in pwm_get_period()  argument
146 	pwm_get_state(pwm, &state);  in pwm_get_period()
148 	return state.period;  in pwm_get_period()
151 static inline u64 pwm_get_duty_cycle(const struct pwm_device *pwm)  in pwm_get_duty_cycle()  argument
155 	pwm_get_state(pwm, &state);  in pwm_get_duty_cycle()
160 static inline enum pwm_polarity pwm_get_polarity(const struct pwm_device *pwm)  in pwm_get_polarity()  argument
164 	pwm_get_state(pwm, &state);  in pwm_get_polarity()
169 static inline void pwm_get_args(const struct pwm_device *pwm,  in pwm_get_args()  argument
172 	*args = pwm->args;  in pwm_get_args()
176  * pwm_init_state() - prepare a new state to be applied with pwm_apply_might_sleep()
177  * @pwm: PWM device
178  * @state: state to fill with the prepared PWM state
181  * to the PWM device with pwm_apply_might_sleep(). This is a convenient function
182  * that first retrieves the current PWM state and the replaces the period
183  * and polarity fields with the reference values defined in pwm->args.
184  * Once the function returns, you can adjust the ->enabled and ->duty_cycle
187  * ->duty_cycle is initially set to zero to avoid cases where the current
188  * ->duty_cycle value exceed the pwm_args->period one, which would trigger
189  * an error if the user calls pwm_apply_might_sleep() without adjusting ->duty_cycle
192 static inline void pwm_init_state(const struct pwm_device *pwm,  in pwm_init_state()  argument
198 	pwm_get_state(pwm, state);  in pwm_init_state()
201 	pwm_get_args(pwm, &args);  in pwm_init_state()
203 	state->period = args.period;  in pwm_init_state()
204 	state->polarity = args.polarity;  in pwm_init_state()
205 	state->duty_cycle = 0;  in pwm_init_state()
206 	state->usage_power = false;  in pwm_init_state()
210  * pwm_get_relative_duty_cycle() - Get a relative duty cycle value
211  * @state: PWM state to extract the duty cycle from
215  * in nanosecond) into a value relative to the period.
219  * pwm_get_state(pwm, &state);
225 	if (!state->period)  in pwm_get_relative_duty_cycle()
228 	return DIV_ROUND_CLOSEST_ULL((u64)state->duty_cycle * scale,  in pwm_get_relative_duty_cycle()
229 				     state->period);  in pwm_get_relative_duty_cycle()
233  * pwm_set_relative_duty_cycle() - Set a relative duty cycle value
234  * @state: PWM state to fill
239  * in nanoseconds), and puts the result in state->duty_cycle.
243  * pwm_init_state(pwm, &state);
245  * pwm_apply_might_sleep(pwm, &state);
247  * This functions returns -EINVAL if @duty_cycle and/or @scale are
255 		return -EINVAL;  in pwm_set_relative_duty_cycle()
257 	state->duty_cycle = DIV_ROUND_CLOSEST_ULL((u64)duty_cycle *  in pwm_set_relative_duty_cycle()
258 						  state->period,  in pwm_set_relative_duty_cycle()
265  * struct pwm_capture - PWM capture data
266  * @period: period of the PWM signal (in nanoseconds)
267  * @duty_cycle: duty cycle of the PWM signal (in nanoseconds)
270 	unsigned int period;  member
275  * struct pwm_ops - PWM controller operations
276  * @request: optional hook for requesting a PWM
277  * @free: optional hook for freeing a PWM
278  * @capture: capture and report PWM signal
284  * @apply: atomically apply a new PWM config
285  * @get_state: get the current PWM state.
288 	int (*request)(struct pwm_chip *chip, struct pwm_device *pwm);
289 	void (*free)(struct pwm_chip *chip, struct pwm_device *pwm);
290 	int (*capture)(struct pwm_chip *chip, struct pwm_device *pwm,
294 	int (*round_waveform_tohw)(struct pwm_chip *chip, struct pwm_device *pwm,
296 	int (*round_waveform_fromhw)(struct pwm_chip *chip, struct pwm_device *pwm,
298 	int (*read_waveform)(struct pwm_chip *chip, struct pwm_device *pwm,
300 	int (*write_waveform)(struct pwm_chip *chip, struct pwm_device *pwm,
303 	int (*apply)(struct pwm_chip *chip, struct pwm_device *pwm,
305 	int (*get_state)(struct pwm_chip *chip, struct pwm_device *pwm,
310  * struct pwm_chip - abstract a PWM controller
312  * @ops: callbacks for this PWM controller
314  * @id: unique number of this PWM chip
316  * @of_xlate: request a PWM device given a device tree PWM specifier
317  * @atomic: can the driver's ->apply() be called in atomic context
322  * @pwms: array of PWM devices allocated by the framework
335 	/* only used internally by the PWM framework */
351  * pwmchip_supports_waveform() - checks if the given chip supports waveform callbacks
354  * Returns true iff the pwm chip support the waveform functions like
364 	return chip->ops->write_waveform != NULL;  in pwmchip_supports_waveform()
369 	return chip->dev.parent;  in pwmchip_parent()
374 	return dev_get_drvdata(&chip->dev);  in pwmchip_get_drvdata()
379 	dev_set_drvdata(&chip->dev, data);  in pwmchip_set_drvdata()
384 /* PWM consumer APIs */
385 int pwm_round_waveform_might_sleep(struct pwm_device *pwm, struct pwm_waveform *wf);
386 int pwm_get_waveform_might_sleep(struct pwm_device *pwm, struct pwm_waveform *wf);
387 int pwm_set_waveform_might_sleep(struct pwm_device *pwm, const struct pwm_waveform *wf, bool exact);
388 int pwm_apply_might_sleep(struct pwm_device *pwm, const struct pwm_state *state);
389 int pwm_apply_atomic(struct pwm_device *pwm, const struct pwm_state *state);
390 int pwm_get_state_hw(struct pwm_device *pwm, struct pwm_state *state);
391 int pwm_adjust_config(struct pwm_device *pwm);
394  * pwm_config() - change a PWM device configuration
395  * @pwm: PWM device
401 static inline int pwm_config(struct pwm_device *pwm, int duty_ns,  in pwm_config()  argument
406 	if (!pwm)  in pwm_config()
407 		return -EINVAL;  in pwm_config()
410 		return -EINVAL;  in pwm_config()
412 	pwm_get_state(pwm, &state);  in pwm_config()
413 	if (state.duty_cycle == duty_ns && state.period == period_ns)  in pwm_config()
417 	state.period = period_ns;  in pwm_config()
418 	return pwm_apply_might_sleep(pwm, &state);  in pwm_config()
422  * pwm_enable() - start a PWM output toggling
423  * @pwm: PWM device
427 static inline int pwm_enable(struct pwm_device *pwm)  in pwm_enable()  argument
431 	if (!pwm)  in pwm_enable()
432 		return -EINVAL;  in pwm_enable()
434 	pwm_get_state(pwm, &state);  in pwm_enable()
439 	return pwm_apply_might_sleep(pwm, &state);  in pwm_enable()
443  * pwm_disable() - stop a PWM output toggling
444  * @pwm: PWM device
446 static inline void pwm_disable(struct pwm_device *pwm)  in pwm_disable()  argument
450 	if (!pwm)  in pwm_disable()
453 	pwm_get_state(pwm, &state);  in pwm_disable()
458 	pwm_apply_might_sleep(pwm, &state);  in pwm_disable()
462  * pwm_might_sleep() - is pwm_apply_atomic() supported?
463  * @pwm: PWM device
467 static inline bool pwm_might_sleep(struct pwm_device *pwm)  in pwm_might_sleep()  argument
469 	return !pwm->chip->atomic;  in pwm_might_sleep()
472 /* PWM provider APIs */
490 void pwm_put(struct pwm_device *pwm);
497 static inline bool pwm_might_sleep(struct pwm_device *pwm)  in pwm_might_sleep()  argument
502 static inline int pwm_apply_might_sleep(struct pwm_device *pwm,  in pwm_apply_might_sleep()  argument
506 	return -EOPNOTSUPP;  in pwm_apply_might_sleep()
509 static inline int pwm_apply_atomic(struct pwm_device *pwm,  in pwm_apply_atomic()  argument
512 	return -EOPNOTSUPP;  in pwm_apply_atomic()
515 static inline int pwm_get_state_hw(struct pwm_device *pwm, struct pwm_state *state)  in pwm_get_state_hw()  argument
517 	return -EOPNOTSUPP;  in pwm_get_state_hw()
520 static inline int pwm_adjust_config(struct pwm_device *pwm)  in pwm_adjust_config()  argument
522 	return -EOPNOTSUPP;  in pwm_adjust_config()
525 static inline int pwm_config(struct pwm_device *pwm, int duty_ns,  in pwm_config()  argument
529 	return -EINVAL;  in pwm_config()
532 static inline int pwm_enable(struct pwm_device *pwm)  in pwm_enable()  argument
535 	return -EINVAL;  in pwm_enable()
538 static inline void pwm_disable(struct pwm_device *pwm)  in pwm_disable()  argument
551 	return ERR_PTR(-EINVAL);  in pwmchip_alloc()
563 	return -EINVAL;  in pwmchip_add()
568 	return -EINVAL;  in pwmchip_remove()
573 	return -EINVAL;  in devm_pwmchip_add()
580 	return ERR_PTR(-ENODEV);  in pwm_get()
583 static inline void pwm_put(struct pwm_device *pwm)  in pwm_put()  argument
592 	return ERR_PTR(-ENODEV);  in devm_pwm_get()
600 	return ERR_PTR(-ENODEV);  in devm_fwnode_pwm_get()
604 static inline void pwm_apply_args(struct pwm_device *pwm)  in pwm_apply_args()  argument
609 	 * PWM users calling pwm_apply_args() expect to have a fresh config  in pwm_apply_args()
610 	 * where the polarity and period are set according to pwm_args info.  in pwm_apply_args()
611 	 * The problem is, polarity can only be changed when the PWM is  in pwm_apply_args()
614 	 * PWM drivers supporting hardware readout may declare the PWM device  in pwm_apply_args()
616 	 * existing behavior, where all PWM devices are declared as disabled  in pwm_apply_args()
621 	 * the PWM device and set the reference period and polarity config.  in pwm_apply_args()
623 	 * Note that PWM users requiring a smooth handover between the  in pwm_apply_args()
625 	 * PWM devices) will have to switch to the atomic API and avoid calling  in pwm_apply_args()
630 	state.polarity = pwm->args.polarity;  in pwm_apply_args()
631 	state.period = pwm->args.period;  in pwm_apply_args()
634 	pwm_apply_might_sleep(pwm, &state);  in pwm_apply_args()
643 	unsigned int period;  member
655 		.period = _period,					\