The regulator module controls the voltage and current supplies of some devices in the system. In an embedded system (especially a mobile phone), it is important to control the power consumption, which directly affects the battery endurance. You can use a regulator to shut down the power supply to an idle module in the system or reduce the voltage and current for the module.
The regulator APIs provide a set of methods for managing a regulator, including those for:
- The regulator APIs provide a set of functions for managing a regulator, including those for:
- Opening or closing a regulator device handle
- Setting the output voltage and current for a regulator
- Enabling or disabling a regulator
- Obtaining the voltage, current, and status of a regulator
## Available APIs<a name="section2_REGULATOR_des"></a>
### How to Use<a name="section3.1_REGULATOR_des"></a>
- Opening or closing a regulator device handle
- Setting the output voltage and current for a regulator
- Enabling or disabling a regulator
- Obtaining the voltage, current, and status of a regulator
During the OS startup process, the driver management module loads the regulator driver based on the configuration file. Then, the regulator driver detects the regulator devices and initializes the driver.
The figure below shows the process of using a regulator.
### Basic Concepts
- Calibrator
Software used to maintain stable output voltage when the output load is different from the input voltage.
- Consumer
The devices served by the regulator are called consumers. Consumers are classified into the following:
* Static consumer: Only the power needs to be turned on or off for this type of consumers. The voltage and current do not need to be changed. Generally, the consumers are set in the bootloader, firmware, and kernel board phases.
* Dynamic consumer: The voltage and current need to be changed based on operation requirements for this type of consumers.
- Power Management IC (PMIC)
Power management chipset provides efficient, reliable, and safe voltage regulation.
### Working Principles
In the Hardware Driver Foundation (HDF), the regulator module uses the unified service mode for API adaptation. In this mode, a device service is used as the regulator manager to handle external access requests in a unified manner, which is reflected in the configuration file. The unified service mode applies to the scenario where there are many device objects of the same type, for example, when the regulator has more than 10 controllers. If the independent service mode is used, more device nodes need to be configured and more memory resources will be consumed by services.
The regulator module is divided into the following layers:
- The interface layer provides APIs for opening or closing a device and writing data.
- The core layer provides the capabilities of binding, initializing, and releasing devices.
- The adaptation layer implements other functions.
NOTE<br/>The core layer can call the functions of the interface layer and uses the hook to call functions of the adaptation layer. In this way, the adaptation layer can indirectly call the functions of the interface layer, but the interface layer cannot call the functions of the adaptation layer.
**Figure 1** Unified service mode
### Constraints
**Figure 1** Process of using a regulator<aname="fig1_regulator_des"></a>
Currently, the regulator module supports only the kernels (LiteOS) of mini and small systems.
## Development Guidelines
### When to Use
Regulators are used to:
- Control the voltage/current supplies of some devices in the system.
| RegulatorOpen | Opens the regulator device handle.|
| RegulatorClose | Closes the regulator device handle.|
| RegulatorEnable | Enables a regulator. |
| RegulatorDisable | Disables a regulator. |
| RegulatorForceDisable | Forcibly disables a regulator. |
| RegulatorSetVoltage | Sets the regulator output voltage. |
| RegulatorGetVoltage | Obtains the regulator output voltage. |
| RegulatorSetCurrent | Sets the regulator output current. |
| RegulatorGetCurrent | Obtains the regulator output current. |
| RegulatorGetStatus | Obtains the regulator status. |
### How to Develop
During the OS startup process, the driver management module loads the regulator driver based on the configuration file. Then, the regulator driver detects the regulator devices and initializes the driver.
The figure below illustrates the process of using a regulator.
**Figure 2** Process of using a regulator
### Opening a Regulator Device Handle<a name="section3.2_REGULATOR_des"></a>
#### Opening a Regulator Device Handle
Before operating a regulator, call **RegulatorOpen** to open the device handle of the regulator. This function returns the device handle of the regulator.
### Closing a Regulator Device Handle<a name="section3.3_REGULATOR_des"></a>
#### Closing a Regulator Device Handle
Call **RegulatorClose** to close the regulator device handle to release resources.
```c
```
void RegulatorClose(DevHandle handle);
```
**Table 3** Description of RegulatorClose
<aname="table3_REGULATOR_des"></a>
| **Parameter** | **Description** |
| ------ | ----------------- |
| handle | Regulator device handle to close.|
| handle | Device handle of the target regulator.|
```c
```
/* Close the regulator device handle. */
RegulatorClose(handle);
```
### Enabling a Regulator<a name="section3.4_REGULATOR_des"></a>
#### Enabling a Regulator
Call **RegulatorEnable** to enable a regulator.
Call **RegulatorEnable()** to enable a regulator.
```c
```
int32_t RegulatorEnable(DevHandle handle);
```
**Table 4** Description of RegulatorEnable
<aname="table4_REGULATOR_des"></a>
| **Parameter** | **Description** |
| ---------- | ----------------- |
| handle | Device handle of the regulator to enable.|
| handle | Device handle of the target regulator.|
| **Return Value**| **Description** |
| 0 | The operation is successful. |
| Negative value | The operation fails. |
```c
```
int32_t ret;
/* Enable the regulator. */
...
...
@@ -179,26 +169,24 @@ if (ret != 0) {
}
```
### Disabling a Regulator<a name="section3.5_REGULATOR_des"></a>
#### Disabling a Regulator
Call **RegulatorDisable** to disable a regulator. The operation will fail if the regulator status is set to always on or if a child node of the regulator is not disabled.
Call **RegulatorDisable()** to disable a regulator. The operation will fail if the regulator status is set to always on or a child node of the regulator is not disabled.
```c
```
int32_t RegulatorDisable(DevHandle handle);
```
**Table 5** Description of RegulatorDisable
<aname="table5_REGULATOR_des"></a>
| **Parameter** | **Description** |
| ---------- | ----------------- |
| handle | Device handle of the regulator to disable.|
| handle | Device handle of the target regulator.|
| **Return Value**| **Description** |
| 0 | The operation is successful. |
| Negative value | The operation fails. |
```c
```
int32_t ret;
/* Disable the regulator. */
...
...
@@ -208,46 +196,44 @@ if (ret != 0) {
}
```
### Forcibly Disabling a Regulator<a name="section3.6_REGULATOR_des"></a>
#### Forcibly Disabling a Regulator
Call **RegulatorForceDisable** to forcibly disable a regulator. The regulator will be disabled event if its status is set to always on or its child node is still enabled.
Call **RegulatorForceDisable()** to forcibly disable a regulator. The regulator will be disabled even if its status is set to always on or its child node is still enabled.
```c
```
int32_t RegulatorForceDisable(DevHandle handle);
```
**Table 6** Description of RegulatorForceDisable
<aname="table6_REGULATOR_des"></a>
| **Parameter** | **Description** |
| ---------- | ----------------- |
| handle | Device handle of the target regulator.|
| **Return Value**| **Description** |
| 0 | The operation is successful. |
| Negative value | The operation fails. |
| 0 | The operation is successful. |
| Negative value | The operation fails. |
```c
```
int32_t ret;
/* Forcibly disable the regulator. */
/* Forcibly disable the regulator. /*
ret = RegulatorForceDisable(handle);
if (ret != 0) {
/* Error handling. */
}
```
### Setting the Output Voltage Range for a Regulator<a name="section3.7_REGULATOR_des"></a>
#### Setting the Output Voltage Range
Call **RegulatorSetVoltage** to set the output voltage range for a regulator.
