diff --git a/en/device-dev/driver/driver-platform-pwm-des.md b/en/device-dev/driver/driver-platform-pwm-des.md index cbe6e321573ba6703da10cf7dd259e18b048db85..bb5f3354ee70c3f78a77c6ff506ee5b9e856334f 100644 --- a/en/device-dev/driver/driver-platform-pwm-des.md +++ b/en/device-dev/driver/driver-platform-pwm-des.md @@ -1,123 +1,82 @@ -# PWM +# PWM -## Overview -Pulse width modulation (PWM) is a method used to digitally encode analog signal levels and convert them into pulses. It can be used for motor control and backlight brightness adjustment. +## Overview + +Pulse width modulation (PWM) is a technology that digitally encodes analog signal levels and converts them into pulses. It can be used for motor control and backlight brightness adjustment. + + The PWM APIs provide a set of functions for operating a PWM device, including those for: +- Opening or closing a PWM device handle -The PWM APIs provide a set of functions for operating a PWM device, including those for: -- Obtaining and releasing a PWM device handle - Setting the PWM period, signal ON-state time, and polarity + - Enabling and disabling a PWM device + - Obtaining and setting PWM parameters -### PwmConfig Structure - -**Table 1** PwmConfig structure - - - -| Parameter| Description| -| -------- | ------------------------------------------------------------ | -| duty | Time that a signal is in the ON state, in ns.| -| period | Time for a signal to complete an on-and-off cycle, in ns.| -| number | Number of square waves to generate. A positive value indicates the number of square waves to generate. The value 0 means to generate square waves repeatedly.| -| polarity | PWM signal polarity, which can be **PWM\_NORMAL\_POLARITY** or **PWM\_INVERTED\_POLARITY**.| -| status | PWM device status, which can be enabled or disabled.| - -## Available APIs - -**Table 2** PWM device APIs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CategoryAPIDescription
Operating PWM handlesPwmOpenOpens the handle of a PWM device.
PwmCloseCloses the handle of a PWM device.
Enabling or disabling PWMPwmEnableEnables a PWM device.
PwmDisableDisables a PWM device.
Performing PWM configurationPwmSetPeriodSets the PWM period.
PwmSetDutySets the signal ON-state time.
PwmSetPolaritySets the PWM signal polarity.
Setting or obtaining the PWM configurationPwmSetConfigSets PWM device parameters.
PwmGetConfigObtains PWM device parameters.
- - - ->![](../public_sys-resources/icon-note.gif) **NOTE:** ->The PWM module can be used in kernel mode but not in user mode. - -## Usage Guidelines - -### How to Use - -During the OS startup process, the driver management module loads the PWM driver based on the configuration file. Then, the PWM driver detects the PWM device and initializes the driver. - -[Figure 1](#fig1_PWM_des) shows the general process of using the PWM module. - -**Figure 1** Process of using the PWM module +### PwmConfig Structure + + **Table 1** PwmConfig structure + +| Parameter| Description| +| -------- | -------- | +| duty | Time that a signal is in the ON state, in ns.| +| period | Time for a signal to complete an on-and-off cycle, in ns.| +| number | Number of square waves to generate.
- Positive value: indicates the number of square waves to generate.
- **0**: indicates that square waves are generated continuously.| +| polarity | PWM signal polarity, which can be positive or reverse.| +| status | PWM device status, which can be enabled or disabled.| + + +## Available APIs + + **Table 2** PWM driver APIs + +| Category| Description| +| -------- | -------- | +| Operating PWM handles| - **PwmOpen**: opens the device handle of a PWM device.
- **PwmClose**: closes the device handle of a PWM device.| +| Enabling or disabling PWM| - **PwmEnable**: enables a PWM device.
- **PwmDisable**: disables a PWM device.| +| Setting PWM| - **PwmSetPeriod**: sets the PWM period.
- **PwmSetDuty**: sets the signal ON-state time.
- **PwmSetPolarity**: sets the PWM signal polarity.| +| Setting or obtaining PWM configuration| - **PwmSetConfig**: sets PWM device parameters.
- **PwmGetConfig**: obtains PWM device parameters.| + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
+> All APIs described in this document can be called only in the kernel space. + + +## Usage Guidelines + + +### How to Use + +The figure below shows the general process of using the PWM. + + **Figure 1** Process of using the PWM module ![](figures/process-of-using-PWM.png) -### Opening a PWM Device Handle + +### Opening a PWM Device Handle Before performing operations on a PWM device, call **PwmOpen** to open the device handle. -```c + +``` DevHandle PwmOpen(uint32_t num); ``` -**Table 3** PwmOpen - - + **Table 3** Description of PwmOpen -| Parameter| Description| -| ---------- | ----------------------- | -| num | PWM device number.| -| **Return Value** | **Description**| +| **Parameter**| **Description**| +| -------- | -------- | +| num | PWM device number. | +| **Return Value** | **Description** | | handle | Handle of the PWM device obtained.| -| NULL | The operation fails.| +| NULL | The operation fails. | + +Example: Open the device handle of PWM device 0. -```c +``` uint32_t num = 0; /* PWM device number. */ DevHandle handle = NULL; @@ -128,48 +87,49 @@ if (handle == NULL) { } ``` -### Closing a PWM Device Handle -Close a PWM device to release resources. +### Closing a PWM Device Handle -```c -void PwmClose(DevHandle handle); -``` +Call **PwmClose()** to close a PWM device handle to release resources. -**Table 4** PwmClose - +``` +voidPwmClose(DevHandle handle); +``` -| Parameter| Description| -| ------ | ----------- | -| handle | PWM device handle to close.| + **Table 4** Description of PwmClose +| **Parameter**| **Description**| +| -------- | -------- | +| handle | PWM device handle to close. | -```c + +``` /* Close a PWM device handle. */ PwmClose(handle); ``` -### Enabling a PWM Device -Enable a PWM device. +### Enabling a PWM Device -```c +Call **PwmEnable()** to enable a PWM device. + + +``` int32_t PwmEnable(DevHandle handle); ``` -**Table 5** PwmEnable + **Table 5** Description of PwmEnable - - -| Parameter| Description| -| ---------- | -------------- | -| handle | PWM device handle.| +| **Parameter**| **Description**| +| -------- | -------- | +| handle | PWM device handle. | | **Return Value** | **Description** | -| 0 | The operation is successful.| -| Negative number| The operation fails.| +| 0 | The operation is successful. | +| Negative number | The operation fails. | + -```c +``` int32_t ret; /* Enable a PWM device. */ @@ -179,26 +139,27 @@ if (ret != 0) { } ``` -### Disabling a PWM Device -Disable a PWM device. +### Disabling a PWM Device + +Call **PwmDisable()** to disable a PWM device. -```c + +``` int32_t PwmDisable(DevHandle handle); ``` -**Table 6** PwmDisable + **Table 6** Description of PwmDisable - - -| Parameter| Description| -| ---------- | -------------- | -| handle | PWM device handle.| +| **Parameter**| **Description**| +| -------- | -------- | +| handle | PWM device handle. | | **Return Value** | **Description** | -| 0 | The operation is successful.| -| Negative number| The operation fails.| +| 0 | The operation is successful. | +| Negative number | The operation fails. | + -```c +``` int32_t ret; /* Disable a PWM device. */ @@ -208,27 +169,28 @@ if (ret != 0) { } ``` -### Setting the PWM Period -Set the PWM period. +### Setting the PWM Period + +Call **PwmSetPeriod()** to set the PWM period. + -```c +``` int32_t PwmSetPeriod(DevHandle handle, uint32_t period); ``` -**Table 7** PwmSetPeriod - - + **Table 7** Description of PwmSetPeriod -| Parameter| Description| -| ---------- | ------------------------ | -| handle | PWM device handle.| +| **Parameter**| **Description**| +| -------- | -------- | +| handle | PWM device handle. | | period | PWM period to set, in ns.| -| **Return Value**| **Description**| -| 0 | The operation is successful.| -| Negative number| The operation fails.| +| **Return Value**| **Description** | +| 0 | The operation is successful. | +| Negative number | The operation fails. | -```c + +``` int32_t ret; /* Set the PWM period to 50000000 ns.*/ @@ -237,27 +199,29 @@ if (ret != 0) { /* Error handling. */ } ``` -### Setting the PWM Signal ON-State Time -Set the time that the PWM signal is in the ON state. -```c +### Setting the PWM Signal ON-State Time + +Call **PwmSetDuty()** to set the time that the PWM signal is in the ON state. + + +``` int32_t PwmSetDuty(DevHandle handle, uint32_t duty); ``` -**Table 8** PwmSetDuty - - + **Table 8** Description of PwmSetDuty -| Parameter| Description| -| ---------- | ---------------------------- | -| handle | PWM device handle.| +| **Parameter**| **Description**| +| -------- | -------- | +| handle | PWM device handle. | | duty | Time that the signal is in the ON state, in ns.| -| **Return Value**| **Description**| -| 0 | The operation is successful.| -| Negative number| The operation fails.| +| **Return Value**| **Description** | +| 0 | The operation is successful. | +| Negative number | The operation fails. | -```c + +``` int32_t ret; /* Set the signal ON-state time to 25000000 ns. */ @@ -266,27 +230,29 @@ if (ret != 0) { /* Error handling. */ } ``` -### Setting the PWM Polarity -Set the signal polarity for a PWM device. -```c +### Setting the PWM Signal Polarity + +Call **PwmSetPolarity()** to set the signal polarity for a PWM device. + + +``` int32_t PwmSetPolarity(DevHandle handle, uint8_t polarity); ``` -**Table 9** PwmSetPolarity - - + **Table 9** Description of PwmSetPolarity -| Parameter| Description| -| ---------- | ------------------- | -| handle | PWM device handle.| +| **Parameter**| **Description**| +| -------- | -------- | +| handle | PWM device handle. | | polarity | Polarity to set, which can be **PWM\_NORMAL\_POLARITY** or **PWM\_INVERTED\_POLARITY**.| -| **Return Value**| **Description**| -| 0 | The operation is successful.| -| Negative number| The operation fails.| +| **Return Value**| **Description** | +| 0 | The operation is successful. | +| Negative number | The operation fails. | -```c + +``` int32_t ret; /* Set the PWM polarity to PWM_INVERTED_POLARITY. */ @@ -297,34 +263,34 @@ if (ret != 0) { ``` -### Setting PWM Device Parameters +### Setting PWM Device Parameters -Set PWM device parameters. +Call **PwmSetConfig()** to set PWM device parameters. -```c + +``` int32_t PwmSetConfig(DevHandle handle, struct PwmConfig *config); ``` -**Table 10** PwmSetConfig + **Table 10** Description of PwmSetConfig - +| **Parameter**| **Description**| +| -------- | -------- | +| handle | PWM device handle to close. | +| \*config | Pointer to PWM parameters. | +| **Return Value**| **Description** | +| 0 | The operation is successful. | +| Negative number | The operation fails. | -| Parameter| Description| -| ---------- | -------------- | -| handle | PWM device handle.| -| *config | Pointer to PWM parameters.| -| **Return Value**| **Description**| -| 0 | The operation is successful.| -| Negative number| The operation fails.| -```c +``` int32_t ret; struct PwmConfig pcfg; -pcfg.duty = 25000000; /* Set the signal ON-state time to 25000000 ns. */ -pcfg.period = 50000000; /* Set the PWM period to 50000000 ns. */ -pcfg.number = 0; /* Generate square waves repeatedly. */ +pcfg.duty = 25000000; /* Set the signal ON-state time to 25000000 ns. */ +pcfg.period = 50000000; /* Set the PWM period to 50000000 ns. */ +pcfg.number = 0; /* Generate square waves repeatedly. */ pcfg.polarity = PWM_INVERTED_POLARITY; /* Set the PWM polarity to PWM_INVERTED_POLARITY. */ -pcfg.status = PWM_ENABLE_STATUS; /* Set the running status to Enabled. */ +pcfg.status = PWM_ENABLE_STATUS; /* Set the running status to Enabled. */ /* Set PWM device parameters. */ ret = PwmSetConfig(handle, &pcfg); @@ -333,27 +299,28 @@ if (ret != 0) { } ``` -### Obtaining PWM Device Parameters -Obtain PWM device parameters. +### Obtaining PWM Device Parameters + +Call **PwmGetConfig()** to obtain PWM device parameters. -```c + +``` int32_t PwmGetConfig(DevHandle handle, struct PwmConfig *config); ``` -**Table 11** PwmGetConfig + **Table 11** Description of PwmGetConfig - +| **Parameter**| **Description**| +| -------- | -------- | +| handle | PWM device handle to close. | +| \*config | Pointer to PWM parameters. | +| **Return Value**| **Description** | +| 0 | The operation is successful. | +| Negative number | The operation fails. | -| Parameter| Description| -| ---------- | -------------- | -| handle | PWM device handle.| -| *config | Pointer to PWM parameters.| -| **Return Value**| **Description**| -| 0 | The operation is successful.| -| Negative number| The operation fails.| -```c +``` int32_t ret; struct PwmConfig pcfg; @@ -364,10 +331,12 @@ if (ret != 0) { } ``` -## Usage Example + +## Development Example The following example shows how to use the APIs to implement a PWM driver and manage the PWM device. + ``` void PwmTestSample(void) { @@ -376,12 +345,12 @@ void PwmTestSample(void) DevHandle handle = NULL; struct PwmConfig pcfg; - pcfg.duty = 20000000; /* Set the signal ON-state time to 20000000 ns. */ - pcfg.period = 40000000; /* Set the PWM period to 40000000 ns. */ - pcfg.number = 100; /* Generate 100 square waves. */ + pcfg.duty = 20000000; /* Set the signal ON-state time to 20000000 ns. */ + pcfg.period = 40000000; /* Set the PWM period to 40000000 ns. */ + pcfg.number = 100; /* Generate 100 square waves. */ pcfg.polarity = PWM_NORMAL_POLARITY; /* Set the polarity to PWM_NORMAL_POLARITY. */ pcfg.status = PWM_ENABLE_STATUS; /* Set the running status to Enabled. */ - + /* Enter the PWM device number. */ num = 1; @@ -412,14 +381,14 @@ void PwmTestSample(void) HDF_LOGE("PwmSetPolarity: failed, ret %d\n", ret); goto _ERR; } - + /* Obtain PWM device parameters. */ ret = PwmGetConfig(handle, &pcfg); if (ret != 0) { HDF_LOGE("PwmGetConfig: failed, ret %d\n", ret); goto _ERR; } - + /* Enable the PWM device. */ ret = PwmEnable(handle); if (ret != 0) { @@ -440,7 +409,7 @@ void PwmTestSample(void) HDF_LOGE("PwmDisable: failed, ret %d\n", ret); goto _ERR; } - + _ERR: /* Close the PWM device handle. */ PwmClose(handle);