1 /* ---------------------------------------------------------------------------- 2 * Copyright (c) Huawei Technologies Co., Ltd. 2013-2018. All rights reserved. 3 * Description: mutex 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_mux Mutex 29 * @ingroup kernel 30 */ 31 32 #ifndef _LOS_MUX_H 33 #define _LOS_MUX_H 34 35 #include "los_sys.h" 36 #include "los_list.h" 37 #include "los_task.h" 38 39 #ifdef __cplusplus 40 #if __cplusplus 41 extern "C" { 42 #endif /* __cplusplus */ 43 #endif /* __cplusplus */ 44 45 /** 46 * @ingroup los_mux 47 * Mutex error code: The memory request fails. 48 * 49 * Value: 0x02001d00 50 * 51 * Solution: Decrease the number of mutexes defined by LOSCFG_BASE_IPC_MUX_LIMIT. 52 */ 53 #define LOS_ERRNO_MUX_NO_MEMORY LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x00) 54 55 /** 56 * @ingroup los_mux 57 * Mutex error code: The mutex is not usable. 58 * 59 * Value: 0x02001d01 60 * 61 * Solution: Check whether the mutex ID and the mutex state are applicable for the current operation. 62 */ 63 #define LOS_ERRNO_MUX_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x01) 64 65 /** 66 * @ingroup los_mux 67 * Mutex error code: Null pointer. 68 * 69 * Value: 0x02001d02 70 * 71 * Solution: Check whether the input parameter is usable. 72 */ 73 #define LOS_ERRNO_MUX_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x02) 74 75 /** 76 * @ingroup los_mux 77 * Mutex error code: No mutex is available and the mutex request fails. 78 * 79 * Value: 0x02001d03 80 * 81 * Solution: Increase the number of mutexes defined by LOSCFG_BASE_IPC_MUX_LIMIT. 82 */ 83 #define LOS_ERRNO_MUX_ALL_BUSY LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x03) 84 85 /** 86 * @ingroup los_mux 87 * Mutex error code: The mutex fails to be locked in non-blocking mode because it is locked by another thread. 88 * 89 * Value: 0x02001d04 90 * 91 * Solution: Lock the mutex after it is unlocked by the thread that owns it, or set a waiting time. 92 */ 93 #define LOS_ERRNO_MUX_UNAVAILABLE LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x04) 94 95 /** 96 * @ingroup los_mux 97 * Mutex error code: The mutex is being locked during an interrupt. 98 * 99 * Value: 0x02001d05 100 * 101 * Solution: Check whether the mutex is being locked during an interrupt. 102 */ 103 #define LOS_ERRNO_MUX_PEND_INTERR LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x05) 104 105 /** 106 * @ingroup los_mux 107 * Mutex error code: A thread locks a mutex after waiting for the mutex to be unlocked by another thread 108 * when the task scheduling is disabled. 109 * 110 * Value: 0x02001d06 111 * 112 * Solution: Check whether the task scheduling is disabled, or set uwtimeout to 0, which means that the 113 * thread will not wait for the mutex to become available. 114 */ 115 #define LOS_ERRNO_MUX_PEND_IN_LOCK LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x06) 116 117 /** 118 * @ingroup los_mux 119 * Mutex error code: The mutex locking times out. 120 * 121 * Value: 0x02001d07 122 * 123 * Solution: Increase the waiting time or set the waiting time to LOS_WAIT_FOREVER (forever-blocking mode). 124 */ 125 #define LOS_ERRNO_MUX_TIMEOUT LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x07) 126 127 /** 128 * @ingroup los_mux 129 * 130 * Value: 0x02001d08 131 * Not in use temporarily. 132 */ 133 #define LOS_ERRNO_MUX_OVERFLOW LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x08) 134 135 /** 136 * @ingroup los_mux 137 * Mutex error code: The mutex to be deleted is being locked. 138 * 139 * Value: 0x02001d09 140 * 141 * Solution: Delete the mutex after it is unlocked. 142 */ 143 #define LOS_ERRNO_MUX_PENDED LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x09) 144 145 /** 146 * @ingroup los_mux 147 * 148 * Value: 0x02001d0A 149 * Not in use temporarily. 150 */ 151 #define LOS_ERRNO_MUX_GET_COUNT_ERR LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x0A) 152 153 /** 154 * @ingroup los_mux 155 * 156 * Value: 0x02001d0B 157 * Not in use temporarily. 158 */ 159 #define LOS_ERRNO_MUX_REG_ERROR LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x0B) 160 161 /** 162 * @ingroup los_mux 163 * 164 * Mutex error code: LOS_ERRNO_MUX_MAXNUM_ZERO is zero. 165 * Value: 0x02001d0C 166 * 167 * Solution: LOS_ERRNO_MUX_MAXNUM_ZERO should not be zero. 168 */ 169 #define LOS_ERRNO_MUX_MAXNUM_ZERO LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x0C) 170 171 /** 172 * @ingroup los_mux 173 * @brief Create a mutex. 174 * 175 * @par Description: 176 * This API is used to create a mutex. A mutex handle is assigned to muxHandle when the mutex is created successfully. 177 * Return LOS_OK on creating successful, return specific error code otherwise. 178 * @attention 179 * <ul> 180 * <li>The total number of mutexes is pre-configured. If there are no available mutexes, the mutex creation fails.</li> 181 * </ul> 182 * 183 * @param muxHandle [OUT] Handle pointer of the successfully created mutex. The value of handle should be in 184 * [0, LOSCFG_BASE_IPC_MUX_LIMIT - 1]. 185 * 186 * @retval #LOS_ERRNO_MUX_PTR_NULL The muxHandle pointer is NULL. 187 * @retval #LOS_ERRNO_MUX_ALL_BUSY No available mutex. 188 * @retval #LOS_OK The mutex is successfully created. 189 * @par Dependency: 190 * <ul><li>los_mux.h: the header file that contains the API declaration.</li></ul> 191 * @see LOS_MuxDelete 192 */ 193 extern UINT32 LOS_MuxCreate(UINT32 *muxHandle); 194 195 /** 196 * @ingroup los_mux 197 * @brief Delete a mutex. 198 * 199 * @par Description: 200 * This API is used to delete a specified mutex. Return LOS_OK on deleting successfully, return specific error code 201 * otherwise. 202 * @attention 203 * <ul> 204 * <li>The specific mutex should be created firstly.</li> 205 * <li>The mutex can be deleted successfully only if no other tasks pend on it.</li> 206 * </ul> 207 * 208 * @param muxHandle [IN] Handle of the mutex to be deleted. The value of handle should be in 209 * [0, LOSCFG_BASE_IPC_MUX_LIMIT - 1]. 210 * 211 * @retval #LOS_ERRNO_MUX_INVALID Invalid handle or mutex in use. 212 * @retval #LOS_ERRNO_MUX_PENDED Tasks pended on this mutex. 213 * @retval #LOS_OK The mutex is successfully deleted. 214 * @par Dependency: 215 * <ul><li>los_mux.h: the header file that contains the API declaration.</li></ul> 216 * @see LOS_MuxCreate 217 */ 218 extern UINT32 LOS_MuxDelete(UINT32 muxHandle); 219 220 /** 221 * @ingroup los_mux 222 * @brief Wait to lock a mutex. 223 * 224 * @par Description: 225 * This API is used to wait for a specified period of time to lock a mutex. 226 * @attention 227 * <ul> 228 * <li>The specific mutex should be created firstly.</li> 229 * <li>The function fails if the mutex that is waited on is already locked by another thread when the task scheduling 230 * is disabled.</li> 231 * <li>Do not wait on a mutex during an interrupt.</li> 232 * <li>The priority inheritance protocol is supported. If a higher-priority thread is waiting on a mutex, it changes 233 * the priority of the thread that owns the mutex to avoid priority inversion.</li> 234 * <li>A recursive mutex can be locked more than once by the same thread.</li> 235 * </ul> 236 * 237 * @param muxHandle [IN] Handle of the mutex to be waited on. The value of handle should be 238 * in [0, LOSCFG_BASE_IPC_MUX_LIMIT - 1]. 239 * @param timeout [IN] Waiting time. The value range is [0, LOS_WAIT_FOREVER](unit: Tick). 240 * 241 * @retval #LOS_ERRNO_MUX_INVALID The mutex state (for example, the mutex does not exist or is not in use) 242 * is not applicable for the current operation. 243 * @retval #LOS_ERRNO_MUX_UNAVAILABLE The mutex fails to be locked because it is locked by another thread and 244 * a period of time is not set for waiting for the mutex to become available. 245 * @retval #LOS_ERRNO_MUX_PEND_INTERR The mutex is being locked during an interrupt. 246 * @retval #LOS_ERRNO_MUX_PEND_IN_LOCK The mutex is waited on when the task scheduling is disabled. 247 * @retval #LOS_ERRNO_MUX_TIMEOUT The mutex waiting times out. 248 * @retval #LOS_OK The mutex is successfully locked. 249 * @par Dependency: 250 * <ul><li>los_mux.h: the header file that contains the API declaration.</li></ul> 251 * @see LOS_MuxCreate | LOS_MuxPost 252 */ 253 extern UINT32 LOS_MuxPend(UINT32 muxHandle, UINT32 timeout); 254 255 /** 256 * @ingroup los_mux 257 * @brief Release a mutex. 258 * 259 * @par Description: 260 * This API is used to release a specified mutex. 261 * @attention 262 * <ul> 263 * <li>The specific mutex should be created firstly.</li> 264 * <li>Do not release a mutex during an interrupt.</li> 265 * <li>If a recursive mutex is locked for many times, it must be unlocked for the same times to be released.</li> 266 * </ul> 267 * 268 * @param muxHandle [IN] Handle of the mutex to be released. The value of handle should be in 269 * [0, LOSCFG_BASE_IPC_MUX_LIMIT - 1]. 270 * 271 * @retval #LOS_ERRNO_MUX_INVALID The mutex state (for example, the mutex does not exist or is not in use 272 * or owned by other thread) is not applicable for the current operation. 273 * @retval #LOS_ERRNO_MUX_PEND_INTERR The mutex is being released during an interrupt. 274 * @retval #LOS_OK The mutex is successfully released. 275 * @par Dependency: 276 * <ul><li>los_mux.h: the header file that contains the API declaration.</li></ul> 277 * @see LOS_MuxCreate | LOS_MuxPend 278 */ 279 extern UINT32 LOS_MuxPost(UINT32 muxHandle); 280 extern UINT32 LOS_MuxUsage(VOID); 281 282 #ifdef __cplusplus 283 #if __cplusplus 284 } 285 #endif 286 #endif /* __cplusplus */ 287 288 #endif /* _LOS_MUX_H */ 289