1 /***************************************************************************
2 * Copyright (c) 2024 Microsoft Corporation
3 *
4 * This program and the accompanying materials are made available under the
5 * terms of the MIT License which is available at
6 * https://opensource.org/licenses/MIT.
7 *
8 * SPDX-License-Identifier: MIT
9 **************************************************************************/
10
11
12 /**************************************************************************/
13 /**************************************************************************/
14 /** */
15 /** ThreadX Component */
16 /** */
17 /** Semaphore */
18 /** */
19 /**************************************************************************/
20 /**************************************************************************/
21
22 #define TX_SOURCE_CODE
23
24
25 /* Include necessary system files. */
26
27 #include "tx_api.h"
28 #include "tx_trace.h"
29 #include "tx_thread.h"
30 #include "tx_semaphore.h"
31
32
33 /**************************************************************************/
34 /* */
35 /* FUNCTION RELEASE */
36 /* */
37 /* _tx_semaphore_get PORTABLE C */
38 /* 6.1 */
39 /* AUTHOR */
40 /* */
41 /* William E. Lamie, Microsoft Corporation */
42 /* */
43 /* DESCRIPTION */
44 /* */
45 /* This function gets an instance from the specified counting */
46 /* semaphore. */
47 /* */
48 /* INPUT */
49 /* */
50 /* semaphore_ptr Pointer to semaphore control block*/
51 /* wait_option Suspension option */
52 /* */
53 /* OUTPUT */
54 /* */
55 /* status Completion status */
56 /* */
57 /* CALLS */
58 /* */
59 /* _tx_thread_system_suspend Suspend thread service */
60 /* _tx_thread_system_ni_suspend Non-interruptable suspend thread */
61 /* */
62 /* CALLED BY */
63 /* */
64 /* Application Code */
65 /* */
66 /* RELEASE HISTORY */
67 /* */
68 /* DATE NAME DESCRIPTION */
69 /* */
70 /* 05-19-2020 William E. Lamie Initial Version 6.0 */
71 /* 09-30-2020 Yuxin Zhou Modified comment(s), */
72 /* resulting in version 6.1 */
73 /* */
74 /**************************************************************************/
_tx_semaphore_get(TX_SEMAPHORE * semaphore_ptr,ULONG wait_option)75 UINT _tx_semaphore_get(TX_SEMAPHORE *semaphore_ptr, ULONG wait_option)
76 {
77
78 TX_INTERRUPT_SAVE_AREA
79
80 TX_THREAD *thread_ptr;
81 TX_THREAD *next_thread;
82 TX_THREAD *previous_thread;
83 UINT status;
84
85
86 /* Default the status to TX_SUCCESS. */
87 status = TX_SUCCESS;
88
89 /* Disable interrupts to get an instance from the semaphore. */
90 TX_DISABLE
91
92 #ifdef TX_SEMAPHORE_ENABLE_PERFORMANCE_INFO
93
94 /* Increment the total semaphore get counter. */
95 _tx_semaphore_performance_get_count++;
96
97 /* Increment the number of attempts to get this semaphore. */
98 semaphore_ptr -> tx_semaphore_performance_get_count++;
99 #endif
100
101 /* If trace is enabled, insert this event into the trace buffer. */
102 TX_TRACE_IN_LINE_INSERT(TX_TRACE_SEMAPHORE_GET, semaphore_ptr, wait_option, semaphore_ptr -> tx_semaphore_count, TX_POINTER_TO_ULONG_CONVERT(&thread_ptr), TX_TRACE_SEMAPHORE_EVENTS)
103
104 /* Log this kernel call. */
105 TX_EL_SEMAPHORE_GET_INSERT
106
107 /* Determine if there is an instance of the semaphore. */
108 if (semaphore_ptr -> tx_semaphore_count != ((ULONG) 0))
109 {
110
111 /* Decrement the semaphore count. */
112 semaphore_ptr -> tx_semaphore_count--;
113
114 /* Restore interrupts. */
115 TX_RESTORE
116 }
117
118 /* Determine if the request specifies suspension. */
119 else if (wait_option != TX_NO_WAIT)
120 {
121
122 /* Determine if the preempt disable flag is non-zero. */
123 if (_tx_thread_preempt_disable != ((UINT) 0))
124 {
125
126 /* Restore interrupts. */
127 TX_RESTORE
128
129 /* Suspension is not allowed if the preempt disable flag is non-zero at this point - return error completion. */
130 status = TX_NO_INSTANCE;
131 }
132 else
133 {
134
135 /* Prepare for suspension of this thread. */
136
137 #ifdef TX_SEMAPHORE_ENABLE_PERFORMANCE_INFO
138
139 /* Increment the total semaphore suspensions counter. */
140 _tx_semaphore_performance_suspension_count++;
141
142 /* Increment the number of suspensions on this semaphore. */
143 semaphore_ptr -> tx_semaphore_performance_suspension_count++;
144 #endif
145
146 /* Pickup thread pointer. */
147 TX_THREAD_GET_CURRENT(thread_ptr)
148
149 /* Setup cleanup routine pointer. */
150 thread_ptr -> tx_thread_suspend_cleanup = &(_tx_semaphore_cleanup);
151
152 /* Setup cleanup information, i.e. this semaphore control
153 block. */
154 thread_ptr -> tx_thread_suspend_control_block = (VOID *) semaphore_ptr;
155
156 #ifndef TX_NOT_INTERRUPTABLE
157
158 /* Increment the suspension sequence number, which is used to identify
159 this suspension event. */
160 thread_ptr -> tx_thread_suspension_sequence++;
161 #endif
162
163 /* Setup suspension list. */
164 if (semaphore_ptr -> tx_semaphore_suspended_count == TX_NO_SUSPENSIONS)
165 {
166
167 /* No other threads are suspended. Setup the head pointer and
168 just setup this threads pointers to itself. */
169 semaphore_ptr -> tx_semaphore_suspension_list = thread_ptr;
170 thread_ptr -> tx_thread_suspended_next = thread_ptr;
171 thread_ptr -> tx_thread_suspended_previous = thread_ptr;
172 }
173 else
174 {
175
176 /* This list is not NULL, add current thread to the end. */
177 next_thread = semaphore_ptr -> tx_semaphore_suspension_list;
178 thread_ptr -> tx_thread_suspended_next = next_thread;
179 previous_thread = next_thread -> tx_thread_suspended_previous;
180 thread_ptr -> tx_thread_suspended_previous = previous_thread;
181 previous_thread -> tx_thread_suspended_next = thread_ptr;
182 next_thread -> tx_thread_suspended_previous = thread_ptr;
183 }
184
185 /* Increment the number of suspensions. */
186 semaphore_ptr -> tx_semaphore_suspended_count++;
187
188 /* Set the state to suspended. */
189 thread_ptr -> tx_thread_state = TX_SEMAPHORE_SUSP;
190
191 #ifdef TX_NOT_INTERRUPTABLE
192
193 /* Call actual non-interruptable thread suspension routine. */
194 _tx_thread_system_ni_suspend(thread_ptr, wait_option);
195
196 /* Restore interrupts. */
197 TX_RESTORE
198 #else
199
200 /* Set the suspending flag. */
201 thread_ptr -> tx_thread_suspending = TX_TRUE;
202
203 /* Setup the timeout period. */
204 thread_ptr -> tx_thread_timer.tx_timer_internal_remaining_ticks = wait_option;
205
206 /* Temporarily disable preemption. */
207 _tx_thread_preempt_disable++;
208
209 /* Restore interrupts. */
210 TX_RESTORE
211
212 /* Call actual thread suspension routine. */
213 _tx_thread_system_suspend(thread_ptr);
214 #endif
215
216 /* Return the completion status. */
217 status = thread_ptr -> tx_thread_suspend_status;
218 }
219 }
220 else
221 {
222
223 /* Restore interrupts. */
224 TX_RESTORE
225
226 /* Immediate return, return error completion. */
227 status = TX_NO_INSTANCE;
228 }
229
230 /* Return completion status. */
231 return(status);
232 }
233
234