1 /* SPDX-License-Identifier: GPL-2.0-only */ 2 /* 3 * consumer.h -- SoC Regulator consumer support. 4 * 5 * Copyright (C) 2007, 2008 Wolfson Microelectronics PLC. 6 * 7 * Author: Liam Girdwood <[email protected]> 8 * 9 * Regulator Consumer Interface. 10 * 11 * A Power Management Regulator framework for SoC based devices. 12 * Features:- 13 * o Voltage and current level control. 14 * o Operating mode control. 15 * o Regulator status. 16 * o sysfs entries for showing client devices and status 17 * 18 * EXPERIMENTAL FEATURES: 19 * Dynamic Regulator operating Mode Switching (DRMS) - allows regulators 20 * to use most efficient operating mode depending upon voltage and load and 21 * is transparent to client drivers. 22 * 23 * e.g. Devices x,y,z share regulator r. Device x and y draw 20mA each during 24 * IO and 1mA at idle. Device z draws 100mA when under load and 5mA when 25 * idling. Regulator r has > 90% efficiency in NORMAL mode at loads > 100mA 26 * but this drops rapidly to 60% when below 100mA. Regulator r has > 90% 27 * efficiency in IDLE mode at loads < 10mA. Thus regulator r will operate 28 * in normal mode for loads > 10mA and in IDLE mode for load <= 10mA. 29 */ 30 31 #ifndef __LINUX_REGULATOR_CONSUMER_H_ 32 #define __LINUX_REGULATOR_CONSUMER_H_ 33 34 #include <linux/err.h> 35 #include <linux/suspend.h> 36 #include <regulator/regulator.h> 37 38 struct device; 39 struct notifier_block; 40 struct regmap; 41 struct regulator_dev; 42 43 /* 44 * Regulator operating modes. 45 * 46 * Regulators can run in a variety of different operating modes depending on 47 * output load. This allows further system power savings by selecting the 48 * best (and most efficient) regulator mode for a desired load. 49 * 50 * Most drivers will only care about NORMAL. The modes below are generic and 51 * will probably not match the naming convention of your regulator data sheet 52 * but should match the use cases in the datasheet. 53 * 54 * In order of power efficiency (least efficient at top). 55 * 56 * Mode Description 57 * FAST Regulator can handle fast changes in it's load. 58 * e.g. useful in CPU voltage & frequency scaling where 59 * load can quickly increase with CPU frequency increases. 60 * 61 * NORMAL Normal regulator power supply mode. Most drivers will 62 * use this mode. 63 * 64 * IDLE Regulator runs in a more efficient mode for light 65 * loads. Can be used for devices that have a low power 66 * requirement during periods of inactivity. This mode 67 * may be more noisy than NORMAL and may not be able 68 * to handle fast load switching. 69 * 70 * STANDBY Regulator runs in the most efficient mode for very 71 * light loads. Can be used by devices when they are 72 * in a sleep/standby state. This mode is likely to be 73 * the most noisy and may not be able to handle fast load 74 * switching. 75 * 76 * NOTE: Most regulators will only support a subset of these modes. Some 77 * will only just support NORMAL. 78 * 79 * These modes can be OR'ed together to make up a mask of valid register modes. 80 */ 81 82 #define REGULATOR_MODE_INVALID 0x0 83 #define REGULATOR_MODE_FAST 0x1 84 #define REGULATOR_MODE_NORMAL 0x2 85 #define REGULATOR_MODE_IDLE 0x4 86 #define REGULATOR_MODE_STANDBY 0x8 87 88 /* 89 * Regulator errors that can be queried using regulator_get_error_flags 90 * 91 * UNDER_VOLTAGE Regulator output is under voltage. 92 * OVER_CURRENT Regulator output current is too high. 93 * REGULATION_OUT Regulator output is out of regulation. 94 * FAIL Regulator output has failed. 95 * OVER_TEMP Regulator over temp. 96 * 97 * NOTE: These errors can be OR'ed together. 98 */ 99 100 #define REGULATOR_ERROR_UNDER_VOLTAGE BIT(1) 101 #define REGULATOR_ERROR_OVER_CURRENT BIT(2) 102 #define REGULATOR_ERROR_REGULATION_OUT BIT(3) 103 #define REGULATOR_ERROR_FAIL BIT(4) 104 #define REGULATOR_ERROR_OVER_TEMP BIT(5) 105 106 #define REGULATOR_ERROR_UNDER_VOLTAGE_WARN BIT(6) 107 #define REGULATOR_ERROR_OVER_CURRENT_WARN BIT(7) 108 #define REGULATOR_ERROR_OVER_VOLTAGE_WARN BIT(8) 109 #define REGULATOR_ERROR_OVER_TEMP_WARN BIT(9) 110 111 /** 112 * struct pre_voltage_change_data - Data sent with PRE_VOLTAGE_CHANGE event 113 * 114 * @old_uV: Current voltage before change. 115 * @min_uV: Min voltage we'll change to. 116 * @max_uV: Max voltage we'll change to. 117 */ 118 struct pre_voltage_change_data { 119 unsigned long old_uV; 120 unsigned long min_uV; 121 unsigned long max_uV; 122 }; 123 124 struct regulator; 125 126 /** 127 * struct regulator_bulk_data - Data used for bulk regulator operations. 128 * 129 * @supply: The name of the supply. Initialised by the user before 130 * using the bulk regulator APIs. 131 * @consumer: The regulator consumer for the supply. This will be managed 132 * by the bulk API. 133 * @init_load_uA: After getting the regulator, regulator_set_load() will be 134 * called with this load. Initialised by the user before 135 * using the bulk regulator APIs. 136 * 137 * The regulator APIs provide a series of regulator_bulk_() API calls as 138 * a convenience to consumers which require multiple supplies. This 139 * structure is used to manage data for these calls. 140 */ 141 struct regulator_bulk_data { 142 const char *supply; 143 struct regulator *consumer; 144 int init_load_uA; 145 146 /* private: Internal use */ 147 int ret; 148 }; 149 150 #if defined(CONFIG_REGULATOR) 151 152 /* regulator get and put */ 153 struct regulator *__must_check regulator_get(struct device *dev, 154 const char *id); 155 struct regulator *__must_check devm_regulator_get(struct device *dev, 156 const char *id); 157 struct regulator *__must_check regulator_get_exclusive(struct device *dev, 158 const char *id); 159 struct regulator *__must_check devm_regulator_get_exclusive(struct device *dev, 160 const char *id); 161 struct regulator *__must_check regulator_get_optional(struct device *dev, 162 const char *id); 163 struct regulator *__must_check devm_regulator_get_optional(struct device *dev, 164 const char *id); 165 int devm_regulator_get_enable(struct device *dev, const char *id); 166 int devm_regulator_get_enable_optional(struct device *dev, const char *id); 167 int devm_regulator_get_enable_read_voltage(struct device *dev, const char *id); 168 void regulator_put(struct regulator *regulator); 169 void devm_regulator_put(struct regulator *regulator); 170 171 #if IS_ENABLED(CONFIG_OF) 172 struct regulator *__must_check of_regulator_get_optional(struct device *dev, 173 struct device_node *node, 174 const char *id); 175 struct regulator *__must_check devm_of_regulator_get_optional(struct device *dev, 176 struct device_node *node, 177 const char *id); 178 #else 179 static inline struct regulator *__must_check of_regulator_get_optional(struct device *dev, 180 struct device_node *node, 181 const char *id) 182 { 183 return ERR_PTR(-ENODEV); 184 } 185 186 static inline struct regulator *__must_check devm_of_regulator_get_optional(struct device *dev, 187 struct device_node *node, 188 const char *id) 189 { 190 return ERR_PTR(-ENODEV); 191 } 192 #endif 193 194 int regulator_register_supply_alias(struct device *dev, const char *id, 195 struct device *alias_dev, 196 const char *alias_id); 197 void regulator_unregister_supply_alias(struct device *dev, const char *id); 198 199 int regulator_bulk_register_supply_alias(struct device *dev, 200 const char *const *id, 201 struct device *alias_dev, 202 const char *const *alias_id, 203 int num_id); 204 void regulator_bulk_unregister_supply_alias(struct device *dev, 205 const char * const *id, int num_id); 206 207 int devm_regulator_register_supply_alias(struct device *dev, const char *id, 208 struct device *alias_dev, 209 const char *alias_id); 210 211 int devm_regulator_bulk_register_supply_alias(struct device *dev, 212 const char *const *id, 213 struct device *alias_dev, 214 const char *const *alias_id, 215 int num_id); 216 217 /* regulator output control and status */ 218 int __must_check regulator_enable(struct regulator *regulator); 219 int regulator_disable(struct regulator *regulator); 220 int regulator_force_disable(struct regulator *regulator); 221 int regulator_is_enabled(struct regulator *regulator); 222 int regulator_disable_deferred(struct regulator *regulator, int ms); 223 224 int __must_check regulator_bulk_get(struct device *dev, int num_consumers, 225 struct regulator_bulk_data *consumers); 226 int __must_check of_regulator_bulk_get_all(struct device *dev, struct device_node *np, 227 struct regulator_bulk_data **consumers); 228 int __must_check devm_regulator_bulk_get(struct device *dev, int num_consumers, 229 struct regulator_bulk_data *consumers); 230 void devm_regulator_bulk_put(struct regulator_bulk_data *consumers); 231 int __must_check devm_regulator_bulk_get_exclusive(struct device *dev, int num_consumers, 232 struct regulator_bulk_data *consumers); 233 int __must_check devm_regulator_bulk_get_const( 234 struct device *dev, int num_consumers, 235 const struct regulator_bulk_data *in_consumers, 236 struct regulator_bulk_data **out_consumers); 237 int __must_check regulator_bulk_enable(int num_consumers, 238 struct regulator_bulk_data *consumers); 239 int devm_regulator_bulk_get_enable(struct device *dev, int num_consumers, 240 const char * const *id); 241 int regulator_bulk_disable(int num_consumers, 242 struct regulator_bulk_data *consumers); 243 int regulator_bulk_force_disable(int num_consumers, 244 struct regulator_bulk_data *consumers); 245 void regulator_bulk_free(int num_consumers, 246 struct regulator_bulk_data *consumers); 247 248 int regulator_count_voltages(struct regulator *regulator); 249 int regulator_list_voltage(struct regulator *regulator, unsigned selector); 250 int regulator_is_supported_voltage(struct regulator *regulator, 251 int min_uV, int max_uV); 252 unsigned int regulator_get_linear_step(struct regulator *regulator); 253 int regulator_set_voltage(struct regulator *regulator, int min_uV, int max_uV); 254 int regulator_set_voltage_time(struct regulator *regulator, 255 int old_uV, int new_uV); 256 int regulator_get_voltage(struct regulator *regulator); 257 int regulator_sync_voltage(struct regulator *regulator); 258 int regulator_set_current_limit(struct regulator *regulator, 259 int min_uA, int max_uA); 260 int regulator_get_current_limit(struct regulator *regulator); 261 262 int regulator_set_mode(struct regulator *regulator, unsigned int mode); 263 unsigned int regulator_get_mode(struct regulator *regulator); 264 int regulator_get_error_flags(struct regulator *regulator, 265 unsigned int *flags); 266 int regulator_set_load(struct regulator *regulator, int load_uA); 267 268 int regulator_allow_bypass(struct regulator *regulator, bool allow); 269 270 struct regmap *regulator_get_regmap(struct regulator *regulator); 271 int regulator_get_hardware_vsel_register(struct regulator *regulator, 272 unsigned *vsel_reg, 273 unsigned *vsel_mask); 274 int regulator_list_hardware_vsel(struct regulator *regulator, 275 unsigned selector); 276 int regulator_hardware_enable(struct regulator *regulator, bool enable); 277 278 /* regulator notifier block */ 279 int regulator_register_notifier(struct regulator *regulator, 280 struct notifier_block *nb); 281 int devm_regulator_register_notifier(struct regulator *regulator, 282 struct notifier_block *nb); 283 int regulator_unregister_notifier(struct regulator *regulator, 284 struct notifier_block *nb); 285 void devm_regulator_unregister_notifier(struct regulator *regulator, 286 struct notifier_block *nb); 287 288 /* regulator suspend */ 289 int regulator_suspend_enable(struct regulator_dev *rdev, 290 suspend_state_t state); 291 int regulator_suspend_disable(struct regulator_dev *rdev, 292 suspend_state_t state); 293 int regulator_set_suspend_voltage(struct regulator *regulator, int min_uV, 294 int max_uV, suspend_state_t state); 295 296 /* driver data - core doesn't touch */ 297 void *regulator_get_drvdata(struct regulator *regulator); 298 void regulator_set_drvdata(struct regulator *regulator, void *data); 299 300 /* misc helpers */ 301 302 void regulator_bulk_set_supply_names(struct regulator_bulk_data *consumers, 303 const char *const *supply_names, 304 unsigned int num_supplies); 305 306 bool regulator_is_equal(struct regulator *reg1, struct regulator *reg2); 307 308 #else 309 310 /* 311 * Make sure client drivers will still build on systems with no software 312 * controllable voltage or current regulators. 313 */ 314 static inline struct regulator *__must_check regulator_get(struct device *dev, 315 const char *id) 316 { 317 /* Nothing except the stubbed out regulator API should be 318 * looking at the value except to check if it is an error 319 * value. Drivers are free to handle NULL specifically by 320 * skipping all regulator API calls, but they don't have to. 321 * Drivers which don't, should make sure they properly handle 322 * corner cases of the API, such as regulator_get_voltage() 323 * returning 0. 324 */ 325 return NULL; 326 } 327 328 static inline struct regulator *__must_check 329 devm_regulator_get(struct device *dev, const char *id) 330 { 331 return NULL; 332 } 333 334 static inline struct regulator *__must_check 335 regulator_get_exclusive(struct device *dev, const char *id) 336 { 337 return ERR_PTR(-ENODEV); 338 } 339 340 static inline struct regulator *__must_check 341 devm_regulator_get_exclusive(struct device *dev, const char *id) 342 { 343 return ERR_PTR(-ENODEV); 344 } 345 346 static inline int devm_regulator_get_enable(struct device *dev, const char *id) 347 { 348 return 0; 349 } 350 351 static inline int devm_regulator_get_enable_optional(struct device *dev, 352 const char *id) 353 { 354 return 0; 355 } 356 357 static inline int devm_regulator_get_enable_read_voltage(struct device *dev, 358 const char *id) 359 { 360 return -ENODEV; 361 } 362 363 static inline struct regulator *__must_check 364 regulator_get_optional(struct device *dev, const char *id) 365 { 366 return ERR_PTR(-ENODEV); 367 } 368 369 370 static inline struct regulator *__must_check 371 devm_regulator_get_optional(struct device *dev, const char *id) 372 { 373 return ERR_PTR(-ENODEV); 374 } 375 376 static inline struct regulator *__must_check of_regulator_get_optional(struct device *dev, 377 struct device_node *node, 378 const char *id) 379 { 380 return ERR_PTR(-ENODEV); 381 } 382 383 static inline struct regulator *__must_check devm_of_regulator_get_optional(struct device *dev, 384 struct device_node *node, 385 const char *id) 386 { 387 return ERR_PTR(-ENODEV); 388 } 389 390 static inline void regulator_put(struct regulator *regulator) 391 { 392 } 393 394 static inline void devm_regulator_put(struct regulator *regulator) 395 { 396 } 397 398 static inline void devm_regulator_bulk_put(struct regulator_bulk_data *consumers) 399 { 400 } 401 402 static inline int regulator_register_supply_alias(struct device *dev, 403 const char *id, 404 struct device *alias_dev, 405 const char *alias_id) 406 { 407 return 0; 408 } 409 410 static inline void regulator_unregister_supply_alias(struct device *dev, 411 const char *id) 412 { 413 } 414 415 static inline int regulator_bulk_register_supply_alias(struct device *dev, 416 const char *const *id, 417 struct device *alias_dev, 418 const char * const *alias_id, 419 int num_id) 420 { 421 return 0; 422 } 423 424 static inline void regulator_bulk_unregister_supply_alias(struct device *dev, 425 const char * const *id, 426 int num_id) 427 { 428 } 429 430 static inline int devm_regulator_register_supply_alias(struct device *dev, 431 const char *id, 432 struct device *alias_dev, 433 const char *alias_id) 434 { 435 return 0; 436 } 437 438 static inline int devm_regulator_bulk_register_supply_alias(struct device *dev, 439 const char *const *id, 440 struct device *alias_dev, 441 const char *const *alias_id, 442 int num_id) 443 { 444 return 0; 445 } 446 447 static inline int regulator_enable(struct regulator *regulator) 448 { 449 return 0; 450 } 451 452 static inline int regulator_disable(struct regulator *regulator) 453 { 454 return 0; 455 } 456 457 static inline int regulator_force_disable(struct regulator *regulator) 458 { 459 return 0; 460 } 461 462 static inline int regulator_disable_deferred(struct regulator *regulator, 463 int ms) 464 { 465 return 0; 466 } 467 468 static inline int regulator_is_enabled(struct regulator *regulator) 469 { 470 return 1; 471 } 472 473 static inline int regulator_bulk_get(struct device *dev, 474 int num_consumers, 475 struct regulator_bulk_data *consumers) 476 { 477 return 0; 478 } 479 480 static inline int devm_regulator_bulk_get(struct device *dev, int num_consumers, 481 struct regulator_bulk_data *consumers) 482 { 483 return 0; 484 } 485 486 static inline int of_regulator_bulk_get_all(struct device *dev, struct device_node *np, 487 struct regulator_bulk_data **consumers) 488 { 489 return 0; 490 } 491 492 static inline int devm_regulator_bulk_get_const( 493 struct device *dev, int num_consumers, 494 const struct regulator_bulk_data *in_consumers, 495 struct regulator_bulk_data **out_consumers) 496 { 497 return 0; 498 } 499 500 static inline int regulator_bulk_enable(int num_consumers, 501 struct regulator_bulk_data *consumers) 502 { 503 return 0; 504 } 505 506 static inline int devm_regulator_bulk_get_enable(struct device *dev, 507 int num_consumers, 508 const char * const *id) 509 { 510 return 0; 511 } 512 513 static inline int regulator_bulk_disable(int num_consumers, 514 struct regulator_bulk_data *consumers) 515 { 516 return 0; 517 } 518 519 static inline int regulator_bulk_force_disable(int num_consumers, 520 struct regulator_bulk_data *consumers) 521 { 522 return 0; 523 } 524 525 static inline void regulator_bulk_free(int num_consumers, 526 struct regulator_bulk_data *consumers) 527 { 528 } 529 530 static inline int regulator_set_voltage(struct regulator *regulator, 531 int min_uV, int max_uV) 532 { 533 return 0; 534 } 535 536 static inline int regulator_set_voltage_time(struct regulator *regulator, 537 int old_uV, int new_uV) 538 { 539 return 0; 540 } 541 542 static inline int regulator_get_voltage(struct regulator *regulator) 543 { 544 return -EINVAL; 545 } 546 547 static inline int regulator_sync_voltage(struct regulator *regulator) 548 { 549 return -EINVAL; 550 } 551 552 static inline int regulator_is_supported_voltage(struct regulator *regulator, 553 int min_uV, int max_uV) 554 { 555 return 0; 556 } 557 558 static inline unsigned int regulator_get_linear_step(struct regulator *regulator) 559 { 560 return 0; 561 } 562 563 static inline int regulator_set_current_limit(struct regulator *regulator, 564 int min_uA, int max_uA) 565 { 566 return 0; 567 } 568 569 static inline int regulator_get_current_limit(struct regulator *regulator) 570 { 571 return 0; 572 } 573 574 static inline int regulator_set_mode(struct regulator *regulator, 575 unsigned int mode) 576 { 577 return 0; 578 } 579 580 static inline unsigned int regulator_get_mode(struct regulator *regulator) 581 { 582 return REGULATOR_MODE_NORMAL; 583 } 584 585 static inline int regulator_get_error_flags(struct regulator *regulator, 586 unsigned int *flags) 587 { 588 return -EINVAL; 589 } 590 591 static inline int regulator_set_load(struct regulator *regulator, int load_uA) 592 { 593 return 0; 594 } 595 596 static inline int regulator_allow_bypass(struct regulator *regulator, 597 bool allow) 598 { 599 return 0; 600 } 601 602 static inline struct regmap *regulator_get_regmap(struct regulator *regulator) 603 { 604 return ERR_PTR(-EOPNOTSUPP); 605 } 606 607 static inline int regulator_get_hardware_vsel_register(struct regulator *regulator, 608 unsigned *vsel_reg, 609 unsigned *vsel_mask) 610 { 611 return -EOPNOTSUPP; 612 } 613 614 static inline int regulator_list_hardware_vsel(struct regulator *regulator, 615 unsigned selector) 616 { 617 return -EOPNOTSUPP; 618 } 619 620 static inline int regulator_hardware_enable(struct regulator *regulator, 621 bool enable) 622 { 623 return -EOPNOTSUPP; 624 } 625 626 static inline int regulator_register_notifier(struct regulator *regulator, 627 struct notifier_block *nb) 628 { 629 return 0; 630 } 631 632 static inline int devm_regulator_register_notifier(struct regulator *regulator, 633 struct notifier_block *nb) 634 { 635 return 0; 636 } 637 638 static inline int regulator_unregister_notifier(struct regulator *regulator, 639 struct notifier_block *nb) 640 { 641 return 0; 642 } 643 644 static inline int devm_regulator_unregister_notifier(struct regulator *regulator, 645 struct notifier_block *nb) 646 { 647 return 0; 648 } 649 650 static inline int regulator_suspend_enable(struct regulator_dev *rdev, 651 suspend_state_t state) 652 { 653 return -EINVAL; 654 } 655 656 static inline int regulator_suspend_disable(struct regulator_dev *rdev, 657 suspend_state_t state) 658 { 659 return -EINVAL; 660 } 661 662 static inline int regulator_set_suspend_voltage(struct regulator *regulator, 663 int min_uV, int max_uV, 664 suspend_state_t state) 665 { 666 return -EINVAL; 667 } 668 669 static inline void *regulator_get_drvdata(struct regulator *regulator) 670 { 671 return NULL; 672 } 673 674 static inline void regulator_set_drvdata(struct regulator *regulator, 675 void *data) 676 { 677 } 678 679 static inline int regulator_count_voltages(struct regulator *regulator) 680 { 681 return 0; 682 } 683 684 static inline int regulator_list_voltage(struct regulator *regulator, unsigned selector) 685 { 686 return -EINVAL; 687 } 688 689 static inline void 690 regulator_bulk_set_supply_names(struct regulator_bulk_data *consumers, 691 const char *const *supply_names, 692 unsigned int num_supplies) 693 { 694 } 695 696 static inline bool 697 regulator_is_equal(struct regulator *reg1, struct regulator *reg2) 698 { 699 return false; 700 } 701 #endif 702 703 static inline int regulator_set_voltage_triplet(struct regulator *regulator, 704 int min_uV, int target_uV, 705 int max_uV) 706 { 707 if (regulator_set_voltage(regulator, target_uV, max_uV) == 0) 708 return 0; 709 710 return regulator_set_voltage(regulator, min_uV, max_uV); 711 } 712 713 static inline int regulator_set_voltage_tol(struct regulator *regulator, 714 int new_uV, int tol_uV) 715 { 716 if (regulator_set_voltage(regulator, new_uV, new_uV + tol_uV) == 0) 717 return 0; 718 else 719 return regulator_set_voltage(regulator, 720 new_uV - tol_uV, new_uV + tol_uV); 721 } 722 723 static inline int regulator_is_supported_voltage_tol(struct regulator *regulator, 724 int target_uV, int tol_uV) 725 { 726 return regulator_is_supported_voltage(regulator, 727 target_uV - tol_uV, 728 target_uV + tol_uV); 729 } 730 731 #endif 732