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