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