1 /* 2 * Copyright (c) 2013-2019 Huawei Technologies Co., Ltd. All rights reserved. 3 * Copyright (c) 2020-2022 Huawei Device Co., Ltd. All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without modification, 6 * are permitted provided that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, this list of 9 * conditions and the following disclaimer. 10 * 11 * 2. Redistributions in binary form must reproduce the above copyright notice, this list 12 * of conditions and the following disclaimer in the documentation and/or other materials 13 * provided with the distribution. 14 * 15 * 3. Neither the name of the copyright holder nor the names of its contributors may be used 16 * to endorse or promote products derived from this software without specific prior written 17 * permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 21 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 23 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 24 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 25 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 26 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 27 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 28 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 29 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32 /** 33 * @defgroup los_event Event 34 * @ingroup kernel 35 */ 36 37 #ifndef _LOS_EVENT_H 38 #define _LOS_EVENT_H 39 40 #include "los_list.h" 41 42 #ifdef __cplusplus 43 #if __cplusplus 44 extern "C" { 45 #endif /* __cplusplus */ 46 #endif /* __cplusplus */ 47 48 /** 49 * @ingroup los_event 50 * Event reading mode: The task waits for all its expected events to occur. 51 */ 52 #define LOS_WAITMODE_AND (4) /* all bits must be set */ 53 54 /** 55 * @ingroup los_event 56 * Event reading mode: The task waits for any of its expected events to occur. 57 */ 58 #define LOS_WAITMODE_OR (2) /* any bit must be set */ 59 60 /** 61 * @ingroup los_event 62 * Event reading mode: The event flag is immediately cleared after the event is read. 63 */ 64 #define LOS_WAITMODE_CLR (1) /* clear when satisfied */ 65 66 /** 67 * @ingroup los_event 68 * Bit 25 of the event mask cannot be set to an event because it is set to an error code. 69 * 70 * Value: 0x02001c00 71 * 72 * Solution: Set bits excluding bit 25 of the event mask to events. 73 */ 74 #define LOS_ERRNO_EVENT_SETBIT_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x00) 75 /** 76 * @ingroup los_event 77 * Event reading error code: Event reading times out. 78 * 79 * Value: 0x02001c01 80 * 81 * Solution: Increase the waiting time for event reading, or make another task write a mask for the event. 82 */ 83 #define LOS_ERRNO_EVENT_READ_TIMEOUT LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x01) 84 85 /** 86 * @ingroup los_event 87 * Event reading error code: The EVENTMASK input parameter value is valid. The input parameter value must not be 0. 88 * 89 * Value: 0x02001c02 90 * 91 * Solution: Pass in a valid EVENTMASK value. 92 */ 93 #define LOS_ERRNO_EVENT_EVENTMASK_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x02) 94 95 /** 96 * @ingroup los_event 97 * Event reading error code: The event is being read during an interrupt. 98 * 99 * Value: 0x02001c03 100 * 101 * Solution: Read the event in a task. 102 */ 103 #define LOS_ERRNO_EVENT_READ_IN_INTERRUPT LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x03) 104 105 /** 106 * @ingroup los_event 107 * Event reading error code: The uwFlags input parameter value used in the event reading API is invalid. 108 * This input parameter value is obtained by performing an OR operation on corresponding bits of either OS_EVENT_ANY or 109 * OS_EVENT_ANY and corresponding bits of either OS_EVENT_WAIT or OS_EVENT_NOWAIT. The waiting time must be set to 110 * a nonzero value when an event is read in the mode of OS_EVENT_WAIT. 111 * 112 * Value: 0x02001c04 113 * 114 * Solution: Pass in a valid uwFlags value. 115 */ 116 #define LOS_ERRNO_EVENT_FLAGS_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x04) 117 118 /** 119 * @ingroup los_event 120 * Event reading error code: The task is locked and is unable to read the event. 121 * 122 * Value: 0x02001c05 123 * 124 * Solution: Unlock the task and read the event. 125 */ 126 #define LOS_ERRNO_EVENT_READ_IN_LOCK LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x05) 127 128 /** 129 * @ingroup los_event 130 * Event reading error code: Null pointer. 131 * 132 * Value: 0x02001c06 133 * 134 * Solution: Check whether the input parameter is null. 135 */ 136 #define LOS_ERRNO_EVENT_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x06) 137 138 /** 139 * @ingroup los_event 140 * Event reading error code: no initialized. 141 * 142 * Value: 0x02001c07 143 * 144 * Solution: Check whether the event is initialized. 145 */ 146 #define LOS_ERRNO_EVENT_NOT_INITIALIZED LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x07) 147 148 /** 149 * @ingroup los_event 150 * Event reading error code: should not be destroyed. 151 * 152 * Value: 0x02001c08 153 * 154 * Solution: Check whether the event list is not empty. 155 */ 156 #define LOS_ERRNO_EVENT_SHOULD_NOT_DESTROYED LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x08) 157 158 /** 159 * @ingroup los_event 160 * Event reading error code: The event is being read in a system-level task. 161 * Value: 0x02001c09 162 * 163 * Solution: Read the event in a valid task. 164 */ 165 #define LOS_ERRNO_EVENT_READ_IN_SYSTEM_TASK LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x09) 166 167 /** 168 * @ingroup los_event 169 * Event control structure 170 */ 171 typedef struct tagEvent { 172 UINT32 uwEventID; /**< Event mask in the event control block, 173 indicating the event that has been logically processed. */ 174 LOS_DL_LIST stEventList; /**< Event control block linked list */ 175 } EVENT_CB_S, *PEVENT_CB_S; 176 /** 177 * @ingroup los_event 178 * @brief Initialize an event control block. 179 * 180 * @par Description: 181 * This API is used to initialize the event control block pointed to by eventCB. 182 * @attention 183 * <ul> 184 * <li>None.</li> 185 * </ul> 186 * 187 * @param eventCB [IN/OUT] Pointer to the event control block to be initialized. 188 * 189 * @retval #LOS_ERRNO_EVENT_PTR_NULL Null pointer. 190 * @retval #LOS_OK The event control block is successfully initialized. 191 * @par Dependency: 192 * <ul><li>los_event.h: the header file that contains the API declaration.</li></ul> 193 * @see LOS_EventClear 194 */ 195 extern UINT32 LOS_EventInit(PEVENT_CB_S eventCB); 196 197 /** 198 * @ingroup los_event 199 * @brief Obtain an event specified by the event ID. 200 * 201 * @par Description: 202 * This API is used to check whether an event expected by the user occurs according to the event ID, event mask, 203 * and event reading mode, and process the event based on the event reading mode. The event ID must point to 204 * valid memory. 205 * @attention 206 * <ul> 207 * <li>When the mode is LOS_WAITMODE_CLR, the eventID is passed-out.</li> 208 * <li>Otherwise the eventID is passed-in.</li> 209 * </ul> 210 * 211 * @param eventID [IN/OUT] Pointer to the ID of the event to be checked. 212 * @param eventMask [IN] Mask of the event expected to occur by the user, indicating the event obtained after 213 * it is logically processed that matches the ID pointed to by mode. 214 * @param mode [IN] Event reading mode. The modes include LOS_WAITMODE_AND, LOS_WAITMODE_OR, LOS_WAITMODE_CLR. 215 * 216 * @retval 0 The event expected by the user does not occur. 217 * @retval #UINT32 The event expected by the user occurs. 218 * @par Dependency: 219 * <ul><li>los_event.h: the header file that contains the API declaration.</li></ul> 220 * @see LOS_EventRead | LOS_EventWrite 221 */ 222 extern UINT32 LOS_EventPoll(UINT32 *eventID, UINT32 eventMask, UINT32 mode); 223 224 /** 225 * @ingroup los_event 226 * @brief Read an event. 227 * 228 * @par Description: 229 * This API is used to block or schedule a task that reads an event of which the event control block, event mask, 230 * reading mode, 231 * and timeout information are specified. 232 * </ul> 233 * @attention 234 * <ul> 235 * <li>An error code and an event return value can be same. To differentiate the error code and return value, bit 25 of 236 * the event mask is forbidden to be used.</li> 237 * </ul> 238 * 239 * @param eventCB [IN/OUT] Pointer to the event control block to be checked. This parameter must point to 240 * valid memory. 241 * @param eventMask [IN] Mask of the event expected to occur by the user, indicating the event obtained after 242 * it is logically processed that matches the ID pointed to by eventID. 243 * @param mode [IN] Event reading mode. 244 * @param timeOut [IN] Timeout interval of event reading (unit: Tick). 245 * 246 * @retval #LOS_ERRNO_EVENT_SETBIT_INVALID Bit 25 of the event mask cannot be set because 247 * it is set to an error number. 248 * @retval #LOS_ERRNO_EVENT_EVENTMASK_INVALID The passed-in event reading mode is incorrect. 249 * @retval #LOS_ERRNO_EVENT_READ_IN_INTERRUPT The event is being read during an interrupt. 250 * @retval #LOS_ERRNO_EVENT_FLAGS_INVALID The event mode is invalid. 251 * @retval #LOS_ERRNO_EVENT_READ_IN_LOCK The event reading task is locked. 252 * @retval #LOS_ERRNO_EVENT_PTR_NULL The passed-in pointer is null. 253 * @retval 0 The event expected by the user does not occur. 254 * @retval #UINT32 The event expected by the user occurs. 255 * @par Dependency: 256 * <ul><li>los_event.h: the header file that contains the API declaration.</li></ul> 257 * @see LOS_EventPoll | LOS_EventWrite 258 */ 259 extern UINT32 LOS_EventRead(PEVENT_CB_S eventCB, UINT32 eventMask, UINT32 mode, UINT32 timeOut); 260 261 /** 262 * @ingroup los_event 263 * @brief Write an event. 264 * 265 * @par Description: 266 * This API is used to write an event specified by the passed-in event mask into an event control block 267 * pointed to by eventCB. 268 * @attention 269 * <ul> 270 * <li>To determine whether the LOS_EventRead API returns an event or an error code, bit 25 of the event mask 271 * is forbidden to be used.</li> 272 * </ul> 273 * 274 * @param eventCB [IN/OUT] Pointer to the event control block into which an event is to be written. 275 * This parameter must point to valid memory. 276 * @param events [IN] Event mask to be written. 277 * 278 * @retval #LOS_ERRNO_EVENT_SETBIT_INVALID Bit 25 of the event mask cannot be set to an event 279 * because it is set to an error code. 280 * @retval #LOS_ERRNO_EVENT_PTR_NULL Null pointer. 281 * @retval #LOS_OK The event is successfully written. 282 * @par Dependency: 283 * <ul><li>los_event.h: the header file that contains the API declaration.</li></ul> 284 * @see LOS_EventPoll | LOS_EventRead 285 */ 286 extern UINT32 LOS_EventWrite(PEVENT_CB_S eventCB, UINT32 events); 287 288 /** 289 * @ingroup los_event 290 * @brief Clear the event of the eventCB by a specified eventMask. 291 * 292 * @par Description: 293 * <ul> 294 * <li>This API is used to set the ID of an event that has a specified mask and of which the information is stored in 295 * an event control block pointed to by eventCB to 0. eventCB must point to valid memory.</li> 296 * </ul> 297 * @attention 298 * <ul> 299 * <li>The value of events needs to be reversed when it is passed-in.</li> 300 * </ul> 301 * 302 * @param eventCB [IN/OUT] Pointer to the event control block to be cleared. 303 * @param eventMask [IN] Mask of the event to be cleared. 304 * 305 * @retval #LOS_ERRNO_EVENT_PTR_NULL Null pointer. 306 * @retval #LOS_OK The event is successfully cleared. 307 * @par Dependency: 308 * <ul><li>los_event.h: the header file that contains the API declaration.</li></ul> 309 * @see LOS_EventPoll | LOS_EventRead | LOS_EventWrite 310 */ 311 extern UINT32 LOS_EventClear(PEVENT_CB_S eventCB, UINT32 eventMask); 312 313 /** 314 * @ingroup los_event 315 * @brief Destroy an event. 316 * 317 * @par Description: 318 * <ul> 319 * <li>This API is used to Destroy an event.</li> 320 * </ul> 321 * @attention 322 * <ul> 323 * <li>The specific event should be a valid one.</li> 324 * </ul> 325 * 326 * @param eventCB [IN/OUT] Pointer to the event control block to be Destroyed. 327 * 328 * @retval #LOS_ERRNO_EVENT_PTR_NULL Null pointer. 329 * @retval #LOS_OK The event is successfully cleared. 330 * @par Dependency: 331 * <ul><li>los_event.h: the header file that contains the API declaration.</li></ul> 332 * @see LOS_EventPoll | LOS_EventRead | LOS_EventWrite 333 */ 334 extern UINT32 LOS_EventDestroy(PEVENT_CB_S eventCB); 335 336 extern UINT32 OsEventReadOnce(PEVENT_CB_S eventCB, UINT32 eventMask, UINT32 mode, UINT32 timeOut); 337 extern UINT32 OsEventWriteOnce(PEVENT_CB_S eventCB, UINT32 events); 338 339 #ifdef __cplusplus 340 #if __cplusplus 341 } 342 #endif /* __cplusplus */ 343 #endif /* __cplusplus */ 344 345 #endif /* _LOS_EVENT_H */ 346