diff --git a/en/device-dev/driver/driver-platform-regulator-des.md b/en/device-dev/driver/driver-platform-regulator-des.md index 27ecccbefa5d7eff9984c5b72b1c8e5bdaa5382c..0131dae05046bd67c73b0cd625e9cf203f79b6d5 100644 --- a/en/device-dev/driver/driver-platform-regulator-des.md +++ b/en/device-dev/driver/driver-platform-regulator-des.md @@ -1,113 +1,105 @@ -# Regulator +# Regulator -## Overview + +## Overview + +### Regulator 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 - -**Table 1** Regulator APIs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CategoryAPIDescription
Operating a regulator device handleRegulatorOpenOpens a regulator device handle.
RegulatorCloseCloses a regulator device handle.
Enabling or disable a regulatorRegulatorEnableEnables a regulator.
RegulatorDisableDisables a regulator.
RegulatorForceDisableForcibly disables a regulator.
Setting or obtaining the output voltageRegulatorSetVoltageSets the output voltage for a regulator.
RegulatorGetVoltageObtains the output voltage of a regulator.
Setting or obtaining the output currentRegulatorSetCurrentSets the output current for a regulator.
RegulatorGetCurrentObtains the output current of a regulator.
Querying the regulator statusRegulatorGetStatusObtains the regulator status.
- ->![](../public_sys-resources/icon-note.gif) **NOTE** ->The regulator module can be used in kernel mode but not in user mode. - -## Usage Guidelines - -### How to Use +- 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. + +![](../public_sys-resources/icon-note.gif)NOTE
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 + +![image1](figures/unified-service-mode.png) + +### Constraints -**Figure 1** Process of using a regulator +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. +- Manage regulated power supplies. + +### Available APIs + +**Table 1** Regulator module APIs + +| API | Description | +| --------------------- | ------------------------- | +| 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 ![](figures/process-of-using-regulator.png) -### Opening a Regulator Device Handle +#### 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. -```c +``` DevHandle RegulatorOpen(const char *name); ``` **Table 2** Description of RegulatorOpen - - | **Parameter** | **Description** | | ---------- | ----------------------------- | | name | Name of the target regulator. | @@ -116,8 +108,9 @@ DevHandle RegulatorOpen(const char *name); | NULL | The operation fails. | -```c -/* Regulator name. */ + +``` +/* Regulator device name */ const char *name = "regulator_virtual_1"; DevHandle handle = NULL; @@ -128,48 +121,45 @@ if (handle == NULL) { } ``` -### Closing a Regulator Device Handle +#### 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 - - | **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 +#### 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 - - | **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 +#### 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 - - | **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 +#### 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 - | **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 + +#### Setting the Output Voltage Range Call **RegulatorSetVoltage** to set the output voltage range for a regulator. -```c +``` int32_t RegulatorSetVoltage(DevHandle handle, uint32_t minUv, uint32_t maxUv); ``` **Table 7** Description of RegulatorSetVoltage - - | **Parameter** | **Description** | | ---------- | ----------------- | | handle | Device handle of the target regulator.| @@ -257,28 +243,28 @@ int32_t RegulatorSetVoltage(DevHandle handle, uint32_t minUv, uint32_t maxUv); | 0 | The operation is successful. | | Negative value | The operation fails. | -```c +``` int32_t ret; -int32_t minUv = 0; // Set the minimum voltage to 0 µV. -int32_t maxUv = 20000; // Set the maximum voltage to 20000 µV. +int32_t minUv = 0; // The minimum voltage is 0 µV. +int32_t maxUv = 20000; // The maximum voltage is 20000 µV. -/* Set the output voltage range for the regulator. */ +/* Set the output voltage range of the regulator. */ ret = RegulatorSetVoltage(handle, minUv, maxUv); if (ret != 0) { /* Error handling. */ } ``` -### Obtaining Regulator Voltage Information -Call **RegulatorGetVoltage** to obtain voltage information of a regulator. +#### Obtaining the Regulator Voltage + +Call **RegulatorGetVoltage()** to obtain the regulator voltage. -```c +``` int32_t RegulatorGetVoltage(DevHandle handle, uint32_t *voltage); ``` **Table 8** Description of RegulatorGetVoltage - | **Parameter** | **Description** | | ---------- | ----------------- | @@ -288,30 +274,27 @@ int32_t RegulatorGetVoltage(DevHandle handle, uint32_t *voltage); | 0 | The operation is successful. | | Negative value | The operation fails. | -```c +``` int32_t ret; uint32_t voltage; -/* Obtain the regulator voltage information. */ +/* Obtain the regulator voltage. */ ret = RegulatorGetVoltage(handle, &voltage); if (ret != 0) { /* Error handling. */ } ``` +#### Setting the Output Current Range -### Setting the Output Current Range for a Regulator - -Call **RegulatorSetCurrent** to set the output current range for a regulator. +Call **RegulatorSetCurrent()** to set the output current range of the regulator. -```c +``` int32_t RegulatorSetCurrent(DevHandle handle, uint32_t minUa, uint32_t maxUa); ``` **Table 9** Description of RegulatorSetCurrent - - | **Parameter** | **Description** | | ---------- | ----------------- | | handle | Device handle of the target regulator.| @@ -321,30 +304,28 @@ int32_t RegulatorSetCurrent(DevHandle handle, uint32_t minUa, uint32_t maxUa); | 0 | The operation is successful. | | Negative value | The operation fails. | -```c +``` int32_t ret; -int32_t minUa = 0; // Set the minimum current to 0 μA. -int32_t maxUa = 200; // Set the maximum current to 200 μA. +int32_t minUa = 0; // The minimum current is 0 μA. +int32_t maxUa = 200; // The maximum current is 200 μA. -/* Set the output current range for the regulator. */ +/* Set the output current range of the regulator. */ ret = RegulatorSetCurrent(handle, minUa, maxUa); if (ret != 0) { /* Error handling. */ } ``` -### Obtaining Regulator Current Information +#### Obtaining the Regulator Current -Call **RegulatorGetCurrent** to obtain current information of a regulator. +Call **RegulatorGetCurrent()** to obtain the current of the regulator. -```c +``` int32_t RegulatorGetCurrent(DevHandle handle, uint32_t *regCurrent); ``` **Table 10** Description of RegulatorGetCurrent - - | **Parameter** | **Description** | | ----------- | ----------------- | | handle | Device handle of the target regulator.| @@ -353,28 +334,27 @@ int32_t RegulatorGetCurrent(DevHandle handle, uint32_t *regCurrent); | 0 | The operation is successful. | | Negative value | The operation fails. | -```c +``` int32_t ret; uint32_t regCurrent; -/* Obtain the regulator current information. */ +/* Obtain the current of the regulator. */ ret = RegulatorGetCurrent(handle, ®Current); if (ret != 0) { /* Error handling. */ } ``` -### Obtaining Regulator Status -Call **RegulatorGetStatus** to obtain the regulator status. +#### Obtaining the Regulator Status + +Call **RegulatorGetStatus()** to obtain the regulator status. -```c +``` int32_t RegulatorGetStatus(DevHandle handle, uint32_t *status); ``` **Table 11** Description of RegulatorGetStatus - - | **Parameter** | **Description** | | ---------- | ----------------- | | handle | Device handle of the target regulator.| @@ -383,7 +363,7 @@ int32_t RegulatorGetStatus(DevHandle handle, uint32_t *status); | 0 | The operation is successful. | | Negative value | The operation fails. | -```c +``` int32_t ret; uint32_t status; @@ -394,16 +374,18 @@ if (ret != 0) { } ``` -## Development Example + + +## Development Example The following is an example of using a regulator. -```c +``` void RegulatorTestSample(void) { int32_t ret; - /* Regulator name. */ + /* Regulator device name */ const char *name = "regulator_virtual_1"; DevHandle handle = NULL; @@ -421,10 +403,10 @@ void RegulatorTestSample(void) goto _ERR; } - int32_t minUv = 0; // Set the minimum voltage to 0 µV. - int32_t maxUv = 20000; // Set the maximum voltage to 20000 µV. + int32_t minUv = 0; // The minimum voltage is 0 µV. + int32_t maxUv = 20000; // The maximum voltage is 20000 µV. - /* Set the output voltage range for the regulator. */ + /* Set the output voltage range of the regulator. */ ret = RegulatorSetVoltage(handle, minUv, maxUv); if (ret != 0) { HDF_LOGE("RegulatorSetVoltage: failed, ret %d\n", ret); @@ -433,7 +415,7 @@ void RegulatorTestSample(void) uint32_t voltage; - /* Obtain the regulator voltage information. */ + /* Obtain the regulator voltage. */ ret = RegulatorGetVoltage(handle, &voltage); if (ret != 0) { HDF_LOGE("RegulatorGetVoltage: failed, ret %d\n", ret); diff --git a/en/device-dev/driver/driver-platform-regulator-develop.md b/en/device-dev/driver/driver-platform-regulator-develop.md index 18b1721f9a81bc86f3ea9987f66ae6cb03ff87a0..94fd1f76d09106a5698aa27b89503be6ab231a2d 100644 --- a/en/device-dev/driver/driver-platform-regulator-develop.md +++ b/en/device-dev/driver/driver-platform-regulator-develop.md @@ -1,18 +1,51 @@ -# Regulator +# Regulator -## Overview +## Overview -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. + +![](../public_sys-resources/icon-note.gif)NOTE
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 + ![image1](figures/unified-service-mode.png) -## Available APIs + + +### 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: -```c +``` struct RegulatorMethod { int32_t (*open)(struct RegulatorNode *node); int32_t (*close)(struct RegulatorNode *node); @@ -28,87 +61,80 @@ struct RegulatorMethod { }; ``` -**Table 1** APIs for the members in the RegulatorMethod structure +**Table 1** Description of the RegulatorMethod structure -| Method | Input Parameter | Return Value| Description| -| ------------ | ------------------------------------------- | ------ | ---- | -| open | **node**: structure pointer to the regulator node at the core layer.|HDF_STATUS|Opens a device.| -| close | **node**: structure pointer to the regulator node at the core layer.| HDF_STATUS| Closes a device.| -| release | **node**: structure pointer to the regulator node at the core layer.| HDF_STATUS| Releases a device handle.| -| enable | **node**: structure pointer to the regulator node at the core layer.| HDF_STATUS| Enables a device.| -| disable | **node**: structure pointer to the regulator node at the core layer.| HDF_STATUS| Disables a device.| -| forceDisable | **node**: structure pointer to the regulator node at the core layer.| HDF_STATUS| Forcibly disables a device.| + +| Method | Input Parameter | Return Value | Description | +| ------------ | ------------------------------------------------------------ | ------------------ | ---------------- | +| open | **node**: structure pointer to the regulator node at the core layer. | HDF_STATUS| Opens a device. | +| close | **node**: structure pointer to the regulator node at the core layer. | HDF_STATUS| Closes a device. | +| release | **node**: structure pointer to the regulator node at the core layer. | HDF_STATUS| Releases a device handle. | +| enable | **node**: structure pointer to the regulator node at the core layer. | HDF_STATUS| Enabling a Regulator | +| 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.
**minUv**: minimum voltage to set. It is a uint32_t variable.
**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.
**voltage**: pointer to the output voltage value.| HDF_STATUS| Obtains the voltage.| +| getVoltage | **node**: structure pointer to the regulator node at the core layer.
**voltage**: pointer to the output voltage value.| HDF_STATUS| Obtains the voltage. | | setCurrent | **node**: structure pointer to the regulator node at the core layer.
**minUa**: minimum current to set. It is a uint32_t variable.
**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.
**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.
**status**: pointer to the output status, which is of the uint32_t type.| HDF_STATUS| Obtains the device status.| - -## How to Develop - -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. +| getCurrent | **node**: structure pointer to the regulator node at the core layer.
**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.
**status**: pointer to the output status, which is of the uint32_t type.| HDF_STATUS| Obtains the device status. | - - Add the **deviceNode** information to the **device_info.hcs** file. - - (Optional) Add the **regulator_config.hcs** file. +### How to Develop -3. Instantiate the regulator controller object. - - - Initialize **RegulatorNode** members. - - - Instantiate **RegulatorMethod**. - - >![](../public_sys-resources/icon-note.gif) **NOTE** - - >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. +The regulator module adaptation procedure is as follows: -## Development Example +- 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. + 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 **Init()** function to load the driver. If **Init()** fails to be called, the HDF calls **Release** to release driver resources and exit. + + ``` + struct HdfDriverEntry g_regulatorDriverEntry = { + .moduleVersion = 1, + .moduleName = "virtual_regulator_driver",// (Mandatory) The value must be the same as that of moduleName in the .hcs file. + .Init = VirtualRegulatorInit, + .Release = VirtualRegulatorRelease, + }; + // Call HDF_INIT to register the driver entry with the HDF framework. + HDF_INIT(g_regulatorDriverEntry); + ``` + +2. Configure attribute files. - 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. + - Add the device node description to the **vendor/hisilicon/hispark_taurus/hdf_config/device_info/device_info.hcs** file. - Regulator driver entry 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 - struct HdfDriverEntry g_regulatorDriverEntry = { - .moduleVersion = 1, - .moduleName = "virtual_regulator_driver",// (Mandatory) The value must be the same as that of moduleName in the .hcs file. - .Init = VirtualRegulatorInit, - .Release = VirtualRegulatorRelease, - }; - // Call HDF_INIT to register the driver entry with the HDF framework. - HDF_INIT(g_regulatorDriverEntry); - ``` + 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: -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. + | Member | Value | + | --------------- | ------------------------------------------------------------ | + | 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. | - >![](W:\doc\docs\en\device-dev\public_sys-resources\icon-note.gif) **NOTE** - >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. + 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** reference: + - **device_info.hcs** configuration reference - ```c - root { + ``` + root { device_info { platform :: host { hostName = "platform_host"; priority = 50; device_regulator :: device { device0 :: deviceNode { // Configure an HDF device node for each regulator controller. - policy = 1; // 2: visible in user mode; 1: visible in kernel mode; 0: no service required. - priority = 50; // Driver startup priority. + policy = 1; // 2: visible in user mode; 1: visible in kernel mode; 0: no service required. + priority = 50; // Driver startup priority. permission = 0644; // Permission to create device nodes of the driver. /* (Mandatory) Driver name, which must be the same as the moduleName in the driver entry. */ moduleName = "HDF_PLATFORM_REGULATOR_MANAGER"; @@ -126,211 +152,197 @@ The following uses **regulator_virtual.c** as an example to present the content } } } - } - ``` - - - **regulator\_config.hcs** reference: - - ```c - root { - platform { - regulator_config { - match_attr = "linux_regulator_adapter"; - template regulator_controller { // (Mandatory) Template configuration. In the template, you can configure the common parameters shared by device nodes. - device_num = 1; - name = ""; - devName = "regulator_adapter_consumer01"; - supplyName = ""; - mode = 1; - minUv = 0; - maxUv = 20000; - minUa = 0; - maxUa = 0; - } - controller_0x130d0000 :: regulator_controller { - device_num = 1; - name = "regulator_adapter_1"; - devName = "regulator_adapter_consumer01"; - supplyName = "virtual-regulator-hdf-adapter"; - mode = 1; - minUv = 1000; - maxUv = 50000; - minUa = 0; - maxUa = 0; - } - /* Each regulator controller corresponds to a controller node. If there are multiple regulator controllers, add the corresponding controller nodes one by one.*/ - controller_0x130d0001 :: regulator_controller { - device_num = 1; - name = "regulator_adapter_2"; - devName = "regulator_adapter_consumer01"; - supplyName = "virtual2-regulator-hdf-adapter"; - mode = 2; - minUv = 0; - maxUv = 0; - minUa = 1000; - maxUa = 50000; - } - } - } - } - ``` - -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**). - - - 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**. - - ```c - // RegulatorNode is the controller structure at the core layer. Its members are assigned with values by using the Init function. - struct RegulatorNode { - struct RegulatorDesc regulatorInfo; - struct DListHead node; - struct RegulatorMethod *ops; - void *priv; - struct OsalMutex lock; - }; - - struct RegulatorDesc { - const char *name; /* Regulator name. */ - const char *parentName; /* Regulator parent node name. */ - struct RegulatorConstraints constraints; /* Regulator constraint information. */ - uint32_t minUv; /* Minimum output voltage. */ - uint32_t maxUv; /* Maximum output voltage. */ - uint32_t minUa; /* Minimum output current. */ - uint32_t maxUa; /* Maximum output current. */ - uint32_t status; /* Regulator status, which can be on or off. */ - int useCount; - int consumerRegNums; /* Number of regulator consumers. */ - RegulatorStatusChangecb cb; /* Variable used to notify the regulator status changes. */ - }; - - struct RegulatorConstraints { - uint8_t alwaysOn; /* Whether the regulator is always on. */ - uint8_t mode; /* Voltage or current. */ - uint32_t minUv; /* Minimum output voltage allowed. */ - uint32_t maxUv; /* Maximum output voltage allowed. */ - uint32_t minUa; /* Minimum output current allowed. */ - uint32_t maxUa; /* Maximum output current allowed. */ - }; - ``` - - - Instantiating **RegulatorMethod** (other members are initialized by **Init**) - - ```c - // Example of regulator_virtual.c: Instantiate the hook. - static struct RegulatorMethod g_method = { - .enable = VirtualRegulatorEnable, - .disable = VirtualRegulatorDisable, - .setVoltage = VirtualRegulatorSetVoltage, - .getVoltage = VirtualRegulatorGetVoltage, - .setCurrent = VirtualRegulatorSetCurrent, - .getCurrent = VirtualRegulatorGetCurrent, - .getStatus = VirtualRegulatorGetStatus, - }; - ``` - - - **Init** function - - Input parameters: - - **HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs configuration. - - Return value: - - **HDF\_STATUS** (The following table lists some states. For more details, see **HDF\_STATUS** in **/drivers/framework/include/utils/hdf\_base.h**.) - - **Table 2** HDF\_STATUS - - - - - - - - - - - - - - - - - - - - - - - - -

