• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# PWM
2
3
4## Overview
5
6Pulse 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.
7
8  The PWM APIs provide a set of functions for operating a PWM device, including those for:
9- Opening or closing a PWM device handle
10
11- Setting the PWM period, signal ON-state time, and polarity
12
13- Enabling and disabling a PWM device
14
15- Obtaining and setting PWM parameters
16
17
18### PwmConfig Structure
19
20  **Table 1** PwmConfig structure
21
22| Parameter| Description|
23| -------- | -------- |
24| duty | Time that a signal is in the ON state, in ns.|
25| period | Time for a signal to complete an on-and-off cycle, in ns.|
26| 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.|
27| polarity | PWM signal polarity, which can be positive or reverse.|
28| status | PWM device status, which can be enabled or disabled.|
29
30
31## Available APIs
32
33  **Table 2** PWM driver APIs
34
35| Category| Description|
36| -------- | -------- |
37| Operating PWM handles| -&nbsp;**PwmOpen**: opens the device handle of a PWM device.<br>-&nbsp;**PwmClose**: closes the device handle of a PWM device.|
38| Enabling or disabling PWM| -&nbsp;**PwmEnable**: enables a PWM device.<br>-&nbsp;**PwmDisable**: disables a PWM device.|
39| 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.|
40| Setting or obtaining PWM configuration| -&nbsp;**PwmSetConfig**: sets PWM device parameters.<br>-&nbsp;**PwmGetConfig**: obtains PWM device parameters.|
41
42> ![icon-note.gif](../public_sys-resources/icon-note.gif) **NOTE**<br/>
43> All APIs described in this document can be called only in the kernel space.
44
45
46## Usage Guidelines
47
48
49### How to Use
50
51The figure below illustrates how to use the APIs.
52
53**Figure 1** Using the PWM driver APIs
54
55![](figures/using-PWM-process.png)
56
57
58### Opening a PWM Device Handle
59
60Before performing operations on a PWM device, call **PwmOpen** to open the device handle.
61
62
63```
64DevHandle PwmOpen(uint32_t num);
65```
66
67  **Table 3** Description of PwmOpen
68
69| **Parameter**| **Description**|
70| -------- | -------- |
71| num        | PWM device number.            |
72| **Return Value** | **Description**         |
73| handle     | Handle of the PWM device obtained.|
74| NULL       | The operation failed.             |
75
76Example: Open the device handle of PWM device 0.
77
78
79```
80uint32_t num = 0;             /* PWM device number. */
81DevHandle handle = NULL;
82
83/* Obtain the PWM device handle. */
84handle = PwmOpen(num);
85if (handle  == NULL) {
86    /* Error handling. */
87}
88```
89
90
91### Closing a PWM Device Handle
92
93Call **PwmClose()** to close a PWM device handle to release resources.
94
95
96```
97voidPwmClose(DevHandle handle);
98```
99
100  **Table 4** Description of PwmClose
101
102| **Parameter**| **Description**|
103| -------- | -------- |
104| handle   | PWM device handle to close. |
105
106
107```
108/* Close a PWM device handle. */
109PwmClose(handle);
110```
111
112
113### Enabling a PWM Device
114
115Call **PwmEnable()** to enable a PWM device.
116
117
118```
119int32_t PwmEnable(DevHandle handle);
120```
121
122  **Table 5** Description of PwmEnable
123
124| **Parameter**| **Description**|
125| -------- | -------- |
126| handle     | PWM device handle.   |
127| **Return Value** | **Description** |
128| 0          | The operation is successful.      |
129| Negative number      | The operation failed.    |
130
131
132```
133int32_t ret;
134
135/* Enable a PWM device. */
136ret = PwmEnable(handle);
137if (ret != 0) {
138	/* Error handling. */
139}
140```
141
142
143### Disabling a PWM Device
144
145Call **PwmDisable()** to disable a PWM device.
146
147
148```
149int32_t PwmDisable(DevHandle handle);
150```
151
152  **Table 6** Description of PwmDisable
153
154| **Parameter**| **Description**|
155| -------- | -------- |
156| handle     | PWM device handle.   |
157| **Return Value** | **Description** |
158| 0          | The operation is successful.      |
159| Negative number      | The operation failed.     |
160
161
162```
163int32_t ret;
164
165/* Disable a PWM device. */
166ret = PwmDisable(handle);
167if (ret != 0) {
168	/* Error handling. */
169}
170```
171
172
173### Setting the PWM Period
174
175Call **PwmSetPeriod()** to set the PWM period.
176
177
178```
179int32_t PwmSetPeriod(DevHandle handle, uint32_t period);
180```
181
182  **Table 7** Description of PwmSetPeriod
183
184| **Parameter**| **Description**|
185| -------- | -------- |
186| handle     | PWM device handle.             |
187| period     | PWM period to set, in ns.|
188| **Return Value**| **Description**           |
189| 0          | The operation is successful.                |
190| Negative number      | The operation failed.              |
191
192
193```
194int32_t ret;
195
196/* Set the PWM period to 50000000 ns.*/
197ret = PwmSetPeriod(handle, 50000000);
198if (ret != 0) {
199	/* Error handling. */
200}
201```
202
203
204### Setting the PWM Signal ON-State Time
205
206Call **PwmSetDuty()** to set the time that the PWM signal is in the ON state.
207
208
209```
210int32_t PwmSetDuty(DevHandle handle, uint32_t duty);
211```
212
213  **Table 8** Description of PwmSetDuty
214
215| **Parameter**| **Description**|
216| -------- | -------- |
217| handle     | PWM device handle.                 |
218| duty       | Time that the signal is in the ON state, in ns.|
219| **Return Value**| **Description**               |
220| 0          | The operation is successful.                    |
221| Negative number      | The operation failed.                  |
222
223
224```
225int32_t ret;
226
227/* Set the signal ON-state time to 25000000 ns. */
228ret = PwmSetDuty(handle, 25000000);
229if (ret != 0) {
230	/* Error handling. */
231}
232```
233
234
235### Setting the PWM Signal Polarity
236
237Call **PwmSetPolarity()** to set the signal polarity for a PWM device.
238
239
240```
241int32_t PwmSetPolarity(DevHandle handle, uint8_t polarity);
242```
243
244  **Table 9** Description of PwmSetPolarity
245
246| **Parameter**| **Description**|
247| -------- | -------- |
248| handle     | PWM device handle.        |
249| polarity   | Polarity to set, which can be **PWM\_NORMAL\_POLARITY** or **PWM\_INVERTED\_POLARITY**.|
250| **Return Value**| **Description**      |
251| 0          | The operation is successful.           |
252| Negative number      | The operation failed.          |
253
254
255```
256int32_t ret;
257
258/* Set the PWM polarity to PWM_INVERTED_POLARITY. */
259ret = PwmSetPolarity(handle, PWM_INVERTED_POLARITY);
260if (ret != 0) {
261	/* Error handling. */
262}
263```
264
265
266### Setting PWM Device Parameters
267
268Call **PwmSetConfig()** to set PWM device parameters.
269
270
271```
272int32_t PwmSetConfig(DevHandle handle, struct PwmConfig *config);
273```
274
275  **Table 10** Description of PwmSetConfig
276
277| **Parameter**| **Description**|
278| -------- | -------- |
279| handle     | PWM device handle to close.   |
280| \*config   | Pointer to PWM parameters.      |
281| **Return Value**| **Description** |
282| 0          | The operation is successful.      |
283| Negative number      | The operation failed.    |
284
285
286```
287int32_t ret;
288struct PwmConfig pcfg;
289pcfg.duty = 25000000;			/* Set the signal ON-state time to 25000000 ns. */
290pcfg.period = 50000000;			/* Set the PWM period to 50000000 ns. */
291pcfg.number = 0;			/* Generate square waves repeatedly. */
292pcfg.polarity = PWM_INVERTED_POLARITY;	/* Set the PWM polarity to PWM_INVERTED_POLARITY. */
293pcfg.status = PWM_ENABLE_STATUS;	/* Set the running status to Enabled. */
294
295/* Set PWM device parameters. */
296ret = PwmSetConfig(handle, &pcfg);
297if (ret != 0) {
298	/* Error handling. */
299}
300```
301
302
303### Obtaining PWM Device Parameters
304
305Call **PwmGetConfig()** to obtain PWM device parameters.
306
307
308```
309int32_t PwmGetConfig(DevHandle handle, struct PwmConfig *config);
310```
311
312  **Table 11** Description of PwmGetConfig
313
314| **Parameter**| **Description**|
315| -------- | -------- |
316| handle     | PWM device handle to close.   |
317| \*config   | Pointer to PWM parameters.      |
318| **Return Value**| **Description** |
319| 0          | The operation is successful.      |
320| Negative number      | The operation failed.    |
321
322
323```
324int32_t ret;
325struct PwmConfig pcfg;
326
327/* Obtain PWM device parameters. */
328ret = PwmGetConfig(handle, &pcfg);
329if (ret != 0) {
330	/* Error handling. */
331}
332```
333
334
335## Development Example
336
337The following example shows how to use the APIs to implement a PWM driver and manage the PWM device.
338
339
340```
341void PwmTestSample(void)
342{
343    int32_t ret;
344    uint32_t num;
345    DevHandle handle = NULL;
346
347    struct PwmConfig pcfg;
348    pcfg.duty = 20000000;			/* Set the signal ON-state time to 20000000 ns. */
349    pcfg.period = 40000000;			/* Set the PWM period to 40000000 ns. */
350    pcfg.number = 100;				/* Generate 100 square waves. */
351    pcfg.polarity = PWM_NORMAL_POLARITY;	/* Set the polarity to PWM_NORMAL_POLARITY. */
352    pcfg.status = PWM_ENABLE_STATUS;		/* Set the running status to Enabled. */
353
354    /* Enter the PWM device number. */
355    num = 1;
356
357    /* Open the PWM device handle. */
358    handle = PwmOpen(num);
359    if (handle == NULL) {
360        HDF_LOGE("PwmOpen: failed!\n");
361        return;
362    }
363
364    /* Set the PWM period to 50000000 ns.*/
365    ret = PwmSetPeriod(handle, 50000000);
366    if (ret != 0) {
367        HDF_LOGE("PwmSetPeriod: failed, ret %d\n", ret);
368        goto _ERR;
369    }
370
371    /* Set the signal ON-state time to 25000000 ns. */
372    ret = PwmSetDuty(handle, 25000000);
373    if (ret != 0) {
374        HDF_LOGE("PwmSetDuty: failed, ret %d\n", ret);
375        goto _ERR;
376    }
377
378    /* Set the PWM polarity to PWM_INVERTED_POLARITY. */
379    ret = PwmSetPolarity(handle, PWM_INVERTED_POLARITY);
380    if (ret != 0) {
381        HDF_LOGE("PwmSetPolarity: failed, ret %d\n", ret);
382        goto _ERR;
383    }
384
385    /* Obtain PWM device parameters. */
386    ret = PwmGetConfig(handle, &pcfg);
387    if (ret != 0) {
388        HDF_LOGE("PwmGetConfig: failed, ret %d\n", ret);
389        goto _ERR;
390    }
391
392    /* Enable the PWM device. */
393    ret = PwmEnable(handle);
394    if (ret != 0) {
395	    HDF_LOGE("PwmEnable: failed, ret %d\n", ret);
396        goto _ERR;
397    }
398
399    /* Set PWM device parameters. */
400    ret = PwmSetConfig(handle, &pcfg);
401    if (ret != 0) {
402        HDF_LOGE("PwmSetConfig: failed, ret %d\n", ret);
403        goto _ERR;
404    }
405
406    /* Disable the PWM device. */
407    ret = PwmDisable(handle);
408    if (ret != 0) {
409        HDF_LOGE("PwmDisable: failed, ret %d\n", ret);
410        goto _ERR;
411    }
412
413_ERR:
414    /* Close the PWM device handle. */
415    PwmClose(handle);
416}
417```
418