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_spinlock osal_spinlock 19 */ 20 #ifndef __OSAL_SPINLOCK_H__ 21 #define __OSAL_SPINLOCK_H__ 22 23 #ifdef __cplusplus 24 #if __cplusplus 25 extern "C" { 26 #endif 27 #endif 28 29 typedef struct { 30 void *lock; 31 } osal_spinlock; 32 33 /** 34 * @ingroup osal_spinlock 35 * @brief Initialize a spin lock. 36 * 37 * @par Description: 38 * This API is used to initialization of spin_lock. 39 * 40 * @param lock [out] the lock to be initialized. 41 * 42 * @attention 43 * must be free with osal_spin_lock_destroy, other wise will lead to memory leak; 44 * 45 * @return OSAL_SUCCESS/OSAL_FAILURE 46 * 47 * @par Support System: 48 * linux liteos. 49 */ 50 int osal_spin_lock_init(osal_spinlock *lock); 51 52 /** 53 * @ingroup osal_spinlock 54 * @brief Lock the spinlock. 55 * 56 * @par Description: 57 * This API is used to lock the spinlock. If the spinlock has been obtained by another thread, 58 * the thread will wait cyclically until it can lock the spinlock successfully. 59 * 60 * @attention 61 * The spinlock must be initialized before it is used. It should be initialized by osal_spin_lock_init. 62 * A spinlock can not be locked for multiple times in a task. Otherwise, a deadlock occurs. 63 * If the spinlock will be used in both task and interrupt, using osal_spin_lock_irqsave instead of this API. 64 * 65 * @param lock [in] The lock to be acquired, Initialized by osal_spin_lock_init. 66 * 67 * @par Support System: 68 * linux liteos. 69 */ 70 void osal_spin_lock(osal_spinlock *lock); 71 72 /** 73 * @ingroup osal_spinlock 74 * @brief Disable soft interrupts and lock the spin lock. 75 * 76 * @par Description: 77 * Disable soft interrupts and lock the spin lock on linux. Same as osal_spin_lock, but it disables soft interrupts. 78 * Disables scheduling on LiteOS and Freertos. 79 * 80 * @param lock [in] The lock to be acquired, Initialized by osal_spin_lock_init. 81 * 82 * @par Support System: 83 * linux liteos freertos. 84 */ 85 void osal_spin_lock_bh(osal_spinlock *lock); 86 87 /** 88 * @ingroup osal_spinlock 89 * @brief Try to acquire the spin_lock. 90 * 91 * @par Description: 92 * try to acquire the spin_lock. 93 * 94 * @param lock [in] the lock to be acquired. 95 * 96 * @return Returns true if the lock can be obtained immediately, otherwise returns false immediately. 97 * 98 * @par Support System: 99 * linux liteos. 100 */ 101 int osal_spin_trylock(osal_spinlock *lock); 102 103 /** 104 * @ingroup osal_spinlock 105 * @brief Try to acquire the spin_lock. 106 * 107 * @par Description: 108 * Try to acquire the spin_lock and disables the CPU interrupt. 109 * 110 * @param lock [in] the lock to be acquired. 111 * 112 * @return Returns true if the lock can be obtained immediately, otherwise returns false immediately. 113 * 114 * @par Support System: 115 * linux. 116 */ 117 int osal_spin_trylock_irq(osal_spinlock *lock); 118 119 /** 120 * @ingroup osal_spinlock 121 * @brief Try to acquire the spin_lock. 122 * 123 * @par Description: 124 * Saves the current IRQ status of the CPU, try to acquire the spin_lock, and disables the interrupts of the CPU. 125 * 126 * @param lock [in] the lock to be acquired. 127 * @param flags [in] the lock status to be acquired. 128 * 129 * @par Support System: 130 * linux. 131 */ 132 void osal_spin_trylock_irqsave(osal_spinlock *lock, unsigned long *flags); 133 134 /** 135 * @ingroup osal_spinlock 136 * @brief release the spin_lock. 137 * 138 * @par Description: 139 * release the spin_lock. 140 * 141 * @param lock [in] the lock to be released. 142 * 143 * @par Support System: 144 * linux liteos. 145 */ 146 void osal_spin_unlock(osal_spinlock *lock); 147 148 /** 149 * @ingroup osal_spinlock 150 * @brief release the spin_lock. 151 * 152 * @par Description: 153 * Release the spin_lock and enables the interrupts of the CPU on linux. 154 * Resume scheduling on LiteOS and Freertos. 155 * 156 * @par Support System: 157 * linux liteos freertos. 158 */ 159 void osal_spin_unlock_bh(osal_spinlock *lock); 160 161 /** 162 * @ingroup osal_spinlock 163 * @brief acquire the spin_lock. 164 * 165 * @par Description: 166 * Saves the current IRQ status of the CPU, obtains the specified spin_lock, and disables the interrupts of the CPU. 167 * 168 * @param lock [in] the lock to be acquired. 169 * @param flags [in] the lock status to be acquired. 170 * 171 * @par Support System: 172 * linux liteos freertos. 173 */ 174 void osal_spin_lock_irqsave(osal_spinlock *lock, unsigned long *flags); 175 176 /** 177 * @ingroup osal_spinlock 178 * @brief release the spin_lock. 179 * 180 * @par Description: 181 * Releases the specified spin_lock and restores the interrupt status of the CPU, and enables the interrupts of the CPU. 182 * 183 * @param lock [in] the lock to be released. 184 * @param flags [in] the lock status to be released. 185 * 186 * @par Support System: 187 * linux liteos freertos. 188 */ 189 void osal_spin_unlock_irqrestore(osal_spinlock *lock, unsigned long *flags); 190 191 /** 192 * @ingroup osal_spinlock 193 * @brief Destroy the spin_lock. 194 * 195 * @par Description: 196 * Destroy the spin_lock. 197 * 198 * @param lock [in] The lock to be destroyed. 199 * 200 * @attention 201 * must be called when kmod exit, other wise will lead to memory leak; 202 * this API will free memory, lock must be from osal_spin_lock_init returns 203 * 204 * @par Support System: 205 * linux liteos. 206 */ 207 void osal_spin_lock_destroy(osal_spinlock *lock); 208 209 #ifdef __cplusplus 210 #if __cplusplus 211 } 212 #endif 213 #endif 214 #endif /* __OSAL_SPINLOCK_H__ */