pwm.h 17 KB

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