• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Software Timer<a name="EN-US_TOPIC_0000001078575728"></a>
2
3-   [Basic Concepts](#section4118241563)
4-   [Working Principles](#section31079397569)
5-   [Development Guidelines](#section18576131520577)
6    -   [Available APIs](#section3138019145719)
7    -   [How to Develop](#section1344817403575)
8    -   [Development Example](#section114416313585)
9
10
11## Basic Concepts<a name="section4118241563"></a>
12
13The software timer is a software-simulated timer based on system tick interrupts. When the preset tick counter value has elapsed, the user-defined callback will be invoked. The timing precision is related to the cycle of the system tick clock. Due to the limitation in hardware, the number of hardware timers cannot meet users' requirements. Therefore, the Huawei LiteOS provides the software timer function. The software timer allows more timing services to be created, increasing the number of timers.
14
15The software timer supports the following functions:
16
17-   Disabling the software timer using a macro
18-   Creating a software timer
19-   Starting a software timer
20-   Stopping a software timer
21-   Deleting a software timer
22-   Obtaining the number of remaining ticks of a software timer
23
24## Working Principles<a name="section31079397569"></a>
25
26The software timer is a system resource. When modules are initialized, a contiguous section of memory is allocated for software timers. The maximum number of timers supported by the system is configured by the  **LOSCFG\_BASE\_CORE\_SWTMR\_LIMIT**  macro in  **los\_config.h**. Software timers use a queue and a task resource of the system. The software timers are triggered based on the First In First Out \(FIFO\) rule. For the timers set at the same time, the timer with a shorter value is always closer to the queue head than the timer with a longer value, and is preferentially triggered. The software timer counts time in ticks. When a software timer is created and started, the OpenHarmony system determines the timer expiry time based on the current system time \(in ticks\) and the timing interval set by the user, and adds the timer control structure to the global timing list.
27
28When a tick interrupt occurs, the tick interrupt handler scans the global timing list for expired timers. If such timers are found, the timers are recorded.
29
30When the tick interrupt handling function is complete, the software timer task \(with the highest priority\) is woken up. In this task, the timeout callback function for the recorded timer is called.
31
32Timer States
33
34-   OS\_SWTMR\_STATUS\_UNUSED
35
36    The timer is not in use. When the timer module is initialized, all timer resources in the system are set to this state.
37
38-   OS\_SWTMR\_STATUS\_CREATED
39
40    The timer is created but not started or the timer is stopped. When  **LOS\_SwtmrCreate**  is called for a timer that is not in use or  **LOS\_SwtmrStop**  is called for a newly started timer, the timer changes to this state.
41
42-   OS\_SWTMR\_STATUS\_TICKING
43
44    The timer is running \(counting\). When  **LOS\_SwtmrStart**  is called for a newly created timer, the timer enters this state.
45
46
47Timer Modes
48
49The OpenHarmony provides three types of software timers:
50
51-   One-shot timer: Once started, the timer is automatically deleted after triggering only one timer event.
52-   Periodic timer: This type of timer periodically triggers timer events until it is manually stopped.
53-   One-shot timer deleted by calling an API
54
55## Development Guidelines<a name="section18576131520577"></a>
56
57### Available APIs<a name="section3138019145719"></a>
58
59The following table describes APIs available for the OpenHarmony LiteOS-A software timer module. For more details about the APIs, see the API reference.
60
61**Table  1**  Software timer APIs
62
63<a name="table107038227425"></a>
64<table><thead align="left"><tr id="row2704122217420"><th class="cellrowborder" valign="top" width="20.6020602060206%" id="mcps1.2.4.1.1"><p id="p57041622144212"><a name="p57041622144212"></a><a name="p57041622144212"></a>Category</p>
65</th>
66<th class="cellrowborder" valign="top" width="29.542954295429542%" id="mcps1.2.4.1.2"><p id="p19704142216424"><a name="p19704142216424"></a><a name="p19704142216424"></a>API</p>
67</th>
68<th class="cellrowborder" valign="top" width="49.85498549854985%" id="mcps1.2.4.1.3"><p id="p670412224217"><a name="p670412224217"></a><a name="p670412224217"></a>Description</p>
69</th>
70</tr>
71</thead>
72<tbody><tr id="row1470413222429"><td class="cellrowborder" rowspan="2" valign="top" width="20.6020602060206%" headers="mcps1.2.4.1.1 "><p id="p8284115918428"><a name="p8284115918428"></a><a name="p8284115918428"></a>Creating or deleting timers</p>
73</td>
74<td class="cellrowborder" valign="top" width="29.542954295429542%" headers="mcps1.2.4.1.2 "><p id="p117045225428"><a name="p117045225428"></a><a name="p117045225428"></a>LOS_SwtmrCreate</p>
75</td>
76<td class="cellrowborder" valign="top" width="49.85498549854985%" headers="mcps1.2.4.1.3 "><p id="p170422234213"><a name="p170422234213"></a><a name="p170422234213"></a>Creates a software timer.</p>
77</td>
78</tr>
79<tr id="row11704102217425"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1970492213426"><a name="p1970492213426"></a><a name="p1970492213426"></a>LOS_SwtmrDelete</p>
80</td>
81<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p870442211421"><a name="p870442211421"></a><a name="p870442211421"></a>Deletes a software timer.</p>
82</td>
83</tr>
84<tr id="row57041422184215"><td class="cellrowborder" rowspan="2" valign="top" width="20.6020602060206%" headers="mcps1.2.4.1.1 "><p id="p1476172124318"><a name="p1476172124318"></a><a name="p1476172124318"></a>Starting or stopping timers</p>
85</td>
86<td class="cellrowborder" valign="top" width="29.542954295429542%" headers="mcps1.2.4.1.2 "><p id="p167040225423"><a name="p167040225423"></a><a name="p167040225423"></a>LOS_SwtmrStart</p>
87</td>
88<td class="cellrowborder" valign="top" width="49.85498549854985%" headers="mcps1.2.4.1.3 "><p id="p1570412229421"><a name="p1570412229421"></a><a name="p1570412229421"></a>Starts a software timer.</p>
89</td>
90</tr>
91<tr id="row15704172224219"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1170422214216"><a name="p1170422214216"></a><a name="p1170422214216"></a>LOS_SwtmrStop</p>
92</td>
93<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p17705122211426"><a name="p17705122211426"></a><a name="p17705122211426"></a>Stops a software timer.</p>
94</td>
95</tr>
96<tr id="row12705222154214"><td class="cellrowborder" valign="top" width="20.6020602060206%" headers="mcps1.2.4.1.1 "><p id="p0705622134214"><a name="p0705622134214"></a><a name="p0705622134214"></a>Obtaining remaining ticks of a software timer</p>
97</td>
98<td class="cellrowborder" valign="top" width="29.542954295429542%" headers="mcps1.2.4.1.2 "><p id="p177052220424"><a name="p177052220424"></a><a name="p177052220424"></a>LOS_SwtmrTimeGet</p>
99</td>
100<td class="cellrowborder" valign="top" width="49.85498549854985%" headers="mcps1.2.4.1.3 "><p id="p3705122264210"><a name="p3705122264210"></a><a name="p3705122264210"></a>Obtains the number of remaining ticks of a software timer.</p>
101</td>
102</tr>
103</tbody>
104</table>
105
106### How to Develop<a name="section1344817403575"></a>
107
108The typical development process of software timers is as follows:
109
1101.  Configure the software timer.
111    -   Check that  **LOSCFG\_BASE\_CORE\_SWTMR**  and  **LOSCFG\_BASE\_IPC\_QUEUE**  are enabled.
112    -   Configure  **LOSCFG\_BASE\_CORE\_SWTMR\_LIMIT**  \(maximum number of software timers supported by the system\).
113    -   Configure  **OS\_SWTMR\_HANDLE\_QUEUE\_SIZE**  \(maximum length of the software timer queue\).
114
1152.  Call  **LOS\_SwtmrCreate**  to create a software timer.
116    -   Create a software timer with the specified timing duration, timeout handling function, and triggering mode.
117    -   Return the function execution result \(success or failure\).
118
1193.  Call  **LOS\_SwtmrStart**  to start the software timer.
1204.  Call  **LOS\_SwtmrTimeGet**  to obtain the remaining number of ticks of the software timer.
1215.  Call  **LOS\_SwtmrStop**  to stop the software timer.
1226.  Call  **LOS\_SwtmrDelete**  to delete the software timer.
123
124>![](../public_sys-resources/icon-note.gif) **NOTE:**
125>-   Avoid too many operations in the callback function of the software timer. Do not use APIs or perform operations that may cause task suspension or blocking.
126>-   The software timers use a queue and a task resource of the system. The priority of the software timer tasks is set to  **0**  and cannot be changed.
127>-   The number of software timer resources that can be configured in the system is the total number of software timer resources available to the entire system, not the number of software timer resources available to users. For example, if the system software timer occupies one more resource, the number of software timer resources available to users decreases by one.
128>-   If a one-shot software timer is created, the system automatically deletes the timer and reclaims resources after the timer times out and the callback function is executed.
129>-   For a one-shot software timer that will not be automatically deleted after expiration, you need to call  **LOS\_SwtmrDelete**  to delete it and reclaim the timer resource to prevent resource leakage.
130
131### Development Example<a name="section114416313585"></a>
132
133Prerequisites:
134
135-   In  **los\_config.h**,  **LOSCFG\_BASE\_CORE\_SWTMR**  is enabled.
136-   The maximum number of software timers supported by the system \(**LOSCFG\_BASE\_CORE\_SWTMR\_LIMIT**\) is configured.
137-   The maximum length of the software timer queue \(OS\_SWTMR\_HANDLE\_QUEUE\_SIZE\) is configured.
138
139**Sample Code**
140
141```
142#include "los_swtmr.h"
143
144void Timer1_Callback(uint32_t arg);
145void Timer2_Callback(uint32_t arg);
146
147UINT32 g_timercount1 = 0;
148UINT32 g_timercount2 = 0;
149
150void Timer1_Callback(uint32_t arg) // Callback function 1
151{
152    unsigned long tick_last1;
153    g_timercount1++;
154    tick_last1=(UINT32)LOS_TickCountGet(); // Obtain the current number of ticks.
155    PRINTK("g_timercount1=%d\n",g_timercount1);
156    PRINTK("tick_last1=%d\n",tick_last1);
157}
158
159void Timer2_Callback(uint32_t arg) // Callback function 2
160{
161    unsigned long tick_last2;
162    tick_last2=(UINT32)LOS_TickCountGet();
163    g_timercount2 ++;
164    PRINTK("g_timercount2=%d\n",g_timercount2);
165    PRINTK("tick_last2=%d\n",tick_last2);
166}
167
168void Timer_example(void)
169{
170    UINT16 id1;
171    UINT16 id2; // timer id
172    UINT32 uwTick;
173
174    /* Create a one-shot software timer, with the number of ticks set to 1000. When the number of ticks reaches 1000, callback function 1 is executed. */
175    LOS_SwtmrCreate (1000, LOS_SWTMR_MODE_ONCE, Timer1_Callback, &id1, 1);
176
177    /* Create a periodic software timer and execute callback function 2 every 100 ticks. */
178    LOS_SwtmrCreate(100, LOS_SWTMR_MODE_PERIOD, Timer2_Callback, &id2, 1);
179    PRINTK("create Timer1 success\n");
180
181    LOS_SwtmrStart (id1); // Start the one-shot software timer.
182    dprintf("start Timer1 success\n");
183    LOS_TaskDelay(200); // Delay 200 ticks.
184    LOS_SwtmrTimeGet(id1, &uwTick); // Obtain the number of remaining ticks of the one-short software timer.
185    PRINTK("uwTick =%d\n", uwTick);
186
187    LOS_SwtmrStop(id1); // Stop the software timer.
188    PRINTK("stop Timer1 success\n");
189
190    LOS_SwtmrStart(id1);
191    LOS_TaskDelay(1000);
192    LOS_SwtmrDelete(id1); // Delete the software timer.
193    PRINTK("delete Timer1 success\n");
194
195    LOS_SwtmrStart(id2); // Start the periodic software timer.
196    PRINTK("start Timer2\n");
197
198    LOS_TaskDelay(1000);
199    LOS_SwtmrStop(id2);
200    LOS_SwtmrDelete(id2);
201}
202```
203
204**Output**
205
206```
207create Timer1 success
208start Timer1 success
209uwTick =800
210stop Timer1 success
211g_timercount1=1
212tick_last1=1201
213delete Timer1 success
214start Timer2
215g_timercount2 =1
216tick_last1=1301
217g_timercount2 =2
218tick_last1=1401
219g_timercount2 =3
220tick_last1=1501
221g_timercount2 =4
222tick_last1=1601
223g_timercount2 =5
224tick_last1=1701
225g_timercount2 =6
226tick_last1=1801
227g_timercount2 =7
228tick_last1=1901
229g_timercount2 =8
230tick_last1=2001
231g_timercount2 =9
232tick_last1=2101
233g_timercount2 =10
234tick_last1=2201
235```
236
237