Skip to content

D
Docs

yang2765 / Docs
与 Fork 源项目一致

Fork自 OpenHarmony / Docs

通知 1
Star 0
Fork 0
D
Docs

前往新版Gitcode，体验更适合开发者的 AI 搜索 >>

未验证 提交 646a7fd6 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!3093 #I4ZZGG完成，请审批 

Merge pull request !3093 from Annie_wang/PR2649
上级 d6089cd0 09f9af15
隐藏空白更改
内联 并排
Showing with 180 addition and 211 deletion
en/device-dev/driver/driver-platform-pwm-des.md
浏览文件 @ 646a7fd6
# PWM<a name="title_PWM_des"></a>
# PWM
## Overview <a name="section1_PWM_des"></a>
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<a name="section1.1_PWM_des"></a>
**Table 1** PwmConfig structure
<a name="table1_PWM_des"></a>
| 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 <b>0</b> 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<a name="section2_PWM_des"></a>
**Table 2** PWM device APIs
<a name="table2_PWM_des"></a>
<table border="0" cellpadding="0" cellspacing="0" width="800" style="border-collapse:
collapse;table-layout:fixed;width:700pt">
<tbody><tr height="19" style="height:14.25pt">
<td height="19" class="xl66" width="300" style="height:14.25pt;width:300pt">Category</td>
<td class="xl67" width="250" style="width:250pt">API</td>
<td class="xl67" width="300" style="width:300pt">Description</td>
</tr>
<tr height="19" style="height:14.25pt">
<td rowspan="2" height="38" class="xl65" style="height:28.5pt">Operating PWM handles</td>
<td>PwmOpen</td>
<td>Opens the handle of a PWM device.</td>
</tr>
<tr height="19" style="height:14.25pt">
<td height="19" style="height:14.25pt">PwmClose</td>
<td>Closes the handle of a PWM device.</td>
</tr>
<tr height="19" style="height:14.25pt">
<td rowspan="2" height="38" class="xl65" style="height:28.5pt">Enabling or disabling PWM</td>
<td>PwmEnable</td>
<td>Enables a PWM device.</td>
</tr>
<tr height="19" style="height:14.25pt">
<td height="19" style="height:14.25pt">PwmDisable</td>
<td>Disables a PWM device.</td>
</tr>
<tr height="19" style="height:14.25pt">
<td rowspan="3" height="57" class="xl65" style="height:42.75pt">Performing PWM configuration</td>
<td>PwmSetPeriod</td>
<td>Sets the PWM period.</td>
</tr>
<tr height="19" style="height:14.25pt">
<td height="19" style="height:14.25pt">PwmSetDuty</td>
<td>Sets the signal ON-state time.</td>
</tr>
<tr height="19" style="height:14.25pt">
<td height="19" style="height:14.25pt">PwmSetPolarity</td>
<td>Sets the PWM signal polarity.</td>
</tr>
<tr height="19" style="height:14.25pt">
<td rowspan="2" height="38" class="xl65" style="height:28.5pt">Setting or obtaining the PWM configuration</td>
<td>PwmSetConfig</td>
<td>Sets PWM device parameters.</td>
</tr>
<tr height="19" style="height:14.25pt">
<td height="19" style="height:14.25pt">PwmGetConfig</td>
<td>Obtains PWM device parameters.</td>
</tr>
</tbody></table>
>![](../public_sys-resources/icon-note.gif) **NOTE:**
>The PWM module can be used in kernel mode but not in user mode.
## Usage Guidelines<a name="section3_PWM_des"></a>
### How to Use<a name="section3.1_PWM_des"></a>
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<a name="fig1_PWM_des"></a>
### 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.<br>-&nbsp;Positive value: indicates the number of square waves to generate.<br>-&nbsp;**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| -&nbsp;**PwmOpen**: opens the device handle of a PWM device.<br>-&nbsp;**PwmClose**: closes the device handle of a PWM device.|
| Enabling or disabling PWM| -&nbsp;**PwmEnable**: enables a PWM device.<br>-&nbsp;**PwmDisable**: disables a PWM device.|
| Setting PWM| -&nbsp;**PwmSetPeriod**: sets the PWM period.<br>-&nbsp;**PwmSetDuty**: sets the signal ON-state time.<br>-&nbsp;**PwmSetPolarity**: sets the PWM signal polarity.|
| Setting or obtaining PWM configuration| -&nbsp;**PwmSetConfig**: sets PWM device parameters.<br>-&nbsp;**PwmGetConfig**: obtains PWM device parameters.|
> ![icon-note.gif](../public_sys-resources/icon-note.gif) **NOTE**<br/>
> 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<a name="section3.2_PWM_des"></a>
### 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
<a name="table3_PWM_des"></a>
**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<a name="section3.3_PWM_des"></a>
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
<a name="table4_PWM_des"></a>
```
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<a name="section3.4_PWM_des"></a>
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
<a name="table5_PWM_des"></a>
| 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<a name="section3.5_PWM_des"></a>
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
<a name="table6_PWM_des"></a>
| 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<a name="section3.6_PWM_des"></a>
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
<a name="table7_PWM_des"></a>
**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<a name="section3.7_PWM_des"></a>
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
<a name="table8_PWM_des"></a>
**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<a name="section3.8_PWM_des"></a>
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
<a name="table9_PWM_des"></a>
**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<a name="section3.9_PWM_des"></a>
### 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
<a name="table10_PWM_des"></a>
| **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<a name="section3.10_PWM_des"></a>
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
<a name="table11_PWM_des"></a>
| **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<a name="section4_PWM_des"></a>
## 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);
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或