xref: /linux/drivers/pwm/core.c (revision 705c09bb3cdffb141986598ad4ff9c9b0a66c3bd)
1 // SPDX-License-Identifier: GPL-2.0-or-later
2 /*
3  * Generic pwmlib implementation
4  *
5  * Copyright (C) 2011 Sascha Hauer <s.hauer@pengutronix.de>
6  * Copyright (C) 2011-2012 Avionic Design GmbH
7  */
8 
9 #include <linux/acpi.h>
10 #include <linux/module.h>
11 #include <linux/idr.h>
12 #include <linux/of.h>
13 #include <linux/pwm.h>
14 #include <linux/list.h>
15 #include <linux/mutex.h>
16 #include <linux/err.h>
17 #include <linux/slab.h>
18 #include <linux/device.h>
19 #include <linux/debugfs.h>
20 #include <linux/seq_file.h>
21 
22 #include <dt-bindings/pwm/pwm.h>
23 
24 #define CREATE_TRACE_POINTS
25 #include <trace/events/pwm.h>
26 
27 /* protects access to pwm_chips */
28 static DEFINE_MUTEX(pwm_lock);
29 
30 static DEFINE_IDR(pwm_chips);
31 
32 static void pwm_apply_debug(struct pwm_device *pwm,
33 			    const struct pwm_state *state)
34 {
35 	struct pwm_state *last = &pwm->last;
36 	struct pwm_chip *chip = pwm->chip;
37 	struct pwm_state s1 = { 0 }, s2 = { 0 };
38 	int err;
39 
40 	if (!IS_ENABLED(CONFIG_PWM_DEBUG))
41 		return;
42 
43 	/* No reasonable diagnosis possible without .get_state() */
44 	if (!chip->ops->get_state)
45 		return;
46 
47 	/*
48 	 * *state was just applied. Read out the hardware state and do some
49 	 * checks.
50 	 */
51 
52 	err = chip->ops->get_state(chip, pwm, &s1);
53 	trace_pwm_get(pwm, &s1, err);
54 	if (err)
55 		/* If that failed there isn't much to debug */
56 		return;
57 
58 	/*
59 	 * The lowlevel driver either ignored .polarity (which is a bug) or as
60 	 * best effort inverted .polarity and fixed .duty_cycle respectively.
61 	 * Undo this inversion and fixup for further tests.
62 	 */
63 	if (s1.enabled && s1.polarity != state->polarity) {
64 		s2.polarity = state->polarity;
65 		s2.duty_cycle = s1.period - s1.duty_cycle;
66 		s2.period = s1.period;
67 		s2.enabled = s1.enabled;
68 	} else {
69 		s2 = s1;
70 	}
71 
72 	if (s2.polarity != state->polarity &&
73 	    state->duty_cycle < state->period)
74 		dev_warn(pwmchip_parent(chip), ".apply ignored .polarity\n");
75 
76 	if (state->enabled &&
77 	    last->polarity == state->polarity &&
78 	    last->period > s2.period &&
79 	    last->period <= state->period)
80 		dev_warn(pwmchip_parent(chip),
81 			 ".apply didn't pick the best available period (requested: %llu, applied: %llu, possible: %llu)\n",
82 			 state->period, s2.period, last->period);
83 
84 	if (state->enabled && state->period < s2.period)
85 		dev_warn(pwmchip_parent(chip),
86 			 ".apply is supposed to round down period (requested: %llu, applied: %llu)\n",
87 			 state->period, s2.period);
88 
89 	if (state->enabled &&
90 	    last->polarity == state->polarity &&
91 	    last->period == s2.period &&
92 	    last->duty_cycle > s2.duty_cycle &&
93 	    last->duty_cycle <= state->duty_cycle)
94 		dev_warn(pwmchip_parent(chip),
95 			 ".apply didn't pick the best available duty cycle (requested: %llu/%llu, applied: %llu/%llu, possible: %llu/%llu)\n",
96 			 state->duty_cycle, state->period,
97 			 s2.duty_cycle, s2.period,
98 			 last->duty_cycle, last->period);
99 
100 	if (state->enabled && state->duty_cycle < s2.duty_cycle)
101 		dev_warn(pwmchip_parent(chip),
102 			 ".apply is supposed to round down duty_cycle (requested: %llu/%llu, applied: %llu/%llu)\n",
103 			 state->duty_cycle, state->period,
104 			 s2.duty_cycle, s2.period);
105 
106 	if (!state->enabled && s2.enabled && s2.duty_cycle > 0)
107 		dev_warn(pwmchip_parent(chip),
108 			 "requested disabled, but yielded enabled with duty > 0\n");
109 
110 	/* reapply the state that the driver reported being configured. */
111 	err = chip->ops->apply(chip, pwm, &s1);
112 	trace_pwm_apply(pwm, &s1, err);
113 	if (err) {
114 		*last = s1;
115 		dev_err(pwmchip_parent(chip), "failed to reapply current setting\n");
116 		return;
117 	}
118 
119 	*last = (struct pwm_state){ 0 };
120 	err = chip->ops->get_state(chip, pwm, last);
121 	trace_pwm_get(pwm, last, err);
122 	if (err)
123 		return;
124 
125 	/* reapplication of the current state should give an exact match */
126 	if (s1.enabled != last->enabled ||
127 	    s1.polarity != last->polarity ||
128 	    (s1.enabled && s1.period != last->period) ||
129 	    (s1.enabled && s1.duty_cycle != last->duty_cycle)) {
130 		dev_err(pwmchip_parent(chip),
131 			".apply is not idempotent (ena=%d pol=%d %llu/%llu) -> (ena=%d pol=%d %llu/%llu)\n",
132 			s1.enabled, s1.polarity, s1.duty_cycle, s1.period,
133 			last->enabled, last->polarity, last->duty_cycle,
134 			last->period);
135 	}
136 }
137 
138 /**
139  * __pwm_apply() - atomically apply a new state to a PWM device
140  * @pwm: PWM device
141  * @state: new state to apply
142  */
143 static int __pwm_apply(struct pwm_device *pwm, const struct pwm_state *state)
144 {
145 	struct pwm_chip *chip;
146 	int err;
147 
148 	if (!pwm || !state || !state->period ||
149 	    state->duty_cycle > state->period)
150 		return -EINVAL;
151 
152 	chip = pwm->chip;
153 
154 	if (state->period == pwm->state.period &&
155 	    state->duty_cycle == pwm->state.duty_cycle &&
156 	    state->polarity == pwm->state.polarity &&
157 	    state->enabled == pwm->state.enabled &&
158 	    state->usage_power == pwm->state.usage_power)
159 		return 0;
160 
161 	err = chip->ops->apply(chip, pwm, state);
162 	trace_pwm_apply(pwm, state, err);
163 	if (err)
164 		return err;
165 
166 	pwm->state = *state;
167 
168 	/*
169 	 * only do this after pwm->state was applied as some
170 	 * implementations of .get_state depend on this
171 	 */
172 	pwm_apply_debug(pwm, state);
173 
174 	return 0;
175 }
176 
177 /**
178  * pwm_apply_might_sleep() - atomically apply a new state to a PWM device
179  * Cannot be used in atomic context.
180  * @pwm: PWM device
181  * @state: new state to apply
182  */
183 int pwm_apply_might_sleep(struct pwm_device *pwm, const struct pwm_state *state)
184 {
185 	int err;
186 
187 	/*
188 	 * Some lowlevel driver's implementations of .apply() make use of
189 	 * mutexes, also with some drivers only returning when the new
190 	 * configuration is active calling pwm_apply_might_sleep() from atomic context
191 	 * is a bad idea. So make it explicit that calling this function might
192 	 * sleep.
193 	 */
194 	might_sleep();
195 
196 	if (IS_ENABLED(CONFIG_PWM_DEBUG) && pwm->chip->atomic) {
197 		/*
198 		 * Catch any drivers that have been marked as atomic but
199 		 * that will sleep anyway.
200 		 */
201 		non_block_start();
202 		err = __pwm_apply(pwm, state);
203 		non_block_end();
204 	} else {
205 		err = __pwm_apply(pwm, state);
206 	}
207 
208 	return err;
209 }
210 EXPORT_SYMBOL_GPL(pwm_apply_might_sleep);
211 
212 /**
213  * pwm_apply_atomic() - apply a new state to a PWM device from atomic context
214  * Not all PWM devices support this function, check with pwm_might_sleep().
215  * @pwm: PWM device
216  * @state: new state to apply
217  */
218 int pwm_apply_atomic(struct pwm_device *pwm, const struct pwm_state *state)
219 {
220 	WARN_ONCE(!pwm->chip->atomic,
221 		  "sleeping PWM driver used in atomic context\n");
222 
223 	return __pwm_apply(pwm, state);
224 }
225 EXPORT_SYMBOL_GPL(pwm_apply_atomic);
226 
227 /**
228  * pwm_adjust_config() - adjust the current PWM config to the PWM arguments
229  * @pwm: PWM device
230  *
231  * This function will adjust the PWM config to the PWM arguments provided
232  * by the DT or PWM lookup table. This is particularly useful to adapt
233  * the bootloader config to the Linux one.
234  */
235 int pwm_adjust_config(struct pwm_device *pwm)
236 {
237 	struct pwm_state state;
238 	struct pwm_args pargs;
239 
240 	pwm_get_args(pwm, &pargs);
241 	pwm_get_state(pwm, &state);
242 
243 	/*
244 	 * If the current period is zero it means that either the PWM driver
245 	 * does not support initial state retrieval or the PWM has not yet
246 	 * been configured.
247 	 *
248 	 * In either case, we setup the new period and polarity, and assign a
249 	 * duty cycle of 0.
250 	 */
251 	if (!state.period) {
252 		state.duty_cycle = 0;
253 		state.period = pargs.period;
254 		state.polarity = pargs.polarity;
255 
256 		return pwm_apply_might_sleep(pwm, &state);
257 	}
258 
259 	/*
260 	 * Adjust the PWM duty cycle/period based on the period value provided
261 	 * in PWM args.
262 	 */
263 	if (pargs.period != state.period) {
264 		u64 dutycycle = (u64)state.duty_cycle * pargs.period;
265 
266 		do_div(dutycycle, state.period);
267 		state.duty_cycle = dutycycle;
268 		state.period = pargs.period;
269 	}
270 
271 	/*
272 	 * If the polarity changed, we should also change the duty cycle.
273 	 */
274 	if (pargs.polarity != state.polarity) {
275 		state.polarity = pargs.polarity;
276 		state.duty_cycle = state.period - state.duty_cycle;
277 	}
278 
279 	return pwm_apply_might_sleep(pwm, &state);
280 }
281 EXPORT_SYMBOL_GPL(pwm_adjust_config);
282 
283 /**
284  * pwm_capture() - capture and report a PWM signal
285  * @pwm: PWM device
286  * @result: structure to fill with capture result
287  * @timeout: time to wait, in milliseconds, before giving up on capture
288  *
289  * Returns: 0 on success or a negative error code on failure.
290  */
291 int pwm_capture(struct pwm_device *pwm, struct pwm_capture *result,
292 		unsigned long timeout)
293 {
294 	int err;
295 
296 	if (!pwm || !pwm->chip->ops)
297 		return -EINVAL;
298 
299 	if (!pwm->chip->ops->capture)
300 		return -ENOSYS;
301 
302 	mutex_lock(&pwm_lock);
303 	err = pwm->chip->ops->capture(pwm->chip, pwm, result, timeout);
304 	mutex_unlock(&pwm_lock);
305 
306 	return err;
307 }
308 EXPORT_SYMBOL_GPL(pwm_capture);
309 
310 static struct pwm_chip *pwmchip_find_by_name(const char *name)
311 {
312 	struct pwm_chip *chip;
313 	unsigned long id, tmp;
314 
315 	if (!name)
316 		return NULL;
317 
318 	mutex_lock(&pwm_lock);
319 
320 	idr_for_each_entry_ul(&pwm_chips, chip, tmp, id) {
321 		const char *chip_name = dev_name(pwmchip_parent(chip));
322 
323 		if (chip_name && strcmp(chip_name, name) == 0) {
324 			mutex_unlock(&pwm_lock);
325 			return chip;
326 		}
327 	}
328 
329 	mutex_unlock(&pwm_lock);
330 
331 	return NULL;
332 }
333 
334 static int pwm_device_request(struct pwm_device *pwm, const char *label)
335 {
336 	int err;
337 	struct pwm_chip *chip = pwm->chip;
338 	const struct pwm_ops *ops = chip->ops;
339 
340 	if (test_bit(PWMF_REQUESTED, &pwm->flags))
341 		return -EBUSY;
342 
343 	if (!try_module_get(chip->owner))
344 		return -ENODEV;
345 
346 	if (ops->request) {
347 		err = ops->request(chip, pwm);
348 		if (err) {
349 			module_put(chip->owner);
350 			return err;
351 		}
352 	}
353 
354 	if (ops->get_state) {
355 		/*
356 		 * Zero-initialize state because most drivers are unaware of
357 		 * .usage_power. The other members of state are supposed to be
358 		 * set by lowlevel drivers. We still initialize the whole
359 		 * structure for simplicity even though this might paper over
360 		 * faulty implementations of .get_state().
361 		 */
362 		struct pwm_state state = { 0, };
363 
364 		err = ops->get_state(chip, pwm, &state);
365 		trace_pwm_get(pwm, &state, err);
366 
367 		if (!err)
368 			pwm->state = state;
369 
370 		if (IS_ENABLED(CONFIG_PWM_DEBUG))
371 			pwm->last = pwm->state;
372 	}
373 
374 	set_bit(PWMF_REQUESTED, &pwm->flags);
375 	pwm->label = label;
376 
377 	return 0;
378 }
379 
380 /**
381  * pwm_request_from_chip() - request a PWM device relative to a PWM chip
382  * @chip: PWM chip
383  * @index: per-chip index of the PWM to request
384  * @label: a literal description string of this PWM
385  *
386  * Returns: A pointer to the PWM device at the given index of the given PWM
387  * chip. A negative error code is returned if the index is not valid for the
388  * specified PWM chip or if the PWM device cannot be requested.
389  */
390 struct pwm_device *pwm_request_from_chip(struct pwm_chip *chip,
391 					 unsigned int index,
392 					 const char *label)
393 {
394 	struct pwm_device *pwm;
395 	int err;
396 
397 	if (!chip || index >= chip->npwm)
398 		return ERR_PTR(-EINVAL);
399 
400 	mutex_lock(&pwm_lock);
401 	pwm = &chip->pwms[index];
402 
403 	err = pwm_device_request(pwm, label);
404 	if (err < 0)
405 		pwm = ERR_PTR(err);
406 
407 	mutex_unlock(&pwm_lock);
408 	return pwm;
409 }
410 EXPORT_SYMBOL_GPL(pwm_request_from_chip);
411 
412 
413 struct pwm_device *
414 of_pwm_xlate_with_flags(struct pwm_chip *chip, const struct of_phandle_args *args)
415 {
416 	struct pwm_device *pwm;
417 
418 	/* period in the second cell and flags in the third cell are optional */
419 	if (args->args_count < 1)
420 		return ERR_PTR(-EINVAL);
421 
422 	pwm = pwm_request_from_chip(chip, args->args[0], NULL);
423 	if (IS_ERR(pwm))
424 		return pwm;
425 
426 	if (args->args_count > 1)
427 		pwm->args.period = args->args[1];
428 
429 	pwm->args.polarity = PWM_POLARITY_NORMAL;
430 	if (args->args_count > 2 && args->args[2] & PWM_POLARITY_INVERTED)
431 		pwm->args.polarity = PWM_POLARITY_INVERSED;
432 
433 	return pwm;
434 }
435 EXPORT_SYMBOL_GPL(of_pwm_xlate_with_flags);
436 
437 struct pwm_device *
438 of_pwm_single_xlate(struct pwm_chip *chip, const struct of_phandle_args *args)
439 {
440 	struct pwm_device *pwm;
441 
442 	pwm = pwm_request_from_chip(chip, 0, NULL);
443 	if (IS_ERR(pwm))
444 		return pwm;
445 
446 	if (args->args_count > 1)
447 		pwm->args.period = args->args[0];
448 
449 	pwm->args.polarity = PWM_POLARITY_NORMAL;
450 	if (args->args_count > 1 && args->args[1] & PWM_POLARITY_INVERTED)
451 		pwm->args.polarity = PWM_POLARITY_INVERSED;
452 
453 	return pwm;
454 }
455 EXPORT_SYMBOL_GPL(of_pwm_single_xlate);
456 
457 #define PWMCHIP_ALIGN ARCH_DMA_MINALIGN
458 
459 static void *pwmchip_priv(struct pwm_chip *chip)
460 {
461 	return (void *)chip + ALIGN(sizeof(*chip), PWMCHIP_ALIGN);
462 }
463 
464 /* This is the counterpart to pwmchip_alloc() */
465 void pwmchip_put(struct pwm_chip *chip)
466 {
467 	kfree(chip);
468 }
469 EXPORT_SYMBOL_GPL(pwmchip_put);
470 
471 struct pwm_chip *pwmchip_alloc(struct device *parent, unsigned int npwm, size_t sizeof_priv)
472 {
473 	struct pwm_chip *chip;
474 	size_t alloc_size;
475 
476 	alloc_size = size_add(ALIGN(sizeof(*chip), PWMCHIP_ALIGN), sizeof_priv);
477 
478 	chip = kzalloc(alloc_size, GFP_KERNEL);
479 	if (!chip)
480 		return ERR_PTR(-ENOMEM);
481 
482 	chip->dev = parent;
483 	chip->npwm = npwm;
484 
485 	pwmchip_set_drvdata(chip, pwmchip_priv(chip));
486 
487 	return chip;
488 }
489 EXPORT_SYMBOL_GPL(pwmchip_alloc);
490 
491 static void devm_pwmchip_put(void *data)
492 {
493 	struct pwm_chip *chip = data;
494 
495 	pwmchip_put(chip);
496 }
497 
498 struct pwm_chip *devm_pwmchip_alloc(struct device *parent, unsigned int npwm, size_t sizeof_priv)
499 {
500 	struct pwm_chip *chip;
501 	int ret;
502 
503 	chip = pwmchip_alloc(parent, npwm, sizeof_priv);
504 	if (IS_ERR(chip))
505 		return chip;
506 
507 	ret = devm_add_action_or_reset(parent, devm_pwmchip_put, chip);
508 	if (ret)
509 		return ERR_PTR(ret);
510 
511 	return chip;
512 }
513 EXPORT_SYMBOL_GPL(devm_pwmchip_alloc);
514 
515 static void of_pwmchip_add(struct pwm_chip *chip)
516 {
517 	if (!pwmchip_parent(chip) || !pwmchip_parent(chip)->of_node)
518 		return;
519 
520 	if (!chip->of_xlate)
521 		chip->of_xlate = of_pwm_xlate_with_flags;
522 
523 	of_node_get(pwmchip_parent(chip)->of_node);
524 }
525 
526 static void of_pwmchip_remove(struct pwm_chip *chip)
527 {
528 	if (pwmchip_parent(chip))
529 		of_node_put(pwmchip_parent(chip)->of_node);
530 }
531 
532 static bool pwm_ops_check(const struct pwm_chip *chip)
533 {
534 	const struct pwm_ops *ops = chip->ops;
535 
536 	if (!ops->apply)
537 		return false;
538 
539 	if (IS_ENABLED(CONFIG_PWM_DEBUG) && !ops->get_state)
540 		dev_warn(pwmchip_parent(chip),
541 			 "Please implement the .get_state() callback\n");
542 
543 	return true;
544 }
545 
546 /**
547  * __pwmchip_add() - register a new PWM chip
548  * @chip: the PWM chip to add
549  * @owner: reference to the module providing the chip.
550  *
551  * Register a new PWM chip. @owner is supposed to be THIS_MODULE, use the
552  * pwmchip_add wrapper to do this right.
553  *
554  * Returns: 0 on success or a negative error code on failure.
555  */
556 int __pwmchip_add(struct pwm_chip *chip, struct module *owner)
557 {
558 	unsigned int i;
559 	int ret;
560 
561 	if (!chip || !pwmchip_parent(chip) || !chip->ops || !chip->npwm)
562 		return -EINVAL;
563 
564 	if (!pwm_ops_check(chip))
565 		return -EINVAL;
566 
567 	chip->owner = owner;
568 
569 	chip->pwms = kcalloc(chip->npwm, sizeof(*chip->pwms), GFP_KERNEL);
570 	if (!chip->pwms)
571 		return -ENOMEM;
572 
573 	mutex_lock(&pwm_lock);
574 
575 	ret = idr_alloc(&pwm_chips, chip, 0, 0, GFP_KERNEL);
576 	if (ret < 0) {
577 		mutex_unlock(&pwm_lock);
578 		kfree(chip->pwms);
579 		return ret;
580 	}
581 
582 	chip->id = ret;
583 
584 	for (i = 0; i < chip->npwm; i++) {
585 		struct pwm_device *pwm = &chip->pwms[i];
586 
587 		pwm->chip = chip;
588 		pwm->hwpwm = i;
589 	}
590 
591 	mutex_unlock(&pwm_lock);
592 
593 	if (IS_ENABLED(CONFIG_OF))
594 		of_pwmchip_add(chip);
595 
596 	pwmchip_sysfs_export(chip);
597 
598 	return 0;
599 }
600 EXPORT_SYMBOL_GPL(__pwmchip_add);
601 
602 /**
603  * pwmchip_remove() - remove a PWM chip
604  * @chip: the PWM chip to remove
605  *
606  * Removes a PWM chip.
607  */
608 void pwmchip_remove(struct pwm_chip *chip)
609 {
610 	pwmchip_sysfs_unexport(chip);
611 
612 	if (IS_ENABLED(CONFIG_OF))
613 		of_pwmchip_remove(chip);
614 
615 	mutex_lock(&pwm_lock);
616 
617 	idr_remove(&pwm_chips, chip->id);
618 
619 	mutex_unlock(&pwm_lock);
620 
621 	kfree(chip->pwms);
622 }
623 EXPORT_SYMBOL_GPL(pwmchip_remove);
624 
625 static void devm_pwmchip_remove(void *data)
626 {
627 	struct pwm_chip *chip = data;
628 
629 	pwmchip_remove(chip);
630 }
631 
632 int __devm_pwmchip_add(struct device *dev, struct pwm_chip *chip, struct module *owner)
633 {
634 	int ret;
635 
636 	ret = __pwmchip_add(chip, owner);
637 	if (ret)
638 		return ret;
639 
640 	return devm_add_action_or_reset(dev, devm_pwmchip_remove, chip);
641 }
642 EXPORT_SYMBOL_GPL(__devm_pwmchip_add);
643 
644 static struct device_link *pwm_device_link_add(struct device *dev,
645 					       struct pwm_device *pwm)
646 {
647 	struct device_link *dl;
648 
649 	if (!dev) {
650 		/*
651 		 * No device for the PWM consumer has been provided. It may
652 		 * impact the PM sequence ordering: the PWM supplier may get
653 		 * suspended before the consumer.
654 		 */
655 		dev_warn(pwmchip_parent(pwm->chip),
656 			 "No consumer device specified to create a link to\n");
657 		return NULL;
658 	}
659 
660 	dl = device_link_add(dev, pwmchip_parent(pwm->chip), DL_FLAG_AUTOREMOVE_CONSUMER);
661 	if (!dl) {
662 		dev_err(dev, "failed to create device link to %s\n",
663 			dev_name(pwmchip_parent(pwm->chip)));
664 		return ERR_PTR(-EINVAL);
665 	}
666 
667 	return dl;
668 }
669 
670 static struct pwm_chip *fwnode_to_pwmchip(struct fwnode_handle *fwnode)
671 {
672 	struct pwm_chip *chip;
673 	unsigned long id, tmp;
674 
675 	mutex_lock(&pwm_lock);
676 
677 	idr_for_each_entry_ul(&pwm_chips, chip, tmp, id)
678 		if (pwmchip_parent(chip) && device_match_fwnode(pwmchip_parent(chip), fwnode)) {
679 			mutex_unlock(&pwm_lock);
680 			return chip;
681 		}
682 
683 	mutex_unlock(&pwm_lock);
684 
685 	return ERR_PTR(-EPROBE_DEFER);
686 }
687 
688 /**
689  * of_pwm_get() - request a PWM via the PWM framework
690  * @dev: device for PWM consumer
691  * @np: device node to get the PWM from
692  * @con_id: consumer name
693  *
694  * Returns the PWM device parsed from the phandle and index specified in the
695  * "pwms" property of a device tree node or a negative error-code on failure.
696  * Values parsed from the device tree are stored in the returned PWM device
697  * object.
698  *
699  * If con_id is NULL, the first PWM device listed in the "pwms" property will
700  * be requested. Otherwise the "pwm-names" property is used to do a reverse
701  * lookup of the PWM index. This also means that the "pwm-names" property
702  * becomes mandatory for devices that look up the PWM device via the con_id
703  * parameter.
704  *
705  * Returns: A pointer to the requested PWM device or an ERR_PTR()-encoded
706  * error code on failure.
707  */
708 static struct pwm_device *of_pwm_get(struct device *dev, struct device_node *np,
709 				     const char *con_id)
710 {
711 	struct pwm_device *pwm = NULL;
712 	struct of_phandle_args args;
713 	struct device_link *dl;
714 	struct pwm_chip *chip;
715 	int index = 0;
716 	int err;
717 
718 	if (con_id) {
719 		index = of_property_match_string(np, "pwm-names", con_id);
720 		if (index < 0)
721 			return ERR_PTR(index);
722 	}
723 
724 	err = of_parse_phandle_with_args(np, "pwms", "#pwm-cells", index,
725 					 &args);
726 	if (err) {
727 		pr_err("%s(): can't parse \"pwms\" property\n", __func__);
728 		return ERR_PTR(err);
729 	}
730 
731 	chip = fwnode_to_pwmchip(of_fwnode_handle(args.np));
732 	if (IS_ERR(chip)) {
733 		if (PTR_ERR(chip) != -EPROBE_DEFER)
734 			pr_err("%s(): PWM chip not found\n", __func__);
735 
736 		pwm = ERR_CAST(chip);
737 		goto put;
738 	}
739 
740 	pwm = chip->of_xlate(chip, &args);
741 	if (IS_ERR(pwm))
742 		goto put;
743 
744 	dl = pwm_device_link_add(dev, pwm);
745 	if (IS_ERR(dl)) {
746 		/* of_xlate ended up calling pwm_request_from_chip() */
747 		pwm_put(pwm);
748 		pwm = ERR_CAST(dl);
749 		goto put;
750 	}
751 
752 	/*
753 	 * If a consumer name was not given, try to look it up from the
754 	 * "pwm-names" property if it exists. Otherwise use the name of
755 	 * the user device node.
756 	 */
757 	if (!con_id) {
758 		err = of_property_read_string_index(np, "pwm-names", index,
759 						    &con_id);
760 		if (err < 0)
761 			con_id = np->name;
762 	}
763 
764 	pwm->label = con_id;
765 
766 put:
767 	of_node_put(args.np);
768 
769 	return pwm;
770 }
771 
772 /**
773  * acpi_pwm_get() - request a PWM via parsing "pwms" property in ACPI
774  * @fwnode: firmware node to get the "pwms" property from
775  *
776  * Returns the PWM device parsed from the fwnode and index specified in the
777  * "pwms" property or a negative error-code on failure.
778  * Values parsed from the device tree are stored in the returned PWM device
779  * object.
780  *
781  * This is analogous to of_pwm_get() except con_id is not yet supported.
782  * ACPI entries must look like
783  * Package () {"pwms", Package ()
784  *     { <PWM device reference>, <PWM index>, <PWM period> [, <PWM flags>]}}
785  *
786  * Returns: A pointer to the requested PWM device or an ERR_PTR()-encoded
787  * error code on failure.
788  */
789 static struct pwm_device *acpi_pwm_get(const struct fwnode_handle *fwnode)
790 {
791 	struct pwm_device *pwm;
792 	struct fwnode_reference_args args;
793 	struct pwm_chip *chip;
794 	int ret;
795 
796 	memset(&args, 0, sizeof(args));
797 
798 	ret = __acpi_node_get_property_reference(fwnode, "pwms", 0, 3, &args);
799 	if (ret < 0)
800 		return ERR_PTR(ret);
801 
802 	if (args.nargs < 2)
803 		return ERR_PTR(-EPROTO);
804 
805 	chip = fwnode_to_pwmchip(args.fwnode);
806 	if (IS_ERR(chip))
807 		return ERR_CAST(chip);
808 
809 	pwm = pwm_request_from_chip(chip, args.args[0], NULL);
810 	if (IS_ERR(pwm))
811 		return pwm;
812 
813 	pwm->args.period = args.args[1];
814 	pwm->args.polarity = PWM_POLARITY_NORMAL;
815 
816 	if (args.nargs > 2 && args.args[2] & PWM_POLARITY_INVERTED)
817 		pwm->args.polarity = PWM_POLARITY_INVERSED;
818 
819 	return pwm;
820 }
821 
822 static DEFINE_MUTEX(pwm_lookup_lock);
823 static LIST_HEAD(pwm_lookup_list);
824 
825 /**
826  * pwm_add_table() - register PWM device consumers
827  * @table: array of consumers to register
828  * @num: number of consumers in table
829  */
830 void pwm_add_table(struct pwm_lookup *table, size_t num)
831 {
832 	mutex_lock(&pwm_lookup_lock);
833 
834 	while (num--) {
835 		list_add_tail(&table->list, &pwm_lookup_list);
836 		table++;
837 	}
838 
839 	mutex_unlock(&pwm_lookup_lock);
840 }
841 
842 /**
843  * pwm_remove_table() - unregister PWM device consumers
844  * @table: array of consumers to unregister
845  * @num: number of consumers in table
846  */
847 void pwm_remove_table(struct pwm_lookup *table, size_t num)
848 {
849 	mutex_lock(&pwm_lookup_lock);
850 
851 	while (num--) {
852 		list_del(&table->list);
853 		table++;
854 	}
855 
856 	mutex_unlock(&pwm_lookup_lock);
857 }
858 
859 /**
860  * pwm_get() - look up and request a PWM device
861  * @dev: device for PWM consumer
862  * @con_id: consumer name
863  *
864  * Lookup is first attempted using DT. If the device was not instantiated from
865  * a device tree, a PWM chip and a relative index is looked up via a table
866  * supplied by board setup code (see pwm_add_table()).
867  *
868  * Once a PWM chip has been found the specified PWM device will be requested
869  * and is ready to be used.
870  *
871  * Returns: A pointer to the requested PWM device or an ERR_PTR()-encoded
872  * error code on failure.
873  */
874 struct pwm_device *pwm_get(struct device *dev, const char *con_id)
875 {
876 	const struct fwnode_handle *fwnode = dev ? dev_fwnode(dev) : NULL;
877 	const char *dev_id = dev ? dev_name(dev) : NULL;
878 	struct pwm_device *pwm;
879 	struct pwm_chip *chip;
880 	struct device_link *dl;
881 	unsigned int best = 0;
882 	struct pwm_lookup *p, *chosen = NULL;
883 	unsigned int match;
884 	int err;
885 
886 	/* look up via DT first */
887 	if (is_of_node(fwnode))
888 		return of_pwm_get(dev, to_of_node(fwnode), con_id);
889 
890 	/* then lookup via ACPI */
891 	if (is_acpi_node(fwnode)) {
892 		pwm = acpi_pwm_get(fwnode);
893 		if (!IS_ERR(pwm) || PTR_ERR(pwm) != -ENOENT)
894 			return pwm;
895 	}
896 
897 	/*
898 	 * We look up the provider in the static table typically provided by
899 	 * board setup code. We first try to lookup the consumer device by
900 	 * name. If the consumer device was passed in as NULL or if no match
901 	 * was found, we try to find the consumer by directly looking it up
902 	 * by name.
903 	 *
904 	 * If a match is found, the provider PWM chip is looked up by name
905 	 * and a PWM device is requested using the PWM device per-chip index.
906 	 *
907 	 * The lookup algorithm was shamelessly taken from the clock
908 	 * framework:
909 	 *
910 	 * We do slightly fuzzy matching here:
911 	 *  An entry with a NULL ID is assumed to be a wildcard.
912 	 *  If an entry has a device ID, it must match
913 	 *  If an entry has a connection ID, it must match
914 	 * Then we take the most specific entry - with the following order
915 	 * of precedence: dev+con > dev only > con only.
916 	 */
917 	mutex_lock(&pwm_lookup_lock);
918 
919 	list_for_each_entry(p, &pwm_lookup_list, list) {
920 		match = 0;
921 
922 		if (p->dev_id) {
923 			if (!dev_id || strcmp(p->dev_id, dev_id))
924 				continue;
925 
926 			match += 2;
927 		}
928 
929 		if (p->con_id) {
930 			if (!con_id || strcmp(p->con_id, con_id))
931 				continue;
932 
933 			match += 1;
934 		}
935 
936 		if (match > best) {
937 			chosen = p;
938 
939 			if (match != 3)
940 				best = match;
941 			else
942 				break;
943 		}
944 	}
945 
946 	mutex_unlock(&pwm_lookup_lock);
947 
948 	if (!chosen)
949 		return ERR_PTR(-ENODEV);
950 
951 	chip = pwmchip_find_by_name(chosen->provider);
952 
953 	/*
954 	 * If the lookup entry specifies a module, load the module and retry
955 	 * the PWM chip lookup. This can be used to work around driver load
956 	 * ordering issues if driver's can't be made to properly support the
957 	 * deferred probe mechanism.
958 	 */
959 	if (!chip && chosen->module) {
960 		err = request_module(chosen->module);
961 		if (err == 0)
962 			chip = pwmchip_find_by_name(chosen->provider);
963 	}
964 
965 	if (!chip)
966 		return ERR_PTR(-EPROBE_DEFER);
967 
968 	pwm = pwm_request_from_chip(chip, chosen->index, con_id ?: dev_id);
969 	if (IS_ERR(pwm))
970 		return pwm;
971 
972 	dl = pwm_device_link_add(dev, pwm);
973 	if (IS_ERR(dl)) {
974 		pwm_put(pwm);
975 		return ERR_CAST(dl);
976 	}
977 
978 	pwm->args.period = chosen->period;
979 	pwm->args.polarity = chosen->polarity;
980 
981 	return pwm;
982 }
983 EXPORT_SYMBOL_GPL(pwm_get);
984 
985 /**
986  * pwm_put() - release a PWM device
987  * @pwm: PWM device
988  */
989 void pwm_put(struct pwm_device *pwm)
990 {
991 	if (!pwm)
992 		return;
993 
994 	mutex_lock(&pwm_lock);
995 
996 	if (!test_and_clear_bit(PWMF_REQUESTED, &pwm->flags)) {
997 		pr_warn("PWM device already freed\n");
998 		goto out;
999 	}
1000 
1001 	if (pwm->chip->ops->free)
1002 		pwm->chip->ops->free(pwm->chip, pwm);
1003 
1004 	pwm->label = NULL;
1005 
1006 	module_put(pwm->chip->owner);
1007 out:
1008 	mutex_unlock(&pwm_lock);
1009 }
1010 EXPORT_SYMBOL_GPL(pwm_put);
1011 
1012 static void devm_pwm_release(void *pwm)
1013 {
1014 	pwm_put(pwm);
1015 }
1016 
1017 /**
1018  * devm_pwm_get() - resource managed pwm_get()
1019  * @dev: device for PWM consumer
1020  * @con_id: consumer name
1021  *
1022  * This function performs like pwm_get() but the acquired PWM device will
1023  * automatically be released on driver detach.
1024  *
1025  * Returns: A pointer to the requested PWM device or an ERR_PTR()-encoded
1026  * error code on failure.
1027  */
1028 struct pwm_device *devm_pwm_get(struct device *dev, const char *con_id)
1029 {
1030 	struct pwm_device *pwm;
1031 	int ret;
1032 
1033 	pwm = pwm_get(dev, con_id);
1034 	if (IS_ERR(pwm))
1035 		return pwm;
1036 
1037 	ret = devm_add_action_or_reset(dev, devm_pwm_release, pwm);
1038 	if (ret)
1039 		return ERR_PTR(ret);
1040 
1041 	return pwm;
1042 }
1043 EXPORT_SYMBOL_GPL(devm_pwm_get);
1044 
1045 /**
1046  * devm_fwnode_pwm_get() - request a resource managed PWM from firmware node
1047  * @dev: device for PWM consumer
1048  * @fwnode: firmware node to get the PWM from
1049  * @con_id: consumer name
1050  *
1051  * Returns the PWM device parsed from the firmware node. See of_pwm_get() and
1052  * acpi_pwm_get() for a detailed description.
1053  *
1054  * Returns: A pointer to the requested PWM device or an ERR_PTR()-encoded
1055  * error code on failure.
1056  */
1057 struct pwm_device *devm_fwnode_pwm_get(struct device *dev,
1058 				       struct fwnode_handle *fwnode,
1059 				       const char *con_id)
1060 {
1061 	struct pwm_device *pwm = ERR_PTR(-ENODEV);
1062 	int ret;
1063 
1064 	if (is_of_node(fwnode))
1065 		pwm = of_pwm_get(dev, to_of_node(fwnode), con_id);
1066 	else if (is_acpi_node(fwnode))
1067 		pwm = acpi_pwm_get(fwnode);
1068 	if (IS_ERR(pwm))
1069 		return pwm;
1070 
1071 	ret = devm_add_action_or_reset(dev, devm_pwm_release, pwm);
1072 	if (ret)
1073 		return ERR_PTR(ret);
1074 
1075 	return pwm;
1076 }
1077 EXPORT_SYMBOL_GPL(devm_fwnode_pwm_get);
1078 
1079 #ifdef CONFIG_DEBUG_FS
1080 static void pwm_dbg_show(struct pwm_chip *chip, struct seq_file *s)
1081 {
1082 	unsigned int i;
1083 
1084 	for (i = 0; i < chip->npwm; i++) {
1085 		struct pwm_device *pwm = &chip->pwms[i];
1086 		struct pwm_state state;
1087 
1088 		pwm_get_state(pwm, &state);
1089 
1090 		seq_printf(s, " pwm-%-3d (%-20.20s):", i, pwm->label);
1091 
1092 		if (test_bit(PWMF_REQUESTED, &pwm->flags))
1093 			seq_puts(s, " requested");
1094 
1095 		if (state.enabled)
1096 			seq_puts(s, " enabled");
1097 
1098 		seq_printf(s, " period: %llu ns", state.period);
1099 		seq_printf(s, " duty: %llu ns", state.duty_cycle);
1100 		seq_printf(s, " polarity: %s",
1101 			   state.polarity ? "inverse" : "normal");
1102 
1103 		if (state.usage_power)
1104 			seq_puts(s, " usage_power");
1105 
1106 		seq_puts(s, "\n");
1107 	}
1108 }
1109 
1110 static void *pwm_seq_start(struct seq_file *s, loff_t *pos)
1111 {
1112 	unsigned long id = *pos;
1113 	void *ret;
1114 
1115 	mutex_lock(&pwm_lock);
1116 	s->private = "";
1117 
1118 	ret = idr_get_next_ul(&pwm_chips, &id);
1119 	*pos = id;
1120 	return ret;
1121 }
1122 
1123 static void *pwm_seq_next(struct seq_file *s, void *v, loff_t *pos)
1124 {
1125 	unsigned long id = *pos + 1;
1126 	void *ret;
1127 
1128 	s->private = "\n";
1129 
1130 	ret = idr_get_next_ul(&pwm_chips, &id);
1131 	*pos = id;
1132 	return ret;
1133 }
1134 
1135 static void pwm_seq_stop(struct seq_file *s, void *v)
1136 {
1137 	mutex_unlock(&pwm_lock);
1138 }
1139 
1140 static int pwm_seq_show(struct seq_file *s, void *v)
1141 {
1142 	struct pwm_chip *chip = v;
1143 
1144 	seq_printf(s, "%s%d: %s/%s, %d PWM device%s\n",
1145 		   (char *)s->private, chip->id,
1146 		   pwmchip_parent(chip)->bus ? pwmchip_parent(chip)->bus->name : "no-bus",
1147 		   dev_name(pwmchip_parent(chip)), chip->npwm,
1148 		   (chip->npwm != 1) ? "s" : "");
1149 
1150 	pwm_dbg_show(chip, s);
1151 
1152 	return 0;
1153 }
1154 
1155 static const struct seq_operations pwm_debugfs_sops = {
1156 	.start = pwm_seq_start,
1157 	.next = pwm_seq_next,
1158 	.stop = pwm_seq_stop,
1159 	.show = pwm_seq_show,
1160 };
1161 
1162 DEFINE_SEQ_ATTRIBUTE(pwm_debugfs);
1163 
1164 static int __init pwm_debugfs_init(void)
1165 {
1166 	debugfs_create_file("pwm", 0444, NULL, NULL, &pwm_debugfs_fops);
1167 
1168 	return 0;
1169 }
1170 subsys_initcall(pwm_debugfs_init);
1171 #endif /* CONFIG_DEBUG_FS */
1172