1# Development Guidelines<a name="EN-US_TOPIC_0000001078876508"></a> 2 3- [Available APIs](#section158501652121514) 4- [How to Develop](#section783435801510) 5- [Development Example](#section460018317164) 6 - [Example Description](#section896412438910) 7 - [Sample Code](#section149077554912) 8 - [Verification](#section4461439172017) 9 10 11## Available APIs<a name="section158501652121514"></a> 12 13<a name="table14277123518139"></a> 14<table><thead align="left"><tr id="row152771935131315"><th class="cellrowborder" valign="top" width="17.77177717771777%" id="mcps1.1.4.1.1"><p id="p1127733591316"><a name="p1127733591316"></a><a name="p1127733591316"></a>Category</p> 15</th> 16<th class="cellrowborder" valign="top" width="22.932293229322934%" id="mcps1.1.4.1.2"><p id="p22771357138"><a name="p22771357138"></a><a name="p22771357138"></a>API</p> 17</th> 18<th class="cellrowborder" valign="top" width="59.2959295929593%" id="mcps1.1.4.1.3"><p id="p327714358130"><a name="p327714358130"></a><a name="p327714358130"></a>Description</p> 19</th> 20</tr> 21</thead> 22<tbody><tr id="row1627793517136"><td class="cellrowborder" valign="top" width="17.77177717771777%" headers="mcps1.1.4.1.1 "><p id="p10525141151410"><a name="p10525141151410"></a><a name="p10525141151410"></a>Checking events</p> 23</td> 24<td class="cellrowborder" valign="top" width="22.932293229322934%" headers="mcps1.1.4.1.2 "><p id="p1027783551315"><a name="p1027783551315"></a><a name="p1027783551315"></a>LOS_EventPoll</p> 25</td> 26<td class="cellrowborder" valign="top" width="59.2959295929593%" headers="mcps1.1.4.1.3 "><p id="p1717215119159"><a name="p1717215119159"></a><a name="p1717215119159"></a>Checks whether the expected event occurs based on <strong id="b1698610296113"><a name="b1698610296113"></a><a name="b1698610296113"></a>eventID</strong>, <strong id="b11901203414114"><a name="b11901203414114"></a><a name="b11901203414114"></a>eventMask</strong>, and <strong id="b1198339016"><a name="b1198339016"></a><a name="b1198339016"></a>mode</strong>.</p> 27<div class="notice" id="note29631113132915"><a name="note29631113132915"></a><a name="note29631113132915"></a><span class="noticetitle"> NOTICE: </span><div class="noticebody"><p id="p886616817302"><a name="p886616817302"></a><a name="p886616817302"></a>If <strong id="b172231736214"><a name="b172231736214"></a><a name="b172231736214"></a>mode</strong> contains <strong id="b166781764215"><a name="b166781764215"></a><a name="b166781764215"></a>LOS_WAITMODE_CLR</strong> and the expected event occurs, the event that meets the requirements in <strong id="b194063713315"><a name="b194063713315"></a><a name="b194063713315"></a>eventID</strong> will be cleared. In this case, <strong id="b53278201333"><a name="b53278201333"></a><a name="b53278201333"></a>eventID</strong> is an input parameter and an output parameter. In other cases, <strong id="b1163116507319"><a name="b1163116507319"></a><a name="b1163116507319"></a>eventID</strong> is used only as an input parameter.</p> 28</div></div> 29</td> 30</tr> 31<tr id="row20278035131316"><td class="cellrowborder" valign="top" width="17.77177717771777%" headers="mcps1.1.4.1.1 "><p id="p135816209511"><a name="p135816209511"></a><a name="p135816209511"></a>Initializing events</p> 32</td> 33<td class="cellrowborder" valign="top" width="22.932293229322934%" headers="mcps1.1.4.1.2 "><p id="p5361103903417"><a name="p5361103903417"></a><a name="p5361103903417"></a>LOS_EventInit</p> 34</td> 35<td class="cellrowborder" valign="top" width="59.2959295929593%" headers="mcps1.1.4.1.3 "><p id="p1936143993419"><a name="p1936143993419"></a><a name="p1936143993419"></a>Initializes an event control block.</p> 36</td> 37</tr> 38<tr id="row1736713145208"><td class="cellrowborder" valign="top" width="17.77177717771777%" headers="mcps1.1.4.1.1 "><p id="p65802020512"><a name="p65802020512"></a><a name="p65802020512"></a>Reading events</p> 39</td> 40<td class="cellrowborder" valign="top" width="22.932293229322934%" headers="mcps1.1.4.1.2 "><p id="p1436015394341"><a name="p1436015394341"></a><a name="p1436015394341"></a>LOS_EventRead</p> 41</td> 42<td class="cellrowborder" valign="top" width="59.2959295929593%" headers="mcps1.1.4.1.3 "><p id="p1935911398345"><a name="p1935911398345"></a><a name="p1935911398345"></a>Reads an event (wait event). The task is blocked to wait based on the timeout period (in ticks).</p> 43<p id="p624360131813"><a name="p624360131813"></a><a name="p624360131813"></a>If no event is read, <strong id="b8113141912912"><a name="b8113141912912"></a><a name="b8113141912912"></a>0</strong> is returned.</p> 44<p id="p825491321911"><a name="p825491321911"></a><a name="p825491321911"></a>If an event is successfully read, a positive value (event set) is returned.</p> 45<p id="p262373895217"><a name="p262373895217"></a><a name="p262373895217"></a>In other cases, a specific error code is returned.</p> 46</td> 47</tr> 48<tr id="row19475718122016"><td class="cellrowborder" valign="top" width="17.77177717771777%" headers="mcps1.1.4.1.1 "><p id="p18580201754"><a name="p18580201754"></a><a name="p18580201754"></a>Writing events</p> 49</td> 50<td class="cellrowborder" valign="top" width="22.932293229322934%" headers="mcps1.1.4.1.2 "><p id="p1135843933412"><a name="p1135843933412"></a><a name="p1135843933412"></a>LOS_EventWrite</p> 51</td> 52<td class="cellrowborder" valign="top" width="59.2959295929593%" headers="mcps1.1.4.1.3 "><p id="p526932914325"><a name="p526932914325"></a><a name="p526932914325"></a>Writes a specific event to the event control block.</p> 53</td> 54</tr> 55<tr id="row913918371962"><td class="cellrowborder" valign="top" width="17.77177717771777%" headers="mcps1.1.4.1.1 "><p id="p13581201655"><a name="p13581201655"></a><a name="p13581201655"></a>Clearing events</p> 56</td> 57<td class="cellrowborder" valign="top" width="22.932293229322934%" headers="mcps1.1.4.1.2 "><p id="p12140137165"><a name="p12140137165"></a><a name="p12140137165"></a>LOS_EventClear</p> 58</td> 59<td class="cellrowborder" valign="top" width="59.2959295929593%" headers="mcps1.1.4.1.3 "><p id="p19140637968"><a name="p19140637968"></a><a name="p19140637968"></a>Clears an event in the event control block based on the event mask.</p> 60</td> 61</tr> 62<tr id="row1173017715"><td class="cellrowborder" valign="top" width="17.77177717771777%" headers="mcps1.1.4.1.1 "><p id="p1458102010519"><a name="p1458102010519"></a><a name="p1458102010519"></a>Destroying events</p> 63</td> 64<td class="cellrowborder" valign="top" width="22.932293229322934%" headers="mcps1.1.4.1.2 "><p id="p31740171"><a name="p31740171"></a><a name="p31740171"></a>LOS_EventDestroy</p> 65</td> 66<td class="cellrowborder" valign="top" width="59.2959295929593%" headers="mcps1.1.4.1.3 "><p id="p17171501971"><a name="p17171501971"></a><a name="p17171501971"></a>Destroys an event control block.</p> 67</td> 68</tr> 69</tbody> 70</table> 71 72## How to Develop<a name="section783435801510"></a> 73 74The typical event development process is as follows: 75 761. Initialize an event control block. 772. Block a read event control block. 783. Write related events. 794. Wake up a blocked task, read the event, and check whether the event meets conditions. 805. Handle the event control block. 816. Destroy an event control block. 82 83> **NOTE:** 84>- When an event is read or written, the 25th bit of the event is reserved and cannot be set. 85>- Repeated writes of the same event are treated as one write. 86 87## Development Example<a name="section460018317164"></a> 88 89### Example Description<a name="section896412438910"></a> 90 91In this example, run the **Example\_TaskEntry** task to create the **Example\_Event** task. Run the **Example\_Event** task to read an event to trigger task switching. Run the **Example\_TaskEntry** task to write an event. You can understand the task switching during event operations based on the sequence in which logs are recorded. 92 931. Create the **Example\_Event** task in the **Example\_TaskEntry** task with a higher priority than the **Example\_TaskEntry** task. 942. Run the **Example\_Event** task to read event **0x00000001**. Task switching occurs to execute the **Example\_TaskEntry** task. 953. Run the **Example\_TaskEntry** task to write event **0x00000001**. Task switching occurs to execute the **Example\_Event** task. 964. The **Example\_Event** task is executed. 975. The **Example\_TaskEntry** task is executed. 98 99### Sample Code<a name="section149077554912"></a> 100 101The sample code is as follows: 102 103``` 104#include "los_event.h" 105#include "los_task.h" 106#include "securec.h" 107 108/* Task ID*/ 109UINT32 g_testTaskId; 110 111/* Event control structure*/ 112EVENT_CB_S g_exampleEvent; 113 114/* Type of the wait event*/ 115#define EVENT_WAIT 0x00000001 116 117/* Example task entry function*/ 118VOID Example_Event(VOID) 119{ 120 UINT32 ret; 121 UINT32 event; 122 123 /* Set a timeout period for event reading to 100 ticks. If the specified event is not read within 100 ticks, the read operation times out and the task is woken up.*/ 124 printf("Example_Event wait event 0x%x \n", EVENT_WAIT); 125 126 event = LOS_EventRead(&g_exampleEvent, EVENT_WAIT, LOS_WAITMODE_AND, 100); 127 if (event == EVENT_WAIT) { 128 printf("Example_Event,read event :0x%x\n", event); 129 } else { 130 printf("Example_Event,read event timeout\n"); 131 } 132} 133 134UINT32 Example_TaskEntry(VOID) 135{ 136 UINT32 ret; 137 TSK_INIT_PARAM_S task1; 138 139 /* Initialize the event.*/ 140 ret = LOS_EventInit(&g_exampleEvent); 141 if (ret != LOS_OK) { 142 printf("init event failed .\n"); 143 return -1; 144 } 145 146 /* Create a task.*/ 147 (VOID)memset_s(&task1, sizeof(TSK_INIT_PARAM_S), 0, sizeof(TSK_INIT_PARAM_S)); 148 task1.pfnTaskEntry = (TSK_ENTRY_FUNC)Example_Event; 149 task1.pcName = "EventTsk1"; 150 task1.uwStackSize = OS_TSK_DEFAULT_STACK_SIZE; 151 task1.usTaskPrio = 5; 152 ret = LOS_TaskCreate(&g_testTaskId, &task1); 153 if (ret != LOS_OK) { 154 printf("task create failed.\n"); 155 return LOS_NOK; 156 } 157 158 /* Write the task wait event (g_testTaskId). */ 159 printf("Example_TaskEntry write event.\n"); 160 161 ret = LOS_EventWrite(&g_exampleEvent, EVENT_WAIT); 162 if (ret != LOS_OK) { 163 printf("event write failed.\n"); 164 return LOS_NOK; 165 } 166 167 /* Clear the flag.*/ 168 printf("EventMask:%d\n", g_exampleEvent.uwEventID); 169 LOS_EventClear(&g_exampleEvent, ~g_exampleEvent.uwEventID); 170 printf("EventMask:%d\n", g_exampleEvent.uwEventID); 171 172 /* Delete the task.*/ 173 ret = LOS_TaskDelete(g_testTaskId); 174 if (ret != LOS_OK) { 175 printf("task delete failed.\n"); 176 return LOS_NOK; 177 } 178 179 return LOS_OK; 180} 181``` 182 183### Verification<a name="section4461439172017"></a> 184 185The development is successful if the return result is as follows: 186 187``` 188Example_Event wait event 0x1 189Example_TaskEntry write event. 190Example_Event,read event :0x1 191EventMask:1 192EventMask:0 193``` 194 195
