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