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