1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup OSAL 11 * @{ 12 * 13 * @brief Defines the structures and interfaces for the Operating System Abstraction Layer (OSAL) module. 14 * 15 * The OSAL module OpenHarmony OS interface differences and provides unified OS interfaces externally, 16 * including the memory management, thread, mutex, spinlock, semaphore, timer, file, interrupt, time, 17 * atomic, firmware, and I/O operation modules. 18 * 19 * @since 1.0 20 * @version 1.0 21 */ 22 23 /** 24 * @file osal_spinlock.h 25 * 26 * @brief Declares spinlock types and interfaces. 27 * 28 * This file provides the interfaces for initializing, destroying, obtaining, and releasing a spinlock, 29 * the interfaces for obtaining a spinlock and disabling the interrupt request (IRQ), releasing a spinlock 30 * and enabling the IRQ, obtaining a spinlock, disabling the IRQ, and saving its status, and releasing a spinlock, 31 * enabling the IRQ, and restoring the saved IRQ status. The spinlock needs to be destroyed when it is no longer used. 32 * 33 * @since 1.0 34 * @version 1.0 35 */ 36 #ifndef OSAL_SPINLOCK_H 37 #define OSAL_SPINLOCK_H 38 39 #include "hdf_base.h" 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif /* __cplusplus */ 44 45 /** 46 * @brief Describes a spinlock. 47 */ 48 typedef struct { 49 void *realSpinlock; /**< Pointer to a spinlock */ 50 } OsalSpinlock; 51 52 /** 53 * @brief Defines a spinlock. 54 */ 55 #define OSAL_DECLARE_SPINLOCK(spinlock) OsalSpinlock spinlock 56 57 /** 58 * @brief Initializes a spinlock. 59 * 60 * @param spinlock Indicates the pointer to the spinlock {@link OsalSpinlock}. 61 * 62 * @return Returns a value listed below: \n 63 * HDF_STATUS | Description 64 * ----------------------| ----------------------- 65 * HDF_SUCCESS | The operation is successful. 66 * HDF_FAILURE | Failed to invoke the system function to initialize the spinlock. 67 * HDF_ERR_INVALID_PARAM | Invalid parameter. 68 * HDF_ERR_MALLOC_FAIL | Memory allocation fails. 69 * 70 * @since 1.0 71 * @version 1.0 72 */ 73 int32_t OsalSpinInit(OsalSpinlock *spinlock); 74 75 /** 76 * @brief Destroys a spinlock. 77 * 78 * @param spinlock Indicates the pointer to the spinlock {@link OsalSpinlock}. 79 * 80 * @return Returns a value listed below: \n 81 * HDF_STATUS | Description 82 * ----------------------| ----------------------- 83 * HDF_SUCCESS | The operation is successful. 84 * HDF_FAILURE | Failed to invoke the system function to destroy the spinlock. 85 * HDF_ERR_INVALID_PARAM | Invalid parameter. 86 * 87 * @since 1.0 88 * @version 1.0 89 */ 90 int32_t OsalSpinDestroy(OsalSpinlock *spinlock); 91 92 /** 93 * @brief Obtains a spinlock. 94 * 95 * @param spinlock Indicates the pointer to the spinlock {@link OsalSpinlock}. 96 * 97 * @return Returns a value listed below: \n 98 * HDF_STATUS | Description 99 * ----------------------| ----------------------- 100 * HDF_SUCCESS | The operation is successful. 101 * HDF_FAILURE | Failed to invoke the system function to obtain the spinlock. 102 * HDF_ERR_INVALID_PARAM | Invalid parameter. 103 * 104 * @since 1.0 105 * @version 1.0 106 */ 107 int32_t OsalSpinLock(OsalSpinlock *spinlock); 108 109 /** 110 * @brief Releases a spinlock. 111 * 112 * @param spinlock Indicates the pointer to the spinlock {@link OsalSpinlock}. 113 * 114 * @return Returns a value listed below: \n 115 * HDF_STATUS | Description 116 * ----------------------| ----------------------- 117 * HDF_SUCCESS | The operation is successful. 118 * HDF_FAILURE | Failed to invoke the system function to release the spinlock. 119 * HDF_ERR_INVALID_PARAM | Invalid parameter. 120 * 121 * @since 1.0 122 * @version 1.0 123 */ 124 int32_t OsalSpinUnlock(OsalSpinlock *spinlock); 125 126 /** 127 * @brief Obtains a spinlock and disables the IRQ. 128 * 129 * @param spinlock Indicates the pointer to the spinlock {@link OsalSpinlock}. 130 * 131 * @return Returns a value listed below: \n 132 * HDF_STATUS | Description 133 * ----------------------| ----------------------- 134 * HDF_SUCCESS | The operation is successful. 135 * HDF_FAILURE | Failed to invoke the system function to obtain the spinlock. 136 * HDF_ERR_INVALID_PARAM | Invalid parameter. 137 * 138 * @since 1.0 139 * @version 1.0 140 */ 141 int32_t OsalSpinLockIrq(OsalSpinlock *spinlock); 142 143 /** 144 * @brief Releases a spinlock and enables the IRQ. 145 * 146 * @param spinlock Indicates the pointer to the spinlock {@link OsalSpinlock}. 147 * 148 * @return Returns a value listed below: \n 149 * HDF_STATUS | Description 150 * ----------------------| ----------------------- 151 * HDF_SUCCESS | The operation is successful. 152 * HDF_FAILURE | Failed to invoke the system function to release the spinlock. 153 * HDF_ERR_INVALID_PARAM | Invalid parameter. 154 * 155 * @since 1.0 156 * @version 1.0 157 */ 158 int32_t OsalSpinUnlockIrq(OsalSpinlock *spinlock); 159 160 /** 161 * @brief Obtains a spinlock, disables the IRQ, and saves its status. 162 * 163 * @param spinlock Indicates the pointer to the spinlock {@link OsalSpinlock}. 164 * @param flags Indicates the pointer to the status of the IRQ register. 165 * 166 * @return Returns a value listed below: \n 167 * HDF_STATUS | Description 168 * ----------------------| ----------------------- 169 * HDF_SUCCESS | The operation is successful. 170 * HDF_FAILURE | Failed to invoke the system function to obtain the spinlock. 171 * HDF_ERR_INVALID_PARAM | Invalid parameter. 172 * 173 * @since 1.0 174 * @version 1.0 175 */ 176 int32_t OsalSpinLockIrqSave(OsalSpinlock *spinlock, uint32_t *flags); 177 178 /** 179 * @brief Releases a spinlock, enables the IRQ, and restores the saved IRQ status. 180 * 181 * @param spinlock Indicates the pointer to the spinlock {@link OsalSpinlock}. 182 * @param flags Indicates the pointer to the value used to restore the IRQ register. 183 * 184 * @return Returns a value listed below: \n 185 * HDF_STATUS | Description 186 * ----------------------| ----------------------- 187 * HDF_SUCCESS | The operation is successful. 188 * HDF_FAILURE | Failed to invoke the system function to release the spinlock. 189 * HDF_ERR_INVALID_PARAM | Invalid parameter. 190 * 191 * @since 1.0 192 * @version 1.0 193 */ 194 int32_t OsalSpinUnlockIrqRestore(OsalSpinlock *spinlock, uint32_t *flags); 195 196 #ifdef __cplusplus 197 } 198 #endif /* __cplusplus */ 199 200 #endif /* OSAL_SPINLOCK_H */ 201 /** @} */ 202