Tracing: Mailbox tracing

Add Mailbox tracing, default tracing hooks, and documentation.

Signed-off-by: Torbjörn Leksell <torbjorn.leksell@percepio.com>

include/tracing/tracing.h

@@ -1093,6 +1093,105 @@
  */ /* end of msgq_tracing_apis */
 
 
+
+
+/**
+ * @brief Mailbox Tracing APIs
+ * @defgroup mbox_tracing_apis Mailbox Tracing APIs
+ * @ingroup tracing_apis
+ * @{
+ */
+
+/**
+ * @brief Trace initialization of Mailbox
+ * @param mbox Mailbox object
+ */
+#define sys_port_trace_k_mbox_init(mbox)
+
+/**
+ * @brief Trace Mailbox message put attempt entry
+ * @param mbox Mailbox object
+ * @param timeout Timeout period
+ */
+#define sys_port_trace_k_mbox_message_put_enter(mbox, timeout)
+
+/**
+ * @brief Trace Mailbox message put attempt blocking
+ * @param mbox Mailbox object
+ * @param timeout Timeout period
+ */
+#define sys_port_trace_k_mbox_message_put_blocking(mbox, timeout)
+
+/**
+ * @brief Trace Mailbox message put attempt outcome
+ * @param mbox Mailbox object
+ * @param timeout Timeout period
+ * @param ret Return value
+ */
+#define sys_port_trace_k_mbox_message_put_exit(mbox, timeout, ret)
+
+/**
+ * @brief Trace Mailbox put attempt entry
+ * @param mbox Mailbox object
+ * @param timeout Timeout period
+ */
+#define sys_port_trace_k_mbox_put_enter(mbox, timeout)
+
+/**
+ * @brief Trace Mailbox put attempt blocking
+ * @param mbox Mailbox object
+ * @param timeout Timeout period
+ * @param ret Return value
+ */
+#define sys_port_trace_k_mbox_put_exit(mbox, timeout, ret)
+
+/**
+ * @brief Trace Mailbox async put entry
+ * @param mbox Mailbox object
+ * @param sem Semaphore object
+ */
+#define sys_port_trace_k_mbox_async_put_enter(mbox, sem)
+
+/**
+ * @brief Trace Mailbox async put exit
+ * @param mbox Mailbox object
+ * @param sem Semaphore object
+ */
+#define sys_port_trace_k_mbox_async_put_exit(mbox, sem)
+
+/**
+ * @brief Trace Mailbox get attempt entry
+ * @param mbox Mailbox entry
+ * @param timeout Timeout period
+ */
+#define sys_port_trace_k_mbox_get_enter(mbox, timeout)
+
+/**
+ * @brief Trace Mailbox get attempt blocking
+ * @param mbox Mailbox entry
+ * @param timeout Timeout period
+ */
+#define sys_port_trace_k_mbox_get_blocking(mbox, timeout)
+
+/**
+ * @brief Trace Mailbox get attempt outcome
+ * @param mbox Mailbox entry
+ * @param timeout Timeout period
+ * @param ret Return value
+ */
+#define sys_port_trace_k_mbox_get_exit(mbox, timeout, ret)
+
+/**
+ * @brief Trace Mailbox data get
+ * @brief rx_msg Receive Message object
+ */
+#define sys_port_trace_k_mbox_data_get(rx_msg)
+
+/**
+ * @}
+ */ /* end of mbox_tracing_apis */
+
+
 /**
  * @}
  */

kernel/mailbox.c

@@ -102,6 +102,9 @@ void k_mbox_init(struct k_mbox *mbox)
 	z_waitq_init(&mbox->tx_msg_queue);
 	z_waitq_init(&mbox->rx_msg_queue);
 	mbox->lock = (struct k_spinlock) {};
+
+	SYS_PORT_TRACING_OBJ_INIT(k_mbox, mbox);
+
 	SYS_TRACING_OBJ_INIT(k_mbox, mbox);
 }
 
@@ -248,6 +251,8 @@ static int mbox_message_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
 	/* search mailbox's rx queue for a compatible receiver */
 	key = k_spin_lock(&mbox->lock);
 
+	SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_mbox, message_put, mbox, timeout);
+
 	_WAIT_Q_FOR_EACH(&mbox->rx_msg_queue, receiving_thread) {
 		rx_msg = (struct k_mbox_msg *)receiving_thread->base.swap_data;
 
@@ -273,18 +278,24 @@ static int mbox_message_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
 				return 0;
 			}
 #endif
