4  * SPDX-License-Identifier: Apache-2.0
52  * Do run-time initialization of mailbox object subsystem.
89 	z_waitq_init(&mbox->tx_msg_queue);  in k_mbox_init()
90 	z_waitq_init(&mbox->rx_msg_queue);  in k_mbox_init()
91 	mbox->lock = (struct k_spinlock) {};  in k_mbox_init()
110  * @return 0 if successfully matched, otherwise -1.
117 	if (((tx_msg->tx_target_thread == (k_tid_t)K_ANY) ||  in mbox_message_match()
118 	     (tx_msg->tx_target_thread == rx_msg->tx_target_thread)) &&  in mbox_message_match()
119 	    ((rx_msg->rx_source_thread == (k_tid_t)K_ANY) ||  in mbox_message_match()
120 	     (rx_msg->rx_source_thread == tx_msg->rx_source_thread))) {  in mbox_message_match()
123 		rx_msg->rx_source_thread = tx_msg->rx_source_thread;  in mbox_message_match()
124 		tx_msg->tx_target_thread = rx_msg->tx_target_thread;  in mbox_message_match()
127 		temp_info = rx_msg->info;  in mbox_message_match()
128 		rx_msg->info = tx_msg->info;  in mbox_message_match()
129 		tx_msg->info = temp_info;  in mbox_message_match()
131 		/* update data size field for receiver only */  in mbox_message_match()
132 		if (rx_msg->size > tx_msg->size) {  in mbox_message_match()
133 			rx_msg->size = tx_msg->size;  in mbox_message_match()
136 		/* update data location fields for receiver only */  in mbox_message_match()
137 		rx_msg->tx_data = tx_msg->tx_data;  in mbox_message_match()
140 		rx_msg->_syncing_thread = tx_msg->_syncing_thread;  in mbox_message_match()
145 	return -1;  in mbox_message_match()
161 	if (rx_msg->_syncing_thread == NULL) {  in mbox_message_dispose()
166 	sending_thread = rx_msg->_syncing_thread;  in mbox_message_dispose()
167 	rx_msg->_syncing_thread = NULL;  in mbox_message_dispose()
168 	tx_msg = (struct k_mbox_msg *)sending_thread->base.swap_data;  in mbox_message_dispose()
170 	/* update data size field for sender */  in mbox_message_dispose()
171 	tx_msg->size = rx_msg->size;  in mbox_message_dispose()
178 	if ((sending_thread->base.thread_state & _THREAD_DUMMY) != 0U) {  in mbox_message_dispose()
179 		struct k_sem *async_sem = tx_msg->_async_sem;  in mbox_message_dispose()
203  * @param timeout Maximum time (milliseconds) to wait for the message to be
208  * @return 0 if successful, -ENOMSG if failed immediately, -EAGAIN if timed out
211 			     k_timeout_t timeout)  in mbox_message_put()  argument
219 	tx_msg->rx_source_thread = arch_current_thread();  in mbox_message_put()
222 	sending_thread = tx_msg->_syncing_thread;  in mbox_message_put()
223 	sending_thread->base.swap_data = tx_msg;  in mbox_message_put()
226 	key = k_spin_lock(&mbox->lock);  in mbox_message_put()
228 	SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_mbox, message_put, mbox, timeout);  in mbox_message_put()
230 	_WAIT_Q_FOR_EACH(&mbox->rx_msg_queue, receiving_thread) {  in mbox_message_put()
231 		rx_msg = (struct k_mbox_msg *)receiving_thread->base.swap_data;  in mbox_message_put()
249 			if ((sending_thread->base.thread_state & _THREAD_DUMMY)  in mbox_message_put()
251 				z_reschedule(&mbox->lock, key);  in mbox_message_put()
255 			SYS_PORT_TRACING_OBJ_FUNC_BLOCKING(k_mbox, message_put, mbox, timeout);  in mbox_message_put()
261 			int ret = z_pend_curr(&mbox->lock, key, NULL, K_FOREVER);  in mbox_message_put()
263 			SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, message_put, mbox, timeout, ret);  in mbox_message_put()
270 	if (K_TIMEOUT_EQ(timeout, K_NO_WAIT)) {  in mbox_message_put()
271 		SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, message_put, mbox, timeout, -ENOMSG);  in mbox_message_put()
273 		k_spin_unlock(&mbox->lock, key);  in mbox_message_put()
274 		return -ENOMSG;  in mbox_message_put()
279 	if ((sending_thread->base.thread_state & _THREAD_DUMMY) != 0U) {  in mbox_message_put()
280 		z_pend_thread(sending_thread, &mbox->tx_msg_queue, K_FOREVER);  in mbox_message_put()
281 		k_spin_unlock(&mbox->lock, key);  in mbox_message_put()
285 	SYS_PORT_TRACING_OBJ_FUNC_BLOCKING(k_mbox, message_put, mbox, timeout);  in mbox_message_put()
287 	/* synchronous send: sender waits on tx queue for receiver or timeout */  in mbox_message_put()
288 	int ret = z_pend_curr(&mbox->lock, key, &mbox->tx_msg_queue, timeout);  in mbox_message_put()
290 	SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, message_put, mbox, timeout, ret);  in mbox_message_put()
296 	       k_timeout_t timeout)  in k_mbox_put()  argument
299 	tx_msg->_syncing_thread = arch_current_thread();  in k_mbox_put()
301 	SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_mbox, put, mbox, timeout);  in k_mbox_put()
303 	int ret = mbox_message_put(mbox, tx_msg, timeout);  in k_mbox_put()
305 	SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, put, mbox, timeout, ret);  in k_mbox_put()
324 	async->thread.prio = arch_current_thread()->base.prio;  in k_mbox_async_put()
326 	async->tx_msg = *tx_msg;  in k_mbox_async_put()
327 	async->tx_msg._syncing_thread = (struct k_thread *)&async->thread;  in k_mbox_async_put()
328 	async->tx_msg._async_sem = sem;  in k_mbox_async_put()
330 	(void)mbox_message_put(mbox, &async->tx_msg, K_FOREVER);  in k_mbox_async_put()
337 	/* handle case where data is to be discarded */  in k_mbox_data_get()
339 		rx_msg->size = 0;  in k_mbox_data_get()
344 	/* copy message data to buffer, then dispose of message */  in k_mbox_data_get()
345 	if ((rx_msg->tx_data != NULL) && (rx_msg->size > 0U)) {  in k_mbox_data_get()
346 		(void)memcpy(buffer, rx_msg->tx_data, rx_msg->size);  in k_mbox_data_get()
352  * @brief Handle immediate consumption of received mailbox message data.
354  * Checks to see if received message data should be kept for later retrieval,
355  * or if the data should consumed immediately and the message disposed of.
357  * The data is consumed immediately in either of the following cases:
359  *        to receive the data.
360  *     2) There is no data to be retrieved. (i.e. Data size is 0 bytes.)
363  * @param buffer Pointer to buffer to receive data.
370 		/* retrieve data now, then dispose of message */  in mbox_message_data_check()
372 	} else if (rx_msg->size == 0U) {  in mbox_message_data_check()
373 		/* there is no data to get, so just dispose of message */  in mbox_message_data_check()
376 		/* keep message around for later data retrieval */  in mbox_message_data_check()
383 	       k_timeout_t timeout)  in k_mbox_get()  argument
391 	rx_msg->tx_target_thread = arch_current_thread();  in k_mbox_get()
394 	key = k_spin_lock(&mbox->lock);  in k_mbox_get()
396 	SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_mbox, get, mbox, timeout);  in k_mbox_get()
398 	_WAIT_Q_FOR_EACH(&mbox->tx_msg_queue, sending_thread) {  in k_mbox_get()
399 		tx_msg = (struct k_mbox_msg *)sending_thread->base.swap_data;  in k_mbox_get()
405 			k_spin_unlock(&mbox->lock, key);  in k_mbox_get()
407 			/* consume message data immediately, if needed */  in k_mbox_get()
410 			SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, get, mbox, timeout, result);  in k_mbox_get()
417 	if (K_TIMEOUT_EQ(timeout, K_NO_WAIT)) {  in k_mbox_get()
418 		SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, get, mbox, timeout, -ENOMSG);  in k_mbox_get()
421 		k_spin_unlock(&mbox->lock, key);  in k_mbox_get()
422 		return -ENOMSG;  in k_mbox_get()
425 	SYS_PORT_TRACING_OBJ_FUNC_BLOCKING(k_mbox, get, mbox, timeout);  in k_mbox_get()
427 	/* wait until a matching sender appears or a timeout occurs */  in k_mbox_get()
428 	arch_current_thread()->base.swap_data = rx_msg;  in k_mbox_get()
429 	result = z_pend_curr(&mbox->lock, key, &mbox->rx_msg_queue, timeout);  in k_mbox_get()
431 	/* consume message data immediately, if needed */  in k_mbox_get()
436 	SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, get, mbox, timeout, result);  in k_mbox_get()