zephyr/kernel/unified/mailbox.c

/*
 * Copyright (c) 2016 Wind River Systems, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @brief Mailboxes.
 */

#include <kernel.h>
#include <nano_private.h>
#include <misc/debug/object_tracing_common.h>
#include <toolchain.h>
#include <sections.h>
#include <string.h>
#include <wait_q.h>
#include <misc/dlist.h>


#if (CONFIG_NUM_MBOX_ASYNC_MSGS > 0)

/* asynchronous message descriptor type */
struct k_mbox_async {
	struct tcs_base thread;		/* dummy thread object */
	struct k_mbox_msg tx_msg;	/* transmit message descriptor */
};

/* array of asynchronous message descriptors */
static struct k_mbox_async __noinit async_msg[CONFIG_NUM_MBOX_ASYNC_MSGS];

/* stack of unused asynchronous message descriptors */
K_STACK_DEFINE(async_msg_free, CONFIG_NUM_MBOX_ASYNC_MSGS);

/**
 * @brief Create pool of asynchronous message descriptors.
 *
 * A dummy thread requires minimal initialization, since it never actually
 * gets to execute. The K_DUMMY flag is sufficient to distinguish a dummy
 * thread from a real one. The threads are *not* added to the kernel's list of
 * known threads.
 *
 * Once initialized, the address of each descriptor is added to a stack
 * that governs access to them.
 *
 * @return N/A
 */
void _k_mbox_init(void)
{
	int i;

	for (i = 0; i < CONFIG_NUM_MBOX_ASYNC_MSGS; i++) {
		async_msg[i].thread.flags = K_DUMMY;
		k_stack_push(async_msg_free, (uint32_t)&async_msg[i]);
	}
}

/**
 * @brief Allocate an asynchronous message descriptor.
 *
 * @param async Address of area to hold the descriptor pointer.
 *
 * @return N/A.
 */
static inline void _mbox_async_alloc(struct k_mbox_async **async)
{
	k_stack_pop(async_msg_free, (uint32_t *)async, K_FOREVER);
}

/**
 * @brief Free an asynchronous message descriptor.
 *
 * @param Descriptor pointer.
 */
static inline void _mbox_async_free(struct k_mbox_async *async)
{
	k_stack_push(async_msg_free, (uint32_t)async);
}

#endif

/**
 * @brief Initialize a mailbox.
 *
 * @return N/A
 */
void k_mbox_init(struct k_mbox *mbox_ptr)
{
	sys_dlist_init(&mbox_ptr->tx_msg_queue);
	sys_dlist_init(&mbox_ptr->rx_msg_queue);
	SYS_TRACING_OBJ_INIT(mbox, mbox_ptr);
}

/**
 * @brief Check compatibility of sender's and receiver's message descriptors.
 *
 * Compares sender's and receiver's message descriptors to see if they are
 * compatible. If so, the descriptor fields are updated to reflect that a
 * match has occurred.
 *
 * @param tx_msg Pointer to transmit message descriptor.
 * @param rx_msg Pointer to receive message descriptor.
 *
 * @return 0 if successfully matched, otherwise -1.
 */
static int _mbox_message_match(struct k_mbox_msg *tx_msg,
			       struct k_mbox_msg *rx_msg)
{
	uint32_t temp_info;

	if (((tx_msg->tx_target_thread == (k_tid_t)K_ANY) ||
	     (tx_msg->tx_target_thread == rx_msg->tx_target_thread)) &&
	    ((rx_msg->rx_source_thread == (k_tid_t)K_ANY) ||
	     (rx_msg->rx_source_thread == tx_msg->rx_source_thread))) {

		/* update thread identifier fields for both descriptors */
		rx_msg->rx_source_thread = tx_msg->rx_source_thread;
		tx_msg->tx_target_thread = rx_msg->tx_target_thread;

		/* update application info fields for both descriptors */
		temp_info = rx_msg->info;
		rx_msg->info = tx_msg->info;
		tx_msg->info = temp_info;

		/* update data size field for receiver only */
		if (rx_msg->size > tx_msg->size) {
			rx_msg->size = tx_msg->size;
		}

		/* update data location fields for receiver only */
		rx_msg->tx_data = tx_msg->tx_data;
		rx_msg->tx_block = tx_msg->tx_block;
		if (rx_msg->tx_data != NULL) {
			rx_msg->tx_block.pool_id = NULL;
		} else if (rx_msg->tx_block.pool_id != NULL) {
			rx_msg->tx_data = rx_msg->tx_block.data;
		}

		/* update syncing thread field for receiver only */
		rx_msg->_syncing_thread = tx_msg->_syncing_thread;

		return 0;
	}

