1 /*
2 * Copyright (c) 2006-2023, RT-Thread Development Team
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 *
6 * Change Logs:
7 * Date Author Notes
8 * 2012-09-30 Bernard first version.
9 * 2021-08-18 chenyingchun add comments
10 * 2023-09-15 xqyjlj perf rt_hw_interrupt_disable/enable
11 * 2024-01-25 Shell reduce resource usage in completion for better synchronization
12 * and smaller footprint.
13 */
14
15 #define DBG_TAG "drivers.ipc"
16 #define DBG_LVL DBG_INFO
17 #include <rtdbg.h>
18
19 #include <rthw.h>
20 #include <rtdevice.h>
21
22 /**
23 * This is an implementation of completion core on UP system.
24 * Noted that spinlock is (preempt_lock + irq_mask) on UP scheduler.
25 */
26
27 #define RT_COMPLETED 1
28 #define RT_UNCOMPLETED 0
29 #define RT_COMPLETION_FLAG(comp) ((comp)->susp_thread_n_flag & 1)
30 #define RT_COMPLETION_THREAD(comp) ((rt_thread_t)((comp)->susp_thread_n_flag & ~1))
31 #define RT_COMPLETION_NEW_STAT(thread, flag) (((flag) & 1) | (((rt_base_t)thread) & ~1))
32
33 static struct rt_spinlock _completion_lock = RT_SPINLOCK_INIT;
34
35 /**
36 * @brief This function will initialize a completion object.
37 *
38 * @param completion is a pointer to a completion object.
39 */
rt_completion_init(struct rt_completion * completion)40 void rt_completion_init(struct rt_completion *completion)
41 {
42 RT_ASSERT(completion != RT_NULL);
43
44 completion->susp_thread_n_flag = RT_COMPLETION_NEW_STAT(RT_NULL, RT_UNCOMPLETED);
45 }
46 RTM_EXPORT(rt_completion_init);
47
48 /**
49 * @brief This function will wait for a completion, if the completion is unavailable, the thread shall wait for
50 * the completion up to a specified time.
51 *
52 * @param completion is a pointer to a completion object.
53 *
54 * @param timeout is a timeout period (unit: OS ticks). If the completion is unavailable, the thread will wait for
55 * the completion done up to the amount of time specified by the argument.
56 * NOTE: Generally, we use the macro RT_WAITING_FOREVER to set this parameter, which means that when the
57 * completion is unavailable, the thread will be waitting forever.
58 * @param suspend_flag suspend flags. See rt_thread_suspend_with_flag()
59 *
60 * @return Return the operation status. ONLY when the return value is RT_EOK, the operation is successful.
61 * If the return value is any other values, it means that the completion wait failed.
62 *
63 * @warning This function can ONLY be called in the thread context. It MUST NOT be called in interrupt context.
64 */
rt_completion_wait_flags(struct rt_completion * completion,rt_int32_t timeout,int suspend_flag)65 rt_err_t rt_completion_wait_flags(struct rt_completion *completion,
66 rt_int32_t timeout, int suspend_flag)
67 {
68 rt_err_t result;
69 rt_base_t level;
70 rt_thread_t thread;
71 RT_ASSERT(completion != RT_NULL);
72
73 /* current context checking */
74 RT_DEBUG_SCHEDULER_AVAILABLE(timeout != 0);
75
76 result = RT_EOK;
77 thread = rt_thread_self();
78
79 level = rt_spin_lock_irqsave(&_completion_lock);
80
81 __try_again:
82 if (RT_COMPLETION_FLAG(completion) != RT_COMPLETED)
83 {
84 /* only one thread can suspend on complete */
85 RT_ASSERT(RT_COMPLETION_THREAD(completion) == RT_NULL);
86
87 if (timeout == 0)
88 {
89 result = -RT_ETIMEOUT;
90 goto __exit;
91 }
92 else
93 {
94 /* reset thread error number */
95 thread->error = RT_EOK;
96
97 /* suspend thread */
98 result = rt_thread_suspend_with_flag(thread, suspend_flag);
99 if (result == RT_EOK)
100 {
101 /* add to suspended thread */
102 rt_base_t waiting_stat = RT_COMPLETION_NEW_STAT(thread, RT_UNCOMPLETED);
103 completion->susp_thread_n_flag = waiting_stat;
104
105 /* current context checking */
106 RT_DEBUG_NOT_IN_INTERRUPT;
107
108 /* start timer */
109 if (timeout > 0)
110 {
111 /* reset the timeout of thread timer and start it */
112 rt_timer_control(&(thread->thread_timer),
113 RT_TIMER_CTRL_SET_TIME,
114 &timeout);
115 rt_timer_start(&(thread->thread_timer));
116 }
117 /* enable interrupt */
118 rt_spin_unlock_irqrestore(&_completion_lock, level);
119
120 /* do schedule */
121 rt_schedule();
122
123 level = rt_spin_lock_irqsave(&_completion_lock);
124
125 if (completion->susp_thread_n_flag != waiting_stat)
126 {
127 /* completion may be completed after we suspend */
128 timeout = 0;
129 goto __try_again;
130 }
131 else
132 {
133 /* no changes, waiting failed */
134 result = thread->error;
135 result = result > 0 ? -result : result;
136 RT_ASSERT(result != RT_EOK);
137 }
138 }
139 }
140 }
141
142 /* clean completed flag & remove susp_thread on the case of waking by timeout */
143 completion->susp_thread_n_flag = RT_COMPLETION_NEW_STAT(RT_NULL, RT_UNCOMPLETED);
144
145 __exit:
146 rt_spin_unlock_irqrestore(&_completion_lock, level);
147
148 return result;
149 }
150
151 /**
152 * @brief This is same as rt_completion_wait_flags(), except that this API is NOT
153 * ISR-safe (you can NOT call completion_done() on isr routine).
154 *
155 * @param completion is a pointer to a completion object.
156 * @param timeout is a timeout period (unit: OS ticks). If the completion is unavailable, the thread will wait for
157 * the completion done up to the amount of time specified by the argument.
158 * NOTE: Generally, we use the macro RT_WAITING_FOREVER to set this parameter, which means that when the
159 * completion is unavailable, the thread will be waitting forever.
160 * @param suspend_flag suspend flags. See rt_thread_suspend_with_flag()
161 *
162 * @return Return the operation status. ONLY when the return value is RT_EOK, the operation is successful.
163 * If the return value is any other values, it means that the completion wait failed.
164 *
165 * @warning This function can ONLY be called in the thread context. It MUST NOT be called in interrupt context.
166 */
rt_completion_wait_flags_noisr(struct rt_completion * completion,rt_int32_t timeout,int suspend_flag)167 rt_err_t rt_completion_wait_flags_noisr(struct rt_completion *completion,
168 rt_int32_t timeout, int suspend_flag)
169 {
170 return rt_completion_wait_flags(completion, timeout, suspend_flag);
171 }
172
173 /**
174 * @brief This function indicates a completion has done and wakeup the thread
175 * and update its errno. No update is applied if it's a negative value.
176 *
177 * @param completion is a pointer to a completion object.
178 * @param thread_errno is the errno set to waking thread.
179 * @return RT_EOK if wakeup succeed.
180 * RT_EEMPTY if wakeup failure and the completion is set to completed.
181 * RT_EBUSY if the completion is still in completed state
182 */
rt_completion_wakeup_by_errno(struct rt_completion * completion,rt_err_t thread_errno)183 rt_err_t rt_completion_wakeup_by_errno(struct rt_completion *completion,
184 rt_err_t thread_errno)
185 {
186 rt_base_t level;
187 rt_err_t error;
188 rt_thread_t suspend_thread;
189 RT_ASSERT(completion != RT_NULL);
190
191 level = rt_spin_lock_irqsave(&_completion_lock);
192 if (RT_COMPLETION_FLAG(completion) == RT_COMPLETED)
193 {
194 rt_spin_unlock_irqrestore(&_completion_lock, level);
195 return -RT_EBUSY;
196 }
197
198 suspend_thread = RT_COMPLETION_THREAD(completion);
199 if (suspend_thread)
200 {
201 /* there is one thread in suspended list */
202
203 if (thread_errno >= 0)
204 {
205 suspend_thread->error = thread_errno;
206 }
207
208 error = rt_thread_resume(suspend_thread);
209 if (error)
210 {
211 LOG_D("%s: failed to resume thread with %d", __func__, error);
212 error = -RT_EEMPTY;
213 }
214 }
215 else
216 {
217 /* no thread waiting */
218 error = -RT_EEMPTY;
219 }
220
221 completion->susp_thread_n_flag = RT_COMPLETION_NEW_STAT(RT_NULL, RT_COMPLETED);
222
223 rt_spin_unlock_irqrestore(&_completion_lock, level);
224
225 return error;
226 }
227