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 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
- Opening or closing a regulator device handle
- Setting the output voltage and current for a regulator
- Setting the output voltage and current for a regulator
- Enabling or disabling a regulator
- Enabling or disabling a regulator
- Obtaining the voltage, current, and status of 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>
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.
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.
Call **RegulatorClose** to close the regulator device handle to release resources.
```c
```
void RegulatorClose(DevHandle handle);
void RegulatorClose(DevHandle handle);
```
```
**Table 3** Description of RegulatorClose
**Table 3** Description of RegulatorClose
<aname="table3_REGULATOR_des"></a>
| **Parameter** | **Description** |
| **Parameter** | **Description** |
| ------ | ----------------- |
| ------ | ----------------- |
| handle | Regulator device handle to close.|
| handle | Device handle of the target regulator.|
```c
```
/* Close the regulator device handle. */
/* Close the regulator device handle. */
RegulatorClose(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);
int32_t RegulatorEnable(DevHandle handle);
```
```
**Table 4** Description of RegulatorEnable
**Table 4** Description of RegulatorEnable
<aname="table4_REGULATOR_des"></a>
| **Parameter** | **Description** |
| **Parameter** | **Description** |
| ---------- | ----------------- |
| ---------- | ----------------- |
| handle | Device handle of the regulator to enable.|
| handle | Device handle of the target regulator.|
| **Return Value**| **Description** |
| **Return Value**| **Description** |
| 0 | The operation is successful. |
| 0 | The operation is successful. |
| Negative value | The operation fails. |
| Negative value | The operation fails. |
```c
```
int32_t ret;
int32_t ret;
/* Enable the regulator. */
/* Enable the regulator. */
...
@@ -179,26 +169,24 @@ if (ret != 0) {
...
@@ -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);
int32_t RegulatorDisable(DevHandle handle);
```
```
**Table 5** Description of RegulatorDisable
**Table 5** Description of RegulatorDisable
<aname="table5_REGULATOR_des"></a>
| **Parameter** | **Description** |
| **Parameter** | **Description** |
| ---------- | ----------------- |
| ---------- | ----------------- |
| handle | Device handle of the regulator to disable.|
| handle | Device handle of the target regulator.|
| **Return Value**| **Description** |
| **Return Value**| **Description** |
| 0 | The operation is successful. |
| 0 | The operation is successful. |
| Negative value | The operation fails. |
| Negative value | The operation fails. |
```c
```
int32_t ret;
int32_t ret;
/* Disable the regulator. */
/* Disable the regulator. */
...
@@ -208,17 +196,16 @@ if (ret != 0) {
...
@@ -208,17 +196,16 @@ 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.
The regulator module controls the voltage and current supplies of some devices in the system. 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.
### Regulator
The regulator module controls the voltage and current supplies of some devices in the system.
### Basic Concepts
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.
### 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
**Figure 1** Unified service mode
## Available APIs<a name="section2_REGULATORDevelop"></a>
### Constraints
Currently, the regulator module supports only the kernels (LiteOS) of mini and small systems.
## Development Guidelines
### When to Use
The regulator module controls the voltage and current supplies of some devices in the system.
### Available APIs
The functions in **RegulatorMethod** are used to call the corresponding regulator driver functions:
**RegulatorMethod** structure:
**RegulatorMethod** structure:
```c
```
struct RegulatorMethod {
struct RegulatorMethod {
int32_t (*open)(struct RegulatorNode *node);
int32_t (*open)(struct RegulatorNode *node);
int32_t (*close)(struct RegulatorNode *node);
int32_t (*close)(struct RegulatorNode *node);
...
@@ -28,60 +61,39 @@ struct RegulatorMethod {
...
@@ -28,60 +61,39 @@ struct RegulatorMethod {
};
};
```
```
**Table 1**APIs for the members in the RegulatorMethod structure
**Table 1**Description of the RegulatorMethod structure
| close | **node**: structure pointer to the regulator node at the core layer.| HDF_STATUS| Closes a device.|
| open | **node**: structure pointer to the regulator node at the core layer. | HDF_STATUS| Opens a device. |
| release | **node**: structure pointer to the regulator node at the core layer.| HDF_STATUS| Releases a device handle.|
| close | **node**: structure pointer to the regulator node at the core layer. | HDF_STATUS| Closes a device. |
| enable | **node**: structure pointer to the regulator node at the core layer.| HDF_STATUS| Enables a device.|
| release | **node**: structure pointer to the regulator node at the core layer. | HDF_STATUS| Releases a device handle. |
| disable | **node**: structure pointer to the regulator node at the core layer.| HDF_STATUS| Disables a device.|
| enable | **node**: structure pointer to the regulator node at the core layer. | HDF_STATUS| Enabling a Regulator |
| forceDisable | **node**: structure pointer to the regulator node at the core layer.| HDF_STATUS| Forcibly disables a device.|
| disable | **node**: structure pointer to the regulator node at the core layer. | HDF_STATUS| Disabling a Regulator |
| forceDisable | **node**: structure pointer to the regulator node at the core layer. | HDF_STATUS| Forcibly Disabling a Regulator |
| setVoltage | **node**: structure pointer to the regulator node at the core layer.<br>**minUv**: minimum voltage to set. It is a uint32_t variable.<br>**maxUv**: maximum voltage to set. It is a uint32_t variable.| HDF_STATUS| Sets the output voltage range.|
| setVoltage | **node**: structure pointer to the regulator node at the core layer.<br>**minUv**: minimum voltage to set. It is a uint32_t variable.<br>**maxUv**: maximum voltage to set. It is a uint32_t variable.| HDF_STATUS| Sets the output voltage range.|
| getVoltage | **node**: structure pointer to the regulator node at the core layer.<br>**voltage**: pointer to the output voltage value.| HDF_STATUS| Obtains the voltage.|
| getVoltage | **node**: structure pointer to the regulator node at the core layer.<br>**voltage**: pointer to the output voltage value.| HDF_STATUS| Obtains the voltage.|
| setCurrent | **node**: structure pointer to the regulator node at the core layer.<br>**minUa**: minimum current to set. It is a uint32_t variable.<br>**maxUa**: maximum current to set. It is a uint32_t variable.| HDF_STATUS| Sets the output current range.|
| setCurrent | **node**: structure pointer to the regulator node at the core layer.<br>**minUa**: minimum current to set. It is a uint32_t variable.<br>**maxUa**: maximum current to set. It is a uint32_t variable.| HDF_STATUS| Sets the output current range.|
| getCurrent | **node**: structure pointer to the regulator node at the core layer.<br>**regCurrent**: pointer to the output current, which is of the uint32_t type.| HDF_STATUS| Obtains the current.|
| getCurrent | **node**: structure pointer to the regulator node at the core layer.<br>**regCurrent**: pointer to the output current, which is of the uint32_t type.| HDF_STATUS| Obtains the current. |
| getStatus | **node**: structure pointer to the regulator node at the core layer.<br>**status**: pointer to the output status, which is of the uint32_t type.| HDF_STATUS| Obtains the device status.|
| getStatus | **node**: structure pointer to the regulator node at the core layer.<br>**status**: pointer to the output status, which is of the uint32_t type.| HDF_STATUS| Obtains the device status. |
## How to Develop<a name="section3_REGULATORDevelop"></a>
The regulator module adaptation involves the following steps:
1. Instantiate the driver entry.
- Instantiate the **HdfDriverEntry** structure.
- Call **HDF_INIT** to register the **HdfDriverEntry** instance with the HDF.
2. Configure attribute files.
### How to Develop
- Add the **deviceNode** information to the **device_info.hcs** file.
- (Optional) Add the **regulator_config.hcs** file.
3. Instantiate the regulator controller object.
- Initialize **RegulatorNode** members.
- Instantiate **RegulatorMethod**.
The regulator module adaptation procedure is as follows:
>For details, see [Available APIs](#availableapis).
4. Debug the driver.
- (Optional) Verify basic functionalities of new drivers. For example, verify the information returned when the driver is loaded and whether data is successfully transmitted.
## Development Example<a name="section4_REGULATORDevelop"></a>
- Instantiate the driver entry.
- Configure attribute files.
- Instantiate the core layer APIs.
- Debug the driver.
The following uses **regulator_virtual.c** as an example to present the content to be provided by the vendor to implement device functionalities.
1. Instantiate the driver entry.
1. Instantiate the driver entry. The driver entry must be a global variable of the **HdfDriverEntry** type (defined in **hdf\_device\_desc.h**), and the value of **moduleName** must be the same as that in **device\_info.hcs**. In the HDF, the start address of each **HdfDriverEntry** object of all loaded drivers are collected to form a segment address space similar to an array for the upper layer to invoke.
Generally, the HDF calls the **Bind** function and then the **Init** function to load the driver. If **Init** fails to be called, the HDF calls **Release** to release driver resources and exit.
Instantiate the driver entry. The driver entry must be a global variable of the **HdfDriverEntry** type (defined in **hdf_device_desc.h**), and the value of **moduleName** must be the same as that in **device_info.hcs**. In the HDF, the start address of each **HdfDriverEntry** object of all loaded drivers are collected to form a segment address space similar to an array for the upper layer to invoke.
Regulator driver entry reference:
Generally, the HDF calls the **Init()** function to load the driver. If **Init()** fails to be called, the HDF calls **Release** to release driver resources and exit.
```c
```
struct HdfDriverEntry g_regulatorDriverEntry = {
struct HdfDriverEntry g_regulatorDriverEntry = {
.moduleVersion = 1,
.moduleVersion = 1,
.moduleName = "virtual_regulator_driver",// (Mandatory) The value must be the same as that of moduleName in the .hcs file.
.moduleName = "virtual_regulator_driver",// (Mandatory) The value must be the same as that of moduleName in the .hcs file.
...
@@ -92,14 +104,28 @@ The following uses **regulator_virtual.c** as an example to present the content
...
@@ -92,14 +104,28 @@ The following uses **regulator_virtual.c** as an example to present the content
HDF_INIT(g_regulatorDriverEntry);
HDF_INIT(g_regulatorDriverEntry);
```
```
2.Add **deviceNode** to the **device\_info.hcs** file, and set the device attributes in the **regulator\_config.hcs** file. The **deviceNode** information is related to registration of the driver entry. The device attribute values are closely related to the default values or value ranges of the **RegulatorNode** members at the core layer.
- Add the device node description to the **vendor/hisilicon/hispark_taurus/hdf_config/device_info/device_info.hcs** file.
>If there are multiple devices, add the **deviceNode** information to the **device\_info** file and add the corresponding device attributes to the **regulator\_config** file.
-**device\_info.hcs** reference:
The **deviceNode** information is related to registration of the driver entry. The device attribute values are closely related to the default values or value ranges of the **RegulatorNode** members at the core layer.
```c
In the unified service mode, the first device node in the **device_info.hcs** file must be the regulator manager. The parameters must be set as follows:
| policy | **0**, which indicates that no service is published. |
| priority | Driver startup priority. The value range is 0 to 200. A larger value indicates a lower priority. If the priorities are the same, the device loading sequence is not ensured.|
| permission | Driver permission. |
| moduleName | The value is **HDF_PLATFORM_REGULATOR_MANAGER**. |
| serviceName | The value is **HDF_PLATFORM_REGULATOR_MANAGER**. |
| deviceMatchAttr | Reserved. |
Configure regulator controller information from the second node. This node specifies a type of regulator controllers rather than a specific regulator controller. In this example, there is only one regulator device. If there are multiple regulator devices, you need to add the **deviceNode** information to the **device_info** file and add the corresponding device attributes to the **regulator\_config** file.
- **device_info.hcs** configuration reference
```
root {
root {
device_info {
device_info {
platform :: host {
platform :: host {
...
@@ -131,7 +157,7 @@ The following uses **regulator_virtual.c** as an example to present the content
...
@@ -131,7 +157,7 @@ The following uses **regulator_virtual.c** as an example to present the content
- **regulator\_config.hcs** reference:
- **regulator\_config.hcs** reference:
```c
```
root {
root {
platform {
platform {
regulator_config {
regulator_config {
...
@@ -175,13 +201,15 @@ The following uses **regulator_virtual.c** as an example to present the content
...
@@ -175,13 +201,15 @@ The following uses **regulator_virtual.c** as an example to present the content
}
}
```
```
3. Initialize the **RegulatorNode** object at the core layer, including initializing the vendor custom structure (passing parameters and data), instantiating **RegulatorMethod** (used to call underlying functions of the driver) in **PinCntlr**, and implementing the **HdfDriverEntry** member functions (**Bind**, **Init**, and **Release**).
3. Instantiate the APIs of the core layer.
- Initialize the **RegulatorNode** object at the core layer, including initializing the vendor custom structure (passing parameters and data), instantiating **RegulatorMethod** (used to call underlying functions of the driver) in **PinCntlr**, and implementing the **HdfDriverEntry** member functions (**Bind**, **Init**, and **Release**).
- Initializing the vendor custom structure
- Initializing the vendor custom structure
The **RegulatorNode** structure holds parameters and data for the driver. The HDF obtains the values in **regulator\_config.hcs** using **DeviceResourceIface**.
The **RegulatorNode** structure holds parameters and data for the driver. The HDF obtains the values in **regulator\_config.hcs** using **DeviceResourceIface**.
```c
```
// RegulatorNode is the controller structure at the core layer. Its members are assigned with values by using the Init function.
// RegulatorNode is the controller structure at the core layer. Its members are assigned with values by using the Init function.
struct RegulatorNode {
struct RegulatorNode {
struct RegulatorDesc regulatorInfo;
struct RegulatorDesc regulatorInfo;
...
@@ -215,6 +243,8 @@ The following uses **regulator_virtual.c** as an example to present the content
...
@@ -215,6 +243,8 @@ The following uses **regulator_virtual.c** as an example to present the content
};
};
```
```
- Instantiating **RegulatorMethod** (other members are initialized by **Init**)
- Instantiating **RegulatorMethod** (other members are initialized by **Init**)
```c
```c
...
@@ -230,6 +260,8 @@ The following uses **regulator_virtual.c** as an example to present the content
...
@@ -230,6 +260,8 @@ The following uses **regulator_virtual.c** as an example to present the content
};
};
```
```
- **Init** function
- **Init** function
Input parameters:
Input parameters:
...
@@ -242,47 +274,20 @@ The following uses **regulator_virtual.c** as an example to present the content
...
@@ -242,47 +274,20 @@ The following uses **regulator_virtual.c** as an example to present the content
<tdclass="cellrowborder"valign="top"width="50%"headers="mcps1.1.3.1.2 "><pid="entry361497788164144p0"><aname="entry361497788164144p0"></a><aname="entry361497788164144p0"></a>Failed to allocate memory.</p>
Initializes the custom structure and **RegulatorNode** members, and adds the regulator controller by calling the **RegulatorNodeAdd** function at the core layer.
Initializes the custom structure and **RegulatorNode** members, and adds the regulator controller by calling the **RegulatorNodeAdd** function at the core layer.
Releases memory and deletes the controller. This function assigns a value to the **Release** API in the driver entry structure. If the HDF fails to call the **Init()** function to initialize the driver, the **Release()** function can be called to release driver resources.