	return -1;
}

/**
 * @brief Dispose of received message.
 *
 * Releases any memory pool block still associated with the message,
 * then notifies the sender that message processing is complete.
 *
 * @param rx_msg Pointer to receive message descriptor.
 *
 * @return N/A
 */
static void _mbox_message_dispose(struct k_mbox_msg *rx_msg)
{
	struct tcs *sending_thread;
	struct k_mbox_msg *tx_msg;
	unsigned int key;

	/* do nothing if message was disposed of when it was received */
	if (rx_msg->_syncing_thread == NULL) {
		return;
	}

	/* release sender's memory pool block */
	if (rx_msg->tx_block.pool_id != NULL) {
#if 0
		/* NEED TO WAIT FOR MEMORY POOL SUPPORT */
		k_mem_pool_free(&rx_msg->tx_block);
#endif
		rx_msg->tx_block.pool_id = NULL;
	}

	/* recover sender info */
	sending_thread = rx_msg->_syncing_thread;
	rx_msg->_syncing_thread = NULL;
	tx_msg = (struct k_mbox_msg *)sending_thread->swap_data;

	/* update data size field for sender */
	tx_msg->size = rx_msg->size;

#if (CONFIG_NUM_MBOX_ASYNC_MSGS > 0)
	/*
	 * asynchronous send: free asynchronous message descriptor +
	 * dummy thread pair, then give semaphore (if needed)
	 */
	if (sending_thread->flags & K_DUMMY) {
		struct k_sem *async_sem = tx_msg->_async_sem;

		_mbox_async_free((struct k_mbox_async *)sending_thread);
		if (async_sem != NULL) {
			k_sem_give(async_sem);
		}
		return;
	}
#endif

	/* synchronous send: wake up sending thread */
	key = irq_lock();
	_set_thread_return_value(sending_thread, 0);
	_mark_thread_as_not_pending(sending_thread);
	_ready_thread(sending_thread);
	_reschedule_threads(key);
}

/**
 * @brief Send a mailbox message.
 *
 * Helper routine that handles both synchronous and asynchronous sends.
 *
 * @param mbox Pointer to the mailbox object.
 * @param tx_msg Pointer to transmit message descriptor.
 * @param timeout Maximum time (nanoseconds) to wait for the message to be
 *        received (although not necessarily completely processed).
 *        Use K_NO_WAIT to return immediately, or K_FOREVER to wait as long
 *        as necessary.
 *
 * @return 0 if successful, -ENOMSG if failed immediately, -EAGAIN if timed out
 */
static int _mbox_message_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
			     int32_t timeout)
{
	struct tcs *sending_thread;
	struct tcs *receiving_thread;
	struct k_mbox_msg *rx_msg;
	sys_dnode_t *wait_q_item;
	unsigned int key;

	/* save sender id so it can be used during message matching */
	tx_msg->rx_source_thread = _current;

	/* finish readying sending thread (actual or dummy) for send */
	sending_thread = tx_msg->_syncing_thread;
	sending_thread->swap_data = tx_msg;

	/* search mailbox's rx queue for a compatible receiver */
	key = irq_lock();

	SYS_DLIST_FOR_EACH_NODE(&mbox->rx_msg_queue, wait_q_item) {
		receiving_thread = (struct tcs *)wait_q_item;
		rx_msg = (struct k_mbox_msg *)receiving_thread->swap_data;

		if (_mbox_message_match(tx_msg, rx_msg) == 0) {
			/* take receiver out of rx queue */
			_unpend_thread(receiving_thread);
			_timeout_abort(receiving_thread);

			/* ready receiver for execution */
			_set_thread_return_value(receiving_thread, 0);
			_ready_thread(receiving_thread);

#if (CONFIG_NUM_MBOX_ASYNC_MSGS > 0)
			/*
			 * asynchronous send: swap out current thread
			 * if receiver has priority, otherwise let it continue
			 *
			 * note: dummy sending thread sits (unqueued)
			 * until the receiver consumes the message
			 */
			if (sending_thread->flags & K_DUMMY) {
				_reschedule_threads(key);
				return 0;
			}
#endif

			/*
			 * synchronous send: pend current thread (unqueued)
			 * until the receiver consumes the message
			 */
			_remove_thread_from_ready_q(_current);
			_mark_thread_as_pending(_current);
			return _Swap(key);
		}
	}

	/* didn't find a matching receiver: don't wait for one */
	if (timeout == K_NO_WAIT) {
		irq_unlock(key);
		return -ENOMSG;
	}

#if (CONFIG_NUM_MBOX_ASYNC_MSGS > 0)
	/* asynchronous send: dummy thread waits on tx queue for receiver */
	if (sending_thread->flags & K_DUMMY) {
		_pend_thread(sending_thread, &mbox->tx_msg_queue, K_FOREVER);
		irq_unlock(key);
		return 0;
	}
#endif

	/* synchronous send: sender waits on tx queue for receiver or timeout */
	_pend_current_thread(&mbox->tx_msg_queue, timeout);
	return _Swap(key);
}