+			SYS_PORT_TRACING_OBJ_FUNC_BLOCKING(k_mbox, message_put, mbox, timeout);
 
 			/*
 			 * synchronous send: pend current thread (unqueued)
 			 * until the receiver consumes the message
 			 */
-			return z_pend_curr(&mbox->lock, key, NULL, K_FOREVER);
+			int ret = z_pend_curr(&mbox->lock, key, NULL, K_FOREVER);
 
+			SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, message_put, mbox, timeout, ret);
+
+			return ret;
 		}
 	}
 
 	/* didn't find a matching receiver: don't wait for one */
 	if (K_TIMEOUT_EQ(timeout, K_NO_WAIT)) {
+		SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, message_put, mbox, timeout, -ENOMSG);
+
 		k_spin_unlock(&mbox->lock, key);
 		return -ENOMSG;
 	}
@@ -297,9 +308,14 @@ static int mbox_message_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
 		return 0;
 	}
 #endif
+	SYS_PORT_TRACING_OBJ_FUNC_BLOCKING(k_mbox, message_put, mbox, timeout);
 
 	/* synchronous send: sender waits on tx queue for receiver or timeout */
-	return z_pend_curr(&mbox->lock, key, &mbox->tx_msg_queue, timeout);
+	int ret = z_pend_curr(&mbox->lock, key, &mbox->tx_msg_queue, timeout);
+
+	SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, message_put, mbox, timeout, ret);
+
+	return ret;
 }
 
 int k_mbox_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
@@ -308,7 +324,13 @@ int k_mbox_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
 	/* configure things for a synchronous send, then send the message */
 	tx_msg->_syncing_thread = _current;
 
-	return mbox_message_put(mbox, tx_msg, timeout);
+	SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_mbox, put, mbox, timeout);
+
+	int ret = mbox_message_put(mbox, tx_msg, timeout);
+
+	SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, put, mbox, timeout, ret);
+
+	return ret;
 }
 
 #if (CONFIG_NUM_MBOX_ASYNC_MSGS > 0)
@@ -317,6 +339,8 @@ void k_mbox_async_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
 {
 	struct k_mbox_async *async;
 
+	SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_mbox, async_put, mbox, sem);
+
 	/*
 	 * allocate an asynchronous message descriptor, configure both parts,
 	 * then send the message asynchronously
@@ -330,6 +354,7 @@ void k_mbox_async_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
 	async->tx_msg._async_sem = sem;
 
 	(void)mbox_message_put(mbox, &async->tx_msg, K_FOREVER);
+	SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, async_put, mbox, sem);
 }
 #endif
 
@@ -394,6 +419,8 @@ int k_mbox_get(struct k_mbox *mbox, struct k_mbox_msg *rx_msg, void *buffer,
 	/* search mailbox's tx queue for a compatible sender */
 	key = k_spin_lock(&mbox->lock);
 
+	SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_mbox, get, mbox, timeout);
+
 	_WAIT_Q_FOR_EACH(&mbox->tx_msg_queue, sending_thread) {
 		tx_msg = (struct k_mbox_msg *)sending_thread->base.swap_data;
 
@@ -404,18 +431,25 @@ int k_mbox_get(struct k_mbox *mbox, struct k_mbox_msg *rx_msg, void *buffer,
 			k_spin_unlock(&mbox->lock, key);
 
 			/* consume message data immediately, if needed */
-			return mbox_message_data_check(rx_msg, buffer);
+			result = mbox_message_data_check(rx_msg, buffer);
+
+			SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, get, mbox, timeout, result);
+			return result;
 		}
 	}
 
 	/* didn't find a matching sender */
 
 	if (K_TIMEOUT_EQ(timeout, K_NO_WAIT)) {
+		SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, get, mbox, timeout, -ENOMSG);
+
 		/* don't wait for a matching sender to appear */
 		k_spin_unlock(&mbox->lock, key);
 		return -ENOMSG;
 	}
 
+	SYS_PORT_TRACING_OBJ_FUNC_BLOCKING(k_mbox, get, mbox, timeout);
+
 	/* wait until a matching sender appears or a timeout occurs */
 	_current->base.swap_data = rx_msg;
 	result = z_pend_curr(&mbox->lock, key, &mbox->rx_msg_queue, timeout);
@@ -425,5 +459,7 @@ int k_mbox_get(struct k_mbox *mbox, struct k_mbox_msg *rx_msg, void *buffer,
 		result = mbox_message_data_check(rx_msg, buffer);
 	}
 
+	SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mbox, get, mbox, timeout, result);
+
 	return result;
 }