1 /* 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 * Description: OS Abstract Layer. 15 */ 16 17 /** 18 * @defgroup osal_semaphore osal_semaphore 19 */ 20 #ifndef __OSAL_SEMAPHORE_H__ 21 #define __OSAL_SEMAPHORE_H__ 22 23 #ifdef __cplusplus 24 #if __cplusplus 25 extern "C" { 26 #endif 27 #endif 28 29 #define OSAL_SEM_WAIT_FOREVER (-1) 30 31 typedef struct { 32 void *sem; 33 } osal_semaphore; 34 35 /** 36 * @ingroup osal_semaphore 37 * @brief Create a semaphore. 38 * 39 * @par Description: 40 * This API is used to create a semaphore control structure 41 * according to the initial number of available semaphores specified by count 42 * 43 * @param val [in] Initial number of available semaphores. 44 * @param sem [out] Pointer of semaphore control structure that is initialized. 45 * 46 * @return OSAL_SUCCESS/OSAL_FAILURE 47 * 48 * @par Support System: 49 * linux liteos freertos. 50 */ 51 int osal_sem_init(osal_semaphore *sem, int val); 52 53 /** 54 * @ingroup osal_semaphore 55 * @brief Create a binary semaphore. 56 * 57 * @par Description: 58 * This API is used to create a binary semaphore control structure 59 * according to the initial number of available semaphores specified by count 60 * 61 * @param val [in] Initial number of available semaphores. The value range is [0, 1]. 62 * @param sem [out] Pointer of semaphore control structure that is initialized. 63 * 64 * @return OSAL_SUCCESS/OSAL_FAILURE 65 * 66 * @par Support System: 67 * liteos freertos. 68 */ 69 int osal_sem_binary_sem_init(osal_semaphore *sem, int val); 70 71 /** 72 * @ingroup osal_semaphore 73 * @brief Request a semaphore. 74 * 75 * @par Description: 76 * This API is used to attempt to obtain the semaphore. Acquires the semaphore. 77 * If no more tasks are allowed to acquire the semaphore, 78 * calling this function will put the task to sleep until the semaphore is released. 79 * 80 * @attention 81 * Do not pend sem during an interrupt. 82 * Do not pend sem in a system task, such as idle or swtmr task. 83 * The specified sem id must be created first. 84 * Do not recommend to use this API in software timer callback. 85 * 86 * @param sem [in] The semaphore to be acquired. 87 * 88 * @return OSAL_SUCCESS/OSAL_FAILURE 89 * 90 * @par Support System: 91 * linux liteos freertos. 92 */ 93 int osal_sem_down(osal_semaphore *sem); 94 95 /** 96 * @ingroup osal_semaphore 97 * @brief Acquire the semaphore within a specified time that specifies the timeout period. 98 * 99 * @par Description: 100 * Acquire the semaphore within a specified time that specifies the timeout period. 101 * 102 * @attention 103 * Do not pend sem during an interrupt. 104 * Do not pend sem in a system task, such as idle or swtmr task. 105 * The specified sem id must be created first. 106 * Do not recommend to use this API in software timer callback. 107 * 108 * @param sem [in] The semaphore to be acquired. 109 * @param timeout [in] How long to wait before failing. (unit: ms) 110 * 111 * @return OSAL_SUCCESS/OSAL_FAILURE 112 * 113 * @par Support System: 114 * liteos freertos. 115 */ 116 int osal_sem_down_timeout(osal_semaphore *sem, unsigned int timeout); 117 118 /** 119 * @ingroup osal_semaphore 120 * @brief acquire the semaphore unless interrupted. 121 * 122 * @par Description: 123 * Acquire the semaphore unless interrupted. Attempts to acquire the semaphore. 124 * If no more tasks are allowed to acquire the semaphore, calling this function will put the task to sleep. 125 * 126 * @param sem [in] The semaphore to be acquired. 127 * 128 * @return 129 * If the sleep is interrupted by a signal, this function will return OSAL_EINTR. 130 * If the semaphore is successfully acquired, this function returns OSAL_SUCCESS, failed return OSAL_FAILURE 131 * 132 * @par Support System: 133 * linux liteos freertos. 134 */ 135 int osal_sem_down_interruptible(osal_semaphore *sem); 136 137 /** 138 * @ingroup osal_semaphore 139 * @brief try to acquire the semaphore, without waiting. 140 * 141 * @par Description: 142 * try to acquire the semaphore, without waiting. 143 * 144 * @attention 145 * This return value is inverted from both spin_trylock and mutex_trylock! Be careful about this when converting code. 146 * Unlike mutex_trylock, this function can be used from interrupt context, 147 * and the semaphore can be released by any task or interrupt. 148 * 149 * @param sem [in] The semaphore to be acquired. 150 * 151 * @return 152 * If the semaphore cannot be obtained, the system returns 1 instead of sleeping. 153 * If the value 0 is returned, the semaphore is obtained. 154 * 155 * @par Support System: 156 * linux liteos freertos. 157 */ 158 int osal_sem_trydown(osal_semaphore *sem); 159 160 /** 161 * @ingroup osal_semaphore 162 * @brief Release a semaphore. 163 * 164 * @par Description: 165 * Release a semaphore. 166 * 167 * @attention 168 * Unlike mutexes, osal_sem_up() may be called from any context and 169 * even by tasks which have never called osal_sem_down(). 170 * 171 * @param sem [in] The semaphore to release. 172 * 173 * @par Support System: 174 * linux liteos freertos. 175 */ 176 void osal_sem_up(osal_semaphore *sem); 177 178 /** 179 * @ingroup osal_semaphore 180 * @brief Delete a semaphore. 181 * 182 * @par Description: 183 * This API is used to destroy semaphore and release space. 184 * 185 * @attention 186 * The specified sem must be created first before deleting it. 187 * 188 * @param sem [in] The semaphore to destroyed. 189 * 190 * @par Support System: 191 * linux liteos freertos. 192 */ 193 void osal_sem_destroy(osal_semaphore *sem); 194 195 #ifdef __cplusplus 196 #if __cplusplus 197 } 198 #endif 199 #endif 200 #endif /* __OSAL_SEMAPHORE_H__ */ 201