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         pwm_get_state(pwm, &state);
 239         if (state.duty_cycle == duty_ns && state.period == period_ns)
 240                 return 0;
 241
 242         state.duty_cycle = duty_ns;
 243         state.period = period_ns;
 244         return pwm_apply_state(pwm, &state);
 245 }
 246
 247 /**
 248  * pwm_set_polarity() - configure the polarity of a PWM signal
 249  * @pwm: PWM device
 250  * @polarity: new polarity of the PWM signal
 251  *
 252  * Note that the polarity cannot be configured while the PWM device is
 253  * enabled.
 254  *
 255  * Returns: 0 on success or a negative error code on failure.
 256  */
 257 static inline int pwm_set_polarity(struct pwm_device *pwm,
 258                                    enum pwm_polarity polarity)
 259 {
 260         struct pwm_state state;
 261
 262         if (!pwm)
 263                 return -EINVAL;
 264
 265         pwm_get_state(pwm, &state);
 266         if (state.polarity == polarity)
 267                 return 0;
 268
 269         /*
 270          * Changing the polarity of a running PWM without adjusting the
 271          * dutycycle/period value is a bit risky (can introduce glitches).
 272          * Return -EBUSY in this case.
 273          * Note that this is allowed when using pwm_apply_state() because
 274          * the user specifies all the parameters.
 275          */
 276         if (state.enabled)
 277                 return -EBUSY;
 278
 279         state.polarity = polarity;
 280         return pwm_apply_state(pwm, &state);
 281 }
 282
 283 /**
 284  * pwm_enable() - start a PWM output toggling
 285  * @pwm: PWM device
 286  *
 287  * Returns: 0 on success or a negative error code on failure.
 288  */
 289 static inline int pwm_enable(struct pwm_device *pwm)
 290 {
 291         struct pwm_state state;
 292
 293         if (!pwm)
 294                 return -EINVAL;
 295
 296         pwm_get_state(pwm, &state);
 297         if (state.enabled)
 298                 return 0;
 299
 300         state.enabled = true;
 301         return pwm_apply_state(pwm, &state);
 302 }
 303
 304 /**
 305  * pwm_disable() - stop a PWM output toggling
 306  * @pwm: PWM device
 307  */
 308 static inline void pwm_disable(struct pwm_device *pwm)
 309 {
 310         struct pwm_state state;
 311
 312         if (!pwm)
 313                 return;
 314
 315         pwm_get_state(pwm, &state);
 316         if (!state.enabled)
 317                 return;
 318
 319         state.enabled = false;
 320         pwm_apply_state(pwm, &state);
 321 }
 322
 323
 324 /* PWM provider APIs */
 325 int pwm_set_chip_data(struct pwm_device *pwm, void *data);
 326 void *pwm_get_chip_data(struct pwm_device *pwm);
 327
 328 int pwmchip_add_with_polarity(struct pwm_chip *chip,
 329                               enum pwm_polarity polarity);
 330 int pwmchip_add(struct pwm_chip *chip);
 331 int pwmchip_remove(struct pwm_chip *chip);
 332 struct pwm_device *pwm_request_from_chip(struct pwm_chip *chip,
 333                                          unsigned int index,
 334                                          const char *label);
 335
 336 struct pwm_device *of_pwm_xlate_with_flags(struct pwm_chip *pc,
 337                 const struct of_phandle_args *args);
 338
 339 struct pwm_device *pwm_get(struct device *dev, const char *con_id);
 340 struct pwm_device *of_pwm_get(struct device_node *np, const char *con_id);
 341 void pwm_put(struct pwm_device *pwm);
 342
 343 struct pwm_device *devm_pwm_get(struct device *dev, const char *con_id);
 344 struct pwm_device *devm_of_pwm_get(struct device *dev, struct device_node *np,
 345                                    const char *con_id);
 346 void devm_pwm_put(struct device *dev, struct pwm_device *pwm);
 347
 348 bool pwm_can_sleep(struct pwm_device *pwm);
 349 #else
 350 static inline struct pwm_device *pwm_request(int pwm_id, const char *label)
 351 {
 352         return ERR_PTR(-ENODEV);
 353 }
 354
 355 static inline void pwm_free(struct pwm_device *pwm)
 356 {
 357 }
 358
 359 static inline int pwm_apply_state(struct pwm_device *pwm,
 360                                   const struct pwm_state *state)
 361 {
 362         return -ENOTSUPP;
 363 }
 364
 365 static inline int pwm_adjust_config(struct pwm_device *pwm)
 366 {
 367         return -ENOTSUPP;
 368 }
 369
 370 static inline int pwm_config(struct pwm_device *pwm, int duty_ns,
 371                              int period_ns)
 372 {
 373         return -EINVAL;
 374 }
 375
 376 static inline int pwm_set_polarity(struct pwm_device *pwm,
 377                                    enum pwm_polarity polarity)
 378 {
 379         return -ENOTSUPP;
 380 }
 381
 382 static inline int pwm_enable(struct pwm_device *pwm)
 383 {
 384         return -EINVAL;
 385 }
 386
 387 static inline void pwm_disable(struct pwm_device *pwm)
 388 {
 389 }
 390
 391 static inline int pwm_set_chip_data(struct pwm_device *pwm, void *data)
 392 {
 393         return -EINVAL;
 394 }
 395
 396 static inline void *pwm_get_chip_data(struct pwm_device *pwm)
 397 {
 398         return NULL;
 399 }
 400
 401 static inline int pwmchip_add(struct pwm_chip *chip)
 402 {
 403         return -EINVAL;
 404 }
 405
 406 static inline int pwmchip_add_inversed(struct pwm_chip *chip)
 407 {
 408         return -EINVAL;
 409 }
 410
 411 static inline int pwmchip_remove(struct pwm_chip *chip)
 412 {
 413         return -EINVAL;
 414 }
 415
 416 static inline struct pwm_device *pwm_request_from_chip(struct pwm_chip *chip,
 417                                                        unsigned int index,
 418                                                        const char *label)
 419 {
 420         return ERR_PTR(-ENODEV);
 421 }
 422
 423 static inline struct pwm_device *pwm_get(struct device *dev,
 424                                          const char *consumer)
 425 {
 426         return ERR_PTR(-ENODEV);
 427 }
 428
 429 static inline struct pwm_device *of_pwm_get(struct device_node *np,
 430                                             const char *con_id)
 431 {
 432         return ERR_PTR(-ENODEV);
 433 }
 434
 435 static inline void pwm_put(struct pwm_device *pwm)
 436 {
 437 }
 438
 439 static inline struct pwm_device *devm_pwm_get(struct device *dev,
 440                                               const char *consumer)
 441 {
 442         return ERR_PTR(-ENODEV);
 443 }
 444
 445 static inline struct pwm_device *devm_of_pwm_get(struct device *dev,
 446                                                  struct device_node *np,
 447                                                  const char *con_id)
 448 {
 449         return ERR_PTR(-ENODEV);
 450 }
 451
 452 static inline void devm_pwm_put(struct device *dev, struct pwm_device *pwm)
 453 {
 454 }
 455
 456 static inline bool pwm_can_sleep(struct pwm_device *pwm)
 457 {
 458         return false;
 459 }
 460 #endif
 461
 462 static inline void pwm_apply_args(struct pwm_device *pwm)
 463 {
 464         /*
 465          * PWM users calling pwm_apply_args() expect to have a fresh config
 466          * where the polarity and period are set according to pwm_args info.
 467          * The problem is, polarity can only be changed when the PWM is
 468          * disabled.
 469          *
 470          * PWM drivers supporting hardware readout may declare the PWM device
 471          * as enabled, and prevent polarity setting, which changes from the
 472          * existing behavior, where all PWM devices are declared as disabled
 473          * at startup (even if they are actually enabled), thus authorizing
 474          * polarity setting.
 475          *
 476          * Instead of setting ->enabled to false, we call pwm_disable()
 477          * before pwm_set_polarity() to ensure that everything is configured
 478          * as expected, and the PWM is really disabled when the user request
 479          * it.
 480          *
 481          * Note that PWM users requiring a smooth handover between the
 482          * bootloader and the kernel (like critical regulators controlled by
 483          * PWM devices) will have to switch to the atomic API and avoid calling
 484          * pwm_apply_args().
 485          */
 486         pwm_disable(pwm);
 487         pwm_set_polarity(pwm, pwm->args.polarity);
 488 }
 489
 490 struct pwm_lookup {
 491         struct list_head list;
 492         const char *provider;
 493         unsigned int index;
 494         const char *dev_id;
 495         const char *con_id;
 496         unsigned int period;
 497         enum pwm_polarity polarity;
 498 };
 499
 500 #define PWM_LOOKUP(_provider, _index, _dev_id, _con_id, _period, _polarity) \
 501         {                                               \
 502                 .provider = _provider,                  \
 503                 .index = _index,                        \
 504                 .dev_id = _dev_id,                      \
 505                 .con_id = _con_id,                      \
 506                 .period = _period,                      \
 507                 .polarity = _polarity                   \
 508         }
 509
 510 #if IS_ENABLED(CONFIG_PWM)
 511 void pwm_add_table(struct pwm_lookup *table, size_t num);
 512 void pwm_remove_table(struct pwm_lookup *table, size_t num);
 513 #else
 514 static inline void pwm_add_table(struct pwm_lookup *table, size_t num)
 515 {
 516 }
 517
 518 static inline void pwm_remove_table(struct pwm_lookup *table, size_t num)
 519 {
 520 }
 521 #endif
 522
 523 #ifdef CONFIG_PWM_SYSFS
 524 void pwmchip_sysfs_export(struct pwm_chip *chip);
 525 void pwmchip_sysfs_unexport(struct pwm_chip *chip);
 526 #else
 527 static inline void pwmchip_sysfs_export(struct pwm_chip *chip)
 528 {
 529 }
 530
 531 static inline void pwmchip_sysfs_unexport(struct pwm_chip *chip)
 532 {
 533 }
 534 #endif /* CONFIG_PWM_SYSFS */
 535
 536 #endif /* __LINUX_PWM_H */