1# Development Guidelines<a name="EN-US_TOPIC_0000001078876452"></a> 2 3- [Available APIs](#section158501652121514) 4- [How to Develop](#section783435801510) 5- [Development Example](#section460018317164) 6 - [Example Description](#section22061718111412) 7 - [Sample Code](#section1775922321416) 8 - [Verification](#section160404016213) 9 10 11## Available APIs<a name="section158501652121514"></a> 12 13<a name="table1078714915105"></a> 14<table><thead align="left"><tr id="row1280518971010"><th class="cellrowborder" valign="top" width="20.1%" id="mcps1.1.4.1.1"><p id="p1380510912104"><a name="p1380510912104"></a><a name="p1380510912104"></a>Category</p> 15</th> 16<th class="cellrowborder" valign="top" width="20.52%" id="mcps1.1.4.1.2"><p id="p08051291106"><a name="p08051291106"></a><a name="p08051291106"></a>API</p> 17</th> 18<th class="cellrowborder" valign="top" width="59.38%" id="mcps1.1.4.1.3"><p id="p12805149151012"><a name="p12805149151012"></a><a name="p12805149151012"></a>Description</p> 19</th> 20</tr> 21</thead> 22<tbody><tr id="row168052913104"><td class="cellrowborder" rowspan="3" valign="top" width="20.1%" headers="mcps1.1.4.1.1 "><p id="p180618915101"><a name="p180618915101"></a><a name="p180618915101"></a>Creating or deleting a semaphore</p> 23</td> 24<td class="cellrowborder" valign="top" width="20.52%" headers="mcps1.1.4.1.2 "><p id="p198061196105"><a name="p198061196105"></a><a name="p198061196105"></a>LOS_SemCreate</p> 25</td> 26<td class="cellrowborder" valign="top" width="59.38%" headers="mcps1.1.4.1.3 "><p id="p1980609121010"><a name="p1980609121010"></a><a name="p1980609121010"></a>Creates a semaphore and returns the semaphore ID.</p> 27</td> 28</tr> 29<tr id="row4806990105"><td class="cellrowborder" valign="top" headers="mcps1.1.4.1.1 "><p id="p280620917109"><a name="p280620917109"></a><a name="p280620917109"></a>LOS_BinarySemCreate</p> 30</td> 31<td class="cellrowborder" valign="top" headers="mcps1.1.4.1.2 "><p id="p780614919107"><a name="p780614919107"></a><a name="p780614919107"></a>Creates a binary semaphore. The maximum counter value is <strong id="b1669151163313"><a name="b1669151163313"></a><a name="b1669151163313"></a>1</strong>.</p> 32</td> 33</tr> 34<tr id="row17806159151018"><td class="cellrowborder" valign="top" headers="mcps1.1.4.1.1 "><p id="p38067931012"><a name="p38067931012"></a><a name="p38067931012"></a>LOS_SemDelete</p> 35</td> 36<td class="cellrowborder" valign="top" headers="mcps1.1.4.1.2 "><p id="p168063941015"><a name="p168063941015"></a><a name="p168063941015"></a>Deletes a semaphore.</p> 37</td> 38</tr> 39<tr id="row188061098102"><td class="cellrowborder" rowspan="2" valign="top" width="20.1%" headers="mcps1.1.4.1.1 "><p id="p5806179161014"><a name="p5806179161014"></a><a name="p5806179161014"></a>Requesting or releasing a semaphore</p> 40</td> 41<td class="cellrowborder" valign="top" width="20.52%" headers="mcps1.1.4.1.2 "><p id="p16806159201015"><a name="p16806159201015"></a><a name="p16806159201015"></a>LOS_SemPend</p> 42</td> 43<td class="cellrowborder" valign="top" width="59.38%" headers="mcps1.1.4.1.3 "><p id="p4806149191011"><a name="p4806149191011"></a><a name="p4806149191011"></a>Requests a specified semaphore and sets the timeout period.</p> 44</td> 45</tr> 46<tr id="row4806199141019"><td class="cellrowborder" valign="top" headers="mcps1.1.4.1.1 "><p id="p280618913105"><a name="p280618913105"></a><a name="p280618913105"></a>LOS_SemPost</p> 47</td> 48<td class="cellrowborder" valign="top" headers="mcps1.1.4.1.2 "><p id="p178061917109"><a name="p178061917109"></a><a name="p178061917109"></a>Posts (releases) a semaphore.</p> 49</td> 50</tr> 51</tbody> 52</table> 53 54## How to Develop<a name="section783435801510"></a> 55 561. Call **LOS\_SemCreate** to create a semaphore. To create a binary semaphore, call **LOS\_BinarySemCreate**. 572. Call **LOS\_SemPend** to request a semaphore. 583. Call **LOS\_SemPost** to release a semaphore. 594. Call **LOS\_SemDelete** to delete a semaphore. 60 61> **NOTE:** 62>As interrupts cannot be blocked, semaphores cannot be requested in block mode for interrupts. 63 64## Development Example<a name="section460018317164"></a> 65 66### Example Description<a name="section22061718111412"></a> 67 68This example implements the following: 69 701. Create a semaphore in task **ExampleSem** and lock task scheduling. Create two tasks **ExampleSemTask1** and **ExampleSemTask2** \(with higher priority\). Enable the two tasks to request the same semaphore. Unlock task scheduling. Enable task **ExampleSem** to enter sleep mode for 400 ticks. Release the semaphore in task **ExampleSem**. 712. Enable** ExampleSemTask2** to enter sleep mode for 20 ticks after acquiring the semaphore. \(When **ExampleSemTask2** is delayed, **ExampleSemTask1** is woken up.\) 723. Enable **ExampleSemTask1** to request the semaphore in scheduled block mode, with a wait timeout period of 10 ticks. \(Because the semaphore is still held by **ExampleSemTask2**, **ExampleSemTask1** is suspended. **ExampleSemTask1** is woken up after 10 ticks.\) Enable **ExampleSemTask1** to request the semaphore in permanent block mode after it is woken up 10 ticks later. \(Because the semaphore is still held by **ExampleSemTask2**, **ExampleSemTask1** is suspended.\)** ** 734. After 20 ticks, **ExampleSemTask2** is woken up and releases the semaphore. **ExampleSemTask1** acquires the semaphore and is scheduled to run. When **ExampleSemTask1** is complete, it releases the semaphore. 745. Task **ExampleSem** is woken up after 400 ticks and deletes the semaphore. 75 76### Sample Code<a name="section1775922321416"></a> 77 78The sample code is as follows: 79 80``` 81#include "los_sem.h" 82#include "securec.h" 83 84/* Task ID*/ 85static UINT32 g_testTaskId01; 86static UINT32 g_testTaskId02; 87 88/* Task priority */ 89#define TASK_PRIO_TEST 5 90 91/* Semaphore structure ID*/ 92static UINT32 g_semId; 93 94VOID ExampleSemTask1(VOID) 95{ 96 UINT32 ret; 97 98 printf("ExampleSemTask1 try get sem g_semId, timeout 10 ticks.\n"); 99 100 /* Request the semaphore in scheduled block mode, with a wait timeout period of 10 ticks.*/ 101 ret = LOS_SemPend(g_semId, 10); 102 103 /* The semaphore is acquired.*/ 104 if (ret == LOS_OK) { 105 LOS_SemPost(g_semId); 106 return; 107 } 108 /* The semaphore is not acquired when the timeout period has expired.*/ 109 if (ret == LOS_ERRNO_SEM_TIMEOUT) { 110 printf("ExampleSemTask1 timeout and try get sem g_semId wait forever.\n"); 111 112 /* Request the semaphore in permanent block mode.*/ 113 ret = LOS_SemPend(g_semId, LOS_WAIT_FOREVER); 114 printf("ExampleSemTask1 wait_forever and get sem g_semId.\n"); 115 if (ret == LOS_OK) { 116 LOS_SemPost(g_semId); 117 return; 118 } 119 } 120} 121 122VOID ExampleSemTask2(VOID) 123{ 124 UINT32 ret; 125 printf("ExampleSemTask2 try get sem g_semId wait forever.\n"); 126 127 /* Request the semaphore in permanent block mode.*/ 128 ret = LOS_SemPend(g_semId, LOS_WAIT_FOREVER); 129 130 if (ret == LOS_OK) { 131 printf("ExampleSemTask2 get sem g_semId and then delay 20 ticks.\n"); 132 } 133 134 /* Enable the task to enter sleep mode for 20 ticks.*/ 135 LOS_TaskDelay(20); 136 137 printf("ExampleSemTask2 post sem g_semId.\n"); 138 /* Release the semaphore.*/ 139 LOS_SemPost(g_semId); 140 return; 141} 142 143UINT32 ExampleSem(VOID) 144{ 145 UINT32 ret; 146 TSK_INIT_PARAM_S task1; 147 TSK_INIT_PARAM_S task2; 148 149 /* Create a semaphore.*/ 150 LOS_SemCreate(0, &g_semId); 151 152 /* Lock task scheduling.*/ 153 LOS_TaskLock(); 154 155 /* Create task 1.*/ 156 (VOID)memset_s(&task1, sizeof(TSK_INIT_PARAM_S), 0, sizeof(TSK_INIT_PARAM_S)); 157 task1.pfnTaskEntry = (TSK_ENTRY_FUNC)ExampleSemTask1; 158 task1.pcName = "TestTask1"; 159 task1.uwStackSize = LOSCFG_BASE_CORE_TSK_DEFAULT_STACK_SIZE; 160 task1.usTaskPrio = TASK_PRIO_TEST; 161 ret = LOS_TaskCreate(&g_testTaskId01, &task1); 162 if (ret != LOS_OK) { 163 printf("task1 create failed.\n"); 164 return LOS_NOK; 165 } 166 167 /* Create task 2.*/ 168 (VOID)memset_s(&task2, sizeof(TSK_INIT_PARAM_S), 0, sizeof(TSK_INIT_PARAM_S)); 169 task2.pfnTaskEntry = (TSK_ENTRY_FUNC)ExampleSemTask2; 170 task2.pcName = "TestTask2"; 171 task2.uwStackSize = LOSCFG_BASE_CORE_TSK_DEFAULT_STACK_SIZE; 172 task2.usTaskPrio = (TASK_PRIO_TEST - 1); 173 ret = LOS_TaskCreate(&g_testTaskId02, &task2); 174 if (ret != LOS_OK) { 175 printf("task2 create failed.\n"); 176 return LOS_NOK; 177 } 178 179 /* Unlock task scheduling.*/ 180 LOS_TaskUnlock(); 181 182 ret = LOS_SemPost(g_semId); 183 184 /* Enable the task to enter sleep mode for 400 ticks.*/ 185 LOS_TaskDelay(400); 186 187 /* Delete the semaphore. */ 188 LOS_SemDelete(g_semId); 189 return LOS_OK; 190} 191``` 192 193### Verification<a name="section160404016213"></a> 194 195The development is successful if the return result is as follows: 196 197``` 198ExampleSemTask2 try get sem g_semId wait forever. 199ExampleSemTask2 get sem g_semId and then delay 20 ticks. 200ExampleSemTask1 try get sem g_semId, timeout 10 ticks. 201 202ExampleSemTask1 timeout and try get sem g_semId wait forever. 203ExampleSemTask2 post sem g_semId. 204ExampleSemTask1 wait_forever and get sem g_semId. 205``` 206 207