/**
 * @brief Send a mailbox message in a synchronous manner.
 *
 * Sends a message to a mailbox and waits for a receiver to process it.
 * The message data may be in a buffer, in a memory pool block, or non-existent
 * (i.e. empty message).
 *
 * @param mbox Pointer to the mailbox object.
 * @param tx_msg Pointer to transmit message descriptor.
 * @param timeout Maximum time (nanoseconds) to wait for the message to be
 *        received (although not necessarily completely processed).
 *        Use K_NO_WAIT to return immediately, or K_FOREVER to wait as long
 *        as necessary.
 *
 * @return 0 if successful, -ENOMSG if failed immediately, -EAGAIN if timed out
 */
int k_mbox_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg, int32_t timeout)
{
	/* configure things for a synchronous send, then send the message */
	tx_msg->_syncing_thread = _current;

	return _mbox_message_put(mbox, tx_msg, timeout);
}

#if (CONFIG_NUM_MBOX_ASYNC_MSGS > 0)
/**
 * @brief Send a mailbox message in an asynchronous manner.
 *
 * Sends a message to a mailbox without waiting for a receiver to process it.
 * The message data may be in a buffer, in a memory pool block, or non-existent
 * (i.e. an empty message). Optionally, the specified semaphore will be given
 * by the mailbox when the message has been both received and disposed of
 * by the receiver.
 *
 * @param mbox Pointer to the mailbox object.
 * @param tx_msg Pointer to transmit message descriptor.
 * @param sem Semaphore identifier, or NULL if none specified.
 *
 * @return N/A
 */
void k_mbox_async_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
		      struct k_sem *sem)
{
	struct k_mbox_async *async;

	/*
	 * allocate an asynchronous message descriptor, configure both parts,
	 * then send the message asynchronously
	 */
	_mbox_async_alloc(&async);

	async->thread.prio = _current->prio;

	async->tx_msg = *tx_msg;
	async->tx_msg._syncing_thread = (struct tcs *)&async->thread;
	async->tx_msg._async_sem = sem;

	_mbox_message_put(mbox, &async->tx_msg, K_FOREVER);
}
#endif

/**
 * @brief Retrieve mailbox message data into a buffer.
 *
 * Completes the processing of a received message by retrieving its data
 * into a buffer, then disposing of the message.
 *
 * Alternatively, this routine can be used to dispose of a received message
 * without retrieving its data.
 *
 * @param rx_msg Pointer to receive message descriptor.
 * @param buffer Pointer to buffer to receive data. (Use NULL to discard data.)
 *
 * @return N/A
 */
void k_mbox_data_get(struct k_mbox_msg *rx_msg, void *buffer)
{
	/* handle case where data is to be discarded */
	if (buffer == NULL) {
		rx_msg->size = 0;
		_mbox_message_dispose(rx_msg);
		return;
	}

	/* copy message data to buffer, then dispose of message */
	if ((rx_msg->tx_data != NULL) && (rx_msg->size > 0)) {
		memcpy(buffer, rx_msg->tx_data, rx_msg->size);
	}
	_mbox_message_dispose(rx_msg);
}

