• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Software Timer
2
3
4## Basic Concepts
5
6The 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.
7
8Due to the limitation in hardware, the number of hardware timers cannot meet users' requirements. The OpenHarmony LiteOS-A kernel provides the software timer function.
9
10The software timer allows more timing services to be created, increasing the number of timers.
11
12The software timer supports the following functions:
13
14- Disabling the software timer using a macro
15
16- Creating a software timer
17
18- Starting a software timer
19
20- Stopping a software timer
21
22- Deleting a software timer
23
24- Obtaining the number of remaining ticks of a software timer
25
26
27## Working Principles
28
29The 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**.
30
31Software 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.
32
33The 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.
34
35When 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.
36
37When the tick interrupt handler is complete, the software timer task (with the highest priority) will be woken up. In this task, the timeout callback for the recorded timer is called.
38
39A software timer can be in any of the following states:
40
41- OS_SWTMR_STATUS_UNUSED
42
43  The timer is not in use. When the timer module is initialized, all timer resources in the system are set to this state.
44
45- OS_SWTMR_STATUS_CREATED
46
47  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.
48
49- OS_SWTMR_STATUS_TICKING
50
51  The timer is running (counting). When **LOS_SwtmrStart** is called for a newly created timer, the timer enters this state.
52
53OpenHarmony provides three types of software timers:
54
55-   One-shot timer: Once started, the timer is automatically deleted after triggering only one timer event.
56-   Periodic timer: This type of timer periodically triggers timer events until it is manually stopped.
57-   One-shot timer deleted by calling an API
58
59
60## Development Guidelines
61
62
63### Available APIs
64
65The following table describes the APIs of the software timer module of the OpenHarmony LiteOS-A kernel.
66
67**Table 1** APIs for software timers
68
69| Category              | Description                                                    |
70| ---------------------- | ------------------------------------------------------------ |
71| Creating or deleting a timer      | **LOS_SwtmrCreate**: creates a software timer.<br>**LOS_SwtmrDelete**: deletes a software timer.|
72| Starting or stopping a timer      | **LOS_SwtmrStart**: starts a software timer.<br>**LOS_SwtmrStop**: stops a software timer.|
73| Obtaining remaining ticks of a software timer| **LOS_SwtmrTimeGet**: obtains the remaining ticks of a software timer.                  |
74
75
76### How to Develop
77
78The typical development process of software timers is as follows:
79
801. Configure the software timer.
81   - Check that **LOSCFG_BASE_CORE_SWTMR** and **LOSCFG_BASE_IPC_QUEUE** are enabled.
82   - Configure **LOSCFG_BASE_CORE_SWTMR_LIMIT** (maximum number of software timers supported by the system).
83   - Configure **OS_SWTMR_HANDLE_QUEUE_SIZE** (maximum length of the software timer queue).
84
852. Call **LOS_SwtmrCreate** to create a software timer.
86   - Create a software timer with the specified timing duration, timeout handling function, and triggering mode.
87   - Return the function execution result (success or failure).
88
893. Call **LOS_SwtmrStart** to start the software timer.
90
914. Call **LOS_SwtmrTimeGet** to obtain the remaining number of ticks of the software timer.
92
935. Call **LOS_SwtmrStop** to stop the software timer.
94
956. Call **LOS_SwtmrDelete** to delete the software timer.
96
97> **NOTE**<br>
98>
99> - Avoid too many operations in the callback of the software timer. Do not use APIs or perform operations that may cause task suspension or blocking.
100>
101> - 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.
102>
103> - 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.
104>
105> - 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 is invoked.
106>
107> - 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.
108
109
110### Development Example
111
112**Prerequisites**
113
114- In **los_config.h**, **LOSCFG_BASE_CORE_SWTMR** is enabled.
115- The maximum number of software timers supported by the system (**LOSCFG_BASE_CORE_SWTMR_LIMIT**) is configured.
116- The maximum length of the software timer queue (**OS_SWTMR_HANDLE_QUEUE_SIZE**) is configured.
117
118**Sample Code**
119
120```
121#include "los_swtmr.h"
122
123void Timer1_Callback(uint32_t arg);
124void Timer2_Callback(uint32_t arg);
125
126UINT32 g_timercount1 = 0;
127UINT32 g_timercount2 = 0;
128
129void Timer1_Callback(uint32_t arg) // Callback function 1
130{
131    unsigned long tick_last1;
132    g_timercount1++;
133    tick_last1=(UINT32)LOS_TickCountGet(); // Obtain the current number of ticks.
134    PRINTK("g_timercount1=%d\n",g_timercount1);
135    PRINTK("tick_last1=%d\n",tick_last1);
136}
137
138void Timer2_Callback(uint32_t arg) // Callback function 2
139{
140    unsigned long tick_last2;
141    tick_last2=(UINT32)LOS_TickCountGet();
142    g_timercount2 ++;
143    PRINTK("g_timercount2=%d\n",g_timercount2);
144    PRINTK("tick_last2=%d\n",tick_last2);
145}
146
147void Timer_example(void)
148{
149    UINT16 id1;
150    UINT16 id2; // timer id
151    UINT32 uwTick;
152
153    /* Create a one-shot software timer, with the number of ticks set to 1000. Callback 1 will be invoked when the number of ticks reaches 1000. */
154    LOS_SwtmrCreate (1000, LOS_SWTMR_MODE_ONCE, Timer1_Callback, &id1, 1);
155
156    /* Create a periodic software timer and invoke callback 2 every 100 ticks. */
157    LOS_SwtmrCreate(100, LOS_SWTMR_MODE_PERIOD, Timer2_Callback, &id2, 1);
158    PRINTK("create Timer1 success\n");
159
160    LOS_SwtmrStart(id1); // Start the one-shot software timer.
161    dprintf("start Timer1 success\n");
162    LOS_TaskDelay(200); // Delay 200 ticks.
163    LOS_SwtmrTimeGet(id1, &uwTick); // Obtain the number of remaining ticks of the one-short software timer.
164    PRINTK("uwTick =%d\n", uwTick);
165
166    LOS_SwtmrStop(id1); // Stop the software timer.
167    PRINTK("stop Timer1 success\n");
168
169    LOS_SwtmrStart(id1);
170    LOS_TaskDelay(1000);
171    LOS_SwtmrDelete(id1); // Delete the software timer.
172    PRINTK("delete Timer1 success\n");
173
174    LOS_SwtmrStart(id2); // Start the periodic software timer.
175    PRINTK("start Timer2\n");
176
177    LOS_TaskDelay(1000);
178    LOS_SwtmrStop(id2);
179    LOS_SwtmrDelete(id2);
180}
181```
182
183**Output**
184
185
186```
187create Timer1 success
188start Timer1 success
189uwTick =800
190stop Timer1 success
191g_timercount1=1
192tick_last1=1201
193delete Timer1 success
194start Timer2
195g_timercount2 =1
196tick_last1=1301
197g_timercount2 =2
198tick_last1=1401
199g_timercount2 =3
200tick_last1=1501
201g_timercount2 =4
202tick_last1=1601
203g_timercount2 =5
204tick_last1=1701
205g_timercount2 =6
206tick_last1=1801
207g_timercount2 =7
208tick_last1=1901
209g_timercount2 =8
210tick_last1=2001
211g_timercount2 =9
212tick_last1=2101
213g_timercount2 =10
214tick_last1=2201
215```
216