include/linux/pwm.h

   1 #ifndef __LINUX_PWM_H
   2 #define __LINUX_PWM_H
   3
   4 #include <linux/err.h>
   5 #include <linux/mutex.h>
   6 #include <linux/of.h>
   7
   8 struct seq_file;
   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         unsigned int 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  */
  55 struct pwm_state {
  56         unsigned int period;
  57         unsigned int duty_cycle;
  58         enum pwm_polarity polarity;
  59         bool enabled;
  60 };
  61
  62 /**
  63  * struct pwm_device - PWM channel object
  64  * @label: name of the PWM device
  65  * @flags: flags associated with the PWM device
  66  * @hwpwm: per-chip relative index of the PWM device
  67  * @pwm: global index of the PWM device
  68  * @chip: PWM chip providing this PWM device
  69  * @chip_data: chip-private data associated with the PWM device
  70  * @args: PWM arguments
  71  * @state: curent PWM channel state
  72  */
  73 struct pwm_device {
  74         const char *label;
  75         unsigned long flags;
  76         unsigned int hwpwm;
  77         unsigned int pwm;
  78         struct pwm_chip *chip;
  79         void *chip_data;
  80
  81         struct pwm_args args;
  82         struct pwm_state state;
  83 };
  84
  85 /**
  86  * pwm_get_state() - retrieve the current PWM state
  87  * @pwm: PWM device
  88  * @state: state to fill with the current PWM state
  89  */
  90 static inline void pwm_get_state(const struct pwm_device *pwm,
  91                                  struct pwm_state *state)
  92 {
  93         *state = pwm->state;
  94 }
  95
  96 static inline bool pwm_is_enabled(const struct pwm_device *pwm)
  97 {
  98         struct pwm_state state;
  99
 100         pwm_get_state(pwm, &state);
 101
 102         return state.enabled;
 103 }
 104
 105 static inline void pwm_set_period(struct pwm_device *pwm, unsigned int period)
 106 {
 107         if (pwm)
 108                 pwm->state.period = period;
 109 }
 110
 111 static inline unsigned int pwm_get_period(const struct pwm_device *pwm)
 112 {
 113         struct pwm_state state;
 114
 115         pwm_get_state(pwm, &state);
 116
 117         return state.period;
 118 }
 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
 126 static inline unsigned int pwm_get_duty_cycle(const struct pwm_device *pwm)
 127 {
 128         struct pwm_state state;
 129
 130         pwm_get_state(pwm, &state);
 131
 132         return state.duty_cycle;
 133 }
 134
 135 static inline enum pwm_polarity pwm_get_polarity(const struct pwm_device *pwm)
 136 {
 137         struct pwm_state state;
 138
 139         pwm_get_state(pwm, &state);
 140
 141         return state.polarity;
 142 }
 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 /**
 151  * struct pwm_ops - PWM controller operations
 152  * @request: optional hook for requesting a PWM
 153  * @free: optional hook for freeing a PWM
 154  * @config: configure duty cycles and period length for this PWM
 155  * @set_polarity: configure the polarity of this PWM
 156  * @enable: enable PWM output toggling
 157  * @disable: disable PWM output toggling
 158  * @apply: atomically apply a new PWM config. The state argument
 159  *         should be adjusted with the real hardware config (if the
 160  *         approximate the period or duty_cycle value, state should
 161  *         reflect it)
 162  * @get_state: get the current PWM state. This function is only
 163  *             called once per PWM device when the PWM chip is
 164  *             registered.
 165  * @dbg_show: optional routine to show contents in debugfs
 166  * @owner: helps prevent removal of modules exporting active PWMs
 167  */
 168 struct pwm_ops {
 169         int (*request)(struct pwm_chip *chip, struct pwm_device *pwm);
 170         void (*free)(struct pwm_chip *chip, struct pwm_device *pwm);
 171         int (*config)(struct pwm_chip *chip, struct pwm_device *pwm,
 172                       int duty_ns, int period_ns);
 173         int (*set_polarity)(struct pwm_chip *chip, struct pwm_device *pwm,
 174                             enum pwm_polarity polarity);
 175         int (*enable)(struct pwm_chip *chip, struct pwm_device *pwm);
 176         void (*disable)(struct pwm_chip *chip, struct pwm_device *pwm);
 177         int (*apply)(struct pwm_chip *chip, struct pwm_device *pwm,
 178                      struct pwm_state *state);
 179         void (*get_state)(struct pwm_chip *chip, struct pwm_device *pwm,
 180                           struct pwm_state *state);
 181 #ifdef CONFIG_DEBUG_FS
 182         void (*dbg_show)(struct pwm_chip *chip, struct seq_file *s);
 183 #endif
 184         struct module *owner;
 185 };
 186
 187 /**
 188  * struct pwm_chip - abstract a PWM controller
 189  * @dev: device providing the PWMs
 190  * @list: list node for internal use
 191  * @ops: callbacks for this PWM controller
 192  * @base: number of first PWM controlled by this chip
 193  * @npwm: number of PWMs controlled by this chip
 194  * @pwms: array of PWM devices allocated by the framework
 195  * @of_xlate: request a PWM device given a device tree PWM specifier
 196  * @of_pwm_n_cells: number of cells expected in the device tree PWM specifier
 197  * @can_sleep: must be true if the .config(), .enable() or .disable()
 198  *             operations may sleep
 199  */
 200 struct pwm_chip {
 201         struct device *dev;
 202         struct list_head list;
 203         const struct pwm_ops *ops;
 204         int base;
 205         unsigned int npwm;
 206
 207         struct pwm_device *pwms;
 208
 209         struct pwm_device * (*of_xlate)(struct pwm_chip *pc,
 210                                         const struct of_phandle_args *args);
 211         unsigned int of_pwm_n_cells;
 212         bool can_sleep;
 213 };
 214
 215 #if IS_ENABLED(CONFIG_PWM)
 216 /* PWM user APIs */
 217 struct pwm_device *pwm_request(int pwm_id, const char *label);
 218 void pwm_free(struct pwm_device *pwm);
 219 int pwm_apply_state(struct pwm_device *pwm, struct pwm_state *state);
 220 int pwm_adjust_config(struct pwm_device *pwm);
 221
 222 /**
 223  * pwm_config() - change a PWM device configuration
 224  * @pwm: PWM device
 225  * @duty_ns: "on" time (in nanoseconds)
 226  * @period_ns: duration (in nanoseconds) of one cycle
 227  *
 228  * Returns: 0 on success or a negative error code on failure.
 229  */
 230 static inline int pwm_config(struct pwm_device *pwm, int duty_ns,
 231                              int period_ns)
 232 {
 233         struct pwm_state state;
 234
 235         if (!pwm)
 236                 return -EINVAL;
 237
 238         if (duty_ns < 0 || period_ns < 0)
 239                 return -EINVAL;
 240
 241         pwm_get_state(pwm, &state);
 242         if (state.duty_cycle == duty_ns && state.period == period_ns)
 243                 return 0;
 244
 245         state.duty_cycle = duty_ns;
 246         state.period = period_ns;
 247         return pwm_apply_state(pwm, &state);
 248 }
 249
 250 /**
 251  * pwm_set_polarity() - configure the polarity of a PWM signal
 252  * @pwm: PWM device
 253  * @polarity: new polarity of the PWM signal
 254  *
 255  * Note that the polarity cannot be configured while the PWM device is
 256  * enabled.
 257  *
 258  * Returns: 0 on success or a negative error code on failure.
 259  */
 260 static inline int pwm_set_polarity(struct pwm_device *pwm,
 261                                    enum pwm_polarity polarity)
 262 {
 263         struct pwm_state state;
 264
 265         if (!pwm)
 266                 return -EINVAL;
 267
 268         pwm_get_state(pwm, &state);
 269         if (state.polarity == polarity)
 270                 return 0;
 271
 272         /*
 273          * Changing the polarity of a running PWM without adjusting the
 274          * dutycycle/period value is a bit risky (can introduce glitches).
 275          * Return -EBUSY in this case.
 276          * Note that this is allowed when using pwm_apply_state() because
 277          * the user specifies all the parameters.
 278          */
 279         if (state.enabled)
 280                 return -EBUSY;
 281
 282         state.polarity = polarity;
 283         return pwm_apply_state(pwm, &state);
 284 }
 285
 286 /**
 287  * pwm_enable() - start a PWM output toggling
 288  * @pwm: PWM device
 289  *
 290  * Returns: 0 on success or a negative error code on failure.
 291  */
 292 static inline int pwm_enable(struct pwm_device *pwm)
 293 {
 294         struct pwm_state state;
 295
 296         if (!pwm)
 297                 return -EINVAL;
 298
 299         pwm_get_state(pwm, &state);
 300         if (state.enabled)
 301                 return 0;
 302
 303         state.enabled = true;
 304         return pwm_apply_state(pwm, &state);
 305 }
 306
 307 /**
 308  * pwm_disable() - stop a PWM output toggling
 309  * @pwm: PWM device
 310  */
 311 static inline void pwm_disable(struct pwm_device *pwm)
 312 {
 313         struct pwm_state state;
 314
 315         if (!pwm)
 316                 return;
 317
 318         pwm_get_state(pwm, &state);
 319         if (!state.enabled)
 320                 return;
 321
 322         state.enabled = false;
 323         pwm_apply_state(pwm, &state);
 324 }
 325
 326
 327 /* PWM provider APIs */
 328 int pwm_set_chip_data(struct pwm_device *pwm, void *data);
 329 void *pwm_get_chip_data(struct pwm_device *pwm);
 330
 331 int pwmchip_add_with_polarity(struct pwm_chip *chip,
 332                               enum pwm_polarity polarity);
 333 int pwmchip_add(struct pwm_chip *chip);
 334 int pwmchip_remove(struct pwm_chip *chip);
 335 struct pwm_device *pwm_request_from_chip(struct pwm_chip *chip,
 336                                          unsigned int index,
 337                                          const char *label);
 338
 339 struct pwm_device *of_pwm_xlate_with_flags(struct pwm_chip *pc,
 340                 const struct of_phandle_args *args);
 341
 342 struct pwm_device *pwm_get(struct device *dev, const char *con_id);
 343 struct pwm_device *of_pwm_get(struct device_node *np, const char *con_id);
 344 void pwm_put(struct pwm_device *pwm);
 345
 346 struct pwm_device *devm_pwm_get(struct device *dev, const char *con_id);
 347 struct pwm_device *devm_of_pwm_get(struct device *dev, struct device_node *np,
 348                                    const char *con_id);
 349 void devm_pwm_put(struct device *dev, struct pwm_device *pwm);
 350
 351 bool pwm_can_sleep(struct pwm_device *pwm);
 352 #else
 353 static inline struct pwm_device *pwm_request(int pwm_id, const char *label)
 354 {
 355         return ERR_PTR(-ENODEV);
 356 }
 357
 358 static inline void pwm_free(struct pwm_device *pwm)
 359 {
 360 }
 361
 362 static inline int pwm_apply_state(struct pwm_device *pwm,
 363                                   const struct pwm_state *state)
 364 {
 365         return -ENOTSUPP;
 366 }
 367
 368 static inline int pwm_adjust_config(struct pwm_device *pwm)
 369 {
 370         return -ENOTSUPP;
 371 }
 372
 373 static inline int pwm_config(struct pwm_device *pwm, int duty_ns,
 374                              int period_ns)
 375 {
 376         return -EINVAL;
 377 }
 378
 379 static inline int pwm_set_polarity(struct pwm_device *pwm,
 380                                    enum pwm_polarity polarity)
 381 {
 382         return -ENOTSUPP;
 383 }
 384
 385 static inline int pwm_enable(struct pwm_device *pwm)
 386 {
 387         return -EINVAL;
 388 }
 389
 390 static inline void pwm_disable(struct pwm_device *pwm)
 391 {
 392 }
 393
 394 static inline int pwm_set_chip_data(struct pwm_device *pwm, void *data)
 395 {
 396         return -EINVAL;
 397 }
 398
 399 static inline void *pwm_get_chip_data(struct pwm_device *pwm)
 400 {
 401         return NULL;
 402 }
 403
 404 static inline int pwmchip_add(struct pwm_chip *chip)
 405 {
 406         return -EINVAL;
 407 }
 408
 409 static inline int pwmchip_add_inversed(struct pwm_chip *chip)
 410 {
 411         return -EINVAL;
 412 }
 413
 414 static inline int pwmchip_remove(struct pwm_chip *chip)
 415 {
 416         return -EINVAL;
 417 }
 418
 419 static inline struct pwm_device *pwm_request_from_chip(struct pwm_chip *chip,
 420                                                        unsigned int index,
 421                                                        const char *label)
 422 {
 423         return ERR_PTR(-ENODEV);
 424 }
 425
 426 static inline struct pwm_device *pwm_get(struct device *dev,
 427                                          const char *consumer)
 428 {
 429         return ERR_PTR(-ENODEV);
 430 }
 431
 432 static inline struct pwm_device *of_pwm_get(struct device_node *np,
 433                                             const char *con_id)
 434 {
 435         return ERR_PTR(-ENODEV);
 436 }
 437
 438 static inline void pwm_put(struct pwm_device *pwm)
 439 {
 440 }
 441
 442 static inline struct pwm_device *devm_pwm_get(struct device *dev,
 443                                               const char *consumer)
 444 {
 445         return ERR_PTR(-ENODEV);
 446 }
 447
 448 static inline struct pwm_device *devm_of_pwm_get(struct device *dev,
 449                                                  struct device_node *np,
 450                                                  const char *con_id)
 451 {
 452         return ERR_PTR(-ENODEV);
 453 }
 454
 455 static inline void devm_pwm_put(struct device *dev, struct pwm_device *pwm)
 456 {
 457 }
 458
 459 static inline bool pwm_can_sleep(struct pwm_device *pwm)
 460 {
 461         return false;
 462 }
 463 #endif
 464
 465 static inline void pwm_apply_args(struct pwm_device *pwm)
 466 {
 467         /*
 468          * PWM users calling pwm_apply_args() expect to have a fresh config
 469          * where the polarity and period are set according to pwm_args info.
 470          * The problem is, polarity can only be changed when the PWM is
 471          * disabled.
 472          *
 473          * PWM drivers supporting hardware readout may declare the PWM device
 474          * as enabled, and prevent polarity setting, which changes from the
 475          * existing behavior, where all PWM devices are declared as disabled
 476          * at startup (even if they are actually enabled), thus authorizing
 477          * polarity setting.
 478          *
 479          * Instead of setting ->enabled to false, we call pwm_disable()
 480          * before pwm_set_polarity() to ensure that everything is configured
 481          * as expected, and the PWM is really disabled when the user request
 482          * it.
 483          *
 484          * Note that PWM users requiring a smooth handover between the
 485          * bootloader and the kernel (like critical regulators controlled by
 486          * PWM devices) will have to switch to the atomic API and avoid calling
 487          * pwm_apply_args().
 488          */
 489         pwm_disable(pwm);
 490         pwm_set_polarity(pwm, pwm->args.polarity);
 491 }
 492
 493 struct pwm_lookup {
 494         struct list_head list;
 495         const char *provider;
 496         unsigned int index;
 497         const char *dev_id;
 498         const char *con_id;
 499         unsigned int period;
 500         enum pwm_polarity polarity;
 501 };
 502
 503 #define PWM_LOOKUP(_provider, _index, _dev_id, _con_id, _period, _polarity) \
 504         {                                               \
 505                 .provider = _provider,                  \
 506                 .index = _index,                        \
 507                 .dev_id = _dev_id,                      \
 508                 .con_id = _con_id,                      \
 509                 .period = _period,                      \
 510                 .polarity = _polarity                   \
 511         }
 512
 513 #if IS_ENABLED(CONFIG_PWM)
 514 void pwm_add_table(struct pwm_lookup *table, size_t num);
 515 void pwm_remove_table(struct pwm_lookup *table, size_t num);
 516 #else
 517 static inline void pwm_add_table(struct pwm_lookup *table, size_t num)
 518 {
 519 }
 520
 521 static inline void pwm_remove_table(struct pwm_lookup *table, size_t num)
 522 {
 523 }
 524 #endif
 525
 526 #ifdef CONFIG_PWM_SYSFS
 527 void pwmchip_sysfs_export(struct pwm_chip *chip);
 528 void pwmchip_sysfs_unexport(struct pwm_chip *chip);
 529 void pwmchip_sysfs_unexport_children(struct pwm_chip *chip);
 530 #else
 531 static inline void pwmchip_sysfs_export(struct pwm_chip *chip)
 532 {
 533 }
 534
 535 static inline void pwmchip_sysfs_unexport(struct pwm_chip *chip)
 536 {
 537 }
 538
 539 static inline void pwmchip_sysfs_unexport_children(struct pwm_chip *chip)
 540 {
 541 }
 542 #endif /* CONFIG_PWM_SYSFS */
 543
 544 #endif /* __LINUX_PWM_H */