• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Event<a name="EN-US_TOPIC_0000001078753124"></a>
2
3-   [Basic Concepts](#section122115620816)
4-   [Working Principles](#section94611116593)
5    -   [Event Control Block](#section1161415384467)
6    -   [Working Principles](#section187761153144617)
7
8-   [Development Guidelines](#section44744471891)
9    -   [Available APIs](#section172373513919)
10    -   [How to Develop](#section1118215161013)
11    -   [Development Example](#section19986143311020)
12    -   [Example Description](#section128221510145718)
13    -   [Sample Code](#section71507479577)
14    -   [Verification](#section16570171645813)
15
16
17## Basic Concepts<a name="section122115620816"></a>
18
19An event is a mechanism for communication between tasks. It can be used to synchronize tasks.
20
21In multi-task environment, synchronization is required between tasks. Events implement the following types of synchronization:
22
23-   One-to-many synchronization: A task waits for the triggering of multiple events. A task is woken up by one or multiple events.
24-   Many-to-many synchronization: Multiple tasks wait for the triggering of multiple events.
25
26The events provided by the OpenHarmony LiteOS-A event module have the following features:
27
28-   A task triggers or waits for an event by creating an event control block.
29-   Events are independent of each other. The internal implementation is a 32-bit unsigned integer, and each bit indicates an event type. The 25th bit is unavailable. Therefore, a maximum of 31 event types are supported.
30-   Events are used only for synchronization between tasks, but not for data transmission.
31-   Writing the same event type to the event control block for multiple times is equivalent to writing the event type only once before the event control block is cleared.
32-   Multiple tasks can read and write the same event.
33-   The event read/write timeout mechanism is supported.
34
35## Working Principles<a name="section94611116593"></a>
36
37### Event Control Block<a name="section1161415384467"></a>
38
39```
40/**
41* Event control block data structure
42  */
43typedef struct tagEvent {
44    UINT32 uwEventID;        /* Event set, which is a collection of events processed (written and cleared).*/
45    LOS_DL_LIST stEventList; /* List of tasks waiting for specific events*/
46} EVENT_CB_S, *PEVENT_CB_S;
47```
48
49### Working Principles<a name="section187761153144617"></a>
50
51**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.
52
53**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.
54
55**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.
56
57The 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:
58
59-   **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.
60-   **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.
61-   **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.
62
63**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.
64
65**Destroying an event**: Destroy the specified event control block.
66
67**Figure  1**  Event working mechanism<a name="fig17799175324612"></a>
68![](figure/event-working-mechanism-21.png "event-working-mechanism-21")
69
70## Development Guidelines<a name="section44744471891"></a>
71
72### Available APIs<a name="section172373513919"></a>
73
74The following table describes APIs available for the OpenHarmony LiteOS-A event module.
75
76**Table  1**  Event module APIs
77
78<a name="table1415203765610"></a>
79<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>
80</th>
81<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>
82</th>
83<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>
84</th>
85</tr>
86</thead>
87<tbody><tr id="row0415737175610"><td class="cellrowborder" valign="top" width="12.85128512851285%" headers="mcps1.2.4.1.1 "><p id="p9598124913544"><a name="p9598124913544"></a><a name="p9598124913544"></a>Initializing events</p>
88</td>
89<td class="cellrowborder" valign="top" width="29.8029802980298%" headers="mcps1.2.4.1.2 "><p id="p77891354175812"><a name="p77891354175812"></a><a name="p77891354175812"></a>LOS_EventInit</p>
90</td>
91<td class="cellrowborder" valign="top" width="57.34573457345735%" headers="mcps1.2.4.1.3 "><p id="p2334141425515"><a name="p2334141425515"></a><a name="p2334141425515"></a>Initialize an event control block.</p>
92</td>
93</tr>
94<tr id="row421753455514"><td class="cellrowborder" rowspan="2" valign="top" width="12.85128512851285%" headers="mcps1.2.4.1.1 "><p id="p13441112105813"><a name="p13441112105813"></a><a name="p13441112105813"></a>Reading/Writing events</p>
95</td>
96<td class="cellrowborder" valign="top" width="29.8029802980298%" headers="mcps1.2.4.1.2 "><p id="p17234205011559"><a name="p17234205011559"></a><a name="p17234205011559"></a>LOS_EventRead</p>
97</td>
98<td class="cellrowborder" valign="top" width="57.34573457345735%" headers="mcps1.2.4.1.3 "><p id="p1621275475517"><a name="p1621275475517"></a><a name="p1621275475517"></a>Reads a specified type of event, with the timeout period of a relative time period in ticks.</p>
99</td>
100</tr>
101<tr id="row13129193718555"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p17477615564"><a name="p17477615564"></a><a name="p17477615564"></a>LOS_EventWrite</p>
102</td>
103<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p10271958567"><a name="p10271958567"></a><a name="p10271958567"></a>Writes a specified type of event.</p>
104</td>
105</tr>
106<tr id="row1831124035511"><td class="cellrowborder" valign="top" width="12.85128512851285%" headers="mcps1.2.4.1.1 "><p id="p1313401559"><a name="p1313401559"></a><a name="p1313401559"></a>Clearing events</p>
107</td>
108<td class="cellrowborder" valign="top" width="29.8029802980298%" headers="mcps1.2.4.1.2 "><p id="p7788152419567"><a name="p7788152419567"></a><a name="p7788152419567"></a>LOS_EventClear</p>
109</td>
110<td class="cellrowborder" valign="top" width="57.34573457345735%" headers="mcps1.2.4.1.3 "><p id="p14862153525620"><a name="p14862153525620"></a><a name="p14862153525620"></a>Clears a specified type of event.</p>
111</td>
112</tr>
113<tr id="row1525316428553"><td class="cellrowborder" valign="top" width="12.85128512851285%" headers="mcps1.2.4.1.1 "><p id="p4253144265519"><a name="p4253144265519"></a><a name="p4253144265519"></a>Checking the event mask</p>
114</td>
115<td class="cellrowborder" valign="top" width="29.8029802980298%" headers="mcps1.2.4.1.2 "><p id="p768611115563"><a name="p768611115563"></a><a name="p768611115563"></a>LOS_EventPoll</p>
116</td>
117<td class="cellrowborder" valign="top" width="57.34573457345735%" headers="mcps1.2.4.1.3 "><p id="p13998115465617"><a name="p13998115465617"></a><a name="p13998115465617"></a>Returns whether the event input by the user meets the expectation based on the event ID, event mask, and read mode passed by the user.</p>
118</td>
119</tr>
120<tr id="row6447135825614"><td class="cellrowborder" valign="top" width="12.85128512851285%" headers="mcps1.2.4.1.1 "><p id="p104471658155615"><a name="p104471658155615"></a><a name="p104471658155615"></a>Destroying events</p>
121</td>
122<td class="cellrowborder" valign="top" width="29.8029802980298%" headers="mcps1.2.4.1.2 "><p id="p15259169573"><a name="p15259169573"></a><a name="p15259169573"></a>LOS_EventDestroy</p>
123</td>
124<td class="cellrowborder" valign="top" width="57.34573457345735%" headers="mcps1.2.4.1.3 "><p id="p32592615573"><a name="p32592615573"></a><a name="p32592615573"></a>Destroys a specified event control block.</p>
125</td>
126</tr>
127</tbody>
128</table>
129
130### How to Develop<a name="section1118215161013"></a>
131
132The typical event development process is as follows:
133
1341.  Initialize an event control block.
1352.  Block a read event control block.
1363.  Write related events.
1374.  Wake up a blocked task, read the event, and check whether the event meets conditions.
1385.  Handle the event control block.
1396.  Destroy an event control block.
140
141>![](../public_sys-resources/icon-note.gif) **NOTE:**
142>-   When an event is read or written, the 25th bit of the event is reserved and cannot be set.
143>-   Repeated writes of the same event are treated as one write.
144
145### Development Example<a name="section19986143311020"></a>
146
147### Example Description<a name="section128221510145718"></a>
148
149In 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.
150
1511.  Create the  **Example\_Event**  task in the  **Example\_TaskEntry**  task with a higher priority than the  **Example\_TaskEntry**  task.
1522.  Run the  **Example\_Event**  task to read event  **0x00000001**. Task switching occurs to execute the  **Example\_TaskEntry**  task.
1533.  Run the  **Example\_TaskEntry**  task to write event  **0x00000001**. Task switching occurs to execute the  **Example\_Event**  task.
1544.  The  **Example\_Event**  task is executed.
1555.  The  **Example\_TaskEntry**  task is executed.
156
157### Sample Code<a name="section71507479577"></a>
158
159The sample code is as follows:
160
161```
162#include "los_event.h"
163#include "los_task.h"
164#include "securec.h"
165
166/* Task ID*/
167UINT32 g_testTaskId;
168
169/* Event control structure*/
170EVENT_CB_S g_exampleEvent;
171
172/* Type of the wait event*/
173#define EVENT_WAIT 0x00000001
174
175/* Example task entry function*/
176VOID Example_Event(VOID)
177{
178     UINT32 event;
179
180    /* 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.*/
181    printf("Example_Event wait event 0x%x \n", EVENT_WAIT);
182
183    event = LOS_EventRead(&g_exampleEvent, EVENT_WAIT, LOS_WAITMODE_AND, 100);
184    if (event == EVENT_WAIT) {
185        printf("Example_Event,read event :0x%x\n", event);
186    } else {
187        printf("Example_Event,read event timeout\n");
188    }
189}
190
191UINT32 Example_EventEntry(VOID)
192{
193    UINT32 ret;
194    TSK_INIT_PARAM_S task1;
195
196    /* Initialize the event.*/
197    ret = LOS_EventInit(&g_exampleEvent);
198    if (ret != LOS_OK) {
199        printf("init event failed .\n");
200        return -1;
201    }
202
203    /* Create a task.*/
204    (VOID)memset_s(&task1, sizeof(TSK_INIT_PARAM_S), 0, sizeof(TSK_INIT_PARAM_S));
205    task1.pfnTaskEntry = (TSK_ENTRY_FUNC)Example_Event;
206    task1.pcName       = "EventTsk1";
207    task1.uwStackSize  = LOSCFG_BASE_CORE_TSK_DEFAULT_STACK_SIZE;
208    task1.usTaskPrio   = 5;
209    ret = LOS_TaskCreate(&g_testTaskId, &task1);
210    if (ret != LOS_OK) {
211        printf("task create failed.\n");
212        return LOS_NOK;
213    }
214
215    /* Write the task wait event (g_testTaskId). */
216    printf("Example_TaskEntry write event.\n");
217
218    ret = LOS_EventWrite(&g_exampleEvent, EVENT_WAIT);
219    if (ret != LOS_OK) {
220        printf("event write failed.\n");
221        return LOS_NOK;
222    }
223
224    /* Clear the flag.*/
225    printf("EventMask:%d\n", g_exampleEvent.uwEventID);
226    LOS_EventClear(&g_exampleEvent, ~g_exampleEvent.uwEventID);
227    printf("EventMask:%d\n", g_exampleEvent.uwEventID);
228
229    /* Delete the task.*/
230    ret = LOS_TaskDelete(g_testTaskId);
231    if (ret != LOS_OK) {
232        printf("task delete failed.\n");
233        return LOS_NOK;
234    }
235
236    return LOS_OK;
237}
238```
239
240### Verification<a name="section16570171645813"></a>
241
242The development is successful if the return result is as follows:
243
244```
245Example_Event wait event 0x1
246Example_TaskEntry write event.
247Example_Event,read event :0x1
248EventMask:1
249EventMask:0
250```
251
252