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 = 1 << 0,
45 	PWMF_EXPORTED = 1 << 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 	void (*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 *pc,
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 struct pwm_device *pwm_request(int pwm_id, const char *label);
313 void pwm_free(struct pwm_device *pwm);
314 int pwm_apply_state(struct pwm_device *pwm, const struct pwm_state *state);
315 int pwm_adjust_config(struct pwm_device *pwm);
316 
317 /**
318  * pwm_config() - change a PWM device configuration
319  * @pwm: PWM device
320  * @duty_ns: "on" time (in nanoseconds)
321  * @period_ns: duration (in nanoseconds) of one cycle
322  *
323  * Returns: 0 on success or a negative error code on failure.
324  */
pwm_config(struct pwm_device * pwm,int duty_ns,int period_ns)325 static inline int pwm_config(struct pwm_device *pwm, int duty_ns,
326 			     int period_ns)
327 {
328 	struct pwm_state state;
329 
330 	if (!pwm)
331 		return -EINVAL;
332 
333 	if (duty_ns < 0 || period_ns < 0)
334 		return -EINVAL;
335 
336 	pwm_get_state(pwm, &state);
337 	if (state.duty_cycle == duty_ns && state.period == period_ns)
338 		return 0;
339 
340 	state.duty_cycle = duty_ns;
341 	state.period = period_ns;
342 	return pwm_apply_state(pwm, &state);
343 }
344 
345 /**
346  * pwm_enable() - start a PWM output toggling
347  * @pwm: PWM device
348  *
349  * Returns: 0 on success or a negative error code on failure.
350  */
pwm_enable(struct pwm_device * pwm)351 static inline int pwm_enable(struct pwm_device *pwm)
352 {
353 	struct pwm_state state;
354 
355 	if (!pwm)
356 		return -EINVAL;
357 
358 	pwm_get_state(pwm, &state);
359 	if (state.enabled)
360 		return 0;
361 
362 	state.enabled = true;
363 	return pwm_apply_state(pwm, &state);
364 }
365 
366 /**
367  * pwm_disable() - stop a PWM output toggling
368  * @pwm: PWM device
369  */
pwm_disable(struct pwm_device * pwm)370 static inline void pwm_disable(struct pwm_device *pwm)
371 {
372 	struct pwm_state state;
373 
374 	if (!pwm)
375 		return;
376 
377 	pwm_get_state(pwm, &state);
378 	if (!state.enabled)
379 		return;
380 
381 	state.enabled = false;
382 	pwm_apply_state(pwm, &state);
383 }
384 
385 /* PWM provider APIs */
386 int pwm_capture(struct pwm_device *pwm, struct pwm_capture *result,
387 		unsigned long timeout);
388 int pwm_set_chip_data(struct pwm_device *pwm, void *data);
389 void *pwm_get_chip_data(struct pwm_device *pwm);
390 
391 int pwmchip_add(struct pwm_chip *chip);
392 void pwmchip_remove(struct pwm_chip *chip);
393 
394 int devm_pwmchip_add(struct device *dev, struct pwm_chip *chip);
395 
396 struct pwm_device *pwm_request_from_chip(struct pwm_chip *chip,
397 					 unsigned int index,
398 					 const char *label);
399 
400 struct pwm_device *of_pwm_xlate_with_flags(struct pwm_chip *pc,
401 		const struct of_phandle_args *args);
402 struct pwm_device *of_pwm_single_xlate(struct pwm_chip *pc,
403 				       const struct of_phandle_args *args);
404 
405 struct pwm_device *pwm_get(struct device *dev, const char *con_id);
406 void pwm_put(struct pwm_device *pwm);
407 
408 struct pwm_device *devm_pwm_get(struct device *dev, const char *con_id);
409 struct pwm_device *devm_fwnode_pwm_get(struct device *dev,
410 				       struct fwnode_handle *fwnode,
411 				       const char *con_id);
412 #else
pwm_request(int pwm_id,const char * label)413 static inline struct pwm_device *pwm_request(int pwm_id, const char *label)
414 {
415 	might_sleep();
416 	return ERR_PTR(-ENODEV);
417 }
418 
pwm_free(struct pwm_device * pwm)419 static inline void pwm_free(struct pwm_device *pwm)
420 {
421 	might_sleep();
422 }
423 
pwm_apply_state(struct pwm_device * pwm,const struct pwm_state * state)424 static inline int pwm_apply_state(struct pwm_device *pwm,
425 				  const struct pwm_state *state)
426 {
427 	might_sleep();
428 	return -ENOTSUPP;
429 }
430 
pwm_adjust_config(struct pwm_device * pwm)431 static inline int pwm_adjust_config(struct pwm_device *pwm)
432 {
433 	return -ENOTSUPP;
434 }
435 
pwm_config(struct pwm_device * pwm,int duty_ns,int period_ns)436 static inline int pwm_config(struct pwm_device *pwm, int duty_ns,
437 			     int period_ns)
438 {
439 	might_sleep();
440 	return -EINVAL;
441 }
442 
pwm_capture(struct pwm_device * pwm,struct pwm_capture * result,unsigned long timeout)443 static inline int pwm_capture(struct pwm_device *pwm,
444 			      struct pwm_capture *result,
445 			      unsigned long timeout)
446 {
447 	return -EINVAL;
448 }
449 
pwm_enable(struct pwm_device * pwm)450 static inline int pwm_enable(struct pwm_device *pwm)
451 {
452 	might_sleep();
453 	return -EINVAL;
454 }
455 
pwm_disable(struct pwm_device * pwm)456 static inline void pwm_disable(struct pwm_device *pwm)
457 {
458 	might_sleep();
459 }
460 
pwm_set_chip_data(struct pwm_device * pwm,void * data)461 static inline int pwm_set_chip_data(struct pwm_device *pwm, void *data)
462 {
463 	return -EINVAL;
464 }
465 
pwm_get_chip_data(struct pwm_device * pwm)466 static inline void *pwm_get_chip_data(struct pwm_device *pwm)
467 {
468 	return NULL;
469 }
470 
pwmchip_add(struct pwm_chip * chip)471 static inline int pwmchip_add(struct pwm_chip *chip)
472 {
473 	return -EINVAL;
474 }
475 
pwmchip_remove(struct pwm_chip * chip)476 static inline int pwmchip_remove(struct pwm_chip *chip)
477 {
478 	return -EINVAL;
479 }
480 
pwm_request_from_chip(struct pwm_chip * chip,unsigned int index,const char * label)481 static inline struct pwm_device *pwm_request_from_chip(struct pwm_chip *chip,
482 						       unsigned int index,
483 						       const char *label)
484 {
485 	might_sleep();
486 	return ERR_PTR(-ENODEV);
487 }
488 
pwm_get(struct device * dev,const char * consumer)489 static inline struct pwm_device *pwm_get(struct device *dev,
490 					 const char *consumer)
491 {
492 	might_sleep();
493 	return ERR_PTR(-ENODEV);
494 }
495 
pwm_put(struct pwm_device * pwm)496 static inline void pwm_put(struct pwm_device *pwm)
497 {
498 	might_sleep();
499 }
500 
devm_pwm_get(struct device * dev,const char * consumer)501 static inline struct pwm_device *devm_pwm_get(struct device *dev,
502 					      const char *consumer)
503 {
504 	might_sleep();
505 	return ERR_PTR(-ENODEV);
506 }
507 
508 static inline struct pwm_device *
devm_fwnode_pwm_get(struct device * dev,struct fwnode_handle * fwnode,const char * con_id)509 devm_fwnode_pwm_get(struct device *dev, struct fwnode_handle *fwnode,
510 		    const char *con_id)
511 {
512 	might_sleep();
513 	return ERR_PTR(-ENODEV);
514 }
515 #endif
516 
pwm_apply_args(struct pwm_device * pwm)517 static inline void pwm_apply_args(struct pwm_device *pwm)
518 {
519 	struct pwm_state state = { };
520 
521 	/*
522 	 * PWM users calling pwm_apply_args() expect to have a fresh config
523 	 * where the polarity and period are set according to pwm_args info.
524 	 * The problem is, polarity can only be changed when the PWM is
525 	 * disabled.
526 	 *
527 	 * PWM drivers supporting hardware readout may declare the PWM device
528 	 * as enabled, and prevent polarity setting, which changes from the
529 	 * existing behavior, where all PWM devices are declared as disabled
530 	 * at startup (even if they are actually enabled), thus authorizing
531 	 * polarity setting.
532 	 *
533 	 * To fulfill this requirement, we apply a new state which disables
534 	 * the PWM device and set the reference period and polarity config.
535 	 *
536 	 * Note that PWM users requiring a smooth handover between the
537 	 * bootloader and the kernel (like critical regulators controlled by
538 	 * PWM devices) will have to switch to the atomic API and avoid calling
539 	 * pwm_apply_args().
540 	 */
541 
542 	state.enabled = false;
543 	state.polarity = pwm->args.polarity;
544 	state.period = pwm->args.period;
545 	state.usage_power = false;
546 
547 	pwm_apply_state(pwm, &state);
548 }
549 
550 struct pwm_lookup {
551 	struct list_head list;
552 	const char *provider;
553 	unsigned int index;
554 	const char *dev_id;
555 	const char *con_id;
556 	unsigned int period;
557 	enum pwm_polarity polarity;
558 	const char *module; /* optional, may be NULL */
559 };
560 
561 #define PWM_LOOKUP_WITH_MODULE(_provider, _index, _dev_id, _con_id,	\
562 			       _period, _polarity, _module)		\
563 	{								\
564 		.provider = _provider,					\
565 		.index = _index,					\
566 		.dev_id = _dev_id,					\
567 		.con_id = _con_id,					\
568 		.period = _period,					\
569 		.polarity = _polarity,					\
570 		.module = _module,					\
571 	}
572 
573 #define PWM_LOOKUP(_provider, _index, _dev_id, _con_id, _period, _polarity) \
574 	PWM_LOOKUP_WITH_MODULE(_provider, _index, _dev_id, _con_id, _period, \
575 			       _polarity, NULL)
576 
577 #if IS_ENABLED(CONFIG_PWM)
578 void pwm_add_table(struct pwm_lookup *table, size_t num);
579 void pwm_remove_table(struct pwm_lookup *table, size_t num);
580 #else
pwm_add_table(struct pwm_lookup * table,size_t num)581 static inline void pwm_add_table(struct pwm_lookup *table, size_t num)
582 {
583 }
584 
pwm_remove_table(struct pwm_lookup * table,size_t num)585 static inline void pwm_remove_table(struct pwm_lookup *table, size_t num)
586 {
587 }
588 #endif
589 
590 #ifdef CONFIG_PWM_SYSFS
591 void pwmchip_sysfs_export(struct pwm_chip *chip);
592 void pwmchip_sysfs_unexport(struct pwm_chip *chip);
593 #else
pwmchip_sysfs_export(struct pwm_chip * chip)594 static inline void pwmchip_sysfs_export(struct pwm_chip *chip)
595 {
596 }
597 
pwmchip_sysfs_unexport(struct pwm_chip * chip)598 static inline void pwmchip_sysfs_unexport(struct pwm_chip *chip)
599 {
600 }
601 #endif /* CONFIG_PWM_SYSFS */
602 
603 #endif /* __LINUX_PWM_H */
604