1# Event 2 3## Basic Concepts 4 5An event is a mechanism for communication between tasks. It can be used to synchronize tasks. The events have the following features: 6 7- Events can be synchronized in one-to-many or many-to-many mode. In one-to-many mode, a task can wait for multiple events. In many-to-many mode, multiple tasks can wait for multiple events. However, a write event wakes up only one task from the block. 8- Event read timeout mechanism is used. 9- Events are used only for task synchronization, but not for data transmission. 10 11APIs are provided to initialize, read/write, clear, and destroy events. 12 13## Working Principles 14 15### Event Control Block 16 17``` 18/** 19* Event control block data structure 20 */ 21typedef struct tagEvent { 22 UINT32 uwEventID; /* Event set, which is a collection of events processed (written and cleared). */ 23 LOS_DL_LIST stEventList; /* List of tasks waiting for specific events*/ 24} EVENT_CB_S, *PEVENT_CB_S; 25``` 26 27### Working Principles<a name="section187761153144617"></a> 28 29**Initializing an event**: An event control block is created to maintain a collection of processed events and a linked list of tasks waiting for specific events. 30 31**Writing an event**: When a specified event is written to the event control block, the event control block updates the event set, traverses the task linked list, and determines whether to wake up related task based on the task conditions. 32 33**Reading an event**: If the read event already exists, it is returned synchronously. In other cases, the return time is determined based on the timeout period and event triggering status. If the wait event condition is met before the timeout period expires, the blocked task will be directly woken up. Otherwise, the blocked task will be woken up only after the timeout period has expired. 34 35The input parameters **eventMask** and **mode** determine whether the condition for reading an event is met. **eventMask** indicates the mask of the event. **mode** indicates the handling mode, which can be any of the following: 36 37- **LOS\_WAITMODE\_AND**: Event reading is successful only when all the events corresponding to **eventMask** occur. Otherwise, the task will be blocked, or an error code will be returned. 38- **LOS\_WAITMODE\_OR**: Event reading is successful when any of the events corresponding to **eventMask** occur. Otherwise, the task will be blocked, or an error code will be returned. 39- **LOS\_WAITMODE\_CLR**: This mode must be used with **LOS\_WAITMODE\_AND** or **LOS\_WAITMODE\_OR** \(LOS\_WAITMODE\_AND | LOS\_WAITMODE\_CLR or LOS\_WAITMODE\_OR | LOS\_WAITMODE\_CLR\). In this mode, if **LOS\_WAITMODE\_AND** or **LOS\_WAITMODE\_OR** is successful, the corresponding event type bit in the event control block will be automatically cleared. 40 41**Clearing event**: Clear the event set of the event control block based on the specified mask. If the mask is **0**, the event set will be cleared. If the mask is **0xffff**, no event will be cleared, and the event set remains unchanged. 42 43**Destroying an event**: Destroy the specified event control block. 44 45**Figure 1** Event working mechanism for mini systems<a name="fig17799175324612"></a> 46 47 48## Available APIs 49 50<a name="table14277123518139"></a> 51<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>Function</p> 52</th> 53<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> 54</th> 55<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> 56</th> 57</tr> 58</thead> 59<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> 60</td> 61<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> 62</td> 63<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="b209271084844433"><a name="b209271084844433"></a><a name="b209271084844433"></a>eventID</strong>, <strong id="b121646215244433"><a name="b121646215244433"></a><a name="b121646215244433"></a>eventMask</strong>, and <strong id="b192170443144433"><a name="b192170443144433"></a><a name="b192170443144433"></a>mode</strong>.</p> 64<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="b50092866644433"><a name="b50092866644433"></a><a name="b50092866644433"></a>mode</strong> contains <strong id="b195286359344433"><a name="b195286359344433"></a><a name="b195286359344433"></a>LOS_WAITMODE_CLR</strong> and the expected event occurs, the event that meets the requirements in <strong id="b33985475544433"><a name="b33985475544433"></a><a name="b33985475544433"></a>eventID</strong> will be cleared. In this case, <strong id="b637217044433"><a name="b637217044433"></a><a name="b637217044433"></a>eventID</strong> is an input parameter and an output parameter. In other cases, <strong id="b4992196844433"><a name="b4992196844433"></a><a name="b4992196844433"></a>eventID</strong> is used only as an input parameter.</p> 65</div></div> 66</td> 67</tr> 68<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> 69</td> 70<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> 71</td> 72<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> 73</td> 74</tr> 75<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> 76</td> 77<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> 78</td> 79<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> 80<p id="p624360131813"><a name="p624360131813"></a><a name="p624360131813"></a>If no event is read, <strong id="b129351022744433"><a name="b129351022744433"></a><a name="b129351022744433"></a>0</strong> is returned.</p> 81<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> 82<p id="p262373895217"><a name="p262373895217"></a><a name="p262373895217"></a>In other cases, a specific error code is returned.</p> 83</td> 84</tr> 85<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> 86</td> 87<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> 88</td> 89<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> 90</td> 91</tr> 92<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> 93</td> 94<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> 95</td> 96<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> 97</td> 98</tr> 99<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> 100</td> 101<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> 102</td> 103<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> 104</td> 105</tr> 106</tbody> 107</table> 108 109## How to Develop 110 111The typical event development process is as follows: 112 1131. Initialize an event control block. 1142. Block a read event control block. 1153. Write related events. 1164. Wake up a blocked task, read the event, and check whether the event meets conditions. 1175. Handle the event control block. 1186. Destroy an event control block. 119 120> **NOTE:** 121>- When an event is read or written, the 25th bit of the event is reserved and cannot be set. 122>- Repeated writes of the same event are treated as one write. 123 124## Development Example 125 126### Example Description 127 128In 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. 129 1301. Create the **Example\_Event** task in the **Example\_TaskEntry** task with a higher priority than the **Example\_TaskEntry** task. 1312. Run the **Example\_Event** task to read event **0x00000001**. Task switching is triggered to execute the **Example\_TaskEntry** task. 1323. Run the **Example\_TaskEntry** task to write event **0x00000001**. Task switching is triggered to execute the **Example\_Event** task. 1334. The **Example\_Event** task is executed. 1345. The **Example\_TaskEntry** task is executed. 135 136### Sample Code<a name="section149077554912"></a> 137 138The sample code is as follows: 139 140``` 141#include "los_event.h" 142#include "los_task.h" 143#include "securec.h" 144 145/* Task ID*/ 146UINT32 g_testTaskId; 147 148/* Event control structure*/ 149EVENT_CB_S g_exampleEvent; 150 151/* Type of the wait event*/ 152#define EVENT_WAIT 0x00000001 153 154/* Example task entry function*/ 155VOID Example_Event(VOID) 156{ 157 UINT32 ret; 158 UINT32 event; 159 160 /* 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. */ 161 printf("Example_Event wait event 0x%x \n", EVENT_WAIT); 162 163 event = LOS_EventRead(&g_exampleEvent, EVENT_WAIT, LOS_WAITMODE_AND, 100); 164 if (event == EVENT_WAIT) { 165 printf("Example_Event,read event :0x%x\n", event); 166 } else { 167 printf("Example_Event,read event timeout\n"); 168 } 169} 170 171UINT32 Example_TaskEntry(VOID) 172{ 173 UINT32 ret; 174 TSK_INIT_PARAM_S task1; 175 176 /* Initialize the event. */ 177 ret = LOS_EventInit(&g_exampleEvent); 178 if (ret != LOS_OK) { 179 printf("init event failed .\n"); 180 return -1; 181 } 182 183 /* Create a task. */ 184 (VOID)memset_s(&task1, sizeof(TSK_INIT_PARAM_S), 0, sizeof(TSK_INIT_PARAM_S)); 185 task1.pfnTaskEntry = (TSK_ENTRY_FUNC)Example_Event; 186 task1.pcName = "EventTsk1"; 187 task1.uwStackSize = OS_TSK_DEFAULT_STACK_SIZE; 188 task1.usTaskPrio = 5; 189 ret = LOS_TaskCreate(&g_testTaskId, &task1); 190 if (ret != LOS_OK) { 191 printf("task create failed.\n"); 192 return LOS_NOK; 193 } 194 195 /* Write the task wait event (g_testTaskId). */ 196 printf("Example_TaskEntry write event.\n"); 197 198 ret = LOS_EventWrite(&g_exampleEvent, EVENT_WAIT); 199 if (ret != LOS_OK) { 200 printf("event write failed.\n"); 201 return LOS_NOK; 202 } 203 204 /* Clear the flag. */ 205 printf("EventMask:%d\n", g_exampleEvent.uwEventID); 206 LOS_EventClear(&g_exampleEvent, ~g_exampleEvent.uwEventID); 207 printf("EventMask:%d\n", g_exampleEvent.uwEventID); 208 209 /* Delete the task. */ 210 ret = LOS_TaskDelete(g_testTaskId); 211 if (ret != LOS_OK) { 212 printf("task delete failed.\n"); 213 return LOS_NOK; 214 } 215 216 return LOS_OK; 217} 218``` 219 220### Verification 221 222The development is successful if the return result is as follows: 223 224``` 225Example_Event wait event 0x1 226Example_TaskEntry write event. 227Example_Event,read event :0x1 228EventMask:1 229EventMask:0 230``` 231 232
