1 /*
2 * Copyright (c) 2016 Wind River Systems, Inc.
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /**
8 * @brief Mailboxes.
9 */
10
11 #include <zephyr/kernel.h>
12 #include <zephyr/kernel_structs.h>
13
14 #include <zephyr/toolchain.h>
15 #include <zephyr/linker/sections.h>
16 #include <string.h>
17 #include <zephyr/sys/dlist.h>
18 #include <zephyr/init.h>
19 /* private kernel APIs */
20 #include <ksched.h>
21 #include <wait_q.h>
22
23 #ifdef CONFIG_OBJ_CORE_MAILBOX
24 static struct k_obj_type obj_type_mailbox;
25 #endif
26
27 #if (CONFIG_NUM_MBOX_ASYNC_MSGS > 0)
28
29 /* asynchronous message descriptor type */
30 struct k_mbox_async {
31 struct _thread_base thread; /* dummy thread object */
32 struct k_mbox_msg tx_msg; /* transmit message descriptor */
33 };
34
35 /* stack of unused asynchronous message descriptors */
36 K_STACK_DEFINE(async_msg_free, CONFIG_NUM_MBOX_ASYNC_MSGS);
37
38 /* allocate an asynchronous message descriptor */
mbox_async_alloc(struct k_mbox_async ** async)39 static inline void mbox_async_alloc(struct k_mbox_async **async)
40 {
41 (void)k_stack_pop(&async_msg_free, (stack_data_t *)async, K_FOREVER);
42 }
43
44 /* free an asynchronous message descriptor */
mbox_async_free(struct k_mbox_async * async)45 static inline void mbox_async_free(struct k_mbox_async *async)
46 {
47 k_stack_push(&async_msg_free, (stack_data_t)async);
48 }
49
50 #endif /* CONFIG_NUM_MBOX_ASYNC_MSGS > 0 */
51
52 #if (CONFIG_NUM_MBOX_ASYNC_MSGS > 0)
53
54 /*
55 * Do run-time initialization of mailbox object subsystem.
56 */
init_mbox_module(void)57 static int init_mbox_module(void)
58 {
59 /* array of asynchronous message descriptors */
60 static struct k_mbox_async __noinit async_msg[CONFIG_NUM_MBOX_ASYNC_MSGS];
61
62 #if (CONFIG_NUM_MBOX_ASYNC_MSGS > 0)
63 /*
64 * Create pool of asynchronous message descriptors.
65 *
66 * A dummy thread requires minimal initialization, since it never gets
67 * to execute. The _THREAD_DUMMY flag is sufficient to distinguish a
68 * dummy thread from a real one. The threads are *not* added to the
69 * kernel's list of known threads.
70 *
71 * Once initialized, the address of each descriptor is added to a stack
72 * that governs access to them.
73 */
74
75 int i;
76
77 for (i = 0; i < CONFIG_NUM_MBOX_ASYNC_MSGS; i++) {
78 z_init_thread_base(&async_msg[i].thread, 0, _THREAD_DUMMY, 0);
79 k_stack_push(&async_msg_free, (stack_data_t)&async_msg[i]);
80 }
81 #endif /* CONFIG_NUM_MBOX_ASYNC_MSGS > 0 */
82
83 /* Complete initialization of statically defined mailboxes. */
84
85 return 0;
86 }
87
88 SYS_INIT(init_mbox_module, PRE_KERNEL_1, CONFIG_KERNEL_INIT_PRIORITY_OBJECTS);
89
90 #endif /* CONFIG_NUM_MBOX_ASYNC_MSGS */
91
k_mbox_init(struct k_mbox * mbox)92 void k_mbox_init(struct k_mbox *mbox)
93 {
94 z_waitq_init(&mbox->tx_msg_queue);
95 z_waitq_init(&mbox->rx_msg_queue);
96 mbox->lock = (struct k_spinlock) {};
97
98 #ifdef CONFIG_OBJ_CORE_MAILBOX
99 k_obj_core_init_and_link(K_OBJ_CORE(mbox), &obj_type_mailbox);
100 #endif
101
102 SYS_PORT_TRACING_OBJ_INIT(k_mbox, mbox);
103 }
104
105 /**
106 * @brief Check compatibility of sender's and receiver's message descriptors.
107 *
108 * Compares sender's and receiver's message descriptors to see if they are
109 * compatible. If so, the descriptor fields are updated to reflect that a
110 * match has occurred.
111 *
112 * @param tx_msg Pointer to transmit message descriptor.
113 * @param rx_msg Pointer to receive message descriptor.
114 *
115 * @return 0 if successfully matched, otherwise -1.
116 */
mbox_message_match(struct k_mbox_msg * tx_msg,struct k_mbox_msg * rx_msg)117 static int mbox_message_match(struct k_mbox_msg *tx_msg,
118 struct k_mbox_msg *rx_msg)
119 {
120 uint32_t temp_info;
121
122 if (((tx_msg->tx_target_thread == (k_tid_t)K_ANY) ||
123 (tx_msg->tx_target_thread == rx_msg->tx_target_thread)) &&
124 ((rx_msg->rx_source_thread == (k_tid_t)K_ANY) ||
125 (rx_msg->rx_source_thread == tx_msg->rx_source_thread))) {
126
127 /* update thread identifier fields for both descriptors */
128 rx_msg->rx_source_thread = tx_msg->rx_source_thread;
129 tx_msg->tx_target_thread = rx_msg->tx_target_thread;
130
131 /* update application info fields for both descriptors */
132 temp_info = rx_msg->info;
133 rx_msg->info = tx_msg->info;
134 tx_msg->info = temp_info;
135
136 /* update data size field for receiver only */
137 if (rx_msg->size > tx_msg->size) {
138 rx_msg->size = tx_msg->size;
139 }
140
141 /* update data location fields for receiver only */
142 rx_msg->tx_data = tx_msg->tx_data;
143
144 /* update syncing thread field for receiver only */
145 rx_msg->_syncing_thread = tx_msg->_syncing_thread;
146
147 return 0;
148 }
149
150 return -1;
151 }
152
153 /**
154 * @brief Dispose of received message.
155 *
156 * Notifies the sender that message processing is complete.
157 *
158 * @param rx_msg Pointer to receive message descriptor.
159 */
mbox_message_dispose(struct k_mbox_msg * rx_msg)160 static void mbox_message_dispose(struct k_mbox_msg *rx_msg)
161 {
162 struct k_thread *sending_thread;
163 struct k_mbox_msg *tx_msg;
164
165 /* do nothing if message was disposed of when it was received */
166 if (rx_msg->_syncing_thread == NULL) {
167 return;
168 }
169
170 /* recover sender info */
171 sending_thread = rx_msg->_syncing_thread;
172 rx_msg->_syncing_thread = NULL;
173 tx_msg = (struct k_mbox_msg *)sending_thread->base.swap_data;
174
175 /* update data size field for sender */
176 tx_msg->size = rx_msg->size;
177
178 #if (CONFIG_NUM_MBOX_ASYNC_MSGS > 0)
179 /*
180 * asynchronous send: free asynchronous message descriptor +
181 * dummy thread pair, then give semaphore (if needed)
182 */
183 if ((sending_thread->base.thread_state & _THREAD_DUMMY) != 0U) {
184 struct k_sem *async_sem = tx_msg->_async_sem;
185
186 mbox_async_free((struct k_mbox_async *)sending_thread);
187 if (async_sem != NULL) {
188 k_sem_give(async_sem);
189 }
190 return;
191 }
192 #endif
193
194 /* synchronous send: wake up sending thread */
195 arch_thread_return_value_set(sending_thread, 0);
196 z_mark_thread_as_not_pending(sending_thread);
197 z_ready_thread(sending_thread);
198 z_reschedule_unlocked();
199 }
200
201 /**
202 * @brief Send a mailbox message.
203 *
204 * Helper routine that handles both synchronous and asynchronous sends.
205 *
206 * @param mbox Pointer to the mailbox object.
207 * @param tx_msg Pointer to transmit message descriptor.
208 * @param timeout Maximum time (milliseconds) to wait for the message to be
209 * received (although not necessarily completely processed).
210 * Use K_NO_WAIT to return immediately, or K_FOREVER to wait as long
211 * as necessary.
212 *
213 * @return 0 if successful, -ENOMSG if failed immediately, -EAGAIN if timed out
214 */
mbox_message_put(struct k_mbox * mbox,struct k_mbox_msg * tx_msg,k_timeout_t timeout)215 static int mbox_message_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
216 k_timeout_t timeout)
217 {
218 struct k_thread *sending_thread;
219 struct k_thread *receiving_thread;
220 struct k_mbox_msg *rx_msg;
221 k_spinlock_key_t key;
222
223 /* save sender id so it can be used during message matching */
224 tx_msg->rx_source_thread = _current;
225
226 /* finish readying sending thread (actual or dummy) for send */
227 sending_thread = tx_msg->_syncing_thread;
228 sending_thread->base.swap_data = tx_msg;
229
230 /* search mailbox's rx queue for a compatible receiver */
231 key = k_spin_lock(&mbox->lock);
232
233 SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_mbox, message_put, mbox, timeout);
234
235 _WAIT_Q_FOR_EACH(&mbox->rx_msg_queue, receiving_thread) {
236 rx_msg = (struct k_mbox_msg *)receiving_thread->base.swap_data;
237
238 if (mbox_message_match(tx_msg, rx_msg) == 0) {
239 /* take receiver out of rx queue */
240 z_unpend_thread(receiving_thread);
241
242 /* ready receiver for execution */
243 arch_thread_return_value_set(receiving_thread, 0);
244 z_ready_thread(receiving_thread);
245
246 #if (CONFIG_NUM_MBOX_ASYNC_MSGS > 0)
247 /*
248 * asynchronous send: swap out current thread
249 * if receiver has priority, otherwise let it continue
250 *
251 * note: dummy sending thread sits (unqueued)
252 * until the receiver consumes the message
253 */
254 if ((sending_thread->base.thread_state & _THREAD_DUMMY)
255 != 0U) {
256 z_reschedule(&mbox->lock, key);
257 return 0;
258 }
259 #endif
260 SYS_PORT_TRACING_OBJ_FUNC_BLOCKING(k_mbox, message_put, mbox, timeout);
261
262 /*
263 * synchronous send: pend current thread (unqueued)
264 * until the receiver consumes the message
265 */
266 int ret = z_pend_curr(&mbox->lock, key, NULL, K_FOREVER);
267
268 SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, message_put, mbox, timeout, ret);
269
270 return ret;
271 }
272 }
273
274 /* didn't find a matching receiver: don't wait for one */
275 if (K_TIMEOUT_EQ(timeout, K_NO_WAIT)) {
276 SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, message_put, mbox, timeout, -ENOMSG);
277
278 k_spin_unlock(&mbox->lock, key);
279 return -ENOMSG;
280 }
281
282 #if (CONFIG_NUM_MBOX_ASYNC_MSGS > 0)
283 /* asynchronous send: dummy thread waits on tx queue for receiver */
284 if ((sending_thread->base.thread_state & _THREAD_DUMMY) != 0U) {
285 z_pend_thread(sending_thread, &mbox->tx_msg_queue, K_FOREVER);
286 k_spin_unlock(&mbox->lock, key);
287 return 0;
288 }
289 #endif
290 SYS_PORT_TRACING_OBJ_FUNC_BLOCKING(k_mbox, message_put, mbox, timeout);
291
292 /* synchronous send: sender waits on tx queue for receiver or timeout */
293 int ret = z_pend_curr(&mbox->lock, key, &mbox->tx_msg_queue, timeout);
294
295 SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, message_put, mbox, timeout, ret);
296
297 return ret;
298 }
299
k_mbox_put(struct k_mbox * mbox,struct k_mbox_msg * tx_msg,k_timeout_t timeout)300 int k_mbox_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
301 k_timeout_t timeout)
302 {
303 /* configure things for a synchronous send, then send the message */
304 tx_msg->_syncing_thread = _current;
305
306 SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_mbox, put, mbox, timeout);
307
308 int ret = mbox_message_put(mbox, tx_msg, timeout);
309
310 SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, put, mbox, timeout, ret);
311
312 return ret;
313 }
314
315 #if (CONFIG_NUM_MBOX_ASYNC_MSGS > 0)
k_mbox_async_put(struct k_mbox * mbox,struct k_mbox_msg * tx_msg,struct k_sem * sem)316 void k_mbox_async_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
317 struct k_sem *sem)
318 {
319 struct k_mbox_async *async;
320
321 SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_mbox, async_put, mbox, sem);
322
323 /*
324 * allocate an asynchronous message descriptor, configure both parts,
325 * then send the message asynchronously
326 */
327 mbox_async_alloc(&async);
328
329 async->thread.prio = _current->base.prio;
330
331 async->tx_msg = *tx_msg;
332 async->tx_msg._syncing_thread = (struct k_thread *)&async->thread;
333 async->tx_msg._async_sem = sem;
334
335 (void)mbox_message_put(mbox, &async->tx_msg, K_FOREVER);
336 SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, async_put, mbox, sem);
337 }
338 #endif
339
k_mbox_data_get(struct k_mbox_msg * rx_msg,void * buffer)340 void k_mbox_data_get(struct k_mbox_msg *rx_msg, void *buffer)
341 {
342 /* handle case where data is to be discarded */
343 if (buffer == NULL) {
344 rx_msg->size = 0;
345 mbox_message_dispose(rx_msg);
346 return;
347 }
348
349 /* copy message data to buffer, then dispose of message */
350 if ((rx_msg->tx_data != NULL) && (rx_msg->size > 0U)) {
351 (void)memcpy(buffer, rx_msg->tx_data, rx_msg->size);
352 }
353 mbox_message_dispose(rx_msg);
354 }
355
356 /**
357 * @brief Handle immediate consumption of received mailbox message data.
358 *
359 * Checks to see if received message data should be kept for later retrieval,
360 * or if the data should consumed immediately and the message disposed of.
361 *
362 * The data is consumed immediately in either of the following cases:
363 * 1) The receiver requested immediate retrieval by supplying a buffer
364 * to receive the data.
365 * 2) There is no data to be retrieved. (i.e. Data size is 0 bytes.)
366 *
367 * @param rx_msg Pointer to receive message descriptor.
368 * @param buffer Pointer to buffer to receive data.
369 *
370 * @return 0
371 */
mbox_message_data_check(struct k_mbox_msg * rx_msg,void * buffer)372 static int mbox_message_data_check(struct k_mbox_msg *rx_msg, void *buffer)
373 {
374 if (buffer != NULL) {
375 /* retrieve data now, then dispose of message */
376 k_mbox_data_get(rx_msg, buffer);
377 } else if (rx_msg->size == 0U) {
378 /* there is no data to get, so just dispose of message */
379 mbox_message_dispose(rx_msg);
380 } else {
381 /* keep message around for later data retrieval */
382 }
383
384 return 0;
385 }
386
k_mbox_get(struct k_mbox * mbox,struct k_mbox_msg * rx_msg,void * buffer,k_timeout_t timeout)387 int k_mbox_get(struct k_mbox *mbox, struct k_mbox_msg *rx_msg, void *buffer,
388 k_timeout_t timeout)
389 {
390 struct k_thread *sending_thread;
391 struct k_mbox_msg *tx_msg;
392 k_spinlock_key_t key;
393 int result;
394
395 /* save receiver id so it can be used during message matching */
396 rx_msg->tx_target_thread = _current;
397
398 /* search mailbox's tx queue for a compatible sender */
399 key = k_spin_lock(&mbox->lock);
400
401 SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_mbox, get, mbox, timeout);
402
403 _WAIT_Q_FOR_EACH(&mbox->tx_msg_queue, sending_thread) {
404 tx_msg = (struct k_mbox_msg *)sending_thread->base.swap_data;
405
406 if (mbox_message_match(tx_msg, rx_msg) == 0) {
407 /* take sender out of mailbox's tx queue */
408 z_unpend_thread(sending_thread);
409
410 k_spin_unlock(&mbox->lock, key);
411
412 /* consume message data immediately, if needed */
413 result = mbox_message_data_check(rx_msg, buffer);
414
415 SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, get, mbox, timeout, result);
416 return result;
417 }
418 }
419
420 /* didn't find a matching sender */
421
422 if (K_TIMEOUT_EQ(timeout, K_NO_WAIT)) {
423 SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, get, mbox, timeout, -ENOMSG);
424
425 /* don't wait for a matching sender to appear */
426 k_spin_unlock(&mbox->lock, key);
427 return -ENOMSG;
428 }
429
430 SYS_PORT_TRACING_OBJ_FUNC_BLOCKING(k_mbox, get, mbox, timeout);
431
432 /* wait until a matching sender appears or a timeout occurs */
433 _current->base.swap_data = rx_msg;
434 result = z_pend_curr(&mbox->lock, key, &mbox->rx_msg_queue, timeout);
435
436 /* consume message data immediately, if needed */
437 if (result == 0) {
438 result = mbox_message_data_check(rx_msg, buffer);
439 }
440
441 SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, get, mbox, timeout, result);
442
443 return result;
444 }
445
446 #ifdef CONFIG_OBJ_CORE_MAILBOX
447
init_mailbox_obj_core_list(void)448 static int init_mailbox_obj_core_list(void)
449 {
450 /* Initialize mailbox object type */
451
452 z_obj_type_init(&obj_type_mailbox, K_OBJ_TYPE_MBOX_ID,
453 offsetof(struct k_mbox, obj_core));
454
455 /* Initialize and link satically defined mailboxes */
456
457 STRUCT_SECTION_FOREACH(k_mbox, mbox) {
458 k_obj_core_init_and_link(K_OBJ_CORE(mbox), &obj_type_mailbox);
459 }
460
461 return 0;
462 }
463
464 SYS_INIT(init_mailbox_obj_core_list, PRE_KERNEL_1,
465 CONFIG_KERNEL_INIT_PRIORITY_OBJECTS);
466 #endif
467