/**
 * @brief Retrieve mailbox message data into a memory pool block.
 *
 * Completes the processing of a received message by retrieving its data
 * into a memory pool block, then disposing of the message. The memory pool
 * block that results from successful retrieval must be returned to the pool
 * once the data has been processed, even in cases where zero bytes of data
 * are retrieved.
 *
 * Alternatively, this routine can be used to dispose of a received message
 * without retrieving its data. In this case there is no need to return a
 * memory pool block to the pool.
 *
 * This routine allocates a new memory pool block for the data only if the
 * data is not already in one. If a new block cannot be allocated, the routine
 * returns a failure code and the received message is left unchanged. This
 * permits the caller to reattempt data retrieval at a later time or to dispose
 * of the received message without retrieving its data.
 *
 * @param msg Pointer to receive message descriptor.
 * @param pool Memory pool identifier. (Use NULL to discard data.)
 * @param block Pointer to area to hold memory pool block info.
 * @param timeout Maximum time (nanoseconds) to wait for a memory pool block.
 *        Use K_NO_WAIT to return immediately, or K_FOREVER to wait as long as
 *        necessary.
 *
 * @return 0 if successful, -ENOMEM if failed immediately, -EAGAIN if timed out
 */
int k_mbox_data_block_get(struct k_mbox_msg *rx_msg, k_mem_pool_t pool,
			  struct k_mem_block *block, int32_t timeout)
{
	int result;

	/* handle case where data is to be discarded */
	if (pool == NULL) {
		rx_msg->size = 0;
		_mbox_message_dispose(rx_msg);
		return 0;
	}

	/* handle case where data is already in a memory pool block */
	if (rx_msg->tx_block.pool_id != NULL) {
		/* give ownership of the block to receiver */
		*block = rx_msg->tx_block;
		rx_msg->tx_block.pool_id = NULL;

		/* now dispose of message */
		_mbox_message_dispose(rx_msg);
		return 0;
	}

	/* allocate memory pool block (even when message size is 0!) */
	result = k_mem_pool_alloc(pool, block, rx_msg->size, timeout);
	if (result != 0) {
		return result;
	}

	/* retrieve non-block data into new block, then dispose of message */
	k_mbox_data_get(rx_msg, block->data);
	return 0;
}

/**
 * @brief Handle immediate consumption of received mailbox message data.
 *
 * Checks to see if received message data should be kept for later retrieval,
 * or if the data should consumed immediately and the message disposed of.
 *
 * The data is consumed immediately in either of the following cases:
 *     1) The receiver requested immediate retrieval by suppling a buffer
 *        to receive the data.
 *     2) There is no data to be retrieved. (i.e. Data size is 0 bytes.)
 *
 * @param rx_msg Pointer to receive message descriptor.
 * @param buffer Pointer to buffer to receive data.
 *
 * @return 0
 */
static int _mbox_message_data_check(struct k_mbox_msg *rx_msg, void *buffer)
{
	if (buffer != NULL) {
		/* retrieve data now, then dispose of message */
		k_mbox_data_get(rx_msg, buffer);
	} else if (rx_msg->size == 0) {
		/* there is no data to get, so just dispose of message */
		_mbox_message_dispose(rx_msg);
	} else {
		/* keep message around for later data retrieval */
	}

	return 0;
}

/**
 * @brief Receive a mailbox message.
 *
 * Receives a message from a mailbox, then optionally retrieves its data
 * and disposes of the message.
 *
 * @param mbox Pointer to the mailbox object.
 * @param msg Pointer to receive message descriptor.
 * @param buffer Pointer to buffer to receive data.
 *        (Use NULL to defer data retrieval and message disposal until later.)
 * @param timeout Maximum time (nanoseconds) to wait for a message.
 *        Use K_NO_WAIT to return immediately, or K_FOREVER to wait as long as
 *        necessary.
 *
 * @return 0 if successful, -ENOMSG if failed immediately, -EAGAIN if timed out
 */
