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