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_mutex osal_mutex 19 */ 20 #ifndef __OSAL_MUTEX_H__ 21 #define __OSAL_MUTEX_H__ 22 23 #ifdef __cplusplus 24 #if __cplusplus 25 extern "C" { 26 #endif 27 #endif 28 29 #define OSAL_MUTEX_WAIT_FOREVER (-1) 30 31 typedef struct { 32 void *mutex; 33 } osal_mutex; 34 35 /** 36 * @ingroup osal_mutex 37 * @brief Initialize the mutex. 38 * 39 * @par Description: 40 * This API is used to initialize the mutex. 41 * 42 * @param mutex [in] the mutex to be initialized. 43 * 44 * @return OSAL_FAILURE/OSAL_SUCCESS 45 * 46 * @par Support System: 47 * linux liteos freertos. 48 */ 49 int osal_mutex_init(osal_mutex *mutex); 50 51 /** 52 * @ingroup osal_mutex 53 * @brief Acquire the mutex. 54 * 55 * @par Description: 56 * Acquire the mutex. Lock the mutex exclusively for this task. 57 * If the mutex is not available right now, it will sleep until it can get it. 58 * 59 * @param mutex [in] the mutex to be initialized. 60 * 61 * @return OSAL_FAILURE/OSAL_SUCCESS 62 * 63 * @note 64 * The mutex must later on be released by the same task that acquired it. Recursive locking is not allowed. 65 * The task may not exit without first unlocking the mutex. 66 * Also, kernel memory where the mutex resides must not be freed with the mutex still locked. 67 * The mutex must first be initialized (or statically defined) before it can be locked. 68 * memset()-ing the mutex to 0 is not allowed. 69 * 70 * @par Support System: 71 * linux liteos freertos. 72 * @par System Differ:LiteOS and Freertos supports the nested lock feature. 73 */ 74 int osal_mutex_lock(osal_mutex *mutex); 75 76 /** 77 * @ingroup osal_mutex 78 * @brief Acquire the mutex until timeout. 79 * 80 * @par Description: 81 * This API is used to wait for a specified period of time to acquire the mutex. 82 * 83 * @param mutex [in] The mutex to be acquired. 84 * @param timeout [in] how long to wait before failing. 85 * 86 * @return OSAL_FAILURE/OSAL_SUCCESS 87 * 88 * @par Support System: 89 * liteos freertos. 90 * @par System Differ: LiteOS and Freertos supports the nested lock feature. 91 */ 92 int osal_mutex_lock_timeout(osal_mutex *mutex, unsigned int timeout); 93 94 /** 95 * @ingroup osal_mutex 96 * @brief Acquire the mutex until timeout, interruptible by signals. 97 * 98 * @par Description: 99 * Acquire the mutex, interruptible by signals. Lock the mutex like mutex_lock(). 100 * If a signal is delivered while the process is sleeping, this function will return without acquiring the mutex. 101 * 102 * @param mutex [in] The mutex to be acquired. 103 * 104 * @return OSAL_FAILURE/OSAL_SUCCESS/OSAL_EINTR 105 * 106 * @par Support System: 107 * linux liteos. 108 * @par System Differ: Only LiteOS supports the nested lock feature. 109 */ 110 int osal_mutex_lock_interruptible(osal_mutex *mutex); 111 112 /** 113 * @ingroup osal_mutex 114 * @brief Try to acquire the mutex. 115 * 116 * @par Description: 117 * try to acquire the mutex, without waiting. 118 * 119 * @param mutex [in] The mutex to be acquired. 120 * 121 * @return TRUE/FALSE 122 * 123 * @par Support System: 124 * linux liteos freertos. 125 * @par System Differ: LiteOS and Freertos supports the nested lock feature. 126 */ 127 int osal_mutex_trylock(osal_mutex *mutex); 128 129 /** 130 * @ingroup osal_mutex 131 * @brief Release the mutex. 132 * 133 * @par Description: 134 * Release the mutex. Unlock a mutex that has been locked by this task previously. 135 * This function must not be used in interrupt context. Unlocking of a not locked mutex is not allowed. 136 * 137 * @param mutex [in] the mutex to be released. 138 * 139 * @par Support System: 140 * linux liteos freertos. 141 */ 142 void osal_mutex_unlock(osal_mutex *mutex); 143 144 /** 145 * @ingroup osal_mutex 146 * @brief is the mutex locked. 147 * 148 * @par Description: 149 * is the mutex locked. 150 * 151 * @param mutex [in] The mutex to be acquired. 152 * 153 * @return true if the mutex is locked, false if unlocked. 154 * 155 * @par Support System: 156 * linux freertos. 157 */ 158 int osal_mutex_is_locked(osal_mutex *mutex); 159 160 /** 161 * @ingroup osal_mutex 162 * @brief Destroy the mutex. 163 * 164 * @par Description: 165 * This API is used to destroy the mutex. 166 * 167 * @param mutex [in] The mutex to be destroyed. 168 * 169 * @attention 170 * must be called when kmod exit, otherwise will lead to memory leak; osal_mutex_destroy will free memory, 171 * caller should clear pointer to be NULL after called. 172 * 173 * @par Support System: 174 * linux liteos freertos. 175 */ 176 void osal_mutex_destroy(osal_mutex *mutex); 177 178 #ifdef __cplusplus 179 #if __cplusplus 180 } 181 #endif 182 #endif 183 #endif /* __OSAL_MUTEX_H__ */