1 /*
2 * Copyright (C) 2017 XRADIO TECHNOLOGY CO., LTD. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 * 1. Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * 2. Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the
12 * distribution.
13 * 3. Neither the name of XRADIO TECHNOLOGY CO., LTD. nor the names of
14 * its contributors may be used to endorse or promote products derived
15 * from this software without specific prior written permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
20 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
21 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
22 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
23 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
27 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28 */
29
30 #ifndef _KERNEL_OS_RTTHREAD_OS_MUTEX_H_
31 #define _KERNEL_OS_RTTHREAD_OS_MUTEX_H_
32
33 #include "../os_common.h"
34 #include "../os_thread.h"
35
36 #ifdef __cplusplus
37 extern "C" {
38 #endif
39
40 /**
41 * @brief Mutex object definition
42 */
43 typedef struct OS_Mutex {
44 rt_mutex_t handle;
45 } OS_Mutex_t;
46
47 OS_Status OS_MutexCreate(OS_Mutex_t *mutex);
48 OS_Status OS_MutexDelete(OS_Mutex_t *mutex);
49 OS_Status OS_MutexLock(OS_Mutex_t *mutex, OS_Time_t waitMS);
50 OS_Status OS_MutexUnlock(OS_Mutex_t *mutex);
51
52 /**
53 * @brief Create and initialize a recursive mutex object
54 * @note A recursive mutex can be locked repeatedly by one single thread.
55 * The mutex doesn't become available again until the owner has called
56 * OS_RecursiveMutexUnlock() for each successful OS_RecursiveMutexLock().
57 * @param[in] mutex Pointer to the recursive mutex object
58 * @retval OS_Status, OS_OK on success
59 */
OS_RecursiveMutexCreate(OS_Mutex_t * mutex)60 static inline OS_Status OS_RecursiveMutexCreate(OS_Mutex_t *mutex)
61 {
62 return OS_MutexCreate(mutex);
63 }
64
65 /**
66 * @brief Delete the recursive mutex object
67 * @param[in] mutex Pointer to the recursive mutex object
68 * @retval OS_Status, OS_OK on success
69 */
OS_RecursiveMutexDelete(OS_Mutex_t * mutex)70 static inline OS_Status OS_RecursiveMutexDelete(OS_Mutex_t *mutex)
71 {
72 return OS_MutexDelete(mutex);
73 }
74
75 /**
76 * @brief Lock the recursive mutex object
77 * @note A recursive mutex can be locked repeatedly by one single thread.
78 * If the recursive mutex is already locked by other thread, the caller
79 * will be blocked for the specified time duration.
80 * @param[in] mutex Pointer to the recursive mutex object
81 * @param[in] waitMS The maximum amount of time (in millisecond) the thread
82 * should remain in the blocked state to wait for the
83 * recursive mutex to become unlocked.
84 * OS_WAIT_FOREVER for waiting forever, zero for no waiting.
85 * @retval OS_Status, OS_OK on success
86 */
OS_RecursiveMutexLock(OS_Mutex_t * mutex,OS_Time_t waitMS)87 static inline OS_Status OS_RecursiveMutexLock(OS_Mutex_t *mutex, OS_Time_t waitMS)
88 {
89 return OS_MutexLock(mutex, waitMS);
90 }
91
92 /**
93 * @brief Unlock the recursive mutex object previously locked using
94 * OS_RecursiveMutexLock()
95 * @note The recursive mutex should be unlocked from the same thread context
96 * from which it was locked.
97 * @param[in] mutex Pointer to the mutex object
98 * @retval OS_Status, OS_OK on success
99 */
OS_RecursiveMutexUnlock(OS_Mutex_t * mutex)100 static inline OS_Status OS_RecursiveMutexUnlock(OS_Mutex_t *mutex)
101 {
102 return OS_MutexUnlock(mutex);
103 }
104
105 /**
106 * @brief Check whether the mutex object is valid or not
107 * @param[in] mutex Pointer to the mutex object
108 * @return 1 on valid, 0 on invalid
109 */
OS_MutexIsValid(OS_Mutex_t * mutex)110 static inline int OS_MutexIsValid(OS_Mutex_t *mutex)
111 {
112 return (mutex->handle != OS_INVALID_HANDLE);
113 }
114
115 /**
116 * @brief Set the mutex object to invalid state
117 * @param[in] mutex Pointer to the mutex object
118 * @return None
119 */
OS_MutexSetInvalid(OS_Mutex_t * mutex)120 static inline void OS_MutexSetInvalid(OS_Mutex_t *mutex)
121 {
122 mutex->handle = OS_INVALID_HANDLE;
123 }
124
125 /**
126 * @brief Get the mutex object's owner
127 * @note A mutex object's owner is a thread that locks the mutex
128 * @param[in] mutex Pointer to the mutex object
129 * @return The handle of the thread that locks the mutex object.
130 * NULL when the mutex is not locked by any thread.
131 */
OS_MutexGetOwner(OS_Mutex_t * mutex)132 static inline OS_ThreadHandle_t OS_MutexGetOwner(OS_Mutex_t *mutex)
133 {
134 return (OS_ThreadHandle_t)(mutex->handle->owner);
135 }
136
137 #ifdef __cplusplus
138 }
139 #endif
140
141 #endif /* _KERNEL_OS_RTTHREAD_OS_MUTEX_H_ */
142