1/**
2 * @file hi_event.h
3 *
4 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED.
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 * Description: system event API.CNcomment:系统事件接口。CNend
18 * @li Before sending, waiting, or clearing an event, the event must be created to obtain the event ID.
19CNcomment:在发送、等待、清空事件之前首先需要创建事件，获取事件使用ID。CNend
20 * @li Wait event: The wait event API cannot be called in the interrupt, interrupt off,
21 * and lock task contexts to avoid uncontrollable exceptional scheduling.CNcomment:等待事件:在中断、
22关中断、锁任务上下文禁止调用等待事件接口，进而产生不可控的异常调度。CNend
23 * @li TX event: The TX event API cannot be called in the interrupt off context to avoid uncontrollable
24exceptional scheduling.CNcomment:发送事件:在关中断上下文禁止调用发送事件接口，
25进而产生不可控的异常调度。CNend
26 * @li Each bit of bit[0:23] of an event can represent an event type. The meaning of each bit is allocated by the user.
27CNcomment:一个事件的[0:23]bit的每一bit可以表示一种事件，每一位的意义由用户自定义分配。CNend
28 * @li Bit[24:31] of an event are reserved and cannot be used by the user.
29CNcomment:一个事件的[24:31]bit系统保留，用户不得使用。CNend   \n
30 */
31
32/**
33 * @defgroup iot_event Event
34 * @ingroup osa
35 */
36#ifndef __HI_EVENT_H__
37#define __HI_EVENT_H__
38#include <hi_types_base.h>
39
40#define HI_INVALID_EVENT_ID           0xffffffff   /**< Failed to obtain the event ID.CNcoment:获取事件ID失败CNend  */
41#define HI_EVENT_WAITMODE_AND         4            /**< If all expected events occur, the wait is successful.
42                                                        It cannot be used with HI_EVENT_WAITMODE_OR at the same time.
43                                                        CNcomment:所有预期等待的事件均发生时，才认定等待成功，
44                                                        不允许与HI_EVENT_WAITMODE_OR同时使用 CNend */
45#define HI_EVENT_WAITMODE_OR          2            /**< If any of the expected events occurs, the wait is successful.
46                                                        It cannot be used with HI_EVENT_WAITMODE_AND at the same time.
47                                                        CNcomment:所有预期等待的事件发生任意一种，认定等待成功，
48                                                        不允许与HI_EVENT_WAITMODE_AND同时使用 CNend */
49#define HI_EVENT_WAITMODE_CLR         1            /**< The waited event is cleared when the wait event is successful.
50                                                        CNcomment:等待事件成功时，清除等待到的事件CNend  */
51
52/**
53* @ingroup  iot_event
54* @brief  Creates an event.CNcomment:创建事件。CNend
55*
56* @par 描述:
57*           Creates an event to obtain the event ID.CNcomment:创建事件，获取事件使用ID。CNend
58*
59* @attention
60*           @li The read/write event interface cannot be invoked before system initialization.
61CNcomment:在系统初始化之前不能调用读写事件接口。CNend
62*           @li In the interrupt, the event object can be written, but cannot be read.
63CNcomment:在中断中，可以对事件对象进行写操作，但不能读操作。CNend
64*           @li In the lock task scheduling state, a write operation can be performed on an event object, but the
65*               read operation cannot be performed.CNcomment:在锁任务调度状态下，可以对事件对象进行写操作，
66但不能读操作。CNend
67*
68* @param  id       [OUT] type #hi_u32*，Event ID.
69*
70* @retval #0       Success.
71* @retval #Other   Failure. For details, see hi_errno.h.
72*
73* @par 依赖:
74*           @li hi_event.h：Describes event APIs.CNcomment:文件用于描述事件相关接口。CNend
75* @see  hi_event_delete。
76*/
77hi_u32 hi_event_create(HI_OUT hi_u32 *id);
78
79/**
80* @ingroup  iot_event
81* @brief  Defines the TX event. CNcomment:发送事件。CNend
82*
83* @par 描述:
84*           Defines the TX event.CNcomment:发送事件。CNend
85*
86* @attention
87*           @li The read/write event interface cannot be invoked before system initialization.
88CNcomment:在系统初始化之前不能调用读写事件接口。CNend
89*           @li In the interrupt, the event object can be written, but cannot be read.
90CNcomment:在中断中，可以对事件对象进行写操作，但不能读操作。CNend
91*           @li In the lock task scheduling state, a write operation can be performed on an event object, but the
92*               read operation cannot be performed.CNcomment:在锁任务调度状态下，可以对事件对象进行写操作，
93但不能读操作。CNend
94*
95* @param  id         [IN]  type #hi_u32，Event ID.
96* @param  event_bits [IN] type #hi_u32，Set of events to be sent.CNcomment:事件bit位。CNend
97*
98* @retval #0       Success.
99* @retval #Other   Failure. For details, see hi_errno.h.
100*
101* @par 依赖:
102*           @li hi_event.h：Describes event APIs.CNcomment:文件用于描述事件相关接口。CNend
103* @see  hi_event_wait。
104*/
105hi_u32 hi_event_send(hi_u32 id, hi_u32 event_bits);
106
107/**
108* @ingroup  iot_event
109* @brief  Defines the wait event.CNcomment:等待事件。CNend
110*
111* @par 描述:
112*          Defines the wait event.CNcomment:等待事件。CNend
113*
114* @attention
115*           @li The read/write event interface cannot be invoked before system initialization.
116CNcomment:在系统初始化之前不能调用读写事件接口。CNend
117*           @li In the interrupt, the event object can be written, but cannot be read.
118CNcomment:在中断中，可以对事件对象进行写操作，但不能读操作。CNend
119*           @li In the lock task scheduling state, a write operation can be performed on an event object, but the
120*               read operation cannot be performed.CNcomment:在锁任务调度状态下，可以对事件对象进行写操作，
121但不能读操作。CNend
122*
123* @param  id         [IN] type #hi_u32，Event ID.
124* @param  mask       [IN] type #hi_u32，Set of events to be waited for, which may be one bit or multiple bits in
125*                    bits 0-23.CNcomment:预等待的事件集合，可以为0~23bit中的1bit或多bit。CNend
126* @param  event_bits [OUT] type #hi_u32*，Set of events to be sent.CNcomment:事件bit位。CNend
127* @param  timeout    [IN] type #hi_u32，Waiting timeout period (unit: ms).
128CNcomment:等待超时时间（单位：ms）。CNend
129* @param  flag       [IN] type #hi_u32，Waiting option. For details, see #HI_EVENT_WAITMODE_AND,
130*                    #HI_EVENT_WAITMODE_OR, and #HI_EVENT_WAITMODE_CLR.
131CNcomment:等待选项,取值见#HI_EVENT_WAITMODE_AND、#HI_EVENT_WAITMODE_OR、#HI_EVENT_WAITMODE_CLR。CNend
132*
133* @retval #0       Success.
134* @retval #Other   Failure. For details, see hi_errno.h.
135*
136* @par 依赖:
137*           @li hi_event.h：Describes event APIs.CNcomment:文件用于描述事件相关接口。CNend
138* @see  hi_event_send。
139*/
140hi_u32 hi_event_wait(hi_u32 id, hi_u32 mask, HI_OUT hi_u32 *event_bits, hi_u32 timeout, hi_u32 flag);
141
142/**
143* @ingroup  iot_event
144* @brief  Defines the clearing event.CNcomment:清除事件。CNend
145*
146* @par 描述:
147*           Defines the clearing event.CNcomment:清除事件。CNend
148*
149* @attention
150*           @li The read/write event interface cannot be invoked before system initialization.
151CNcomment:在系统初始化之前不能调用读写事件接口。CNend
152*           @li In the interrupt, the event object can be written, but cannot be read.
153CNcomment:在中断中，可以对事件对象进行写操作，但不能读操作。CNend
154*           @li In the lock task scheduling state, a write operation can be performed on an event object, but the
155*               read operation cannot be performed.CNcomment:在锁任务调度状态下，可以对事件对象进行写操作，
156但不能读操作。CNend
157*
158* @param  id         [IN] type #hi_u32，Event ID.
159* @param  event_bits [IN] type #hi_u32，Set of events to be cleared, which may be one bit or multiple bits in
160*                    bits 0-23.CNcomment:清除的事件集合，可以为0~23bit中的1bit或多bit。CNend
161*
162* @retval #0       Success.
163* @retval #Other   Failure. For details, see hi_errno.h.
164*
165* @par 依赖:
166*           @li hi_event.h：Describes event APIs.CNcomment:文件用于描述事件相关接口。CNend
167* @see  hi_event_wait。
168*/
169hi_u32 hi_event_clear(hi_u32 id, hi_u32 event_bits);
170
171/**
172* @ingroup  iot_event
173* @brief  Deletion event.CNcomment:删除事件。CNend
174*
175* @par 描述:
176*           Defines the deletion event, releasing an event ID.CNcomment:删除事件，释放事件使用id。CNend
177*
178* @attention
179*           @li The read/write event interface cannot be invoked before system initialization.
180CNcomment:在系统初始化之前不能调用读写事件接口。CNend
181*           @li In the interrupt, the event object can be written, but cannot be read.
182CNcomment:在中断中，可以对事件对象进行写操作，但不能读操作。CNend
183*           @li In the lock task scheduling state, a write operation can be performed on an event object, but the
184*               read operation cannot be performed.CNcomment:在锁任务调度状态下，可以对事件对象进行写操作，
185但不能读操作。CNend
186*
187* @param  id       [IN]  type #hi_u32，Event ID.
188*
189* @retval #0       Success.
190* @retval #Other   Failure. For details, see hi_errno.h.
191*
192* @par 依赖:
193*           @li hi_event.h：Describes event APIs.CNcomment:文件用于描述事件相关接口。CNend
194* @see  hi_event_create。
195*/
196hi_u32 hi_event_delete(hi_u32 id);
197
198/**
199* @ingroup  iot_event
200* @brief  Initializes event resources.CNcomment:初始化事件资源。CNend
201*
202* @par 描述:
203*           Initializes event resources. This API is called during system initialization only once.
204CNcomment:初始化event资源，初始化阶段调用。CNend
205*
206* @attention Change the number of event resources based on the site requirements.
207CNcomment:用户需根据实际使用情况修改event资源个数CNend
208*
209* @param  max_event_cnt   [IN] type #hi_u8，Number of event resources.CNcomment:event资源个数。CNend
210* @param  event_space   [IN]   type #hi_pvoid，Event resource space. If the value is null,
211* it indicates that the space is applied internally. If this parameter is not null,
212* external space is used to create event resources. Currently, set this parameter to HI_NULL.
213CNcomment:event资源空间。传空表示空间由内部申请；非空表示使用外部空间用于创建event资源。
214当前请传HI_NULL。CNend
215*
216* @retval #0       Success.
217* @retval #Other   Failure. For details, see hi_errno.h.
218*
219* @par 依赖:
220*           @li hi_event.h：Describes event APIs.CNcomment:文件用于描述事件相关接口。CNend
221* @see  None
222*/
223hi_u32 hi_event_init(hi_u8 max_event_cnt, hi_pvoid event_space);
224
225#endif
226
227