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_mux Mutex 00036 * @ingroup kernel 00037 */ 00038 00039 #ifndef _LOS_MUX_H 00040 #define _LOS_MUX_H 00041 00042 #include "los_base.h" 00043 #include "los_sys.h" 00044 #include "los_list.h" 00045 #include "los_task.h" 00046 00047 #ifdef __cplusplus 00048 #if __cplusplus 00049 extern "C"{ 00050 #endif /* __cplusplus */ 00051 #endif /* __cplusplus */ 00052 00053 00054 /** 00055 * @ingroup los_mux 00056 * Mutex error code: The memory request fails. 00057 * 00058 * Value: 0x02001d00 00059 * 00060 * Solution: Decrease the number of mutexes defined by LOSCFG_BASE_IPC_MUX_LIMIT. 00061 */ 00062 #define LOS_ERRNO_MUX_NO_MEMORY LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x00) 00063 00064 /** 00065 * @ingroup los_mux 00066 * Mutex error code: The mutex is not usable. 00067 * 00068 * Value: 0x02001d01 00069 * 00070 * Solution: Check whether the mutex ID and the mutex state are applicable for the current operation. 00071 */ 00072 #define LOS_ERRNO_MUX_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x01) 00073 00074 /** 00075 * @ingroup los_mux 00076 * Mutex error code: Null pointer. 00077 * 00078 * Value: 0x02001d02 00079 * 00080 * Solution: Check whether the input parameter is usable. 00081 */ 00082 #define LOS_ERRNO_MUX_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x02) 00083 00084 /** 00085 * @ingroup los_mux 00086 * Mutex error code: No mutex is available and the mutex request fails. 00087 * 00088 * Value: 0x02001d03 00089 * 00090 * Solution: Increase the number of mutexes defined by LOSCFG_BASE_IPC_MUX_LIMIT. 00091 */ 00092 #define LOS_ERRNO_MUX_ALL_BUSY LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x03) 00093 00094 /** 00095 * @ingroup los_mux 00096 * Mutex error code: The mutex fails to be locked in non-blocking mode because it is locked by another thread. 00097 * 00098 * Value: 0x02001d04 00099 * 00100 * Solution: Lock the mutex after it is unlocked by the thread that owns it, or set a waiting time. 00101 */ 00102 #define LOS_ERRNO_MUX_UNAVAILABLE LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x04) 00103 00104 /** 00105 * @ingroup los_mux 00106 * Mutex error code: The mutex is being locked during an interrupt. 00107 * 00108 * Value: 0x02001d05 00109 * 00110 * Solution: Check whether the mutex is being locked during an interrupt. 00111 */ 00112 #define LOS_ERRNO_MUX_PEND_INTERR LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x05) 00113 00114 /** 00115 * @ingroup los_mux 00116 * Mutex error code: A thread locks a mutex after waiting for the mutex to be unlocked by another thread when the task scheduling is disabled. 00117 * 00118 * Value: 0x02001d06 00119 * 00120 * Solution: Check whether the task scheduling is disabled, or set uwtimeout to 0, which means that the thread will not wait for the mutex to become available. 00121 */ 00122 #define LOS_ERRNO_MUX_PEND_IN_LOCK LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x06) 00123 00124 /** 00125 * @ingroup los_mux 00126 * Mutex error code: The mutex locking times out. 00127 * 00128 * Value: 0x02001d07 00129 * 00130 * Solution: Increase the waiting time or set the waiting time to LOS_WAIT_FOREVER (forever-blocking mode). 00131 */ 00132 #define LOS_ERRNO_MUX_TIMEOUT LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x07) 00133 00134 /** 00135 * @ingroup los_mux 00136 * 00137 * Value: 0x02001d08 00138 * Not in use temporarily. 00139 */ 00140 #define LOS_ERRNO_MUX_OVERFLOW LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x08) 00141 00142 /** 00143 * @ingroup los_mux 00144 * Mutex error code: The mutex to be deleted is being locked. 00145 * 00146 * Value: 0x02001d09 00147 * 00148 * Solution: Delete the mutex after it is unlocked. 00149 */ 00150 #define LOS_ERRNO_MUX_PENDED LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x09) 00151 00152 /** 00153 * @ingroup los_mux 00154 * 00155 * Value: 0x02001d0A 00156 * Not in use temporarily. 00157 */ 00158 #define LOS_ERRNO_MUX_GET_COUNT_ERR LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x0A) 00159 00160 /** 00161 * @ingroup los_mux 00162 * 00163 * Value: 0x02001d0B 00164 * Not in use temporarily. 00165 */ 00166 #define LOS_ERRNO_MUX_REG_ERROR LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x0B) 00167 00168 /** 00169 * @ingroup los_mux 00170 * 00171 * Mutex error code: LOS_ERRNO_MUX_MAXNUM_ZERO is zero. 00172 * Value: 0x02001d0C 00173 * 00174 * Solution: LOS_ERRNO_MUX_MAXNUM_ZERO should not be zero. 00175 */ 00176 #define LOS_ERRNO_MUX_MAXNUM_ZERO LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x0C) 00177 00178 /** 00179 *@ingroup los_mux 00180 *@brief Create a mutex. 00181 * 00182 *@par Description: 00183 *This API is used to create a mutex. A mutex handle is assigned to puwMuxHandle when the mutex is created successfully. Return LOS_OK on creating successful, return specific error code otherwise. 00184 *@attention 00185 *<ul> 00186 *<li>The total number of mutexes is pre-configured. If there are no available mutexes, the mutex creation fails.</li> 00187 *</ul> 00188 * 00189 *@param puwMuxHandle [OUT] Handle pointer of the successfully created mutex. The value of handle should be in [0, LOSCFG_BASE_IPC_MUX_LIMIT - 1]. 00190 * 00191 *@retval #LOS_ERRNO_MUX_PTR_NULL The puwMuxHandle pointer is NULL. 00192 *@retval #LOS_ERRNO_MUX_ALL_BUSY No available mutex. 00193 *@retval #LOS_OK The mutex is successfully created. 00194 *@par Dependency: 00195 *<ul><li>los_mux.h: the header file that contains the API declaration.</li></ul> 00196 *@see LOS_MuxDelete 00197 *@since Huawei LiteOS V100R001C00 00198 */ 00199 extern UINT32 LOS_MuxCreate(UINT32 *puwMuxHandle); 00200 00201 /** 00202 *@ingroup los_mux 00203 *@brief Delete a mutex. 00204 * 00205 *@par Description: 00206 *This API is used to delete a specified mutex. Return LOS_OK on deleting successfully, return specific error code otherwise. 00207 *@attention 00208 *<ul> 00209 *<li>The specific mutex should be created firstly.</li> 00210 *<li>The mutex can be deleted successfully only if no other tasks pend on it.</li> 00211 *</ul> 00212 * 00213 *@param puwMuxHandle [IN] Handle of the mutex to be deleted. The value of handle should be in [0, LOSCFG_BASE_IPC_MUX_LIMIT - 1]. 00214 * 00215 *@retval #LOS_ERRNO_MUX_INVALID Invalid handle or mutex in use. 00216 *@retval #LOS_ERRNO_MUX_PENDED Tasks pended on this mutex. 00217 *@retval #LOS_OK The mutex is successfully deleted. 00218 *@par Dependency: 00219 *<ul><li>los_mux.h: the header file that contains the API declaration.</li></ul> 00220 *@see LOS_MuxCreate 00221 *@since Huawei LiteOS V100R001C00 00222 */ 00223 extern UINT32 LOS_MuxDelete(UINT32 puwMuxHandle); 00224 00225 /** 00226 *@ingroup los_mux 00227 *@brief Wait to lock a mutex. 00228 * 00229 *@par Description: 00230 *This API is used to wait for a specified period of time to lock a mutex. 00231 *@attention 00232 *<ul> 00233 *<li>The specific mutex should be created firstly.</li> 00234 *<li>The function fails if the mutex that is waited on is already locked by another thread when the task scheduling is disabled.</li> 00235 *<li>Do not wait on a mutex during an interrupt.</li> 00236 *<li>The priority inheritance protocol is supported. If a higher-priority thread is waiting on a mutex, it changes the priority of the thread that owns the mutex to avoid priority inversion.</li> 00237 *<li>A recursive mutex can be locked more than once by the same thread.</li> 00238 *</ul> 00239 * 00240 *@param uwMuxHandle [IN] Handle of the mutex to be waited on. The value of handle should be in [0, LOSCFG_BASE_IPC_MUX_LIMIT - 1]. 00241 *@param uwTimeout [IN] Waiting time. The value range is [0, LOS_WAIT_FOREVER](unit: Tick). 00242 * 00243 *@retval #LOS_ERRNO_MUX_INVALID The mutex state (for example, the mutex does not exist or is not in use) is not applicable for the current operation. 00244 *@retval #LOS_ERRNO_MUX_UNAVAILABLE The mutex fails to be locked because it is locked by another thread and a period of time is not set for waiting for the mutex to become available. 00245 *@retval #LOS_ERRNO_MUX_PEND_INTERR The mutex is being locked during an interrupt. 00246 *@retval #LOS_ERRNO_MUX_PEND_IN_LOCK The mutex is waited on when the task scheduling is disabled. 00247 *@retval #LOS_ERRNO_MUX_TIMEOUT The mutex waiting times out. 00248 *@retval #LOS_OK The mutex is successfully locked. 00249 *@par Dependency: 00250 *<ul><li>los_mux.h: the header file that contains the API declaration.</li></ul> 00251 *@see LOS_MuxCreate | LOS_MuxPost 00252 *@since Huawei LiteOS V100R001C00 00253 */ 00254 extern UINT32 LOS_MuxPend(UINT32 uwMuxHandle, UINT32 uwTimeout); 00255 00256 /** 00257 *@ingroup los_mux 00258 *@brief Release a mutex. 00259 * 00260 *@par Description: 00261 *This API is used to release a specified mutex. 00262 *@attention 00263 *<ul> 00264 *<li>The specific mutex should be created firstly.</li> 00265 *<li>Do not release a mutex during an interrupt.</li> 00266 *<li>If a recursive mutex is locked for many times, it must be unlocked for the same times to be released.</li> 00267 *</ul> 00268 * 00269 *@param uwMuxHandle [IN] Handle of the mutex to be released. The value of handle should be in [0, LOSCFG_BASE_IPC_MUX_LIMIT - 1]. 00270 * 00271 *@retval #LOS_ERRNO_MUX_INVALID The mutex state (for example, the mutex does not exist or is not in use or owned by other thread) is not applicable for the current operation. 00272 *@retval #LOS_ERRNO_MUX_PEND_INTERR The mutex is being released during an interrupt. 00273 *@retval #LOS_OK The mutex is successfully released. 00274 *@par Dependency: 00275 *<ul><li>los_mux.h: the header file that contains the API declaration.</li></ul> 00276 *@see LOS_MuxCreate | LOS_MuxPend 00277 *@since Huawei LiteOS V100R001C00 00278 */ 00279 extern UINT32 LOS_MuxPost(UINT32 uwMuxHandle); 00280 00281 00282 #ifdef __cplusplus 00283 #if __cplusplus 00284 } 00285 #endif 00286 #endif /* __cplusplus */ 00287 00288 #endif /* _LOS_MUX_H */