1 /* ---------------------------------------------------------------------------- 2 * Copyright (c) Huawei Technologies Co., Ltd. 2013-2018. All rights reserved. 3 * Description: semaphore 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_sem Semaphore 29 * @ingroup kernel 30 */ 31 32 #ifndef _LOS_SEM_H 33 #define _LOS_SEM_H 34 35 #include "los_err.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_sem 47 * Semaphore error code: The memory is insufficient. 48 * 49 * Value: 0x02000700 50 * 51 * Solution: Allocate more memory. 52 */ 53 #define LOS_ERRNO_SEM_NO_MEMORY LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x00) 54 55 /** 56 * @ingroup los_sem 57 * Semaphore error code: Invalid parameter. 58 * 59 * Value: 0x02000701 60 * 61 * Solution: Change the passed-in invalid parameter value to a valid value. 62 */ 63 #define LOS_ERRNO_SEM_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x01) 64 65 /** 66 * @ingroup los_sem 67 * Semaphore error code: Null pointer. 68 * 69 * Value: 0x02000702 70 * 71 * Solution: Change the passed-in null pointer to a valid non-null pointer. 72 */ 73 #define LOS_ERRNO_SEM_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x02) 74 75 /** 76 * @ingroup los_sem 77 * Semaphore error code: No semaphore control structure is available. 78 * 79 * Value: 0x02000703 80 * 81 * Solution: Perform corresponding operations based on the requirements in the code context. 82 */ 83 #define LOS_ERRNO_SEM_ALL_BUSY LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x03) 84 85 /** 86 * @ingroup los_sem 87 * Semaphore error code: Invalid parameter that specifies the timeout interval. 88 * 89 * Value: 0x02000704 90 * 91 * 92 * Solution: Change the passed-in parameter value to a valid nonzero value. 93 */ 94 #define LOS_ERRNO_SEM_UNAVAILABLE LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x04) 95 96 /** 97 * @ingroup los_sem 98 * Semaphore error code: The API is called during an interrupt, which is forbidden. 99 * 100 * Value: 0x02000705 101 * 102 * Solution: Do not call the API during an interrupt. 103 */ 104 #define LOS_ERRNO_SEM_PEND_INTERR LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x05) 105 106 /** 107 * @ingroup los_sem 108 * Semaphore error code: The task is unable to request a semaphore because task scheduling is locked. 109 * 110 * Value: 0x02000706 111 * 112 * Solution: Do not call LOS_SemPend when task scheduling is locked. 113 */ 114 #define LOS_ERRNO_SEM_PEND_IN_LOCK LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x06) 115 116 /** 117 * @ingroup los_sem 118 * Semaphore error code: The request for a semaphore times out. 119 * 120 * Value: 0x02000707 121 * 122 * Solution: Change the passed-in parameter value to the value within the valid range. 123 */ 124 #define LOS_ERRNO_SEM_TIMEOUT LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x07) 125 126 /** 127 * @ingroup los_sem 128 * Semaphore error code: The times of semaphore release exceed the maximum times permitted. 129 * 130 * Value: 0x02000708 131 * 132 * Solution: Perform corresponding operations based on the requirements in the code context. 133 */ 134 #define LOS_ERRNO_SEM_OVERFLOW LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x08) 135 136 /** 137 * @ingroup los_sem 138 * Semaphore error code: The queue of the tasks that are waiting on the semaphore control structure is not null. 139 * 140 * Value: 0x02000709 141 * 142 * Solution: Delete the semaphore after awaking all tasks that are waiting on the semaphore. 143 */ 144 #define LOS_ERRNO_SEM_PENDED LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x09) 145 146 /** 147 * @ingroup los_sem 148 * Semaphore error code: LOS_ERRNO_SEM_MAXNUM_ZERO is error. 149 * 150 * Value: 0x0200070A 151 * 152 * Solution: LOS_ERRNO_SEM_MAXNUM_ZERO should not be error. 153 */ 154 #define LOS_ERRNO_SEM_MAXNUM_ZERO LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x0A) 155 156 /** 157 * @ingroup los_sem 158 * @brief Create a Counting semaphore. 159 * 160 * @par Description: 161 * This API is used to create a semaphore control structure according to the initial number of available semaphores 162 * specified by count and return the ID of this semaphore control structure. 163 * @attention 164 * <ul> 165 * <li>None.</li> 166 * </ul> 167 * 168 * @param count [IN] Initial number of available semaphores. The value range is [0, OS_SEM_COUNTING_MAX_COUNT]. 169 * @param semHandle [OUT] ID of the semaphore control structure that is initialized. 170 * 171 * @retval #LOS_ERRNO_SEM_PTR_NULL The passed-in semHandle value is NULL. 172 * @retval #LOS_ERRNO_SEM_OVERFLOW The passed-in count value is greater than the maximum number of available 173 * semaphores. 174 * @retval #LOS_ERRNO_SEM_ALL_BUSY No semaphore control structure is available. 175 * @retval #LOS_OK The semaphore is successfully created. 176 * @par Dependency: 177 * <ul><li>los_sem.h: the header file that contains the API declaration.</li></ul> 178 * @see LOS_SemDelete 179 */ 180 extern UINT32 LOS_SemCreate(UINT16 count, UINT32 *semHandle); 181 182 /** 183 * @ingroup los_sem 184 * @brief Create a binary semaphore. 185 * 186 * @par Description: 187 * This API is used to create a binary semaphore control structure according to the initial number of available 188 * semaphores specified by count and return the ID of this semaphore control structure. 189 * @attention 190 * <ul> 191 * <li>None.</li> 192 * </ul> 193 * 194 * @param count [IN] Initial number of available semaphores. The value range is [0, 1]. 195 * @param semHandle [OUT] ID of the semaphore control structure that is initialized. 196 * 197 * @retval #LOS_ERRNO_SEM_PTR_NULL The passed-in semHandle value is NULL. 198 * @retval #LOS_ERRNO_SEM_OVERFLOW The passed-in count value is greater than the maximum number of available 199 * semaphores. 200 * @retval #LOS_ERRNO_SEM_ALL_BUSY No semaphore control structure is available. 201 * @retval #LOS_OK The semaphore is successfully created. 202 * @par Dependency: 203 * <ul><li>los_sem.h: the header file that contains the API declaration.</li></ul> 204 * @see LOS_SemDelete 205 */ 206 extern UINT32 LOS_BinarySemCreate(UINT16 count, UINT32 *semHandle); 207 208 /** 209 * @ingroup los_sem 210 * @brief Delete a semaphore. 211 * 212 * @par Description: 213 * This API is used to delete a semaphore control structure that has an ID specified by semHandle. 214 * @attention 215 * <ul> 216 * <li>The specified sem id must be created first. </li> 217 * </ul> 218 * 219 * @param semHandle [IN] ID of the semaphore control structure to be deleted. The ID of the semaphore 220 * control structure is obtained from semaphore creation. 221 * 222 * @retval #LOS_ERRNO_SEM_INVALID The passed-in semHandle value is invalid. 223 * @retval #LOS_ERRNO_SEM_PENDED The queue of the tasks that are waiting on the semaphore control structure is 224 * not null. 225 * @retval #LOS_OK The semaphore control structure is successfully deleted. 226 * @par Dependency: 227 * <ul><li>los_sem.h: the header file that contains the API declaration.</li></ul> 228 * @see LOS_SemCreate 229 */ 230 extern UINT32 LOS_SemDelete(UINT32 semHandle); 231 232 /** 233 * @ingroup los_sem 234 * @brief Request a semaphore. 235 * 236 * @par Description: 237 * This API is used to request a semaphore based on the semaphore control structure ID specified by semHandle and the 238 * parameter that specifies the timeout period. 239 * @attention 240 * <ul> 241 * <li>The specified sem id must be created first. </li> 242 * </ul> 243 * 244 * @param semHandle [IN] ID of the semaphore control structure to be requested. The ID of the semaphore control 245 * structure is obtained from semaphore creation. 246 * @param timeout [IN] Timeout interval for waiting on the semaphore. The value range is [0, 0xFFFFFFFF]. 247 * If the value is set to 0, the semaphore is not waited on. If the value is set to 0xFFFFFFFF, 248 * the semaphore is waited on forever(unit: Tick). 249 * 250 * @retval #LOS_ERRNO_SEM_INVALID The passed-in semHandle value is invalid. 251 * @retval #LOS_ERRNO_SEM_UNAVAILABLE There is no available semaphore resource. 252 * @retval #LOS_ERRNO_SEM_PEND_INTERR The API is called during an interrupt, which is forbidden. 253 * @retval #LOS_ERRNO_SEM_PEND_IN_LOCK The task is unable to request a semaphore because task scheduling is locked. 254 * @retval #LOS_ERRNO_SEM_TIMEOUT The request for the semaphore times out. 255 * @retval #LOS_OK The semaphore request succeeds. 256 * @par Dependency: 257 * <ul><li>los_sem.h: the header file that contains the API declaration.</li></ul> 258 * @see LOS_SemPost | LOS_SemCreate 259 */ 260 extern UINT32 LOS_SemPend(UINT32 semHandle, UINT32 timeout); 261 262 /** 263 * @ingroup los_sem 264 * @brief Release a semaphore. 265 * 266 * @par Description: 267 * This API is used to release a semaphore that has a semaphore control structure ID specified by semHandle. 268 * @attention 269 * <ul> 270 * <li>The specified sem id must be created first. </li> 271 * </ul> 272 * 273 * @param semHandle [IN] ID of the semaphore control structure to be released.The ID of the semaphore control 274 * structure is obtained from semaphore creation. 275 * 276 * @retval #LOS_ERRNO_SEM_INVALID The passed-in semHandle value is invalid. 277 * @retval #LOS_ERRNO_SEM_OVERFLOW The times of semaphore release exceed the maximum times permitted. 278 * @retval #LOS_OK The semaphore is successfully released. 279 * @par Dependency: 280 * <ul><li>los_sem.h: the header file that contains the API declaration.</li></ul> 281 * @see LOS_SemPend | LOS_SemCreate 282 */ 283 extern UINT32 LOS_SemPost(UINT32 semHandle); 284 extern UINT32 LOS_SemUsage(VOID); 285 286 #ifdef __cplusplus 287 #if __cplusplus 288 } 289 #endif /* __cplusplus */ 290 #endif /* __cplusplus */ 291 292 #endif /* _LOS_SEM_H */ 293