1# Development Guidelines<a name="EN-US_TOPIC_0000001078718194"></a> 2 3- [Available APIs](#section158501652121514) 4- [How to Develop](#section783435801510) 5- [Development Example](#section460018317164) 6 - [Example Description](#section3741753191918) 7 - [Sample Code](#section20760101182016) 8 - [Verification](#section11244112818172) 9 10 11## Available APIs<a name="section158501652121514"></a> 12 13The following table describes APIs available for the OpenHarmony LiteOS-M software timer module. For more details about the APIs, see the API reference. 14 15**Table 1** Software timer APIs 16 17<a name="table14277123518139"></a> 18<table><thead align="left"><tr id="row152771935131315"><th class="cellrowborder" valign="top" width="17.77177717771777%" id="mcps1.2.4.1.1"><p id="p1127733591316"><a name="p1127733591316"></a><a name="p1127733591316"></a>Category</p> 19</th> 20<th class="cellrowborder" valign="top" width="23.782378237823785%" id="mcps1.2.4.1.2"><p id="p22771357138"><a name="p22771357138"></a><a name="p22771357138"></a>API</p> 21</th> 22<th class="cellrowborder" valign="top" width="58.44584458445845%" id="mcps1.2.4.1.3"><p id="p327714358130"><a name="p327714358130"></a><a name="p327714358130"></a>Description</p> 23</th> 24</tr> 25</thead> 26<tbody><tr id="row159539510586"><td class="cellrowborder" rowspan="2" valign="top" width="17.77177717771777%" headers="mcps1.2.4.1.1 "><p id="p1194410585810"><a name="p1194410585810"></a><a name="p1194410585810"></a>Creating or deleting timers</p> 27</td> 28<td class="cellrowborder" valign="top" width="23.782378237823785%" headers="mcps1.2.4.1.2 "><p id="p10944105115814"><a name="p10944105115814"></a><a name="p10944105115814"></a>LOS_SwtmrCreate</p> 29</td> 30<td class="cellrowborder" valign="top" width="58.44584458445845%" headers="mcps1.2.4.1.3 "><p id="p9944105175818"><a name="p9944105175818"></a><a name="p9944105175818"></a>Creates a software timer.</p> 31</td> 32</tr> 33<tr id="row17953454580"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p094419505814"><a name="p094419505814"></a><a name="p094419505814"></a>LOS_SwtmrDelete</p> 34</td> 35<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p39445585817"><a name="p39445585817"></a><a name="p39445585817"></a>Deletes a software timer.</p> 36</td> 37</tr> 38<tr id="row79531357589"><td class="cellrowborder" rowspan="2" valign="top" width="17.77177717771777%" headers="mcps1.2.4.1.1 "><p id="p139443595820"><a name="p139443595820"></a><a name="p139443595820"></a>Starting or stopping timers</p> 39</td> 40<td class="cellrowborder" valign="top" width="23.782378237823785%" headers="mcps1.2.4.1.2 "><p id="p1894435175815"><a name="p1894435175815"></a><a name="p1894435175815"></a>LOS_SwtmrStart</p> 41</td> 42<td class="cellrowborder" valign="top" width="58.44584458445845%" headers="mcps1.2.4.1.3 "><p id="p1194415518581"><a name="p1194415518581"></a><a name="p1194415518581"></a>Starts a software timer.</p> 43</td> 44</tr> 45<tr id="row1095320545814"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p20944355589"><a name="p20944355589"></a><a name="p20944355589"></a>LOS_SwtmrStop</p> 46</td> 47<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p169441515816"><a name="p169441515816"></a><a name="p169441515816"></a>Stop a software timer.</p> 48</td> 49</tr> 50<tr id="row119525513581"><td class="cellrowborder" valign="top" width="17.77177717771777%" headers="mcps1.2.4.1.1 "><p id="p109442053586"><a name="p109442053586"></a><a name="p109442053586"></a>Obtaining remaining ticks of a software timer</p> 51</td> 52<td class="cellrowborder" valign="top" width="23.782378237823785%" headers="mcps1.2.4.1.2 "><p id="p9944354585"><a name="p9944354585"></a><a name="p9944354585"></a>LOS_SwtmrTimeGet</p> 53</td> 54<td class="cellrowborder" valign="top" width="58.44584458445845%" headers="mcps1.2.4.1.3 "><p id="p39441257586"><a name="p39441257586"></a><a name="p39441257586"></a>Obtains the number of remaining ticks of a software timer.</p> 55</td> 56</tr> 57</tbody> 58</table> 59 60## How to Develop<a name="section783435801510"></a> 61 62The typical development process of software timers is as follows: 63 641. Configure the software timer. 65 - Check that **LOSCFG\_BASE\_CORE\_SWTMR** and **LOSCFG\_BASE\_IPC\_QUEUE** are set to **1**. 66 - Configure **LOSCFG\_BASE\_CORE\_SWTMR\_LIMIT** \(maximum number of software timers supported by the system\). 67 - Configure **OS\_SWTMR\_HANDLE\_QUEUE\_SIZE** \(maximum length of the software timer queue\). 68 692. Call **LOS\_SwtmrCreate** to create a software timer. 70 - Create a software timer with the specified timing duration, timeout handling function, and triggering mode. 71 - Return the function execution result \(success or failure\). 72 733. Call **LOS\_SwtmrStart** to start the software timer. 744. Call **LOS\_SwtmrTimeGet** to obtain the remaining number of ticks of the software timer. 755. Call **LOS\_SwtmrStop** to stop the software timer. 766. Call **LOS\_SwtmrDelete** to delete the software timer. 77 78> **NOTE:** 79>- 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. 80>- 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. 81>- 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. 82>- 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. 83>- 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. 84 85## Development Example<a name="section460018317164"></a> 86 87### Example Description<a name="section3741753191918"></a> 88 89The following programming example demonstrates how to: 90 911. Create, start, delete, pause, and restart a software timer. 922. Use a one-shot software timer and a periodic software timer 93 94### Sample Code<a name="section20760101182016"></a> 95 96Prerequisites 97 98- In **los\_config.h**, **LOSCFG\_BASE\_CORE\_SWTMR** is enabled. 99- In **los\_config.h**, **LOSCFG\_BASE\_CORE\_SWTMR\_ALIGN** is disabled. The sample code does not involve timer alignment. 100- The maximum number of software timers supported by the system \(**LOSCFG\_BASE\_CORE\_SWTMR\_LIMIT**\) is configured. 101- The maximum length of the software timer queue \(OS\_SWTMR\_HANDLE\_QUEUE\_SIZE\) is configured. 102 103The sample code is as follows: 104 105``` 106#include "los_swtmr.h" 107 108/* Timer count */ 109UINT32 g_timerCount1 = 0; 110UINT32 g_timerCount2 = 0; 111 112/* Task ID*/ 113UINT32 g_testTaskId01; 114 115void Timer1_Callback(UINT32 arg) // Callback function 1 116{ 117 UINT32 tick_last1; 118 g_timerCount1++; 119 tick_last1 = (UINT32)LOS_TickCountGet(); // Obtain the current number of ticks. 120 printf("g_timerCount1=%d, tick_last1=%d\n", g_timerCount1, tick_last1); 121} 122 123void Timer2_Callback(UINT32 arg) // Callback function 2 124{ 125 UINT32 tick_last2; 126 tick_last2 = (UINT32)LOS_TickCountGet(); 127 g_timerCount2++; 128 printf("g_timerCount2=%d tick_last2=%d\n", g_timerCount2, tick_last2); 129} 130 131void Timer_example(void) 132{ 133 UINT32 ret; 134 UINT32 id1; // timer id1 135 UINT32 id2; // timer id2 136 UINT32 tickCount; 137 138 /* 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. */ 139 LOS_SwtmrCreate(1000, LOS_SWTMR_MODE_ONCE, Timer1_Callback, &id1, 1); 140 141 /* Create a periodic software timer and execute callback function 2 every 100 ticks. */ 142 LOS_SwtmrCreate(100, LOS_SWTMR_MODE_PERIOD, Timer2_Callback, &id2, 1); 143 printf("Timer 1 created.\n"); 144 145 LOS_SwtmrStart(id1); // Start the one-shot software timer. 146 printf("Timer 1 started.\n"); 147 148 LOS_TaskDelay(200); // Delay 200 ticks. 149 LOS_SwtmrTimeGet(id1, &tickCount); // Obtain the number of remaining ticks of the one-short software timer. 150 printf("tickCount=%d\n", tickCount); 151 152 LOS_SwtmrStop(id1); // Stop the software timer. 153 printf("Timer 1 stopped.\n"); 154 155 LOS_SwtmrStart(id1); 156 LOS_TaskDelay(1000); 157 158 LOS_SwtmrStart(id2); // Start the periodic software timer. 159 printf("Timer 2 started.\n"); 160 161 LOS_TaskDelay(1000); 162 LOS_SwtmrStop(id2); 163 ret = LOS_SwtmrDelete(id2); // Delete the software timer. 164 if (ret == LOS_OK) { 165 printf("Timer 2 deleted.\n"); 166 } 167} 168 169UINT32 Example_TaskEntry(VOID) 170{ 171 UINT32 ret; 172 TSK_INIT_PARAM_S task1; 173 174 /* Lock task scheduling. */ 175 LOS_TaskLock(); 176 177 /* Create task 1. */ 178 (VOID)memset(&task1, 0, sizeof(TSK_INIT_PARAM_S)); 179 task1.pfnTaskEntry = (TSK_ENTRY_FUNC)Timer_example; 180 task1.pcName = "TimerTsk"; 181 task1.uwStackSize = LOSCFG_BASE_CORE_TSK_DEFAULT_STACK_SIZE; 182 task1.usTaskPrio = 5; 183 ret = LOS_TaskCreate(&g_testTaskId01, &task1); 184 if (ret != LOS_OK) { 185 printf("Failed to create the timer task.\n"); 186 return LOS_NOK; 187 } 188 189 /* Unlock task scheduling. */ 190 LOS_TaskUnlock(); 191 192 return LOS_OK; 193} 194``` 195 196### Verification<a name="section11244112818172"></a> 197 198The output is as follows: 199 200``` 201Timer 1 created. 202Timer 1 started. 203tickCount=798 204Timer 1 stopped. 205g_timerCount1=1, tick_last1=1208 206Timer 2 started. 207g_timerCount2=1 tick_last2=1313 208g_timerCount2=2 tick_last2=1413 209g_timerCount2=3 tick_last2=1513 210g_timerCount2=4 tick_last2=1613 211g_timerCount2=5 tick_last2=1713 212g_timerCount2=6 tick_last2=1813 213g_timerCount2=7 tick_last2=1913 214g_timerCount2=8 tick_last2=2013 215g_timerCount2=9 tick_last2=2113 216g_timerCount2=10 tick_last2=2213 217Timer 2 deleted. 218``` 219 220
