1# Development Guidelines<a name="EN-US_TOPIC_0000001123948079"></a> 2 3- [Available APIs](#section158501652121514) 4- [How to Develop](#section783435801510) 5- [Development Example](#section460018317164) 6 - [Verification](#section189023104457) 7 8 9When a task is created, the OpenHarmony LiteOS-M kernel can perform operations, such as locking or unlocking task scheduling, suspending, restoring, and delaying the task, and setting or obtaining the task priority. 10 11## Available APIs<a name="section158501652121514"></a> 12 13The following table describes APIs available for the OpenHarmony LiteOS-M task module. For more details about the APIs, see the API reference. 14 15**Table 1** APIs of the task management module 16 17<a name="table1415203765610"></a> 18<table><thead align="left"><tr id="row134151837125611"><th class="cellrowborder" valign="top" width="12.85128512851285%" id="mcps1.2.4.1.1"><p id="p16415637105612"><a name="p16415637105612"></a><a name="p16415637105612"></a>Category</p> 19</th> 20<th class="cellrowborder" valign="top" width="29.8029802980298%" id="mcps1.2.4.1.2"><p id="p11415163718562"><a name="p11415163718562"></a><a name="p11415163718562"></a>API</p> 21</th> 22<th class="cellrowborder" valign="top" width="57.34573457345735%" id="mcps1.2.4.1.3"><p id="p1641533755612"><a name="p1641533755612"></a><a name="p1641533755612"></a>Description</p> 23</th> 24</tr> 25</thead> 26<tbody><tr id="row0415737175610"><td class="cellrowborder" rowspan="3" valign="top" width="12.85128512851285%" headers="mcps1.2.4.1.1 "><p id="p88211552111218"><a name="p88211552111218"></a><a name="p88211552111218"></a>Creating or deleting a task</p> 27</td> 28<td class="cellrowborder" valign="top" width="29.8029802980298%" headers="mcps1.2.4.1.2 "><p id="p6347518151610"><a name="p6347518151610"></a><a name="p6347518151610"></a>LOS_TaskCreateOnly</p> 29</td> 30<td class="cellrowborder" valign="top" width="57.34573457345735%" headers="mcps1.2.4.1.3 "><p id="p5347161814167"><a name="p5347161814167"></a><a name="p5347161814167"></a>Creates a task and suspends the task to disable scheduling of the task. To enable scheduling of the task, call <strong id="b16759181135816"><a name="b16759181135816"></a><a name="b16759181135816"></a>LOS_TaskResume</strong> to make the task enter the Ready state.</p> 31</td> 32</tr> 33<tr id="row1841519376561"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p4166128181614"><a name="p4166128181614"></a><a name="p4166128181614"></a>LOS_TaskCreate</p> 34</td> 35<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1516617282165"><a name="p1516617282165"></a><a name="p1516617282165"></a>Creates a task and places the task in the Ready state. If there is no task with a higher priority in the Ready queue, the task will be executed.</p> 36</td> 37</tr> 38<tr id="row1187514443616"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p9364362169"><a name="p9364362169"></a><a name="p9364362169"></a>LOS_TaskDelete</p> 39</td> 40<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p106058831812"><a name="p106058831812"></a><a name="p106058831812"></a>Deletes the specified task.</p> 41</td> 42</tr> 43<tr id="row1141513373562"><td class="cellrowborder" rowspan="5" valign="top" width="12.85128512851285%" headers="mcps1.2.4.1.1 "><p id="p9438545181812"><a name="p9438545181812"></a><a name="p9438545181812"></a>Controlling task status</p> 44</td> 45<td class="cellrowborder" valign="top" width="29.8029802980298%" headers="mcps1.2.4.1.2 "><p id="p2871432206"><a name="p2871432206"></a><a name="p2871432206"></a>LOS_TaskResume</p> 46</td> 47<td class="cellrowborder" valign="top" width="57.34573457345735%" headers="mcps1.2.4.1.3 "><p id="p2871632201"><a name="p2871632201"></a><a name="p2871632201"></a>Resumes a suspended task to place the task in the Ready state.</p> 48</td> 49</tr> 50<tr id="row1541513745611"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p99679299202"><a name="p99679299202"></a><a name="p99679299202"></a>LOS_TaskSuspend</p> 51</td> 52<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p596712910200"><a name="p596712910200"></a><a name="p596712910200"></a>Suspends the specified task and performs task switching.</p> 53</td> 54</tr> 55<tr id="row14167379561"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1596722915207"><a name="p1596722915207"></a><a name="p1596722915207"></a>LOS_TaskDelay</p> 56</td> 57<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1496792972019"><a name="p1496792972019"></a><a name="p1496792972019"></a>Makes a task wait for a period of time (in ticks) and releases CPU resources. When the delay time expires, the task enters the Ready state again. The input parameter is the number of ticks.</p> 58</td> 59</tr> 60<tr id="row1018605142017"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p19186185119201"><a name="p19186185119201"></a><a name="p19186185119201"></a>LOS_Msleep</p> 61</td> 62<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p418612515207"><a name="p418612515207"></a><a name="p418612515207"></a>Converts the input parameter number of milliseconds into number of ticks, and use the result to calls <strong id="b13541401095"><a name="b13541401095"></a><a name="b13541401095"></a>LOS_TaskDelay</strong>.</p> 63</td> 64</tr> 65<tr id="row2832910132011"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1896722932020"><a name="p1896722932020"></a><a name="p1896722932020"></a>LOS_TaskYield</p> 66</td> 67<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p796702962016"><a name="p796702962016"></a><a name="p796702962016"></a>Sets the time slice of the current task to <strong id="b1226164119919"><a name="b1226164119919"></a><a name="b1226164119919"></a>0</strong> to release CPU resources and schedule the task with the highest priority in the Ready queue to run.</p> 68</td> 69</tr> 70<tr id="row57041546104720"><td class="cellrowborder" rowspan="3" valign="top" width="12.85128512851285%" headers="mcps1.2.4.1.1 "><p id="p11344426483"><a name="p11344426483"></a><a name="p11344426483"></a>Control task scheduling</p> 71</td> 72<td class="cellrowborder" valign="top" width="29.8029802980298%" headers="mcps1.2.4.1.2 "><p id="p83447211482"><a name="p83447211482"></a><a name="p83447211482"></a>LOS_TaskLock</p> 73</td> 74<td class="cellrowborder" valign="top" width="57.34573457345735%" headers="mcps1.2.4.1.3 "><p id="p4344721480"><a name="p4344721480"></a><a name="p4344721480"></a>Locks task scheduling. However, tasks can still be interrupted.</p> 75</td> 76</tr> 77<tr id="row8645184724712"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p133441025480"><a name="p133441025480"></a><a name="p133441025480"></a>LOS_TaskUnlock</p> 78</td> 79<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p934418217482"><a name="p934418217482"></a><a name="p934418217482"></a>Unlocks task scheduling.</p> 80</td> 81</tr> 82<tr id="row16401849185317"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p54011249195317"><a name="p54011249195317"></a><a name="p54011249195317"></a>LOS_Schedule</p> 83</td> 84<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p640144919534"><a name="p640144919534"></a><a name="p640144919534"></a>Triggers task scheduling</p> 85</td> 86</tr> 87<tr id="row955081314485"><td class="cellrowborder" rowspan="3" valign="top" width="12.85128512851285%" headers="mcps1.2.4.1.1 "><p id="p11466102734816"><a name="p11466102734816"></a><a name="p11466102734816"></a>Controlling task priority</p> 88</td> 89<td class="cellrowborder" valign="top" width="29.8029802980298%" headers="mcps1.2.4.1.2 "><p id="p154664278482"><a name="p154664278482"></a><a name="p154664278482"></a>LOS_CurTaskPriSet</p> 90</td> 91<td class="cellrowborder" valign="top" width="57.34573457345735%" headers="mcps1.2.4.1.3 "><p id="p1046632764812"><a name="p1046632764812"></a><a name="p1046632764812"></a>Sets the priority for the current task.</p> 92</td> 93</tr> 94<tr id="row13909142489"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p5467927164811"><a name="p5467927164811"></a><a name="p5467927164811"></a>LOS_TaskPriSet</p> 95</td> 96<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p446772704811"><a name="p446772704811"></a><a name="p446772704811"></a>Sets the priority for a specified task.</p> 97</td> 98</tr> 99<tr id="row355119149485"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p134671527134811"><a name="p134671527134811"></a><a name="p134671527134811"></a>LOS_TaskPriGet</p> 100</td> 101<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1946782717489"><a name="p1946782717489"></a><a name="p1946782717489"></a>Obtains the priority of a specified task.</p> 102</td> 103</tr> 104<tr id="row4964232175514"><td class="cellrowborder" rowspan="8" valign="top" width="12.85128512851285%" headers="mcps1.2.4.1.1 "><p id="p1512125013144"><a name="p1512125013144"></a><a name="p1512125013144"></a>Obtaining task information</p> 105</td> 106<td class="cellrowborder" valign="top" width="29.8029802980298%" headers="mcps1.2.4.1.2 "><p id="p0142259562"><a name="p0142259562"></a><a name="p0142259562"></a>LOS_CurTaskIDGet</p> 107</td> 108<td class="cellrowborder" valign="top" width="57.34573457345735%" headers="mcps1.2.4.1.3 "><p id="p91419257568"><a name="p91419257568"></a><a name="p91419257568"></a>Obtains the ID of the current task.</p> 109</td> 110</tr> 111<tr id="row81994135812"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1620014131982"><a name="p1620014131982"></a><a name="p1620014131982"></a>LOS_NextTaskIDGet</p> 112</td> 113<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1297616371197"><a name="p1297616371197"></a><a name="p1297616371197"></a>Obtains the ID of the task with the highest priority in the Ready queue.</p> 114</td> 115</tr> 116<tr id="row1742101318812"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p147422136816"><a name="p147422136816"></a><a name="p147422136816"></a>LOS_NewTaskIDGet</p> 117</td> 118<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p18742101318812"><a name="p18742101318812"></a><a name="p18742101318812"></a>Same as <strong id="b151555352161"><a name="b151555352161"></a><a name="b151555352161"></a>LOS_NextTaskIDGet</strong>.</p> 119</td> 120</tr> 121<tr id="row135511828165616"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1235774875616"><a name="p1235774875616"></a><a name="p1235774875616"></a>LOS_CurTaskNameGet</p> 122</td> 123<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p52858313568"><a name="p52858313568"></a><a name="p52858313568"></a>Obtains the name of the current task.</p> 124</td> 125</tr> 126<tr id="row1411710407583"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p81176407583"><a name="p81176407583"></a><a name="p81176407583"></a>LOS_TaskNameGet</p> 127</td> 128<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1635193815613"><a name="p1635193815613"></a><a name="p1635193815613"></a>Obtains the name of a specified task.</p> 129</td> 130</tr> 131<tr id="row95431743121216"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p95431434127"><a name="p95431434127"></a><a name="p95431434127"></a>LOS_TaskStatusGet</p> 132</td> 133<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p57752481129"><a name="p57752481129"></a><a name="p57752481129"></a>Obtains the state of a specified task.</p> 134</td> 135</tr> 136<tr id="row5810125105712"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p57171053135711"><a name="p57171053135711"></a><a name="p57171053135711"></a>LOS_TaskInfoGet</p> 137</td> 138<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p77173535571"><a name="p77173535571"></a><a name="p77173535571"></a>Obtains information about a specified task, including the task state, priority, stack size, stack pointer (SP), task entry function, and used stack space.</p> 139</td> 140</tr> 141<tr id="row3909121616111"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p490917165118"><a name="p490917165118"></a><a name="p490917165118"></a>LOS_TaskIsRunning</p> 142</td> 143<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p790991618113"><a name="p790991618113"></a><a name="p790991618113"></a>Checks whether the task module has started scheduling.</p> 144</td> 145</tr> 146<tr id="row248964211159"><td class="cellrowborder" valign="top" width="12.85128512851285%" headers="mcps1.2.4.1.1 "><p id="p194891428158"><a name="p194891428158"></a><a name="p194891428158"></a>Maintaining and testing task information</p> 147</td> 148<td class="cellrowborder" valign="top" width="29.8029802980298%" headers="mcps1.2.4.1.2 "><p id="p14891142171519"><a name="p14891142171519"></a><a name="p14891142171519"></a>LOS_TaskSwitchInfoGet</p> 149</td> 150<td class="cellrowborder" valign="top" width="57.34573457345735%" headers="mcps1.2.4.1.3 "><p id="p6490204221518"><a name="p6490204221518"></a><a name="p6490204221518"></a>Obtains task switching information. The macro <strong id="b164011668388"><a name="b164011668388"></a><a name="b164011668388"></a>LOSCFG_BASE_CORE_EXC_TSK_SWITCH</strong> must be enabled.</p> 151</td> 152</tr> 153</tbody> 154</table> 155 156## How to Develop<a name="section783435801510"></a> 157 158The typical development process of the task module is as follows: 159 1601. Use **LOS\_TaskLock** to lock task scheduling and prevent high-priority tasks from being scheduled. 1612. Use **LOS\_TaskCreate** to create a task. 1623. Use **LOS\_TaskUnlock** to unlock task scheduling so that tasks can be scheduled by priority. 1634. Use **LOS\_TaskDelay** to delay a task. 1645. Use **LOS\_TaskSuspend** to suspend a task. 1656. Use **LOS\_TaskResume** to resume the suspended task. 166 167> **NOTE:** 168>- Running idle tasks reclaims the TCBs and stacks in the to-be-recycled linked list. 169>- The task name is a pointer without memory space allocated. When setting the task name, do not assign the local variable address to the task name pointer. 170>- The task stack size is 8-byte aligned. Follow the "nothing more and nothing less" principle while determining the task stack size. 171>- A running task cannot be suspended if task scheduling is locked. 172>- Idle tasks and software timer tasks cannot be suspended or deleted. 173>- In an interrupt handler or when a task is locked, the operation of calling **LOS\_TaskDelay** fails. 174>- Locking task scheduling does not disable interrupts. Tasks can still be interrupted while task scheduling is locked. 175>- Locking task scheduling must be used together with unlocking task scheduling. 176>- Task scheduling may occur while a task priority is being set. 177>- The maximum number of tasks that can be set for the operating system is the total number of tasks of the operating system, not the number of tasks available to users. For example, if the system software timer occupies one more task resource, the number of task resources available to users decreases by one. 178>- **LOS\_CurTaskPriSet** and **LOS\_TaskPriSet** cannot be used in interrupts or used to modify the priorities of software timer tasks. 179>- If the task corresponding to the task ID sent to **LOS\_TaskPriGet** has not been created or the task ID exceeds the maximum number of tasks, **-1** will be returned. 180>- Resources such as a mutex or a semaphore allocated to a task must have been released before the task is deleted. 181 182## Development Example<a name="section460018317164"></a> 183 184This example describes the priority-based task scheduling and use of task-related APIs, including creating, delaying, suspending, and resuming two tasks with different priorities, and locking/unlocking task scheduling. The sample code is as follows: 185 186``` 187UINT32 g_taskHiId; 188UINT32 g_taskLoId; 189#define TSK_PRIOR_HI 4 190#define TSK_PRIOR_LO 5 191 192UINT32 Example_TaskHi(VOID) 193{ 194 UINT32 ret; 195 196 printf("Enter TaskHi Handler.\n"); 197 198 /* Delay the task for 100 ticks. The task is then suspended, and the remaining task with the highest priority (TaskLo) will be executed.*/ 199 ret = LOS_TaskDelay(100); 200 if (ret != LOS_OK) { 201 printf("Delay TaskHi Failed.\n"); 202 return LOS_NOK; 203 } 204 205 /*After 100 ticks elapse, the task is resumed.*/ 206 printf("TaskHi LOS_TaskDelay Done.\n"); 207 208 /* Suspend the task.*/ 209 ret = LOS_TaskSuspend(g_taskHiId); 210 if (ret != LOS_OK) { 211 printf("Suspend TaskHi Failed.\n"); 212 return LOS_NOK; 213 } 214 printf("TaskHi LOS_TaskResume Success.\n"); 215 return ret; 216} 217 218/* Entry function of low-priority tasks */ 219UINT32 Example_TaskLo(VOID) 220{ 221 UINT32 ret; 222 223 printf("Enter TaskLo Handler.\n"); 224 225 /* Delay the task for 100 ticks. The task is then suspended, and the remaining task with the highest priority will be executed.*/ 226 ret = LOS_TaskDelay(100); 227 if (ret != LOS_OK) { 228 printf("Delay TaskLo Failed.\n"); 229 return LOS_NOK; 230 } 231 232 printf("TaskHi LOS_TaskSuspend Success.\n"); 233 234 /* Resume the suspended task g_taskHiId.*/ 235 ret = LOS_TaskResume(g_taskHiId); 236 if (ret != LOS_OK) { 237 printf("Resume TaskHi Failed.\n"); 238 return LOS_NOK; 239 } 240 return ret; 241} 242 243/* Task entry function used to create two tasks with different priorities */ 244UINT32 Example_TskCaseEntry(VOID) 245{ 246 UINT32 ret; 247 TSK_INIT_PARAM_S initParam; 248 249 /* Lock task scheduling to prevent newly created tasks from being scheduled prior to this task due to higher priority.*/ 250 LOS_TaskLock(); 251 252 printf("LOS_TaskLock() Success!\n"); 253 254 initParam.pfnTaskEntry = (TSK_ENTRY_FUNC)Example_TaskHi; 255 initParam.usTaskPrio = TSK_PRIOR_HI; 256 initParam.pcName = "TaskHi"; 257 initParam.uwStackSize = LOSCFG_BASE_CORE_TSK_DEFAULT_STACK_SIZE; 258 259 /* Create a high-priority task. The task will not be executed immediately after being created, because task scheduling is locked.*/ 260 ret = LOS_TaskCreate(&g_taskHiId, &initParam); 261 if (ret != LOS_OK) { 262 LOS_TaskUnlock(); 263 264 printf("Example_TaskHi create Failed!\n"); 265 return LOS_NOK; 266 } 267 268 printf("Example_TaskHi create Success!\n"); 269 270 initParam.pfnTaskEntry = (TSK_ENTRY_FUNC)Example_TaskLo; 271 initParam.usTaskPrio = TSK_PRIOR_LO; 272 initParam.pcName = "TaskLo"; 273 initParam.uwStackSize = LOSCFG_BASE_CORE_TSK_DEFAULT_STACK_SIZE; 274 275 /*Create a low-priority task. The task will not be executed immediately after being created, because task scheduling is locked.*/ 276 ret = LOS_TaskCreate(&g_taskLoId, &initParam); 277 if (ret != LOS_OK) { 278 LOS_TaskUnlock(); 279 printf("Example_TaskLo create Failed!\n"); 280 return LOS_NOK; 281 } 282 283 printf("Example_TaskLo create Success!\n"); 284 285 /* Unlock task scheduling. The task with the highest priority in the Ready queue will be executed.*/ 286 LOS_TaskUnlock(); 287 288 return LOS_OK; 289} 290``` 291 292### Verification<a name="section189023104457"></a> 293 294The development is successful if the return result is as follows: 295 296``` 297LOS_TaskLock() Success! 298Example_TaskHi create Success! 299Example_TaskLo create Success! 300Enter TaskHi Handler. 301Enter TaskLo Handler. 302TaskHi LOS_TaskDelay Done. 303TaskHi LOS_TaskSuspend Success. 304TaskHi LOS_TaskResume Success. 305``` 306 307
