00001 /*---------------------------------------------------------------------------- 00002 * Copyright (c) <2013-2015>, <Huawei Technologies Co., Ltd> 00003 * All rights reserved. 00004 * Redistribution and use in source and binary forms, with or without modification, 00005 * are permitted provided that the following conditions are met: 00006 * 1. Redistributions of source code must retain the above copyright notice, this list of 00007 * conditions and the following disclaimer. 00008 * 2. Redistributions in binary form must reproduce the above copyright notice, this list 00009 * of conditions and the following disclaimer in the documentation and/or other materials 00010 * provided with the distribution. 00011 * 3. Neither the name of the copyright holder nor the names of its contributors may be used 00012 * to endorse or promote products derived from this software without specific prior written 00013 * permission. 00014 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 00015 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 00016 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 00017 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 00018 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 00019 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 00020 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 00021 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 00022 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 00023 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 00024 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00025 *---------------------------------------------------------------------------*/ 00026 /*---------------------------------------------------------------------------- 00027 * Notice of Export Control Law 00028 * =============================================== 00029 * Huawei LiteOS may be subject to applicable export control laws and regulations, which might 00030 * include those applicable to Huawei LiteOS of U.S. and the country in which you are located. 00031 * Import, export and usage of Huawei LiteOS in any manner by you shall be in compliance with such 00032 * applicable export control laws and regulations. 00033 *---------------------------------------------------------------------------*/ 00034 00035 /**@defgroup los_event Event 00036 * @ingroup kernel 00037 */ 00038 00039 #ifndef _LOS_EVENT_H 00040 #define _LOS_EVENT_H 00041 00042 #include "los_base.h" 00043 #include "los_list.h" 00044 00045 #ifdef __cplusplus 00046 #if __cplusplus 00047 extern "C" { 00048 #endif /* __cplusplus */ 00049 #endif /* __cplusplus */ 00050 00051 00052 /** 00053 * @ingroup los_event 00054 * Event reading mode: The task waits for all its expected events to occur. 00055 */ 00056 #define LOS_WAITMODE_AND (4) /* all bits must be set */ 00057 00058 /** 00059 * @ingroup los_event 00060 * Event reading mode: The task waits for any of its expected events to occur. 00061 */ 00062 #define LOS_WAITMODE_OR (2) /* any bit must be set */ 00063 00064 /** 00065 * @ingroup los_event 00066 * Event reading mode: The event flag is immediately cleared after the event is read. 00067 */ 00068 #define LOS_WAITMODE_CLR (1) /* clear when satisfied */ 00069 00070 /** 00071 * @ingroup los_event 00072 * Bit 25 of the event mask cannot be set to an event because it is set to an error code. 00073 * 00074 * Value: 0x02001c00 00075 * 00076 * Solution: Set bits excluding bit 25 of the event mask to events. 00077 */ 00078 #define LOS_ERRNO_EVENT_SETBIT_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x00) 00079 /** 00080 * @ingroup los_event 00081 * Event reading error code: Event reading times out. 00082 * 00083 * Value: 0x02001c01 00084 * 00085 * Solution: Increase the waiting time for event reading, or make another task write a mask for the event. 00086 */ 00087 #define LOS_ERRNO_EVENT_READ_TIMEOUT LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x01) 00088 00089 /** 00090 * @ingroup los_event 00091 * Event reading error code: The EVENTMASK input parameter value is valid. The input parameter value must not be 0. 00092 * 00093 * Value: 0x02001c02 00094 * 00095 * Solution: Pass in a valid EVENTMASK value. 00096 */ 00097 #define LOS_ERRNO_EVENT_EVENTMASK_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x02) 00098 00099 /** 00100 * @ingroup los_event 00101 * Event reading error code: The event is being read during an interrupt. 00102 * 00103 * Value: 0x02001c03 00104 * 00105 * Solution: Read the event in a task. 00106 */ 00107 #define LOS_ERRNO_EVENT_READ_IN_INTERRUPT LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x03) 00108 00109 /** 00110 * @ingroup los_event 00111 * Event reading error code: The uwFlags input parameter value used in the event reading API is invalid. This input parameter value is obtained by performing an OR operation on corresponding bits of either OS_EVENT_ANY or OS_EVENT_ANY and corresponding bits of either OS_EVENT_WAIT or OS_EVENT_NOWAIT. The waiting time must be set to a nonzero value when an event is read in the mode of OS_EVENT_WAIT. 00112 * 00113 * Value: 0x02001c04 00114 * 00115 * Solution: Pass in a valid uwFlags value. 00116 */ 00117 #define LOS_ERRNO_EVENT_FLAGS_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x04) 00118 00119 /** 00120 * @ingroup los_event 00121 * Event reading error code: The task is locked and is unable to read the event. 00122 * 00123 * Value: 0x02001c05 00124 * 00125 * Solution: Unlock the task and read the event. 00126 */ 00127 #define LOS_ERRNO_EVENT_READ_IN_LOCK LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x05) 00128 00129 /** 00130 * @ingroup los_event 00131 * Event reading error code: Null pointer. 00132 * 00133 * Value: 0x02001c06 00134 * 00135 * Solution: Check whether the input parameter is null. 00136 */ 00137 #define LOS_ERRNO_EVENT_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x06) 00138 00139 /** 00140 * @ingroup los_event 00141 * Event reading error code: no initialized. 00142 * 00143 * Value: 0x02001c07 00144 * 00145 * Solution: Check whether the event is initialized. 00146 */ 00147 #define LOS_ERRNO_EVENT_NOT_INITIALIZED LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x07) 00148 00149 /** 00150 * @ingroup los_event 00151 * Event reading error code: should not be distory. 00152 * 00153 * Value: 0x02001c08 00154 * 00155 * Solution: Check whether the event list is not empty. 00156 */ 00157 #define LOS_ERRNO_EVENT_SHOULD_NOT_DESTORY LOS_ERRNO_OS_ERROR(LOS_MOD_EVENT, 0x08) 00158 00159 /** 00160 * @ingroup los_event 00161 * Event control structure 00162 */ 00163 typedef struct tagEvent 00164 { 00165 UINT32 uwEventID; /**< Event mask in the event control block, indicating the event that has been logically processed.*/ 00166 LOS_DL_LIST stEventList; /**< Event control block linked list*/ 00167 } EVENT_CB_S, *PEVENT_CB_S; 00168 00169 /** 00170 *@ingroup los_event 00171 *@brief Initialize an event control block. 00172 * 00173 *@par Description: 00174 *This API is used to initialize the event control block pointed to by pstEventCB. 00175 *@attention 00176 *<ul> 00177 *<li>None.</li> 00178 *</ul> 00179 * 00180 *@param pstEventCB [IN/OUT] Pointer to the event control block to be initialized. 00181 * 00182 *@retval #LOS_ERRNO_EVENT_PTR_NULL Null pointer. 00183 *@retval #LOS_OK The event control block is successfully initialized. 00184 *@par Dependency: 00185 *<ul><li>los_event.h: the header file that contains the API declaration.</li></ul> 00186 *@see LOS_EventClear 00187 *@since Huawei LiteOS V100R001C00 00188 */ 00189 extern UINT32 LOS_EventInit(PEVENT_CB_S pstEventCB); 00190 00191 /** 00192 *@ingroup los_event 00193 *@brief Obtain an event specified by the event ID. 00194 * 00195 *@par Description: 00196 *This API is used to check whether an event expected by the user occurs according to the event ID, event mask, and event reading mode, and process the event based on the event reading mode. The event ID must point to valid memory. 00197 *@attention 00198 *<ul> 00199 *<li>When the uwMode is LOS_WAITMODE_CLR, the puwEventID is passed-out.</li> 00200 *<li>Otherwise the puwEventID is passed-in.</li> 00201 *</ul> 00202 * 00203 *@param uwEventID [IN/OUT] Pointer to the ID of the event to be checked. 00204 *@param uwEventMask [IN] Mask of the event expected to occur by the user, indicating the event obtained after it is logically processed that matches the ID pointed to by uwEventID. 00205 *@param uwMode [IN] Event reading mode. The modes include LOS_WAITMODE_AND, LOS_WAITMODE_OR, LOS_WAITMODE_CLR. 00206 * 00207 *@retval 0 The event expected by the user does not occur. 00208 *@retval #UINT32 The event expected by the user occurs. 00209 *@par Dependency: 00210 *<ul><li>los_event.h: the header file that contains the API declaration.</li></ul> 00211 *@see LOS_EventRead | LOS_EventWrite 00212 *@since Huawei LiteOS V100R001C00 00213 */ 00214 extern UINT32 LOS_EventPoll(UINT32 *uwEventID, UINT32 uwEventMask, UINT32 uwMode); 00215 00216 /** 00217 *@ingroup los_event 00218 *@brief Read an event. 00219 * 00220 *@par Description: 00221 *This API is used to block or schedule a task that reads an event of which the event control block, event mask, reading mode, and timeout information are specified. 00222 *</ul> 00223 *@attention 00224 *<ul> 00225 *<li>An error code and an event return value can be same. To differentiate the error code and return value, bit 25 of the event mask is forbidden to be used.</li> 00226 *</ul> 00227 * 00228 *@param pstEventCB [IN/OUT] Pointer to the event control block to be checked. This parameter must point to valid memory. 00229 *@param uwEventMask [IN] Mask of the event expected to occur by the user, indicating the event obtained after it is logically processed that matches the ID pointed to by uwEventID. 00230 *@param uwMode [IN] Event reading mode. 00231 *@param uwTimeOut [IN] Timeout interval of event reading (unit: Tick). 00232 * 00233 *@retval #LOS_ERRNO_EVENT_SETBIT_INVALID Bit 25 of the event mask cannot be set because it is set to an error number. 00234 *@retval #LOS_ERRNO_EVENT_EVENTMASK_INVALID The passed-in event reading mode is incorrect. 00235 *@retval #LOS_ERRNO_EVENT_READ_IN_INTERRUPT The event is being read during an interrupt. 00236 *@retval #LOS_ERRNO_EVENT_FLAGS_INVALID The event mode is invalid. 00237 *@retval #LOS_ERRNO_EVENT_READ_IN_LOCK The event reading task is locked. 00238 *@retval #LOS_ERRNO_EVENT_PTR_NULL The passed-in pointer is null. 00239 *@retval 0 The event expected by the user does not occur. 00240 *@retval #UINT32 The event expected by the user occurs. 00241 *@par Dependency: 00242 *<ul><li>los_event.h: the header file that contains the API declaration.</li></ul> 00243 *@see LOS_EventPoll | LOS_EventWrite 00244 *@since Huawei LiteOS V100R001C00 00245 */ 00246 extern UINT32 LOS_EventRead(PEVENT_CB_S pstEventCB, UINT32 uwEventMask, UINT32 uwMode, UINT32 uwTimeOut); 00247 00248 /** 00249 *@ingroup los_event 00250 *@brief Write an event. 00251 * 00252 *@par Description: 00253 *This API is used to write an event specified by the passed-in event mask into an event control block pointed to by pstEventCB. 00254 *@attention 00255 *<ul> 00256 *<li>To determine whether the LOS_EventRead API returns an event or an error code, bit 25 of the event mask is forbidden to be used.</li> 00257 *</ul> 00258 * 00259 *@param pstEventCB [IN/OUT] Pointer to the event control block into which an event is to be written. This parameter must point to valid memory. 00260 *@param uwEvents [IN] Event mask to be written. 00261 * 00262 *@retval #LOS_ERRNO_EVENT_SETBIT_INVALID Bit 25 of the event mask cannot be set to an event because it is set to an error code. 00263 *@retval #LOS_ERRNO_EVENT_PTR_NULL Null pointer. 00264 *@retval #LOS_OK The event is successfully written. 00265 *@par Dependency: 00266 *<ul><li>los_event.h: the header file that contains the API declaration.</li></ul> 00267 *@see LOS_EventPoll | LOS_EventRead 00268 *@since Huawei LiteOS V100R001C00 00269 */ 00270 extern UINT32 LOS_EventWrite(PEVENT_CB_S pstEventCB, UINT32 uwEvents); 00271 00272 /** 00273 *@ingroup los_event 00274 *@brief Clear the event occurring in a specified task. 00275 * 00276 *@par Description: 00277 *<ul> 00278 *<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 an event control block pointed to by pstEventCB to 0. pstEventCB must point to valid memory.</li> 00279 *</ul> 00280 *@attention 00281 *<ul> 00282 *<li>The value of uwEvents needs to be reversed when it is passed-in.</li> 00283 *</ul> 00284 * 00285 *@param pstEventCB [IN/OUT] Pointer to the event control block to be cleared. 00286 *@param uwEvents [IN] Mask of the event to be cleared. 00287 * 00288 *@retval #LOS_ERRNO_EVENT_PTR_NULL Null pointer. 00289 *@retval #LOS_OK The event is successfully cleared. 00290 *@par Dependency: 00291 *<ul><li>los_event.h: the header file that contains the API declaration.</li></ul> 00292 *@see LOS_EventPoll | LOS_EventRead | LOS_EventWrite 00293 *@since Huawei LiteOS V100R001C00 00294 */ 00295 extern UINT32 LOS_EventClear(PEVENT_CB_S pstEventCB, UINT32 uwEvents); 00296 00297 /** 00298 *@ingroup los_event 00299 *@brief Destroy a event. 00300 * 00301 *@par Description: 00302 *<ul> 00303 *<li>This API is used to Destroy a event.</li> 00304 *</ul> 00305 *@attention 00306 *<ul> 00307 *<li>The specific event should be a valid one.</li> 00308 *</ul> 00309 * 00310 *@param pstEventCB [IN/OUT] Pointer to the event control block to be Destroyed. 00311 * 00312 *@retval #LOS_ERRNO_EVENT_PTR_NULL Null pointer. 00313 *@retval #LOS_OK The event is successfully cleared. 00314 *@par Dependency: 00315 *<ul><li>los_event.h: the header file that contains the API declaration.</li></ul> 00316 *@see LOS_EventPoll | LOS_EventRead | LOS_EventWrite 00317 *@since Huawei LiteOS V100R001C00 00318 */ 00319 extern UINT32 LOS_EventDestory(PEVENT_CB_S pstEventCB); 00320 00321 00322 #ifdef __cplusplus 00323 #if __cplusplus 00324 } 00325 #endif /* __cplusplus */ 00326 #endif /* __cplusplus */ 00327 00328 #endif /* _LOS_EVENT_H */