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_mutex.h 25 * 26 * @brief Declares mutex types and interfaces. 27 * 28 * This file provides interfaces for initializing and destroying a mutex, locking a mutex, 29 * locking a mutex upon timeout, and unlocking a mutex. The mutex must be destroyed after being used. 30 * 31 * @since 1.0 32 * @version 1.0 33 */ 34 #ifndef OSAL_MUTEX_H 35 #define OSAL_MUTEX_H 36 37 #include "hdf_base.h" 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif /* __cplusplus */ 42 43 /** 44 * @brief Describes a mutex. 45 */ 46 struct OsalMutex { 47 void *realMutex; /**< Pointer to a mutex object to operate */ 48 }; 49 50 /** 51 * @brief Defines a mutex. 52 */ 53 #define OSAL_DECLARE_MUTEX(mutex) struct OsalMutex mutex 54 55 /** 56 * @brief Initializes a mutex. 57 * 58 * @param mutex Indicates the pointer to the mutex {@link OsalMutex}. 59 * 60 * @return Returns a value listed below: \n 61 * HDF_STATUS | Description 62 * ----------------------| ----------------------- 63 * HDF_SUCCESS | The operation is successful. 64 * HDF_FAILURE | Failed to invoke the system function to initialize the mutex. 65 * HDF_ERR_INVALID_PARAM | Invalid parameter. 66 * 67 * @since 1.0 68 * @version 1.0 69 */ 70 int32_t OsalMutexInit(struct OsalMutex *mutex); 71 72 /** 73 * @brief Destroys a mutex. 74 * 75 * @param mutex Indicates the pointer to the mutex {@link OsalMutex}. 76 * 77 * @return Returns a value listed below: \n 78 * HDF_STATUS | Description 79 * ----------------------| ----------------------- 80 * HDF_SUCCESS | The operation is successful. 81 * HDF_FAILURE | Failed to invoke the system function to destroy the mutex. 82 * HDF_ERR_INVALID_PARAM | Invalid parameter. 83 * 84 * @since 1.0 85 * @version 1.0 86 */ 87 int32_t OsalMutexDestroy(struct OsalMutex *mutex); 88 89 /** 90 * @brief Locks a mutex. 91 * 92 * @param mutex Indicates the pointer to the mutex {@link OsalMutex}. 93 * 94 * @return Returns a value listed below: \n 95 * HDF_STATUS | Description 96 * ----------------------| ----------------------- 97 * HDF_SUCCESS | The operation is successful. 98 * HDF_FAILURE | Failed to invoke the system function to lock the mutex. 99 * HDF_ERR_INVALID_PARAM | Invalid parameter. 100 * 101 * @since 1.0 102 * @version 1.0 103 */ 104 int32_t OsalMutexLock(struct OsalMutex *mutex); 105 106 /** 107 * @brief Locks a mutex with a specified timeout duration. 108 * 109 * @param mutex Indicates the pointer to the mutex {@link OsalMutex}. 110 * @param ms Indicates the timeout duration, in milliseconds. 111 * 112 * @return Returns a value listed below: \n 113 * HDF_STATUS | Description 114 * ----------------------| ----------------------- 115 * HDF_SUCCESS | The operation is successful. 116 * HDF_FAILURE | Failed to invoke the system function to lock the mutex. 117 * HDF_ERR_INVALID_PARAM | Invalid parameter. 118 * HDF_ERR_TIMEOUT | Timeout occurs. 119 * 120 * @since 1.0 121 * @version 1.0 122 */ 123 int32_t OsalMutexTimedLock(struct OsalMutex *mutex, uint32_t ms); 124 125 /** 126 * @brief Unlocks a mutex. 127 * 128 * @param mutex Indicates the pointer to the mutex {@link OsalMutex}. 129 * 130 * @return Returns a value listed below: \n 131 * HDF_STATUS | Description 132 * ----------------------| ----------------------- 133 * HDF_SUCCESS | The operation is successful. 134 * HDF_FAILURE | Failed to invoke the system function to unlock the mutex. 135 * HDF_ERR_INVALID_PARAM | Invalid parameter. 136 * 137 * @since 1.0 138 * @version 1.0 139 */ 140 int32_t OsalMutexUnlock(struct OsalMutex *mutex); 141 142 #ifdef __cplusplus 143 } 144 #endif /* __cplusplus */ 145 146 #endif /* OSAL_MUTEX_H */ 147 /** @} */ 148