include/power/regulator.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  *  Copyright (C) 2014-2015 Samsung Electronics
   4  *  Przemyslaw Marczak <[email protected]>
   5  */
   6
   7 #ifndef _INCLUDE_REGULATOR_H_
   8 #define _INCLUDE_REGULATOR_H_
   9
  10 #include <linux/errno.h>
  11
  12 struct udevice;
  13
  14 /**
  15  * U-Boot Voltage/Current Regulator
  16  * ================================
  17  *
  18  * The regulator API is based on a driver model, with the device tree support.
  19  * And this header describes the functions and data types for the uclass id:
  20  * 'UCLASS_REGULATOR' and the regulator driver API.
  21  *
  22  * The regulator uclass - is based on uclass platform data which is allocated,
  23  * automatically for each regulator device on bind and 'dev->uclass_plat'
  24  * points to it. The data type is: 'struct dm_regulator_uclass_plat'.
  25  * The uclass file: 'drivers/power/regulator/regulator-uclass.c'
  26  *
  27  * The regulator device - is based on driver's model 'struct udevice'.
  28  * The API can use regulator name in two meanings:
  29  * - devname  - the regulator device's name: 'dev->name'
  30  * - platname - the device's plat's name. So in the code it looks like:
  31  *              'uc_pdata = dev->uclass_plat'; 'name = uc_pdata->name'.
  32  *
  33  * The regulator device driver - provide an implementation of uclass operations
  34  * pointed by 'dev->driver->ops' as a struct of type 'struct dm_regulator_ops'.
  35  *
  36  * To proper bind the regulator device, the device tree node should provide
  37  * regulator constraints, like in the example below:
  38  *
  39  * ldo1 {
  40  *      regulator-name = "VDD_MMC_1.8V";     (must be unique for proper bind)
  41  *      regulator-min-microvolt = <1000000>; (optional)
  42  *      regulator-max-microvolt = <1000000>; (optional)
  43  *      regulator-min-microamp = <1000>;     (optional)
  44  *      regulator-max-microamp = <1000>;     (optional)
  45  *      regulator-always-on;                 (optional)
  46  *      regulator-boot-on;                   (optional)
  47  * };
  48  *
  49  * Note: For the proper operation, at least name constraint is needed, since
  50  * it can be used when calling regulator_get_by_platname(). And the mandatory
  51  * rule for this name is, that it must be globally unique for the single dts.
  52  * If regulator-name property is not provided, node name will be chosen.
  53  *
  54  * Regulator bind:
  55  * For each regulator device, the device_bind() should be called with passed
  56  * device tree offset. This is required for this uclass's '.post_bind' method,
  57  * which does the scan on the device node, for the 'regulator-name' constraint.
  58  * If the parent is not a PMIC device, and the child is not bind by function:
  59  * 'pmic_bind_childs()', then it's recommended to bind the device by call to
  60  * dm_scan_fdt_dev() - this is usually done automatically for bus devices,
  61  * as a post bind method.
  62  *
  63  * Regulator get:
  64  * Having the device's name constraint, we can call regulator_by_platname(),
  65  * to find the required regulator. Before return, the regulator is probed,
  66  * and the rest of its constraints are put into the device's uclass platform
  67  * data, by the uclass regulator '.pre_probe' method.
  68  *
  69  * For more info about PMIC bind, please refer to file: 'include/power/pmic.h'
  70  *
  71  * Note:
  72  * Please do not use the device_bind_by_name() function, since it pass '-1' as
  73  * device node offset - and the bind will fail on uclass .post_bind method,
  74  * because of missing 'regulator-name' constraint.
  75  *
  76  *
  77  * Fixed Voltage/Current Regulator
  78  * ===============================
  79  *
  80  * When fixed voltage regulator is needed, then enable the config:
  81  * - CONFIG_DM_REGULATOR_FIXED
  82  *
  83  * The driver file: 'drivers/power/regulator/fixed.c', provides basic support
  84  * for control the GPIO, and return the device tree constraint values.
  85  *
  86  * To bind the fixed voltage regulator device, we usually use a 'simple-bus'
  87  * node as a parent. And 'regulator-fixed' for the driver compatible. This is
  88  * the same as in the kernel. The example node of fixed regulator:
  89  *
  90  * simple-bus {
  91  *     compatible = "simple-bus";
  92  *     #address-cells = <1>;
  93  *     #size-cells = <0>;
  94  *
  95  *     blue_led {
  96  *         compatible = "regulator-fixed";
  97  *         regulator-name = "VDD_LED_3.3V";
  98  *         regulator-min-microvolt = <3300000>;
  99  *         regulator-max-microvolt = <3300000>;
 100  *         gpio = <&gpc1 0 GPIO_ACTIVE_LOW>;
 101  *     };
 102  * };
 103  *
 104  * The fixed regulator devices also provide regulator uclass platform data. And
 105  * devices bound from such node, can use the regulator drivers API.
 106 */
 107
 108 /* enum regulator_type - used for regulator_*() variant calls */
 109 enum regulator_type {
 110         REGULATOR_TYPE_LDO = 0,
 111         REGULATOR_TYPE_BUCK,
 112         REGULATOR_TYPE_DVS,
 113         REGULATOR_TYPE_FIXED,
 114         REGULATOR_TYPE_GPIO,
 115         REGULATOR_TYPE_OTHER,
 116 };
 117
 118 /**
 119  * struct dm_regulator_mode - this structure holds an information about
 120  * each regulator operation mode. Probably in most cases - an array.
 121  * This will be probably a driver-static data, since it is device-specific.
 122  *
 123  * @id             - a driver-specific mode id
 124  * @register_value - a driver-specific value for its mode id
 125  * @name           - the name of mode - used for regulator command
 126  * Note:
 127  * The field 'id', should be always a positive number, since the negative values
 128  * are reserved for the errno numbers when returns the mode id.
 129  */
 130 struct dm_regulator_mode {
 131         int id; /* Set only as >= 0 (negative value is reserved for errno) */
 132         int register_value;
 133         const char *name;
 134 };
 135
 136 enum regulator_flag {
 137         REGULATOR_FLAG_AUTOSET_UV       = 1 << 0,
 138         REGULATOR_FLAG_AUTOSET_UA       = 1 << 1,
 139         REGULATOR_FLAG_AUTOSET_DONE     = 1 << 2,
 140 };
 141
 142 /**
 143  * struct dm_regulator_uclass_plat - pointed by dev->uclass_plat, and
 144  * allocated on each regulator bind. This structure holds an information
 145  * about each regulator's constraints and supported operation modes.
 146  * There is no "step" voltage value - so driver should take care of this.
 147  *
 148  * @type       - one of 'enum regulator_type'
 149  * @mode       - pointer to the regulator mode (array if more than one)
 150  * @mode_count - number of '.mode' entries
 151  * @min_uV*    - minimum voltage (micro Volts)
 152  * @max_uV*    - maximum voltage (micro Volts)
 153  * @min_uA*    - minimum amperage (micro Amps)
 154  * @max_uA*    - maximum amperage (micro Amps)
 155  * @always_on* - bool type, true or false
 156  * @boot_on*   - bool type, true or false
 157  * @force_off* - bool type, true or false
 158  * TODO([email protected]): Consider putting the above two into @flags
 159  * @ramp_delay - Time to settle down after voltage change (unit: uV/us)
 160  * @flags:     - flags value (see REGULATOR_FLAG_...)
 161  * @name**     - fdt regulator name - should be taken from the device tree
 162  * ctrl_reg:   - Control register offset used to enable/disable regulator
 163  * volt_reg:   - register offset for writing voltage vsel values
 164  *
 165  * Note:
 166  * *  - set automatically on device probe by the uclass's '.pre_probe' method.
 167  * ** - set automatically on device bind by the uclass's '.post_bind' method.
 168  * The constraints: type, mode, mode_count, can be set by device driver, e.g.
 169  * by the driver '.probe' method.
 170  */
 171 struct dm_regulator_uclass_plat {
 172         enum regulator_type type;
 173         struct dm_regulator_mode *mode;
 174         int mode_count;
 175         int min_uV;
 176         int max_uV;
 177         int init_uV;
 178         int min_uA;
 179         int max_uA;
 180         unsigned int ramp_delay;
 181         bool always_on;
 182         bool boot_on;
 183         bool force_off;
 184         const char *name;
 185         int flags;
 186         u8 ctrl_reg;
 187         u8 volt_reg;
 188         bool suspend_on;
 189         u32 suspend_uV;
 190 };
 191
 192 /* Regulator device operations */
 193 struct dm_regulator_ops {
 194         /**
 195          * The regulator output value function calls operates on a micro Volts.
 196          *
 197          * get/set_value - get/set output value of the given output number
 198          * @dev          - regulator device
 199          * Sets:
 200          * @uV           - set the output value [micro Volts]
 201          * @return output value [uV] on success or negative errno if fail.
 202          */
 203         int (*get_value)(struct udevice *dev);
 204         int (*set_value)(struct udevice *dev, int uV);
 205
 206         /**
 207          * The regulator suspend output value function calls operates
 208          * on a micro Volts.
 209          *
 210          * get/set_suspen_value - get/set suspend mode output value
 211          * @dev          - regulator device
 212          * Sets:
 213          * @uV           - set the suspend output value [micro Volts]
 214          * @return output value [uV] on success or negative errno if fail.
 215          */
 216         int (*set_suspend_value)(struct udevice *dev, int uV);
 217         int (*get_suspend_value)(struct udevice *dev);
 218
 219         /**
 220          * The regulator output current function calls operates on a micro Amps.
 221          *
 222          * get/set_current - get/set output current of the given output number
 223          * @dev            - regulator device
 224          * Sets:
 225          * @uA           - set the output current [micro Amps]
 226          * @return output value [uA] on success or negative errno if fail.
 227          */
 228         int (*get_current)(struct udevice *dev);
 229         int (*set_current)(struct udevice *dev, int uA);
 230
 231         /**
 232          * The most basic feature of the regulator output is its enable state.
 233          *
 234          * get/set_enable - get/set enable state of the given output number
 235          * @dev           - regulator device
 236          * Sets:
 237          * @enable         - set true - enable or false - disable
 238          * @return true/false for get or -errno if fail; 0 / -errno for set.
 239          */
 240         int (*get_enable)(struct udevice *dev);
 241         int (*set_enable)(struct udevice *dev, bool enable);
 242
 243         /**
 244          * The most basic feature of the regulator output is its enable state
 245          * in suspend mode.
 246          *
 247          * get/set_suspend_enable - get/set enable state of the suspend output
 248          * @dev           - regulator device
 249          * Sets:
 250          * @enable         - set true - enable or false - disable
 251          * @return true/false for get or -errno if fail; 0 / -errno for set.
 252          */
 253         int (*set_suspend_enable)(struct udevice *dev, bool enable);
 254         int (*get_suspend_enable)(struct udevice *dev);
 255
 256         /**
 257          * The 'get/set_mode()' function calls should operate on a driver-
 258          * specific mode id definitions, which should be found in:
 259          * field 'id' of struct dm_regulator_mode.
 260          *
 261          * get/set_mode - get/set operation mode of the given output number
 262          * @dev         - regulator device
 263          * Sets
 264          * @mode_id     - set output mode id (struct dm_regulator_mode->id)
 265          * @return id/0 for get/set on success or negative errno if fail.
 266          * Note:
 267          * The field 'id' of struct type 'dm_regulator_mode', should be always
 268          * a positive number, since the negative is reserved for the error.
 269          */
 270         int (*get_mode)(struct udevice *dev);
 271         int (*set_mode)(struct udevice *dev, int mode_id);
 272 };
 273
 274 #if CONFIG_IS_ENABLED(DM_REGULATOR)
 275 /**
 276  * regulator_mode: returns a pointer to the array of regulator mode info
 277  *
 278  * @dev        - pointer to the regulator device
 279  * @modep      - pointer to the returned mode info array
 280  * Return:     - count of modep entries on success or negative errno if fail.
 281  */
 282 int regulator_mode(struct udevice *dev, struct dm_regulator_mode **modep);
 283
 284 /**
 285  * regulator_get_value: get microvoltage voltage value of a given regulator
 286  *
 287  * @dev    - pointer to the regulator device
 288  * Return: - positive output value [uV] on success or negative errno if fail.
 289  */
 290 int regulator_get_value(struct udevice *dev);
 291
 292 /**
 293  * regulator_set_value: set the microvoltage value of a given regulator.
 294  *
 295  * @dev    - pointer to the regulator device
 296  * @uV     - the output value to set [micro Volts]
 297  * Return: - 0 on success or -errno val if fails
 298  */
 299 int regulator_set_value(struct udevice *dev, int uV);
 300
 301 /**
 302  * regulator_set_suspend_value: set the suspend microvoltage value of a given regulator.
 303  *
 304  * @dev    - pointer to the regulator device
 305  * @uV     - the output suspend value to set [micro Volts]
 306  * Return: - 0 on success or -errno val if fails
 307  */
 308 int regulator_set_suspend_value(struct udevice *dev, int uV);
 309
 310 /**
 311  * regulator_get_suspend_value: get the suspend microvoltage value of a given regulator.
 312  *
 313  * @dev    - pointer to the regulator device
 314  * Return: - positive output value [uV] on success or negative errno if fail.
 315  */
 316 int regulator_get_suspend_value(struct udevice *dev);
 317
 318 /**
 319  * regulator_set_value_force: set the microvoltage value of a given regulator
 320  *                            without any min-,max condition check
 321  *
 322  * @dev    - pointer to the regulator device
 323  * @uV     - the output value to set [micro Volts]
 324  * Return: - 0 on success or -errno val if fails
 325  */
 326 int regulator_set_value_force(struct udevice *dev, int uV);
 327
 328 /**
 329  * regulator_get_current: get microampere value of a given regulator
 330  *
 331  * @dev    - pointer to the regulator device
 332  * Return: - positive output current [uA] on success or negative errno if fail.
 333  */
 334 int regulator_get_current(struct udevice *dev);
 335
 336 /**
 337  * regulator_set_current: set the microampere value of a given regulator.
 338  *
 339  * @dev    - pointer to the regulator device
 340  * @uA     - set the output current [micro Amps]
 341  * Return: - 0 on success or -errno val if fails
 342  */
 343 int regulator_set_current(struct udevice *dev, int uA);
 344
 345 /**
 346  * regulator_get_enable: get regulator device enable state.
 347  *
 348  * @dev    - pointer to the regulator device
 349  * Return: - true/false of enable state or -errno val if fails
 350  */
 351 int regulator_get_enable(struct udevice *dev);
 352
 353 /**
 354  * regulator_set_enable: set regulator enable state
 355  *
 356  * @dev    - pointer to the regulator device
 357  * @enable - set true or false
 358  * Return: - 0 on success or -errno val if fails
 359  */
 360 int regulator_set_enable(struct udevice *dev, bool enable);
 361
 362 /**
 363  * regulator_set_enable_if_allowed: set regulator enable state if allowed by
 364  *                                      regulator
 365  *
 366  * @dev    - pointer to the regulator device
 367  * @enable - set true or false
 368  * Return: - 0 on success or if enabling is not supported
 369  *           -errno val if fails.
 370  */
 371 int regulator_set_enable_if_allowed(struct udevice *dev, bool enable);
 372
 373 /**
 374  * regulator_set_suspend_enable: set regulator suspend enable state
 375  *
 376  * @dev    - pointer to the regulator device
 377  * @enable - set true or false
 378  * Return: - 0 on success or -errno val if fails
 379  */
 380 int regulator_set_suspend_enable(struct udevice *dev, bool enable);
 381
 382 /**
 383  * regulator_get_suspend_enable: get regulator suspend enable state
 384  *
 385  * @dev    - pointer to the regulator device
 386  * Return: - true/false of enable state or -errno val if fails
 387  */
 388 int regulator_get_suspend_enable(struct udevice *dev);
 389
 390 /**
 391  * regulator_get_mode: get active operation mode id of a given regulator
 392  *
 393  * @dev    - pointer to the regulator device
 394  * Return: - positive mode 'id' number on success or -errno val if fails
 395  * Note:
 396  * The device can provide an array of operating modes, which is type of struct
 397  * dm_regulator_mode. Each mode has it's own 'id', which should be unique inside
 398  * that array. By calling this function, the driver should return an active mode
 399  * id of the given regulator device.
 400  */
 401 int regulator_get_mode(struct udevice *dev);
 402
 403 /**
 404  * regulator_set_mode: set the given regulator's, active mode id
 405  *
 406  * @dev     - pointer to the regulator device
 407  * @mode_id - mode id to set ('id' field of struct type dm_regulator_mode)
 408  * Return:  - 0 on success or -errno value if fails
 409  * Note:
 410  * The device can provide an array of operating modes, which is type of struct
 411  * dm_regulator_mode. Each mode has it's own 'id', which should be unique inside
 412  * that array. By calling this function, the driver should set the active mode
 413  * of a given regulator to given by "mode_id" argument.
 414  */
 415 int regulator_set_mode(struct udevice *dev, int mode_id);
 416
 417 /**
 418  * regulator_autoset: setup the voltage/current on a regulator
 419  *
 420  * The setup depends on constraints found in device's uclass's platform data
 421  * (struct dm_regulator_uclass_plat):
 422  *
 423  * - Enable - will set - if any of: 'always_on' or 'boot_on' is set to true,
 424  *   or if both are unset, then the function returns
 425  * - Voltage value - will set - if '.min_uV' and '.max_uV' values are equal
 426  * - Current limit - will set - if '.min_uA' and '.max_uA' values are equal
 427  *
 428  * The function returns on the first-encountered error.
 429  *
 430  * @platname - expected string for dm_regulator_uclass_plat .name field
 431  * @devp     - returned pointer to the regulator device - if non-NULL passed
 432  * @return: 0 on success or negative value of errno.
 433  */
 434 int regulator_autoset(struct udevice *dev);
 435
 436 /**
 437  * regulator_autoset_by_name: setup the regulator given by its uclass's
 438  * platform data name field. The setup depends on constraints found in device's
 439  * uclass's platform data (struct dm_regulator_uclass_plat):
 440  * - Enable - will set - if any of: 'always_on' or 'boot_on' is set to true,
 441  *   or if both are unset, then the function returns
 442  * - Voltage value - will set - if '.min_uV' and '.max_uV' values are equal
 443  * - Current limit - will set - if '.min_uA' and '.max_uA' values are equal
 444  *
 445  * The function returns on first encountered error.
 446  *
 447  * @platname - expected string for dm_regulator_uclass_plat .name field
 448  * @devp     - returned pointer to the regulator device - if non-NULL passed
 449  * @return: 0 on success or negative value of errno.
 450  *
 451  * The returned 'regulator' device can be used with:
 452  * - regulator_get/set_*
 453  */
 454 int regulator_autoset_by_name(const char *platname, struct udevice **devp);
 455
 456 /**
 457  * regulator_list_autoset: setup the regulators given by list of their uclass's
 458  * platform data name field. The setup depends on constraints found in device's
 459  * uclass's platform data. The function loops with calls to:
 460  * regulator_autoset_by_name() for each name from the list.
 461  *
 462  * @list_platname - an array of expected strings for .name field of each
 463  *                  regulator's uclass plat
 464  * @list_devp     - an array of returned pointers to the successfully setup
 465  *                  regulator devices if non-NULL passed
 466  * @verbose       - (true/false) print each regulator setup info, or be quiet
 467  * Return: 0 on successfully setup of all list entries, otherwise first error.
 468  *
 469  * The returned 'regulator' devices can be used with:
 470  * - regulator_get/set_*
 471  *
 472  * Note: The list must ends with NULL entry, like in the "platname" list below:
 473  * char *my_regulators[] = {
 474  *     "VCC_3.3V",
 475  *     "VCC_1.8V",
 476  *     NULL,
 477  * };
 478  */
 479 int regulator_list_autoset(const char *list_platname[],
 480                            struct udevice *list_devp[],
 481                            bool verbose);
 482
 483 /**
 484  * regulator_get_by_devname: returns the pointer to the pmic regulator device.
 485  * Search by name, found in regulator device's name.
 486  *
 487  * @devname - expected string for 'dev->name' of regulator device
 488  * @devp    - returned pointer to the regulator device
 489  * Return: 0 on success or negative value of errno.
 490  *
 491  * The returned 'regulator' device is probed and can be used with:
 492  * - regulator_get/set_*
 493  */
 494 int regulator_get_by_devname(const char *devname, struct udevice **devp);
 495
 496 /**
 497  * regulator_get_by_platname: returns the pointer to the pmic regulator device.
 498  * Search by name, found in regulator uclass plat.
 499  *
 500  * @platname - expected string for uc_pdata->name of regulator uclass plat
 501  * @devp     - returns pointer to the regulator device or NULL on error
 502  * Return: 0 on success or negative value of errno.
 503  *
 504  * The returned 'regulator' device is probed and can be used with:
 505  * - regulator_get/set_*
 506  */
 507 int regulator_get_by_platname(const char *platname, struct udevice **devp);
 508
 509 /**
 510  * device_get_supply_regulator: returns the pointer to the supply regulator.
 511  * Search by phandle, found in device's node.
 512  *
 513  * Note: Please pay attention to proper order of device bind sequence.
 514  * The regulator device searched by the phandle, must be binded before
 515  * this function call.
 516  *
 517  * @dev         - device with supply phandle
 518  * @supply_name - phandle name of regulator
 519  * @devp        - returned pointer to the supply device
 520  * Return: 0 on success or negative value of errno.
 521  */
 522 int device_get_supply_regulator(struct udevice *dev, const char *supply_name,
 523                                 struct udevice **devp);
 524 #else
 525 static inline int regulator_mode(struct udevice *dev, struct dm_regulator_mode **modep)
 526 {
 527         return -ENOSYS;
 528 }
 529
 530 static inline int regulator_get_value(struct udevice *dev)
 531 {
 532         return -ENOSYS;
 533 }
 534
 535 static inline int regulator_set_value(struct udevice *dev, int uV)
 536 {
 537         return -ENOSYS;
 538 }
 539
 540 static inline int regulator_set_suspend_value(struct udevice *dev, int uV)
 541 {
 542         return -ENOSYS;
 543 }
 544
 545 static inline int regulator_get_suspend_value(struct udevice *dev)
 546 {
 547         return -ENOSYS;
 548 }
 549
 550 static inline int regulator_set_value_force(struct udevice *dev, int uV)
 551 {
 552         return -ENOSYS;
 553 }
 554
 555 static inline int regulator_get_current(struct udevice *dev)
 556 {
 557         return -ENOSYS;
 558 }
 559
 560 static inline int regulator_set_current(struct udevice *dev, int uA)
 561 {
 562         return -ENOSYS;
 563 }
 564
 565 static inline int regulator_get_enable(struct udevice *dev)
 566 {
 567         return -ENOSYS;
 568 }
 569
 570 static inline int regulator_set_enable(struct udevice *dev, bool enable)
 571 {
 572         return -ENOSYS;
 573 }
 574
 575 static inline int regulator_set_enable_if_allowed(struct udevice *dev, bool enable)
 576 {
 577         return -ENOSYS;
 578 }
 579
 580 static inline int regulator_set_suspend_enable(struct udevice *dev, bool enable)
 581 {
 582         return -ENOSYS;
 583 }
 584
 585 static inline int regulator_get_suspend_enable(struct udevice *dev)
 586 {
 587         return -ENOSYS;
 588 }
 589
 590 static inline int regulator_get_mode(struct udevice *dev)
 591 {
 592         return -ENOSYS;
 593 }
 594
 595 static inline int regulator_set_mode(struct udevice *dev, int mode_id)
 596 {
 597         return -ENOSYS;
 598 }
 599
 600 static inline int regulator_autoset(struct udevice *dev)
 601 {
 602         return -ENOSYS;
 603 }
 604
 605 static inline int regulator_autoset_by_name(const char *platname, struct udevice **devp)
 606 {
 607         return -ENOSYS;
 608 }
 609
 610 static inline int regulator_list_autoset(const char *list_platname[], struct udevice *list_devp[],
 611                                          bool verbose)
 612 {
 613         return -ENOSYS;
 614 }
 615
 616 static inline int regulator_get_by_devname(const char *devname, struct udevice **devp)
 617 {
 618         return -ENOSYS;
 619 }
 620
 621 static inline int regulator_get_by_platname(const char *platname, struct udevice **devp)
 622 {
 623         return -ENOSYS;
 624 }
 625
 626 static inline int device_get_supply_regulator(struct udevice *dev, const char *supply_name,
 627                                                struct udevice **devp)
 628 {
 629         return -ENOSYS;
 630 }
 631 #endif
 632
 633 #endif /* _INCLUDE_REGULATOR_H_ */