• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Event
2
3
4## Basic Concepts
5
6An event is a communication mechanism used to synchronize tasks.
7
8In multi-task environment, synchronization is required between tasks. Events can be used for synchronization in the following cases:
9
10- One-to-many synchronization: A task waits for the triggering of multiple events. A task can be woken up by one or multiple events.
11
12- Many-to-many synchronization: Multiple tasks wait for the triggering of multiple events.
13
14The event mechanism provided by the OpenHarmony LiteOS-A event module has the following features:
15
16- A task triggers or waits for an event by creating an event control block.
17
18- Events are independent of each other. The internal implementation is a 32-bit unsigned integer, and each bit indicates an event type. The value **0** indicates that the event type does not occur, and the value **1** indicates that the event type has occurred. There are 31 event types in total. The 25th bit (`0x02U << 24`) is reserved.
19
20- Events are used for task synchronization, but not for data transmission.
21
22- Writing the same event type to an event control block multiple times is equivalent to writing the event type only once before the event control block is cleared.
23
24- Multiple tasks can read and write the same event.
25
26- The event read/write timeout mechanism is supported.
27
28
29## Working Principles
30
31
32### Event Control Block
33
34
35```
36/**
37  * Event control block data structure
38  */
39typedef struct tagEvent {
40    UINT32 uwEventID;        /* Event set, which is a collection of events processed (written and cleared). */
41    LOS_DL_LIST stEventList; /* List of tasks waiting for specific events. */
42} EVENT_CB_S, *PEVENT_CB_S;
43```
44
45
46### Working Principles
47
48**Initializing an Event**
49
50An event control block is created to maintain a set of processed events and a linked list of tasks waiting for specific events.
51
52**Writing an Event**
53
54When an 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 specified conditions.
55
56**Reading an Event**
57
58If the event to read already exists, it is returned synchronously. In other cases, the event is returned based on the timeout period and event triggering conditions. If the wait 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.
59
60The parameters **eventMask** and **mode** determine whether the condition for reading an event is met. **eventMask** specifies the event mask. **mode** specifies the handling mode, which can be any of the following:
61
62- **LOS_WAITMODE_AND**: Read the event only when all the events corresponding to **eventMask** occur. Otherwise, the task will be blocked, or an error code will be returned.
63
64- **LOS_WAITMODE_OR**: Read the event only when any of the events corresponding to **eventMask** occur. Otherwise, the task will be blocked, or an error code will be returned.
65
66- **LOS_WAITMODE_CLR**: This mode must be used with one or all of the event modes (LOS_WAITMODE_AND | LOS_WAITMODE_CLR or LOS_WAITMODE_OR | LOS_WAITMODE_CLR). In this mode, if all event modes or any event mode is successful, the corresponding event type bit in the event control block will be automatically cleared.
67
68**Clearing Events**
69
70The events in the event set of the event control block can be cleared based on the specified mask. The mask **0** means to clear the event set; the mask **0xffff** means the opposite.
71
72**Destroying Events**
73
74The event control block can be destroyed to release resources.
75
76**Figure 1** Event working mechanism for small systems
77
78  ![](figures/event-working-mechanism-for-small-systems.png "event-working-mechanism-for-small-systems")
79
80
81## Development Guidelines
82
83
84### Available APIs
85
86The following table describes APIs available for the OpenHarmony LiteOS-A event module.
87
88**Table 1** APIs of the event module
89
90| Category| API Description |
91| -------- | -------- |
92| Initializing an event| **LOS_EventInit**: initializes an event control block.|
93| Reading/Writing an event| - **LOS_EventRead**: reads an event, with a relative timeout period in ticks.<br>- **LOS_EventWrite**: writes an event. |
94| Clearing events| **LOS_EventClear**: clears a specified type of events.|
95| Checking the event mask| **LOS_EventPoll**: checks whether the specified event occurs.|
96| Destroying events | **LOS_EventDestroy**: destroys an event control block.|
97
98
99### How to Develop
100
101The typical event development process is as follows:
102
1031. Initialize an event control block.
104
1052. Block a read event.
106
1073. Write related events.
108
1094. Wake up a blocked task, read the event, and check whether the event meets conditions.
110
1115. Handle the event control block.
112
1136. Destroy an event control block.
114
115> **NOTE**
116>
117> - For event read and write operations, the 25th bit (`0x02U << 24`) of the event is reserved and cannot be set.
118>
119> - Repeated writes of the same event are treated as one write.
120
121
122## Development Example
123
124
125### Example Description
126
127In 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.
128
1291. Create the **Example_Event** task in the **Example_TaskEntry** task with a higher priority than the **Example_TaskEntry** task.
130
1312. Run the **Example_Event** task to read event **0x00000001**. Task switching is triggered to execute the **Example_TaskEntry** task.
132
1333. Run the **Example_TaskEntry** task to write event **0x00000001**. Task switching is triggered to execute the **Example_Event** task.
134
1354. The **Example_Event** task is executed.
136
1375. The **Example_TaskEntry** task is executed.
138
139
140### Sample Code
141
142The sample code can be compiled and verified in **./kernel/liteos_a/testsuites/kernel/src/osTest.c**. The **Example_EventEntry** function is called in **TestTaskEntry**.
143
144The sample code is as follows:
145
146```
147#include "los_event.h"
148#include "los_task.h"
149#include "securec.h"
150
151/* Task ID */
152UINT32 g_testTaskId;
153
154/* Event control structure */
155EVENT_CB_S g_exampleEvent;
156
157/* Type of the wait event */
158#define EVENT_WAIT      0x00000001
159#define EVENT_TIMEOUT   500
160/* Example task entry function */
161VOID Example_Event(VOID)
162{
163     UINT32 event;
164
165    /* 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. */
166    dprintf("Example_Event wait event 0x%x \n", EVENT_WAIT);
167
168    event = LOS_EventRead(&g_exampleEvent, EVENT_WAIT, LOS_WAITMODE_AND, EVENT_TIMEOUT);
169    if (event == EVENT_WAIT) {
170        dprintf("Example_Event,read event :0x%x\n", event);
171    } else {
172        dprintf("Example_Event,read event timeout\n");
173    }
174}
175
176UINT32 Example_EventEntry(VOID)
177{
178    UINT32 ret;
179    TSK_INIT_PARAM_S task1;
180
181    /* Initialize the event. */
182    ret = LOS_EventInit(&g_exampleEvent);
183    if (ret != LOS_OK) {
184        dprintf("init event failed .\n");
185        return -1;
186    }
187
188    /* Create a task. */
189    (VOID)memset_s(&task1, sizeof(TSK_INIT_PARAM_S), 0, sizeof(TSK_INIT_PARAM_S));
190    task1.pfnTaskEntry = (TSK_ENTRY_FUNC)Example_Event;
191    task1.pcName       = "EventTsk1";
192    task1.uwStackSize  = LOSCFG_BASE_CORE_TSK_DEFAULT_STACK_SIZE;
193    task1.usTaskPrio   = 5;
194    ret = LOS_TaskCreate(&g_testTaskId, &task1);
195    if (ret != LOS_OK) {
196        dprintf("task create failed.\n");
197        return LOS_NOK;
198    }
199
200    /* Write the task wait event (g_testTaskId). */
201    dprintf("Example_TaskEntry write event.\n");
202
203    ret = LOS_EventWrite(&g_exampleEvent, EVENT_WAIT);
204    if (ret != LOS_OK) {
205        dprintf("event write failed.\n");
206        return LOS_NOK;
207    }
208
209    /* Clear the flag. */
210    dprintf("EventMask:%d\n", g_exampleEvent.uwEventID);
211    LOS_EventClear(&g_exampleEvent, ~g_exampleEvent.uwEventID);
212    dprintf("EventMask:%d\n", g_exampleEvent.uwEventID);
213
214    return LOS_OK;
215}
216```
217
218
219### Verification
220
221The development is successful if the return result is as follows:
222
223
224```
225Example_Event wait event 0x1
226Example_TaskEntry write event.
227Example_Event,read event :0x1
228EventMask:1
229EventMask:0
230```
231