Tracing: Mutex tracing hooks

Add mutex trace hooks, default mutex trace hooks, and trace hook
documentation.

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

include/tracing/tracing.h

@@ -131,24 +131,6 @@
  * @brief Called when the cpu enters the idle state
  */
 #define sys_trace_idle()
-
-/**
- * @brief Trace initialisation of a Mutex
- * @param mutex  Mutex object
- */
-#define sys_trace_mutex_init(mutex)
-
-/**
- * @brief Trace locking a Mutex
- * @param mutex Mutex object
- */
-#define sys_trace_mutex_lock(mutex)
-
-/**
- * @brief Trace unlocking a Mutex
- * @param mutex Mutex object
- */
-#define sys_trace_mutex_unlock(mutex)
 /**
  * @}
  */
@@ -220,6 +202,60 @@
  */ /* end of sem_tracing_apis */
 
 
+
+
+/**
+ * @brief Mutex Tracing APIs
+ * @defgroup mutex_tracing_apis Mutex Tracing APIs
+ * @ingroup tracing_apis
+ * @{
+ */
+
+/**
+ * @brief Trace initialization of Mutex
+ * @param mutex Mutex object
+ * @param ret Return value
+ */
+#define sys_port_trace_k_mutex_init(mutex, ret)
+
+/**
+ * @brief Trace Mutex lock attempt start
+ * @param mutex Mutex object
+ * @param timeout Timeout period
+ */
+#define sys_port_trace_k_mutex_lock_enter(mutex, timeout)
+
+/**
+ * @brief Trace Mutex lock attempt blocking
+ * @param mutex Mutex object
+ * @param timeout Timeout period
+ */
+#define sys_port_trace_k_mutex_lock_blocking(mutex, timeout)
+
+/**
+ * @brief Trace Mutex lock attempt outcome
+ * @param mutex Mutex object
+ * @param timeout Timeout period
+ * @param ret Return value
+ */
+#define sys_port_trace_k_mutex_lock_exit(mutex, timeout, ret)
+
+/**
+ * @brief Trace Mutex unlock entry
+ * @param mutex Mutex object
+ */
+#define sys_port_trace_k_mutex_unlock_enter(mutex)
+
+/**
+ * @brief Trace Mutex unlock exit
+ */
+#define sys_port_trace_k_mutex_unlock_exit(mutex, ret)
+
+/**
+ * @}
+ */ /* end of mutex_tracing_apis */
+
+
 /**
  * @}
  */

kernel/mutex.c

@@ -73,13 +73,12 @@ int z_impl_k_mutex_init(struct k_mutex *mutex)
 	mutex->owner = NULL;
 	mutex->lock_count = 0U;
 
-	sys_trace_mutex_init(mutex);
-
 	z_waitq_init(&mutex->wait_q);
 
 	SYS_TRACING_OBJ_INIT(k_mutex, mutex);
 	z_object_init(mutex);
-	sys_trace_end_call(SYS_TRACE_ID_MUTEX_INIT);
+
+	SYS_PORT_TRACING_OBJ_INIT(k_mutex, mutex, 0);
 
 	return 0;
 }
@@ -124,7 +123,8 @@ int z_impl_k_mutex_lock(struct k_mutex *mutex, k_timeout_t timeout)
 
 	__ASSERT(!arch_is_in_isr(), "mutexes cannot be used inside ISRs");
 
-	sys_trace_mutex_lock(mutex);
+	SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_mutex, lock, mutex, timeout);
+
 	key = k_spin_lock(&lock);
 
 	if (likely((mutex->lock_count == 0U) || (mutex->owner == _current))) {
@@ -141,17 +141,22 @@ int z_impl_k_mutex_lock(struct k_mutex *mutex, k_timeout_t timeout)
 			mutex->owner_orig_prio);
 
 		k_spin_unlock(&lock, key);
-		sys_trace_end_call(SYS_TRACE_ID_MUTEX_LOCK);
+
+		SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mutex, lock, mutex, timeout, 0);
 
 		return 0;
 	}
 
 	if (unlikely(K_TIMEOUT_EQ(timeout, K_NO_WAIT))) {
 		k_spin_unlock(&lock, key);
-		sys_trace_end_call(SYS_TRACE_ID_MUTEX_LOCK);
+
+		SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mutex, lock, mutex, timeout, -EBUSY);
+
 		return -EBUSY;
 	}
 
+	SYS_PORT_TRACING_OBJ_FUNC_BLOCKING(k_mutex, lock, mutex, timeout);
+
 	new_prio = new_prio_for_inheritance(_current->base.prio,
 					    mutex->owner->base.prio);
 
@@ -169,7 +174,7 @@ int z_impl_k_mutex_lock(struct k_mutex *mutex, k_timeout_t timeout)
 		got_mutex ? 'y' : 'n');
 
 	if (got_mutex == 0) {
-		sys_trace_end_call(SYS_TRACE_ID_MUTEX_LOCK);
+		SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mutex, lock, mutex, timeout, 0);
 		return 0;
 	}
 
@@ -195,7 +200,8 @@ int z_impl_k_mutex_lock(struct k_mutex *mutex, k_timeout_t timeout)
 		k_spin_unlock(&lock, key);
 	}
 
-	sys_trace_end_call(SYS_TRACE_ID_MUTEX_LOCK);
+	SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mutex, lock, mutex, timeout, -EAGAIN);
+
 	return -EAGAIN;
 }
 
@@ -215,13 +221,19 @@ int z_impl_k_mutex_unlock(struct k_mutex *mutex)
 
 	__ASSERT(!arch_is_in_isr(), "mutexes cannot be used inside ISRs");
 
+	SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_mutex, unlock, mutex);
+
 	CHECKIF(mutex->owner == NULL) {
+		SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mutex, unlock, mutex, -EINVAL);
+
 		return -EINVAL;
 	}
 	/*
 	 * The current thread does not own the mutex.
 	 */
 	CHECKIF(mutex->owner != _current) {
+		SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mutex, unlock, mutex, -EPERM);
+
 		return -EPERM;
 	}
 
@@ -233,7 +245,6 @@ int z_impl_k_mutex_unlock(struct k_mutex *mutex)
 	 */
 	__ASSERT_NO_MSG(mutex->lock_count > 0U);
 
-	sys_trace_mutex_unlock(mutex);
 	z_sched_lock();
 
 	LOG_DBG("mutex %p lock_count: %d", mutex, mutex->lock_count);
@@ -277,7 +288,8 @@ int z_impl_k_mutex_unlock(struct k_mutex *mutex)
 
 k_mutex_unlock_return:
 	k_sched_unlock();
-	sys_trace_end_call(SYS_TRACE_ID_MUTEX_UNLOCK);
+
+	SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_mutex, unlock, mutex, 0);
 
 	return 0;
 }