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_put PORTABLE C */
38 /* 6.1 */
39 /* AUTHOR */
40 /* */
41 /* William E. Lamie, Microsoft Corporation */
42 /* */
43 /* DESCRIPTION */
44 /* */
45 /* This function puts an instance into the specified counting */
46 /* semaphore. */
47 /* */
48 /* INPUT */
49 /* */
50 /* semaphore_ptr Pointer to semaphore control block*/
51 /* */
52 /* OUTPUT */
53 /* */
54 /* TX_SUCCESS Success completion status */
55 /* */
56 /* CALLS */
57 /* */
58 /* _tx_thread_system_resume Resume thread service */
59 /* _tx_thread_system_ni_resume Non-interruptable resume thread */
60 /* */
61 /* CALLED BY */
62 /* */
63 /* Application Code */
64 /* */
65 /* RELEASE HISTORY */
66 /* */
67 /* DATE NAME DESCRIPTION */
68 /* */
69 /* 05-19-2020 William E. Lamie Initial Version 6.0 */
70 /* 09-30-2020 Yuxin Zhou Modified comment(s), */
71 /* resulting in version 6.1 */
72 /* */
73 /**************************************************************************/
_tx_semaphore_put(TX_SEMAPHORE * semaphore_ptr)74 UINT _tx_semaphore_put(TX_SEMAPHORE *semaphore_ptr)
75 {
76
77 TX_INTERRUPT_SAVE_AREA
78
79 #ifndef TX_DISABLE_NOTIFY_CALLBACKS
80 VOID (*semaphore_put_notify)(struct TX_SEMAPHORE_STRUCT *notify_semaphore_ptr);
81 #endif
82
83 TX_THREAD *thread_ptr;
84 UINT suspended_count;
85 TX_THREAD *next_thread;
86 TX_THREAD *previous_thread;
87
88
89 /* Disable interrupts to put an instance back to the semaphore. */
90 TX_DISABLE
91
92 #ifdef TX_SEMAPHORE_ENABLE_PERFORMANCE_INFO
93
94 /* Increment the total semaphore put counter. */
95 _tx_semaphore_performance_put_count++;
96
97 /* Increment the number of puts on this semaphore. */
98 semaphore_ptr -> tx_semaphore_performance_put_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_PUT, semaphore_ptr, semaphore_ptr -> tx_semaphore_count, semaphore_ptr -> tx_semaphore_suspended_count, TX_POINTER_TO_ULONG_CONVERT(&thread_ptr), TX_TRACE_SEMAPHORE_EVENTS)
103
104 /* Log this kernel call. */
105 TX_EL_SEMAPHORE_PUT_INSERT
106
107 /* Pickup the number of suspended threads. */
108 suspended_count = semaphore_ptr -> tx_semaphore_suspended_count;
109
110 /* Determine if there are any threads suspended on the semaphore. */
111 if (suspended_count == TX_NO_SUSPENSIONS)
112 {
113
114 /* Increment the semaphore count. */
115 semaphore_ptr -> tx_semaphore_count++;
116
117 #ifndef TX_DISABLE_NOTIFY_CALLBACKS
118
119 /* Pickup the application notify function. */
120 semaphore_put_notify = semaphore_ptr -> tx_semaphore_put_notify;
121 #endif
122
123 /* Restore interrupts. */
124 TX_RESTORE
125
126 #ifndef TX_DISABLE_NOTIFY_CALLBACKS
127
128 /* Determine if notification is required. */
129 if (semaphore_put_notify != TX_NULL)
130 {
131
132 /* Yes, call the appropriate notify callback function. */
133 (semaphore_put_notify)(semaphore_ptr);
134 }
135 #endif
136 }
137 else
138 {
139
140 /* A thread is suspended on this semaphore. */
141
142 /* Pickup the pointer to the first suspended thread. */
143 thread_ptr = semaphore_ptr -> tx_semaphore_suspension_list;
144
145 /* Remove the suspended thread from the list. */
146
147 /* See if this is the only suspended thread on the list. */
148 suspended_count--;
149 if (suspended_count == TX_NO_SUSPENSIONS)
150 {
151
152 /* Yes, the only suspended thread. */
153
154 /* Update the head pointer. */
155 semaphore_ptr -> tx_semaphore_suspension_list = TX_NULL;
156 }
157 else
158 {
159
160 /* At least one more thread is on the same expiration list. */
161
162 /* Update the list head pointer. */
163 next_thread = thread_ptr -> tx_thread_suspended_next;
164 semaphore_ptr -> tx_semaphore_suspension_list = next_thread;
165
166 /* Update the links of the adjacent threads. */
167 previous_thread = thread_ptr -> tx_thread_suspended_previous;
168 next_thread -> tx_thread_suspended_previous = previous_thread;
169 previous_thread -> tx_thread_suspended_next = next_thread;
170 }
171
172 /* Decrement the suspension count. */
173 semaphore_ptr -> tx_semaphore_suspended_count = suspended_count;
174
175 /* Prepare for resumption of the first thread. */
176
177 /* Clear cleanup routine to avoid timeout. */
178 thread_ptr -> tx_thread_suspend_cleanup = TX_NULL;
179
180 #ifndef TX_DISABLE_NOTIFY_CALLBACKS
181
182 /* Pickup the application notify function. */
183 semaphore_put_notify = semaphore_ptr -> tx_semaphore_put_notify;
184 #endif
185
186 /* Put return status into the thread control block. */
187 thread_ptr -> tx_thread_suspend_status = TX_SUCCESS;
188
189 #ifdef TX_NOT_INTERRUPTABLE
190
191 /* Resume the thread! */
192 _tx_thread_system_ni_resume(thread_ptr);
193
194 /* Restore interrupts. */
195 TX_RESTORE
196 #else
197
198 /* Temporarily disable preemption. */
199 _tx_thread_preempt_disable++;
200
201 /* Restore interrupts. */
202 TX_RESTORE
203
204 /* Resume thread. */
205 _tx_thread_system_resume(thread_ptr);
206 #endif
207
208 #ifndef TX_DISABLE_NOTIFY_CALLBACKS
209
210 /* Determine if notification is required. */
211 if (semaphore_put_notify != TX_NULL)
212 {
213
214 /* Yes, call the appropriate notify callback function. */
215 (semaphore_put_notify)(semaphore_ptr);
216 }
217 #endif
218 }
219
220 /* Return successful completion. */
221 return(TX_SUCCESS);
222 }
223
224
