linux/regulator/machine.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * machine.h -- SoC Regulator support, machine/board driver API.
0004  *
0005  * Copyright (C) 2007, 2008 Wolfson Microelectronics PLC.
0006  *
0007  * Author: Liam Girdwood <lrg@slimlogic.co.uk>
0008  *
0009  * Regulator Machine/Board Interface.
0010  */
0011
0012 #ifndef __LINUX_REGULATOR_MACHINE_H_
0013 #define __LINUX_REGULATOR_MACHINE_H_
0014
0015 #include <linux/regulator/consumer.h>
0016 #include <linux/suspend.h>
0017
0018 struct regulator;
0019
0020 /*
0021  * Regulator operation constraint flags. These flags are used to enable
0022  * certain regulator operations and can be OR'ed together.
0023  *
0024  * VOLTAGE:  Regulator output voltage can be changed by software on this
0025  *           board/machine.
0026  * CURRENT:  Regulator output current can be changed by software on this
0027  *           board/machine.
0028  * MODE:     Regulator operating mode can be changed by software on this
0029  *           board/machine.
0030  * STATUS:   Regulator can be enabled and disabled.
0031  * DRMS:     Dynamic Regulator Mode Switching is enabled for this regulator.
0032  * BYPASS:   Regulator can be put into bypass mode
0033  */
0034
0035 #define REGULATOR_CHANGE_VOLTAGE    0x1
0036 #define REGULATOR_CHANGE_CURRENT    0x2
0037 #define REGULATOR_CHANGE_MODE       0x4
0038 #define REGULATOR_CHANGE_STATUS     0x8
0039 #define REGULATOR_CHANGE_DRMS       0x10
0040 #define REGULATOR_CHANGE_BYPASS     0x20
0041
0042 /*
0043  * operations in suspend mode
0044  * DO_NOTHING_IN_SUSPEND - the default value
0045  * DISABLE_IN_SUSPEND   - turn off regulator in suspend states
0046  * ENABLE_IN_SUSPEND    - keep regulator on in suspend states
0047  */
0048 #define DO_NOTHING_IN_SUSPEND   0
0049 #define DISABLE_IN_SUSPEND  1
0050 #define ENABLE_IN_SUSPEND   2
0051
0052 /* Regulator active discharge flags */
0053 enum regulator_active_discharge {
0054     REGULATOR_ACTIVE_DISCHARGE_DEFAULT,
0055     REGULATOR_ACTIVE_DISCHARGE_DISABLE,
0056     REGULATOR_ACTIVE_DISCHARGE_ENABLE,
0057 };
0058
0059 /**
0060  * struct regulator_state - regulator state during low power system states
0061  *
0062  * This describes a regulators state during a system wide low power
0063  * state.  One of enabled or disabled must be set for the
0064  * configuration to be applied.
0065  *
0066  * @uV: Default operating voltage during suspend, it can be adjusted
0067  *  among <min_uV, max_uV>.
0068  * @min_uV: Minimum suspend voltage may be set.
0069  * @max_uV: Maximum suspend voltage may be set.
0070  * @mode: Operating mode during suspend.
0071  * @enabled: operations during suspend.
0072  *       - DO_NOTHING_IN_SUSPEND
0073  *       - DISABLE_IN_SUSPEND
0074  *       - ENABLE_IN_SUSPEND
0075  * @changeable: Is this state can be switched between enabled/disabled,
0076  */
0077 struct regulator_state {
0078     int uV;
0079     int min_uV;
0080     int max_uV;
0081     unsigned int mode;
0082     int enabled;
0083     bool changeable;
0084 };
0085
0086 #define REGULATOR_NOTIF_LIMIT_DISABLE -1
0087 #define REGULATOR_NOTIF_LIMIT_ENABLE -2
0088 struct notification_limit {
0089     int prot;
0090     int err;
0091     int warn;
0092 };
0093
0094 /**
0095  * struct regulation_constraints - regulator operating constraints.
0096  *
0097  * This struct describes regulator and board/machine specific constraints.
0098  *
0099  * @name: Descriptive name for the constraints, used for display purposes.
0100  *
0101  * @min_uV: Smallest voltage consumers may set.
0102  * @max_uV: Largest voltage consumers may set.
0103  * @uV_offset: Offset applied to voltages from consumer to compensate for
0104  *             voltage drops.
0105  *
0106  * @min_uA: Smallest current consumers may set.
0107  * @max_uA: Largest current consumers may set.
0108  * @ilim_uA: Maximum input current.
0109  * @system_load: Load that isn't captured by any consumer requests.
0110  *
0111  * @over_curr_limits:       Limits for acting on over current.
0112  * @over_voltage_limits:    Limits for acting on over voltage.
0113  * @under_voltage_limits:   Limits for acting on under voltage.
0114  * @temp_limits:        Limits for acting on over temperature.
0115  *
0116  * @max_spread: Max possible spread between coupled regulators
0117  * @max_uV_step: Max possible step change in voltage
0118  * @valid_modes_mask: Mask of modes which may be configured by consumers.
0119  * @valid_ops_mask: Operations which may be performed by consumers.
0120  *
0121  * @always_on: Set if the regulator should never be disabled.
0122  * @boot_on: Set if the regulator is enabled when the system is initially
0123  *           started.  If the regulator is not enabled by the hardware or
0124  *           bootloader then it will be enabled when the constraints are
0125  *           applied.
0126  * @apply_uV: Apply the voltage constraint when initialising.
0127  * @ramp_disable: Disable ramp delay when initialising or when setting voltage.
0128  * @soft_start: Enable soft start so that voltage ramps slowly.
0129  * @pull_down: Enable pull down when regulator is disabled.
0130  * @over_current_protection: Auto disable on over current event.
0131  *
0132  * @over_current_detection: Configure over current limits.
0133  * @over_voltage_detection: Configure over voltage limits.
0134  * @under_voltage_detection: Configure under voltage limits.
0135  * @over_temp_detection: Configure over temperature limits.
0136  *
0137  * @input_uV: Input voltage for regulator when supplied by another regulator.
0138  *
0139  * @state_disk: State for regulator when system is suspended in disk mode.
0140  * @state_mem: State for regulator when system is suspended in mem mode.
0141  * @state_standby: State for regulator when system is suspended in standby
0142  *                 mode.
0143  * @initial_state: Suspend state to set by default.
0144  * @initial_mode: Mode to set at startup.
0145  * @ramp_delay: Time to settle down after voltage change (unit: uV/us)
0146  * @settling_time: Time to settle down after voltage change when voltage
0147  *         change is non-linear (unit: microseconds).
0148  * @settling_time_up: Time to settle down after voltage increase when voltage
0149  *            change is non-linear (unit: microseconds).
0150  * @settling_time_down : Time to settle down after voltage decrease when
0151  *           voltage change is non-linear (unit: microseconds).
0152  * @active_discharge: Enable/disable active discharge. The enum
0153  *            regulator_active_discharge values are used for
0154  *            initialisation.
0155  * @enable_time: Turn-on time of the rails (unit: microseconds)
0156  */
0157 struct regulation_constraints {
0158
0159     const char *name;
0160
0161     /* voltage output range (inclusive) - for voltage control */
0162     int min_uV;
0163     int max_uV;
0164
0165     int uV_offset;
0166
0167     /* current output range (inclusive) - for current control */
0168     int min_uA;
0169     int max_uA;
0170     int ilim_uA;
0171
0172     int system_load;
0173
0174     /* used for coupled regulators */
0175     u32 *max_spread;
0176
0177     /* used for changing voltage in steps */
0178     int max_uV_step;
0179
0180     /* valid regulator operating modes for this machine */
0181     unsigned int valid_modes_mask;
0182
0183     /* valid operations for regulator on this machine */
0184     unsigned int valid_ops_mask;
0185
0186     /* regulator input voltage - only if supply is another regulator */
0187     int input_uV;
0188
0189     /* regulator suspend states for global PMIC STANDBY/HIBERNATE */
0190     struct regulator_state state_disk;
0191     struct regulator_state state_mem;
0192     struct regulator_state state_standby;
0193     struct notification_limit over_curr_limits;
0194     struct notification_limit over_voltage_limits;
0195     struct notification_limit under_voltage_limits;
0196     struct notification_limit temp_limits;
0197     suspend_state_t initial_state; /* suspend state to set at init */
0198
0199     /* mode to set on startup */
0200     unsigned int initial_mode;
0201
0202     unsigned int ramp_delay;
0203     unsigned int settling_time;
0204     unsigned int settling_time_up;
0205     unsigned int settling_time_down;
0206     unsigned int enable_time;
0207
0208     unsigned int active_discharge;
0209
0210     /* constraint flags */
0211     unsigned always_on:1;   /* regulator never off when system is on */
0212     unsigned boot_on:1; /* bootloader/firmware enabled regulator */
0213     unsigned apply_uV:1;    /* apply uV constraint if min == max */
0214     unsigned ramp_disable:1; /* disable ramp delay */
0215     unsigned soft_start:1;  /* ramp voltage slowly */
0216     unsigned pull_down:1;   /* pull down resistor when regulator off */
0217     unsigned over_current_protection:1; /* auto disable on over current */
0218     unsigned over_current_detection:1; /* notify on over current */
0219     unsigned over_voltage_detection:1; /* notify on over voltage */
0220     unsigned under_voltage_detection:1; /* notify on under voltage */
0221     unsigned over_temp_detection:1; /* notify on over temperature */
0222 };
0223
0224 /**
0225  * struct regulator_consumer_supply - supply -> device mapping
0226  *
0227  * This maps a supply name to a device. Use of dev_name allows support for
0228  * buses which make struct device available late such as I2C.
0229  *
0230  * @dev_name: Result of dev_name() for the consumer.
0231  * @supply: Name for the supply.
0232  */
0233 struct regulator_consumer_supply {
0234     const char *dev_name;   /* dev_name() for consumer */
0235     const char *supply; /* consumer supply - e.g. "vcc" */
0236 };
0237
0238 /* Initialize struct regulator_consumer_supply */
0239 #define REGULATOR_SUPPLY(_name, _dev_name)          \
0240 {                               \
0241     .supply     = _name,                \
0242     .dev_name   = _dev_name,                \
0243 }
0244
0245 /**
0246  * struct regulator_init_data - regulator platform initialisation data.
0247  *
0248  * Initialisation constraints, our supply and consumers supplies.
0249  *
0250  * @supply_regulator: Parent regulator.  Specified using the regulator name
0251  *                    as it appears in the name field in sysfs, which can
0252  *                    be explicitly set using the constraints field 'name'.
0253  *
0254  * @constraints: Constraints.  These must be specified for the regulator to
0255  *               be usable.
0256  * @num_consumer_supplies: Number of consumer device supplies.
0257  * @consumer_supplies: Consumer device supply configuration.
0258  *
0259  * @regulator_init: Callback invoked when the regulator has been registered.
0260  * @driver_data: Data passed to regulator_init.
0261  */
0262 struct regulator_init_data {
0263     const char *supply_regulator;        /* or NULL for system supply */
0264
0265     struct regulation_constraints constraints;
0266
0267     int num_consumer_supplies;
0268     struct regulator_consumer_supply *consumer_supplies;
0269
0270     /* optional regulator machine specific init */
0271     int (*regulator_init)(void *driver_data);
0272     void *driver_data;  /* core does not touch this */
0273 };
0274
0275 #ifdef CONFIG_REGULATOR
0276 void regulator_has_full_constraints(void);
0277 #else
0278 static inline void regulator_has_full_constraints(void)
0279 {
0280 }
0281 #endif
0282
0283 static inline int regulator_suspend_prepare(suspend_state_t state)
0284 {
0285     return 0;
0286 }
0287 static inline int regulator_suspend_finish(void)
0288 {
0289     return 0;
0290 }
0291
0292 #endif