Copyright © 2007-2008 Wolfson Microelectronics
Copyright © 2008 Liam Girdwood
This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
For more details see the file COPYING in the source distribution of Linux.
Table of Contents
regulator_get
regulator_get_optional
regulator_get_exclusive
regulator_put
regulator_list_voltage selectors
Table of Contents
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:
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.
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.
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.
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.
Table of Contents
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 reguator 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.
Table of Contents
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.
Table of Contents
regulator_get
regulator_get_optional
regulator_get_exclusive
regulator_put
regulator_list_voltage selectors
Due to limitations of the kernel documentation framework and the existing layout of the source code the entire regulator API is documented here.
struct regulator_bulk_data — Data used for bulk regulator operations.
struct regulator_bulk_data {
const char * supply;
struct regulator * consumer;
}; struct regulator_state — regulator state during low power system states
struct regulator_state {
int uV;
unsigned int mode;
int enabled;
int disabled;
}; struct regulation_constraints — regulator operating constraints.
struct regulation_constraints {
const char * name;
int min_uV;
int max_uV;
int uV_offset;
int min_uA;
int max_uA;
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 always_on:1;
unsigned boot_on:1;
unsigned apply_uV:1;
}; Descriptive name for the constraints, used for display purposes.
Smallest voltage consumers may set.
Largest voltage consumers may set.
Offset applied to voltages from consumer to compensate for voltage drops.
Smallest current consumers may set.
Largest current consumers may set.
Mask of modes which may be configured by consumers.
Operations which may be performed by consumers.
Input voltage for regulator when supplied by another regulator.
State for regulator when system is suspended in disk mode.
State for regulator when system is suspended in mem mode.
State for regulator when system is suspended in standby mode.
Suspend state to set by default.
Mode to set at startup.
Time to settle down after voltage change (unit: uV/us)
Set if the regulator should never be disabled.
Set if the regulator is enabled when the system is initially started. If the regulator is not enabled by the hardware or bootloader then it will be enabled when the constraints are applied.
Apply the voltage constraint when initialising.
struct regulator_consumer_supply — supply -> device mapping
struct regulator_consumer_supply {
const char * dev_name;
const char * supply;
}; struct regulator_init_data — regulator platform initialisation data.
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;
}; Parent regulator. Specified using the regulator name as it appears in the name field in sysfs, which can be explicitly set using the constraints field 'name'.
Constraints. These must be specified for the regulator to be usable.
Number of consumer device supplies.
Consumer device supply configuration.
Callback invoked when the regulator has been registered.
Data passed to regulator_init.
struct regulator_ops — regulator operations.
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 (* 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 (* enable_time) (struct regulator_dev *);
int (* set_ramp_delay) (struct regulator_dev *, int ramp_delay);
int (* set_voltage_time_sel) (struct regulator_dev *,unsigned int old_selector,unsigned int new_selector);
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_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);
}; Return one of the supported voltages, in microvolts; zero if the selector indicates a voltage that is unusable on this system; or negative errno. Selectors range from zero to one less than regulator_desc.n_voltages. Voltages may be reported in any order.
Set the voltage for the regulator within the range specified. The driver should select the voltage closest to min_uV.
Convert a voltage into a selector
Set the voltage for the regulator using the specified selector.
Return the currently configured voltage for the regulator.
Return the currently configured voltage selector for the regulator.
Configure a limit for a current-limited regulator. The driver should select the current closest to max_uA.
Get the configured limit for a current-limited regulator.
Configure the regulator as enabled.
Configure the regulator as disabled.
Return 1 if the regulator is enabled, 0 if not. May also return negative errno.
Set the configured operating mode for the regulator.
Get the configured operating mode for the regulator.
Time taken for the regulator voltage output voltage to stabilise after being enabled, in microseconds.
Set the ramp delay for the regulator. The driver should select ramp delay equal to or less than(closest) ramp_delay.
Time taken for the regulator voltage output voltage to stabilise after being set to a new value, in microseconds. The function provides the from and to voltage selector, the function should return the worst case.
Return actual (not as-configured) status of regulator, as a REGULATOR_STATUS value (or negative errno)
Get the most efficient operating mode for the regulator when running with the specified parameters.
Set the regulator in bypass mode.
Get the regulator bypass mode state.
Set the voltage for the regulator when the system is suspended.
Mark the regulator as enabled when the system is suspended.
Mark the regulator as disabled when the system is suspended.
Set the operating mode for the regulator when the system is suspended.
struct regulator_desc — Static regulator descriptor
struct regulator_desc {
const char * name;
const char * supply_name;
int id;
bool continuous_voltage_range;
unsigned n_voltages;
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;
unsigned int ramp_delay;
const unsigned int * volt_table;
unsigned int vsel_reg;
unsigned int vsel_mask;
unsigned int apply_reg;
unsigned int apply_bit;
unsigned int enable_reg;
unsigned int enable_mask;
bool enable_is_inverted;
unsigned int bypass_reg;
unsigned int bypass_mask;
unsigned int enable_time;
}; Identifying name for the regulator.
Identifying the regulator supply
Numerical identifier for the regulator.
Indicates if the regulator can set any voltage within constrains range.
Number of selectors available for ops.list_voltage.
Regulator operations table.
Interrupt number for the regulator.
Indicates if the regulator is a voltage or current regulator.
Module providing the regulator, used for refcounting.
Voltage given by the lowest selector (if linear mapping)
Voltage increase with each selector (if linear mapping)
Minimal selector for starting linear mapping
Time to settle down after voltage change (unit: uV/us)
Voltage mapping table (if table based mapping)
Register for selector when using regulator_regmap_X_voltage_
Mask for register bitfield used for selector
Register for initiate voltage change on the output when using regulator_set_voltage_sel_regmap
Register bitfield used for initiate voltage change on the output when using regulator_set_voltage_sel_regmap
Register for control when using regmap enable/disable ops
Mask for control when using regmap enable/disable ops
A flag to indicate set enable_mask bits to disable when using regulator_enable_regmap and friends APIs.
Register for control when using regmap set_bypass
Mask for control when using regmap set_bypass
Time taken for initial enable of regulator (in uS).
struct regulator_config — Dynamic regulator descriptor
struct regulator_config {
struct device * dev;
const struct regulator_init_data * init_data;
void * driver_data;
struct device_node * of_node;
struct regmap * regmap;
int ena_gpio;
unsigned int ena_gpio_invert:1;
unsigned int ena_gpio_flags;
}; struct device for the regulator
platform provided init data, passed through by driver
private regulator data
OpenFirmware node to parse for device tree bindings (may be NULL).
regmap to use for core regmap helpers if dev_get_regulator is
insufficient.
GPIO controlling regulator enable.
Sense for GPIO enable control.
Flags to use when calling gpio_request_one
regulator_get — lookup and obtain a reference to a regulator.
struct regulator * fsfuncregulator_get ( | dev, | |
id); |
struct device * dev;const char * id;
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.
devm_regulator_get —
Resource managed regulator_get
struct regulator * fsfuncdevm_regulator_get ( | dev, | |
id); |
struct device * dev;const char * id;regulator_get_exclusive — obtain exclusive access to a regulator.
struct regulator * fsfuncregulator_get_exclusive ( | dev, | |
id); |
struct device * dev;const char * id;
Returns a struct regulator corresponding to the regulator producer,
or IS_ERR condition containing errno. Other consumers will be
unable to obtain 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.
regulator_get_optional — obtain optional access to a regulator.
struct regulator * fsfuncregulator_get_optional ( | dev, | |
id); |
struct device * dev;const char * id;
Returns a struct regulator corresponding to the regulator producer,
or IS_ERR condition containing errno. Other consumers will be
unable to obtain 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 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.
devm_regulator_get_optional —
Resource managed regulator_get_optional
struct regulator * fsfuncdevm_regulator_get_optional ( | dev, | |
id); |
struct device * dev;const char * id;devm_regulator_get_exclusive —
Resource managed regulator_get_exclusive
struct regulator * fsfuncdevm_regulator_get_exclusive ( | dev, | |
id); |
struct device * dev;const char * id;regulator_put — "free" the regulator source
void fsfuncregulator_put ( | regulator); |
struct regulator * regulator;devm_regulator_put —
Resource managed regulator_put
void fsfuncdevm_regulator_put ( | regulator); |
struct regulator * regulator;regulator_enable — enable regulator output
int fsfuncregulator_enable ( | regulator); |
struct regulator * regulator;regulator_disable — disable regulator output
int fsfuncregulator_disable ( | regulator); |
struct regulator * regulator;regulator_force_disable — force disable regulator output
int fsfuncregulator_force_disable ( | regulator); |
struct regulator * regulator;regulator_disable_deferred — disable regulator output with delay
int fsfuncregulator_disable_deferred ( | regulator, | |
ms); |
struct regulator * regulator;int ms;regulator_is_enabled — is the regulator output enabled
int fsfuncregulator_is_enabled ( | regulator); |
struct regulator * regulator;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.
regulator_can_change_voltage — check if regulator can change voltage
int fsfuncregulator_can_change_voltage ( | regulator); |
struct regulator * regulator;regulator_count_voltages —
count regulator_list_voltage selectors
int fsfuncregulator_count_voltages ( | regulator); |
struct regulator * regulator;regulator_list_voltage — enumerate supported voltages
int fsfuncregulator_list_voltage ( | regulator, | |
selector); |
struct regulator * regulator;unsigned selector;regulator_get_linear_step — return the voltage step size between VSEL values
unsigned int fsfuncregulator_get_linear_step ( | regulator); |
struct regulator * regulator;regulator_is_supported_voltage — check if a voltage range can be supported
int fsfuncregulator_is_supported_voltage ( | regulator, | |
| min_uV, | ||
max_uV); |
struct regulator * regulator;int min_uV;int max_uV;regulator_set_voltage — set regulator output voltage
int fsfuncregulator_set_voltage ( | regulator, | |
| min_uV, | ||
max_uV); |
struct regulator * regulator;int min_uV;int max_uV;regulatorregulator source
min_uVMinimum required voltage in uV
max_uVMaximum acceptable voltage in uV
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.
regulator_set_voltage_time — get raise/fall time
int fsfuncregulator_set_voltage_time ( | regulator, | |
| old_uV, | ||
new_uV); |
struct regulator * regulator;int old_uV;int new_uV;regulator_set_voltage_time_sel — get raise/fall time
int fsfuncregulator_set_voltage_time_sel ( | rdev, | |
| old_selector, | ||
new_selector); |
struct regulator_dev * rdev;unsigned int old_selector;unsigned int new_selector;regulator_sync_voltage — re-apply last regulator output voltage
int fsfuncregulator_sync_voltage ( | regulator); |
struct regulator * regulator;regulator_get_voltage — get regulator output voltage
int fsfuncregulator_get_voltage ( | regulator); |
struct regulator * regulator;regulator_set_current_limit — set regulator output current limit
int fsfuncregulator_set_current_limit ( | regulator, | |
| min_uA, | ||
max_uA); |
struct regulator * regulator;int min_uA;int max_uA;regulatorregulator source
min_uAMinimum supported current in uA
max_uAMaximum supported current in uA
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.
regulator_get_current_limit — get regulator output current
int fsfuncregulator_get_current_limit ( | regulator); |
struct regulator * regulator;regulator_set_mode — set regulator operating mode
int fsfuncregulator_set_mode ( | regulator, | |
mode); |
struct regulator * regulator;unsigned int mode;regulator_get_mode — get regulator operating mode
unsigned int fsfuncregulator_get_mode ( | regulator); |
struct regulator * regulator;regulator_set_optimum_mode — set regulator optimum operating mode
int fsfuncregulator_set_optimum_mode ( | regulator, | |
uA_load); |
struct regulator * regulator;int uA_load;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
-
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.
Returns the new regulator mode or error.
regulator_allow_bypass — allow the regulator to go into bypass mode
int fsfuncregulator_allow_bypass ( | regulator, | |
enable); |
struct regulator * regulator;bool enable;regulator_register_notifier — register regulator event notifier
int fsfuncregulator_register_notifier ( | regulator, | |
nb); |
struct regulator * regulator;struct notifier_block * nb;regulator_unregister_notifier — unregister regulator event notifier
int fsfuncregulator_unregister_notifier ( | regulator, | |
nb); |
struct regulator * regulator;struct notifier_block * nb;regulator_bulk_get — get multiple regulator consumers
int fsfuncregulator_bulk_get ( | dev, | |
| num_consumers, | ||
consumers); |
struct device * dev;int num_consumers;struct regulator_bulk_data * consumers;devm_regulator_bulk_get — managed get multiple regulator consumers
int fsfuncdevm_regulator_bulk_get ( | dev, | |
| num_consumers, | ||
consumers); |
struct device * dev;int num_consumers;struct regulator_bulk_data * consumers;devDevice to supply
num_consumersNumber of consumers to register
consumersConfiguration of consumers; clients are stored here.
return 0 on success, an errno on failure.
This helper function allows drivers to get several regulator consumers in one operation with management, the regulators will automatically be freed when the device is unbound. If any of the regulators cannot be acquired then any regulators that were allocated will be freed before returning to the caller.
regulator_bulk_enable — enable multiple regulator consumers
int fsfuncregulator_bulk_enable ( | num_consumers, | |
consumers); |
int num_consumers;struct regulator_bulk_data * consumers;regulator_bulk_disable — disable multiple regulator consumers
int fsfuncregulator_bulk_disable ( | num_consumers, | |
consumers); |
int num_consumers;struct regulator_bulk_data * consumers;regulator_bulk_force_disable — force disable multiple regulator consumers
int fsfuncregulator_bulk_force_disable ( | num_consumers, | |
consumers); |
int num_consumers;struct regulator_bulk_data * consumers;num_consumersNumber of consumers
consumers
Consumer data; clients are stored here.
return 0 on success, an errno on failure
regulator_bulk_free — free multiple regulator consumers
void fsfuncregulator_bulk_free ( | num_consumers, | |
consumers); |
int num_consumers;struct regulator_bulk_data * consumers;regulator_notifier_call_chain — call regulator event notifier
int fsfuncregulator_notifier_call_chain ( | rdev, | |
| event, | ||
data); |
struct regulator_dev * rdev;unsigned long event;void * data;regulator_mode_to_status — convert a regulator mode into a status
int fsfuncregulator_mode_to_status ( | mode); |
unsigned int mode;regulator_register — register regulator
struct regulator_dev * fsfuncregulator_register ( | regulator_desc, | |
config); |
const struct regulator_desc * regulator_desc;const struct regulator_config * config;regulator_unregister — unregister regulator
void fsfuncregulator_unregister ( | rdev); |
struct regulator_dev * rdev;regulator_suspend_prepare — prepare regulators for system wide suspend
int fsfuncregulator_suspend_prepare ( | state); |
suspend_state_t state;regulator_suspend_finish — resume regulators from system wide suspend
int fsfuncregulator_suspend_finish ( | void); |
void;regulator_has_full_constraints — the system has fully specified constraints
void fsfuncregulator_has_full_constraints ( | void); |
void;
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.
regulator_use_dummy_regulator — Provide a dummy regulator when none is found
void fsfuncregulator_use_dummy_regulator ( | void); |
void;
Calling this function will cause the regulator API to provide a dummy regulator to consumers if no physical regulator is found, allowing most consumers to proceed as though a regulator were configured. This allows systems such as those with software controllable regulators for the CPU core only to be brought up more readily.
rdev_get_drvdata — get rdev regulator driver data
void * fsfuncrdev_get_drvdata ( | rdev); |
struct regulator_dev * rdev;regulator_get_drvdata — get regulator driver data
void * fsfuncregulator_get_drvdata ( | regulator); |
struct regulator * regulator;