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_sem Semaphore 00036 * @ingroup kernel 00037 */ 00038 00039 #ifndef _LOS_SEM_H 00040 #define _LOS_SEM_H 00041 00042 #include "los_base.h" 00043 #include "los_err.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_sem 00056 * Semaphore error code: The memory is insufficient. 00057 * 00058 * Value: 0x02000700 00059 * 00060 * Solution: Allocate more memory. 00061 */ 00062 #define LOS_ERRNO_SEM_NO_MEMORY LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x00) 00063 00064 /** 00065 * @ingroup los_sem 00066 * Semaphore error code: Invalid parameter. 00067 * 00068 * Value: 0x02000701 00069 * 00070 * Solution: Change the passed-in invalid parameter value to a valid value. 00071 */ 00072 #define LOS_ERRNO_SEM_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x01) 00073 00074 /** 00075 * @ingroup los_sem 00076 * Semaphore error code: Null pointer. 00077 * 00078 * Value: 0x02000702 00079 * 00080 * Solution: Change the passed-in null pointer to a valid non-null pointer. 00081 */ 00082 #define LOS_ERRNO_SEM_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x02) 00083 00084 /** 00085 * @ingroup los_sem 00086 * Semaphore error code: No semaphore control structure is available. 00087 * 00088 * Value: 0x02000703 00089 * 00090 * Solution: Perform corresponding operations based on the requirements in the code context. 00091 */ 00092 #define LOS_ERRNO_SEM_ALL_BUSY LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x03) 00093 00094 /** 00095 * @ingroup los_sem 00096 * Semaphore error code: Invalid parameter that specifies the timeout interval. 00097 * 00098 * Value: 0x02000704 00099 * 00100 * 00101 * Solution: Change the passed-in parameter value to a valid nonzero value. 00102 */ 00103 #define LOS_ERRNO_SEM_UNAVAILABLE LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x04) 00104 00105 /** 00106 * @ingroup los_sem 00107 * Semaphore error code: The API is called during an interrupt, which is forbidden. 00108 * 00109 * Value: 0x02000705 00110 * 00111 * Solution: Do not call the API during an interrupt. 00112 */ 00113 #define LOS_ERRNO_SEM_PEND_INTERR LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x05) 00114 00115 /** 00116 * @ingroup los_sem 00117 * Semaphore error code: The task is unable to request a semaphore because task scheduling is locked. 00118 * 00119 * Value: 0x02000706 00120 * 00121 *Solution: Do not call LOS_SemPend when task scheduling is locked. 00122 */ 00123 #define LOS_ERRNO_SEM_PEND_IN_LOCK LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x06) 00124 00125 /** 00126 * @ingroup los_sem 00127 * Semaphore error code: The request for a semaphore times out. 00128 * 00129 * Value: 0x02000707 00130 * 00131 * Solution: Change the passed-in parameter value to the value within the valid range. 00132 */ 00133 #define LOS_ERRNO_SEM_TIMEOUT LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x07) 00134 00135 /** 00136 * @ingroup los_sem 00137 * Semaphore error code: The times of semaphore release exceed the maximum times permitted. 00138 * 00139 * Value: 0x02000708 00140 * 00141 * Solution: Perform corresponding operations based on the requirements in the code context. 00142 */ 00143 #define LOS_ERRNO_SEM_OVERFLOW LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x08) 00144 00145 /** 00146 * @ingroup los_sem 00147 * Semaphore error code: The queue of the tasks that are waiting on the semaphore control structure is not null. 00148 * 00149 * Value: 0x02000709 00150 * 00151 * Solution: Delete the semaphore after awaking all tasks that are waiting on the semaphore. 00152 */ 00153 #define LOS_ERRNO_SEM_PENDED LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x09) 00154 00155 /** 00156 * @ingroup los_sem 00157 * Semaphore error code: LOS_ERRNO_SEM_MAXNUM_ZERO is error. 00158 * 00159 * Value: 0x0200070A 00160 * 00161 * Solution: LOS_ERRNO_SEM_MAXNUM_ZERO should not be error. 00162 */ 00163 #define LOS_ERRNO_SEM_MAXNUM_ZERO LOS_ERRNO_OS_ERROR(LOS_MOD_SEM, 0x0A) 00164 00165 /** 00166 *@ingroup los_sem 00167 *@brief Create a Counting semaphore. 00168 * 00169 *@par Description: 00170 *This API is used to create a semaphore control structure according to the initial number of available semaphores specified by usCount and return the ID of this semaphore control structure. 00171 *@attention 00172 *<ul> 00173 *<li>None.</li> 00174 *</ul> 00175 * 00176 *@param usCount [IN] Initial number of available semaphores. The value range is [0, OS_SEM_COUNTING_MAX_COUNT). 00177 *@param puwSemHandle [OUT] ID of the semaphore control structure that is initialized. 00178 * 00179 *@retval #LOS_ERRNO_SEM_PTR_NULL The passed-in puwSemHandle value is NULL. 00180 *@retval #LOS_ERRNO_SEM_OVERFLOW The passed-in usCount value is greater than the maximum number of available semaphores. 00181 *@retval #LOS_ERRNO_SEM_ALL_BUSY No semaphore control structure is available. 00182 *@retval #LOS_OK The semaphore is successfully created. 00183 *@par Dependency: 00184 *<ul><li>los_sem.h: the header file that contains the API declaration.</li></ul> 00185 *@see LOS_SemDelete 00186 *@since Huawei LiteOS V100R001C00 00187 */ 00188 extern UINT32 LOS_SemCreate(UINT16 usCount, UINT32 *puwSemHandle); 00189 00190 /** 00191 *@ingroup los_sem 00192 *@brief Create a binary semaphore. 00193 * 00194 *@par Description: 00195 *This API is used to create a binary semaphore control structure according to the initial number of available semaphores specified by usCount and return the ID of this semaphore control structure. 00196 *@attention 00197 *<ul> 00198 *<li>None.</li> 00199 *</ul> 00200 * 00201 *@param usCount [IN] Initial number of available semaphores. The value range is [0, 1]. 00202 *@param puwSemHandle [OUT] ID of the semaphore control structure that is initialized. 00203 * 00204 *@retval #LOS_ERRNO_SEM_PTR_NULL The passed-in puwSemHandle value is NULL. 00205 *@retval #LOS_ERRNO_SEM_OVERFLOW The passed-in usCount value is greater than the maximum number of available semaphores. 00206 *@retval #LOS_ERRNO_SEM_ALL_BUSY No semaphore control structure is available. 00207 *@retval #LOS_OK The semaphore is successfully created. 00208 *@par Dependency: 00209 *<ul><li>los_sem.h: the header file that contains the API declaration.</li></ul> 00210 *@see LOS_SemDelete 00211 *@since Huawei LiteOS V100R001C00 00212 */ 00213 extern UINT32 LOS_BinarySemCreate (UINT16 usCount, UINT32 *puwSemHandle); 00214 00215 /** 00216 *@ingroup los_sem 00217 *@brief Delete a semaphore. 00218 * 00219 *@par Description: 00220 *This API is used to delete a semaphore control structure that has an ID specified by uwSemHandle. 00221 *@attention 00222 *<ul> 00223 *<li>The specified sem id must be created first. </li> 00224 *</ul> 00225 * 00226 *@param uwSemHandle [IN] ID of the semaphore control structure to be deleted. The ID of the semaphore control structure is obtained from semaphore creation. 00227 * 00228 *@retval #LOS_ERRNO_SEM_INVALID The passed-in uwSemHandle value is invalid. 00229 *@retval #LOS_ERRNO_SEM_PENDED The queue of the tasks that are waiting on the semaphore control structure is not null. 00230 *@retval #LOS_OK The semaphore control structure is successfully deleted. 00231 *@par Dependency: 00232 *<ul><li>los_sem.h: the header file that contains the API declaration.</li></ul> 00233 *@see LOS_SemCreate 00234 *@since Huawei LiteOS V100R001C00 00235 */ 00236 extern UINT32 LOS_SemDelete(UINT32 uwSemHandle); 00237 00238 /** 00239 *@ingroup los_sem 00240 *@brief Request a semaphore. 00241 * 00242 *@par Description: 00243 *This API is used to request a semaphore based on the semaphore control structure ID specified by uwSemHandle and the parameter that specifies the timeout period. 00244 *@attention 00245 *<ul> 00246 *<li>The specified sem id must be created first. </li> 00247 *</ul> 00248 * 00249 *@param uwSemHandle [IN] ID of the semaphore control structure to be requested. The ID of the semaphore control structure is obtained from semaphore creation. 00250 *@param uwTimeout [IN] Timeout interval for waiting on the semaphore. The value range is [0, 0xFFFFFFFF]. If the value is set to 0, the semaphore is not waited on. If the value is set to 0xFFFFFFFF, the semaphore is waited on forever(unit: Tick). 00251 * 00252 *@retval #LOS_ERRNO_SEM_INVALID The passed-in uwSemHandle value is invalid. 00253 *@retval #LOS_ERRNO_SEM_UNAVAILABLE There is no available semaphore resource. 00254 *@retval #LOS_ERRNO_SEM_PEND_INTERR The API is called during an interrupt, which is forbidden. 00255 *@retval #LOS_ERRNO_SEM_PEND_IN_LOCK The task is unable to request a semaphore because task scheduling is locked. 00256 *@retval #LOS_ERRNO_SEM_TIMEOUT The request for the semaphore times out. 00257 *@retval #LOS_OK The semaphore request succeeds. 00258 *@par Dependency: 00259 *<ul><li>los_sem.h: the header file that contains the API declaration.</li></ul> 00260 *@see LOS_SemPost | LOS_SemCreate 00261 *@since Huawei LiteOS V100R001C00 00262 */ 00263 extern UINT32 LOS_SemPend(UINT32 uwSemHandle, UINT32 uwTimeout); 00264 00265 /** 00266 *@ingroup los_sem 00267 *@brief Release a semaphore. 00268 * 00269 *@par Description: 00270 *This API is used to release a semaphore that has a semaphore control structure ID specified by uwSemHandle. 00271 *@attention 00272 *<ul> 00273 *<li>The specified sem id must be created first. </li> 00274 *</ul> 00275 * 00276 *@param uwSemHandle [IN] ID of the semaphore control structure to be released.The ID of the semaphore control structure is obtained from semaphore creation. 00277 * 00278 *@retval #LOS_ERRNO_SEM_INVALID The passed-in uwSemHandle value is invalid. 00279 *@retval #LOS_ERRNO_SEM_OVERFLOW The times of semaphore release exceed the maximum times permitted. 00280 *@retval #LOS_OK The semaphore is successfully released. 00281 *@par Dependency: 00282 *<ul><li>los_sem.h: the header file that contains the API declaration.</li></ul> 00283 *@see LOS_SemPend | LOS_SemCreate 00284 *@since Huawei LiteOS V100R001C00 00285 */ 00286 extern UINT32 LOS_SemPost(UINT32 uwSemHandle); 00287 00288 00289 #ifdef __cplusplus 00290 #if __cplusplus 00291 } 00292 #endif /* __cplusplus */ 00293 #endif /* __cplusplus */ 00294 00295 #endif /* _LOS_SEM_H */