int k_mbox_get(struct k_mbox *mbox, struct k_mbox_msg *rx_msg, void *buffer,
	       int32_t timeout)
{
	struct tcs *sending_thread;
	struct k_mbox_msg *tx_msg;
	sys_dnode_t *wait_q_item;
	unsigned int key;
	int result;

	/* save receiver id so it can be used during message matching */
	rx_msg->tx_target_thread = _current;

	/* search mailbox's tx queue for a compatible sender */
	key = irq_lock();

	SYS_DLIST_FOR_EACH_NODE(&mbox->tx_msg_queue, wait_q_item) {
		sending_thread = (struct tcs *)wait_q_item;
		tx_msg = (struct k_mbox_msg *)sending_thread->swap_data;

		if (_mbox_message_match(tx_msg, rx_msg) == 0) {
			/* take sender out of mailbox's tx queue */
			_unpend_thread(sending_thread);
			_timeout_abort(sending_thread);

			irq_unlock(key);

			/* consume message data immediately, if needed */
			return _mbox_message_data_check(rx_msg, buffer);
		}
	}

	/* didn't find a matching sender */

	if (timeout == K_NO_WAIT) {
		/* don't wait for a matching sender to appear */
		irq_unlock(key);
		return -ENOMSG;
	}

	/* wait until a matching sender appears or a timeout occurs */
	_pend_current_thread(&mbox->rx_msg_queue, timeout);
	_current->swap_data = rx_msg;
	result = _Swap(key);

	/* consume message data immediately, if needed */
	if (result == 0) {
		result = _mbox_message_data_check(rx_msg, buffer);
	}

	return result;
}



int task_mbox_put(kmbox_t mbox, kpriority_t prio, struct k_msg *msg,
		  int32_t timeout)
{
	struct k_mbox_msg *tx_msg = (struct k_mbox_msg *)msg;
	kpriority_t curr_prio;
	unsigned int key;
	int result;

	/* handle old-style request to send an empty message */
	if (tx_msg->size == 0) {
		tx_msg->tx_block.pool_id = NULL;
	}

	/* handle sending message of current thread priority */
	curr_prio = _current->prio;
	if (prio == curr_prio) {
		return _error_to_rc(k_mbox_put(mbox, tx_msg,
					       _ticks_to_ms(timeout)));
	}

	/* handle sending message of a different thread priority */
	key = irq_lock();
	_thread_priority_set(_current, prio);
	_reschedule_threads(key);

	result = _error_to_rc(k_mbox_put(mbox, tx_msg, _ticks_to_ms(timeout)));

	key = irq_lock();
	_thread_priority_set(_current, curr_prio);
	_reschedule_threads(key);

	return result;
}

void task_mbox_block_put(kmbox_t mbox, kpriority_t prio, struct k_msg *msg,
			 ksem_t sema)
{
	struct k_mbox_msg *tx_msg = (struct k_mbox_msg *)msg;
	kpriority_t curr_prio;
	unsigned int key;

	/* handle sending message of current thread priority */
	curr_prio = _current->prio;
	if (prio == curr_prio) {
		k_mbox_async_put(mbox, tx_msg, sema);
		return;
	}

	/* handle sending message of a different thread priority */
	key = irq_lock();
	_thread_priority_set(_current, prio);
	_reschedule_threads(key);

	k_mbox_async_put(mbox, tx_msg, sema);

	key = irq_lock();
	_thread_priority_set(_current, curr_prio);
	_reschedule_threads(key);
}

int task_mbox_get(kmbox_t mbox, struct k_msg *msg, int32_t timeout)
{
	struct k_mbox_msg *rx_msg = (struct k_mbox_msg *)msg;

	return _error_to_rc(k_mbox_get(mbox, rx_msg, rx_msg->_rx_data,
				       _ticks_to_ms(timeout)));
}

void task_mbox_data_get(struct k_msg *msg)
{
	struct k_mbox_msg *rx_msg = (struct k_mbox_msg *)msg;

	/* handle old-style request to discard message data */
	if (rx_msg->size == 0) {
		rx_msg->_rx_data = NULL;
	}

	k_mbox_data_get(rx_msg, rx_msg->_rx_data);
}

int task_mbox_data_block_get(struct k_msg *msg, struct k_block *block,
			     kmemory_pool_t pool_id, int32_t timeout)
{
	struct k_mbox_msg *rx_msg = (struct k_mbox_msg *)msg;

	return _error_to_rc(k_mbox_data_block_get(rx_msg, pool_id, block,
						  _ticks_to_ms(timeout)));
}