State

-

Description

-

HDF_ERR_INVALID_OBJECT

-

Invalid controller object.

-

HDF_ERR_MALLOC_FAIL

-

Failed to allocate memory.

-

HDF_ERR_INVALID_PARAM

-

Invalid parameter.

-

HDF_ERR_IO

-

I/O error.

-

HDF_SUCCESS

-

Initialization successful.

-

HDF_FAILURE

-

Initialization failed.

-
- Function description: - Initializes the custom structure and **RegulatorNode** members, and adds the regulator controller by calling the **RegulatorNodeAdd** function at the core layer. - - ```c - static int32_t VirtualRegulatorInit(struct HdfDeviceObject *device) - { - int32_t ret; - const struct DeviceResourceNode *childNode = NULL; - ... - DEV_RES_NODE_FOR_EACH_CHILD_NODE(device->property, childNode) { - ret = VirtualRegulatorParseAndInit(device, childNode);// (Mandatory) The implementation is as follows: - ... - } - ... - } - - static int32_t VirtualRegulatorParseAndInit(struct HdfDeviceObject *device, const struct DeviceResourceNode *node) - { - int32_t ret; - struct RegulatorNode *regNode = NULL; - (void)device; - - regNode = (struct RegulatorNode *)OsalMemCalloc(sizeof(*regNode));// Load the .hcs file. - ... - ret = VirtualRegulatorReadHcs(regNode, node);// Read .hcs information. - ... - regNode->priv = (void *)node; // Instantiate the node. - regNode->ops = &g_method; // Instantiate OPS. - - ret = RegulatorNodeAdd(regNode); // Add the node. - ... - } - - - - **Release** function - - Input parameters: - - **HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs configuration. - - Return value: - - – - - Function description: - - 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. - + } + ``` + + - **regulator\_config.hcs** reference: + + ``` + root { + platform { + regulator_config { + match_attr = "linux_regulator_adapter"; + template regulator_controller { // (Mandatory) Template configuration. In the template, you can configure the common parameters shared by device nodes. + device_num = 1; + name = ""; + devName = "regulator_adapter_consumer01"; + supplyName = ""; + mode = 1; + minUv = 0; + maxUv = 20000; + minUa = 0; + maxUa = 0; + } + controller_0x130d0000 :: regulator_controller { + device_num = 1; + name = "regulator_adapter_1"; + devName = "regulator_adapter_consumer01"; + supplyName = "virtual-regulator-hdf-adapter"; + mode = 1; + minUv = 1000; + maxUv = 50000; + minUa = 0; + maxUa = 0; + } + /* Each regulator controller corresponds to a controller node. If there are multiple regulator controllers, add the corresponding controller nodes one by one.*/ + controller_0x130d0001 :: regulator_controller { + device_num = 1; + name = "regulator_adapter_2"; + devName = "regulator_adapter_consumer01"; + supplyName = "virtual2-regulator-hdf-adapter"; + mode = 2; + minUv = 0; + maxUv = 0; + minUa = 1000; + maxUa = 50000; + } + } + } + } + ``` + +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 + + The **RegulatorNode** structure holds parameters and data for the driver. The HDF obtains the values in **regulator\_config.hcs** using **DeviceResourceIface**. + + ``` + // RegulatorNode is the controller structure at the core layer. Its members are assigned with values by using the Init function. + struct RegulatorNode { + struct RegulatorDesc regulatorInfo; + struct DListHead node; + struct RegulatorMethod *ops; + void *priv; + struct OsalMutex lock; + }; + + struct RegulatorDesc { + const char *name; /* Regulator name. */ + const char *parentName; /* Regulator parent node name. */ + struct RegulatorConstraints constraints; /* Regulator constraint information. */ + uint32_t minUv; /* Minimum output voltage. */ + uint32_t maxUv; /* Maximum output voltage. */ + uint32_t minUa; /* Minimum output current. */ + uint32_t maxUa; /* Maximum output current. */ + uint32_t status; /* Regulator status, which can be on or off. */ + int useCount; + int consumerRegNums; /* Number of regulator consumers. */ + RegulatorStatusChangecb cb; /* Variable used to notify the regulator status changes. */ + }; + + struct RegulatorConstraints { + uint8_t alwaysOn; /* Whether the regulator is always on. */ + uint8_t mode; /* Voltage or current. */ + uint32_t minUv; /* Minimum output voltage allowed. */ + uint32_t maxUv; /* Maximum output voltage allowed. */ + uint32_t minUa; /* Minimum output current allowed. */ + uint32_t maxUa; /* Maximum output current allowed. */ + }; + ``` + + + + - Instantiating **RegulatorMethod** (other members are initialized by **Init**) + + ```c + // Example of regulator_virtual.c: Instantiate the hook. + static struct RegulatorMethod g_method = { + .enable = VirtualRegulatorEnable, + .disable = VirtualRegulatorDisable, + .setVoltage = VirtualRegulatorSetVoltage, + .getVoltage = VirtualRegulatorGetVoltage, + .setCurrent = VirtualRegulatorSetCurrent, + .getCurrent = VirtualRegulatorGetCurrent, + .getStatus = VirtualRegulatorGetStatus, + }; + ``` + + + + - **Init** function + + Input parameters: + + **HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs configuration. + + Return value: + + **HDF\_STATUS** (The following table lists some states. For more details, see **HDF\_STATUS** in **/drivers/framework/include/utils/hdf\_base.h**.) + + **Table 2** HDF\_STATUS + + | State | Description | + | ---------------------- | -------------- | + | HDF_ERR_INVALID_OBJECT | Invalid controller object.| + | HDF_ERR_MALLOC_FAIL | Failed to allocate memory. | + | HDF_ERR_INVALID_PARAM | Invalid parameter. | + | HDF_ERR_IO | I/O error. | + | HDF_SUCCESS | Initialization successful. | + | HDF_FAILURE | Initialization failed. | + + Function description: + + Initializes the custom structure and **RegulatorNode** members, and adds the regulator controller by calling the **RegulatorNodeAdd** function at the core layer. + + + ```c + static int32_t VirtualRegulatorInit(struct HdfDeviceObject *device) + { + int32_t ret; + const struct DeviceResourceNode *childNode = NULL; + ... + DEV_RES_NODE_FOR_EACH_CHILD_NODE(device->property, childNode) { + ret = VirtualRegulatorParseAndInit(device, childNode);// (Mandatory) The implementation is as follows: + ... + } + ... + } + + static int32_t VirtualRegulatorParseAndInit(struct HdfDeviceObject *device, const struct DeviceResourceNode *node) + { + int32_t ret; + struct RegulatorNode *regNode = NULL; + (void)device; + + regNode = (struct RegulatorNode *)OsalMemCalloc(sizeof(*regNode));// Load the .hcs file. + ... + ret = VirtualRegulatorReadHcs(regNode, node);// Read .hcs information. + ... + regNode->priv = (void *)node; // Instantiate the node. + regNode->ops = &g_method; // Instantiate OPS. + + ret = RegulatorNodeAdd(regNode); // Add the node. + ... + } + ``` + + - **Release** function + + Input parameters: + + **HdfDeviceObject**, an interface parameter exposed by the driver, contains the .hcs configuration. + + Return value: + + – + + Function description: + + 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. + ```c static void VirtualRegulatorRelease(struct HdfDeviceObject *device) { ... RegulatorNodeRemoveAll();// (Mandatory) Call the function at the core layer to release regulator controller devices and services. } + ``` + +4. Debug the driver. + + (Optional) Verify the basic functions of the new driver, for example, whether the test cases are successful after the driver is loaded. + +