| Author: | Liam Girdwood |
|---|---|
| Author: | Mark Brown |
This framework is designed to provide a standard kernel interface to control voltage and current regulators.
The intention is to allow systems to dynamically control regulator power output in order to save power and prolong battery life. This applies to both voltage regulators (where voltage output is controllable) and current sinks (where current limit is controllable).
Note that additional (and currently more complete) documentation is available in the Linux kernel source under Documentation/power/regulator.
The regulator API uses a number of terms which may not be familiar:
Regulator
Electronic device that supplies power to other devices. Most regulators can enable and disable their output and some can also control their output voltage or current.
Consumer
Electronic device which consumes power provided by a regulator. These may either be static, requiring only a fixed supply, or dynamic, requiring active management of the regulator at runtime.
Power Domain
The electronic circuit supplied by a given regulator, including the regulator and all consumer devices. The configuration of the regulator is shared between all the components in the circuit.
Power Management Integrated Circuit (PMIC)
An IC which contains numerous regulators and often also other subsystems. In an embedded system the primary PMIC is often equivalent to a combination of the PSU and southbridge in a desktop system.
This offers a similar API to the kernel clock framework. Consumer drivers use get and put operations to acquire and release regulators. Functions are provided to enable and disable the regulator and to get and set the runtime parameters of the regulator.
When requesting regulators consumers use symbolic names for their supplies, such as “Vcc”, which are mapped into actual regulator devices by the machine interface.
A stub version of this API is provided when the regulator framework is not in use in order to minimise the need to use ifdefs.
The regulator API provides reference counted enabling and disabling of regulators. Consumer devices use the regulator_enable() and regulator_disable() functions to enable and disable regulators. Calls to the two functions must be balanced.
Note that since multiple consumers may be using a regulator and machine constraints may not allow the regulator to be disabled there is no guarantee that calling regulator_disable() will actually cause the supply provided by the regulator to be disabled. Consumer drivers should assume that the regulator may be enabled at all times.
Some consumer devices may need to be able to dynamically configure their supplies. For example, MMC drivers may need to select the correct operating voltage for their cards. This may be done while the regulator is enabled or disabled.
The regulator_set_voltage() and regulator_set_current_limit() functions provide the primary interface for this. Both take ranges of voltages and currents, supporting drivers that do not require a specific value (eg, CPU frequency scaling normally permits the CPU to use a wider range of supply voltages at lower frequencies but does not require that the supply voltage be lowered). Where an exact value is required both minimum and maximum values should be identical.
Callbacks may also be registered for events such as regulation failures.
Drivers for regulator chips register the regulators with the regulator core, providing operations structures to the core. A notifier interface allows error conditions to be reported to the core.
Registration should be triggered by explicit setup done by the platform, supplying a struct regulator_init_data for the regulator containing constraint and supply information.
This interface provides a way to define how regulators are connected to consumers on a given system and what the valid operating parameters are for the system.
Regulator supplies are specified using struct regulator_consumer_supply. This is done at driver registration time as part of the machine constraints.
As well as defining the connections the machine interface also provides constraints defining the operations that clients are allowed to perform and the parameters that may be set. This is required since generally regulator devices will offer more flexibility than it is safe to use on a given system, for example supporting higher supply voltages than the consumers are rated for.
This is done at driver registration time` by providing a struct regulation_constraints.
The constraints may also specify an initial configuration for the regulator in the constraints, which is particularly useful for use with static consumers.
Due to limitations of the kernel documentation framework and the existing layout of the source code the entire regulator API is documented here.
Data sent with PRE_VOLTAGE_CHANGE event
Definition
struct pre_voltage_change_data {
unsigned long old_uV;
unsigned long min_uV;
unsigned long max_uV;
};
Members
Data used for bulk regulator operations.
Definition
struct regulator_bulk_data {
const char * supply;
struct regulator * consumer;
};
Members
Description
The regulator APIs provide a series of regulator_bulk_() API calls as a convenience to consumers which require multiple supplies. This structure is used to manage data for these calls.
regulator state during low power system states
Definition
struct regulator_state {
int uV;
unsigned int mode;
int enabled;
int disabled;
};
Members
Description
This describes a regulators state during a system wide low power state. One of enabled or disabled must be set for the configuration to be applied.
regulator operating constraints.
Definition
struct regulation_constraints {
const char * name;
int min_uV;
int max_uV;
int uV_offset;
int min_uA;
int max_uA;
int ilim_uA;
int system_load;
unsigned int valid_modes_mask;
unsigned int valid_ops_mask;
int input_uV;
struct regulator_state state_disk;
struct regulator_state state_mem;
struct regulator_state state_standby;
suspend_state_t initial_state;
unsigned int initial_mode;
unsigned int ramp_delay;
unsigned int enable_time;
unsigned int active_discharge;
unsigned always_on:1;
unsigned boot_on:1;
unsigned apply_uV:1;
unsigned ramp_disable:1;
unsigned soft_start:1;
unsigned pull_down:1;
unsigned over_current_protection:1;
};
Members
Description
This struct describes regulator and board/machine specific constraints.
supply -> device mapping
Definition
struct regulator_consumer_supply {
const char * dev_name;
const char * supply;
};
Members
Description
This maps a supply name to a device. Use of dev_name allows support for buses which make struct device available late such as I2C.
regulator platform initialisation data.
Definition
struct regulator_init_data {
const char * supply_regulator;
struct regulation_constraints constraints;
int num_consumer_supplies;
struct regulator_consumer_supply * consumer_supplies;
int (* regulator_init) (void *driver_data);
void * driver_data;
};
Members
Description
Initialisation constraints, our supply and consumers supplies.
specify linear voltage ranges
Definition
struct regulator_linear_range {
unsigned int min_uV;
unsigned int min_sel;
unsigned int max_sel;
unsigned int uV_step;
};
Members
Description
Specify a range of voltages for regulator_map_linar_range() and regulator_list_linear_range().
regulator operations.
Definition
struct regulator_ops {
int (* list_voltage) (struct regulator_dev *, unsigned selector);
int (* set_voltage) (struct regulator_dev *, int min_uV, int max_uV,unsigned *selector);
int (* map_voltage) (struct regulator_dev *, int min_uV, int max_uV);
int (* set_voltage_sel) (struct regulator_dev *, unsigned selector);
int (* get_voltage) (struct regulator_dev *);
int (* get_voltage_sel) (struct regulator_dev *);
int (* set_current_limit) (struct regulator_dev *,int min_uA, int max_uA);
int (* get_current_limit) (struct regulator_dev *);
int (* set_input_current_limit) (struct regulator_dev *, int lim_uA);
int (* set_over_current_protection) (struct regulator_dev *);
int (* set_active_discharge) (struct regulator_dev *, bool enable);
int (* enable) (struct regulator_dev *);
int (* disable) (struct regulator_dev *);
int (* is_enabled) (struct regulator_dev *);
int (* set_mode) (struct regulator_dev *, unsigned int mode);
unsigned int (* get_mode) (struct regulator_dev *);
int (* get_error_flags) (struct regulator_dev *, unsigned int *flags);
int (* enable_time) (struct regulator_dev *);
int (* set_ramp_delay) (struct regulator_dev *, int ramp_delay);
int (* set_voltage_time) (struct regulator_dev *, int old_uV,int new_uV);
int (* set_voltage_time_sel) (struct regulator_dev *,unsigned int old_selector,unsigned int new_selector);
int (* set_soft_start) (struct regulator_dev *);
int (* get_status) (struct regulator_dev *);
unsigned int (* get_optimum_mode) (struct regulator_dev *, int input_uV,int output_uV, int load_uA);
int (* set_load) (struct regulator_dev *, int load_uA);
int (* set_bypass) (struct regulator_dev *dev, bool enable);
int (* get_bypass) (struct regulator_dev *dev, bool *enable);
int (* set_suspend_voltage) (struct regulator_dev *, int uV);
int (* set_suspend_enable) (struct regulator_dev *);
int (* set_suspend_disable) (struct regulator_dev *);
int (* set_suspend_mode) (struct regulator_dev *, unsigned int mode);
int (* set_pull_down) (struct regulator_dev *);
};
Members
Description
This struct describes regulator operations which can be implemented by regulator chip drivers.
Static regulator descriptor
Definition
struct regulator_desc {
const char * name;
const char * supply_name;
const char * of_match;
const char * regulators_node;
int (* of_parse_cb) (struct device_node *,const struct regulator_desc *,struct regulator_config *);
int id;
unsigned int continuous_voltage_range:1;
unsigned n_voltages;
const struct regulator_ops * ops;
int irq;
enum regulator_type type;
struct module * owner;
unsigned int min_uV;
unsigned int uV_step;
unsigned int linear_min_sel;
int fixed_uV;
unsigned int ramp_delay;
int min_dropout_uV;
const struct regulator_linear_range * linear_ranges;
int n_linear_ranges;
const unsigned int * volt_table;
unsigned int vsel_reg;
unsigned int vsel_mask;
unsigned int csel_reg;
unsigned int csel_mask;
unsigned int apply_reg;
unsigned int apply_bit;
unsigned int enable_reg;
unsigned int enable_mask;
unsigned int enable_val;
unsigned int disable_val;
bool enable_is_inverted;
unsigned int bypass_reg;
unsigned int bypass_mask;
unsigned int bypass_val_on;
unsigned int bypass_val_off;
unsigned int active_discharge_on;
unsigned int active_discharge_off;
unsigned int active_discharge_mask;
unsigned int active_discharge_reg;
unsigned int enable_time;
unsigned int off_on_delay;
unsigned int (* of_map_mode) (unsigned int mode);
};
Members
Description
Each regulator registered with the core is described with a structure of this type and a struct regulator_config. This structure contains the non-varying parts of the regulator description.
Dynamic regulator descriptor
Definition
struct regulator_config {
struct device * dev;
const struct regulator_init_data * init_data;
void * driver_data;
struct device_node * of_node;
struct regmap * regmap;
bool ena_gpio_initialized;
int ena_gpio;
unsigned int ena_gpio_invert:1;
unsigned int ena_gpio_flags;
};
Members
Description
Each regulator registered with the core is described with a structure of this type and a struct regulator_desc. This structure contains the runtime variable parts of the regulator description.
lookup and obtain a reference to a regulator.
Parameters
Description
Returns a struct regulator corresponding to the regulator producer, or IS_ERR() condition containing errno.
Use of supply names configured via regulator_set_device_supply() is strongly encouraged. It is recommended that the supply name used should match the name used for the supply and/or the relevant device pins in the datasheet.
obtain exclusive access to a regulator.
Parameters
Description
Returns a struct regulator corresponding to the regulator producer, or IS_ERR() condition containing errno. Other consumers will be unable to obtain this regulator while this reference is held and the use count for the regulator will be initialised to reflect the current state of the regulator.
This is intended for use by consumers which cannot tolerate shared use of the regulator such as those which need to force the regulator off for correct operation of the hardware they are controlling.
Use of supply names configured via regulator_set_device_supply() is strongly encouraged. It is recommended that the supply name used should match the name used for the supply and/or the relevant device pins in the datasheet.
obtain optional access to a regulator.
Parameters
Description
Returns a struct regulator corresponding to the regulator producer, or IS_ERR() condition containing errno.
This is intended for use by consumers for devices which can have some supplies unconnected in normal use, such as some MMC devices. It can allow the regulator core to provide stub supplies for other supplies requested using normal regulator_get() calls without disrupting the operation of drivers that can handle absent supplies.
Use of supply names configured via regulator_set_device_supply() is strongly encouraged. It is recommended that the supply name used should match the name used for the supply and/or the relevant device pins in the datasheet.
“free” the regulator source
Parameters
Note
drivers must ensure that all regulator_enable calls made on this regulator source are balanced by regulator_disable calls prior to calling this function.
Provide device alias for supply lookup
Parameters
Description
All lookups for id on dev will instead be conducted for alias_id on alias_dev.
Parameters
Description
Remove a lookup alias if one exists for id on dev.
register multiple aliases
Parameters
Description
return 0 on success, an errno on failure.
This helper function allows drivers to register several supply aliases in one operation. If any of the aliases cannot be registered any aliases that were registered will be removed before returning to the caller.
unregister multiple aliases
Parameters
Description
This helper function allows drivers to unregister several supply aliases in one operation.
enable regulator output
Parameters
Description
Request that the regulator be enabled with the regulator output at the predefined voltage or current value. Calls to regulator_enable() must be balanced with calls to regulator_disable().
NOTE
the output value can be set by other drivers, boot loader or may be hardwired in the regulator.
disable regulator output
Parameters
Description
Disable the regulator output voltage or current. Calls to regulator_enable() must be balanced with calls to regulator_disable().
NOTE
this will only disable the regulator output if no other consumer devices have it enabled, the regulator device supports disabling and machine constraints permit this operation.
force disable regulator output
Parameters
Description
Forcibly disable the regulator output voltage or current.
NOTE
this will disable the regulator output even if other consumer devices have it enabled. This should be used for situations when device damage will likely occur if the regulator is not disabled (e.g. over temp).
disable regulator output with delay
Parameters
Description
Execute regulator_disable() on the regulator after a delay. This is intended for use with devices that require some time to quiesce.
NOTE
this will only disable the regulator output if no other consumer devices have it enabled, the regulator device supports disabling and machine constraints permit this operation.
is the regulator output enabled
Parameters
Description
Returns positive if the regulator driver backing the source/client has requested that the device be enabled, zero if it hasn’t, else a negative errno code.
Note that the device backing this regulator handle can have multiple users, so it might be enabled even if regulator_enable() was never called for this particular source.
count regulator_list_voltage() selectors
Parameters
Description
Returns number of selectors, or negative errno. Selectors are numbered starting at zero, and typically correspond to bitfields in hardware registers.
enumerate supported voltages
Parameters
Context
can sleep
Description
Returns a voltage that can be passed to regulator_set_voltage(), zero if this selector code can’t be used on this system, or a negative errno.
get the HW voltage selector register
Parameters
Description
Returns the hardware register offset and bitmask used for setting the regulator voltage. This might be useful when configuring voltage-scaling hardware or firmware that can make I2C requests behind the kernel’s back, for example.
On success, the output parameters vsel_reg and vsel_mask are filled in and 0 is returned, otherwise a negative errno is returned.
get the HW-specific register value for a selector
Parameters
Description
Converts the selector to a hardware-specific voltage selector that can be directly written to the regulator registers. The address of the voltage register can be determined by calling regulator_get_hardware_vsel_register.
On error a negative errno is returned.
return the voltage step size between VSEL values
Parameters
Description
Returns the voltage step size between VSEL values for linear regulators, or return 0 if the regulator isn’t a linear regulator.
check if a voltage range can be supported
Parameters
Description
Returns a boolean or a negative error code.
set regulator output voltage
Parameters
Description
Sets a voltage regulator to the desired output voltage. This can be set during any regulator state. IOW, regulator can be disabled or enabled.
If the regulator is enabled then the voltage will change to the new value immediately otherwise if the regulator is disabled the regulator will output at the new voltage when enabled.
NOTE
If the regulator is shared between several devices then the lowest request voltage that meets the system constraints will be used. Regulator system constraints must be set for this regulator before calling this function otherwise this call will fail.
get raise/fall time
Parameters
Description
Provided with the starting and ending voltage, this function attempts to calculate the time in microseconds required to rise or fall to this new voltage.
get raise/fall time
Parameters
Description
Provided with the starting and target voltage selectors, this function returns time in microseconds required to rise or fall to this new voltage
Drivers providing ramp_delay in regulation_constraints can use this as their set_voltage_time_sel() operation.
re-apply last regulator output voltage
Parameters
Description
Re-apply the last configured voltage. This is intended to be used where some external control source the consumer is cooperating with has caused the configured voltage to change.
get regulator output voltage
Parameters
Description
This returns the current regulator voltage in uV.
NOTE
If the regulator is disabled it will return the voltage value. This function should not be used to determine regulator state.
set regulator output current limit
Parameters
Description
Sets current sink to the desired output current. This can be set during any regulator state. IOW, regulator can be disabled or enabled.
If the regulator is enabled then the current will change to the new value immediately otherwise if the regulator is disabled the regulator will output at the new current when enabled.
NOTE
Regulator system constraints must be set for this regulator before calling this function otherwise this call will fail.
get regulator output current
Parameters
Description
This returns the current supplied by the specified current sink in uA.
NOTE
If the regulator is disabled it will return the current value. This function should not be used to determine regulator state.
set regulator operating mode
Parameters
Description
Set regulator operating mode to increase regulator efficiency or improve regulation performance.
NOTE
Regulator system constraints must be set for this regulator before calling this function otherwise this call will fail.
get regulator operating mode
Parameters
Description
Get the current regulator operating mode.
get regulator error information
Parameters
Description
Get the current regulator error information.
set regulator load
Parameters
Description
Notifies the regulator core of a new device load. This is then used by DRMS (if enabled by constraints) to set the most efficient regulator operating mode for the new regulator loading.
Consumer devices notify their supply regulator of the maximum power they will require (can be taken from device datasheet in the power consumption tables) when they change operational status and hence power state. Examples of operational state changes that can affect power consumption are :-
o Device is opened / closed. o Device I/O is about to begin or has just finished. o Device is idling in between work.
This information is also exported via sysfs to userspace.
DRMS will sum the total requested load on the regulator and change to the most efficient operating mode if platform constraints allow.
On error a negative errno is returned.
allow the regulator to go into bypass mode
Parameters
Description
Allow the regulator to go into bypass mode if all other consumers for the regulator also enable bypass mode and the machine constraints allow this. Bypass mode means that the regulator is simply passing the input directly to the output with no regulation.
register regulator event notifier
Parameters
Description
Register notifier block to receive regulator events.
unregister regulator event notifier
Parameters
Description
Unregister regulator event notifier block.
get multiple regulator consumers
Parameters
Description
return 0 on success, an errno on failure.
This helper function allows drivers to get several regulator consumers in one operation. If any of the regulators cannot be acquired then any regulators that were allocated will be freed before returning to the caller.
enable multiple regulator consumers
Parameters
Description
This convenience API allows consumers to enable multiple regulator clients in a single API call. If any consumers cannot be enabled then any others that were enabled will be disabled again prior to return.
disable multiple regulator consumers
Parameters
Description
This convenience API allows consumers to disable multiple regulator clients in a single API call. If any consumers cannot be disabled then any others that were disabled will be enabled again prior to return.
force disable multiple regulator consumers
Parameters
Description
This convenience API allows consumers to forcibly disable multiple regulator clients in a single API call.
NOTE
This should be used for situations when device damage will likely occur if the regulators are not disabled (e.g. over temp). Although regulator_force_disable function call for some consumers can return error numbers, the function is called for all consumers.
free multiple regulator consumers
Parameters
Description
This convenience API allows consumers to free multiple regulator clients in a single API call.
call regulator event notifier
Parameters
Description
Called by regulator drivers to notify clients a regulator event has occurred. We also notify regulator clients downstream. Note lock must be held by caller.
convert a regulator mode into a status
Parameters
Description
Convert a regulator mode into a status.
register regulator
Parameters
Description
Called by regulator drivers to register a regulator. Returns a valid pointer to struct regulator_dev on success or an ERR_PTR() on error.
unregister regulator
Parameters
Description
Called by regulator drivers to unregister a regulator.
prepare regulators for system wide suspend
Parameters
Description
Configure each regulator with it’s suspend operating parameters for state. This will usually be called by machine suspend code prior to supending.
resume regulators from system wide suspend
Parameters
Description
Turn on regulators that might be turned off by regulator_suspend_prepare and that should be turned on according to the regulators properties.
the system has fully specified constraints
Parameters
Description
Calling this function will cause the regulator API to disable all regulators which have a zero use count and don’t have an always_on constraint in a late_initcall.
The intention is that this will become the default behaviour in a future kernel release so users are encouraged to use this facility now.
get rdev regulator driver data
Parameters
Description
Get rdev regulator driver private data. This call can be used in the regulator driver context.
get regulator driver data
Parameters
Description
Get regulator driver private data. This call can be used in the consumer driver context when non API regulator specific functions need to be called.
set regulator driver data
Parameters
get regulator ID
Parameters