[docs]:Add standardized function comment blocks for mutex_tc

Author: ruanqiuqiu

src/utest/mutex_pi_tc.c

@@ -6,6 +6,37 @@
  * Change Logs:
  * Date           Author       Notes
  */
+
+/**
+ * Test Case Name: RT-Thread Mutex Priority Inheritance & Timeout Behavior Test
+ * Test Objectives:
+ * - Verify RT-Thread mutex behavior under priority inheritance (PI)
+ * - Validate timeout, wake-up, chained mutex dependency, and recursive PI updates
+ * - Test APIs: rt_mutex_init/detach, rt_mutex_take/trytake/release,
+ *   rt_thread_create/startup, rt_thread_resume, rt_timer usage
+ * Test Scenarios:
+ * - Multiple threads contending for shared mutexes with different priorities
+ * - Main thread holding chained mutexes to trigger multi-level PI updates
+ * - Mutex timeout behavior (RT_ETIMEOUT) with concurrent holder priority changes
+ * - Wake-up of a waiting high-priority thread via external resume event
+ * - Recursive dependency chain causing full-chain PI propagation and restoration
+ * Verification Metrics:
+ * - Correct return codes (RT_EOK, -RT_ETIMEOUT, -RT_EINTR)
+ * - Correct priority inheritance and rollback to init_priority
+ * - Expected thread scheduling order and priority transitions
+ * - All synchronization flags increment to expected values
+ * Dependencies:
+ * - RT-Thread kernel with mutex and IPC components enabled
+ * - Preemptive scheduler with priority-based dispatching
+ * - System tick timer accuracy for delay/timeout verification
+ * - Sufficient thread stack size for multi-thread test
+ * Expected Results:
+ * - PI activates and restores correctly across simple and recursive mutex chains
+ * - Timeout and wake-up tests return expected error codes
+ * - All test units complete successfully with correct thread priorities
+ * - Console/log confirms all UTEST cases pass
+ */
+
 #define __RT_IPC_SOURCE__
 
 #include <rtthread.h>

src/utest/mutex_tc.c

@@ -8,6 +8,37 @@
  * 2021-09.01     luckyzjq     the first version
  * 2023-09-15     xqyjlj       change stack size in cpu64
  */
+
+/**
+ * Test Case Name: RT-Thread Mutex Functional and Scheduling Validation
+ * Test Objectives:
+ * - Verify correctness of static and dynamic mutex operations
+ * - Validate priority inheritance, recursive locking, timeout handling, and error cases
+ * - Test core mutex APIs: rt_mutex_init/detach, rt_mutex_create/delete,
+ *   rt_mutex_take/trytake/release, and related thread scheduling functions
+ * Test Scenarios:
+ * - Mutex acquisition under contention with multi-thread scheduling
+ * - Try-take on locked mutex, timeout-based take, recursive take sequence
+ * - Priority inheritance when high-priority threads are blocked by lower-priority holders
+ * - Behavior differences between static and dynamic mutexes
+ * - Mutex release error handling, invalid release, and cleanup
+ * Verification Metrics:
+ * - Correct return codes for all mutex operations (RT_EOK, timeouts, error states)
+ * - Proper priority inheritance and restoration during contention
+ * - Expected thread wake-up and state transition behavior
+ * - Successful thread synchronization via _sync_flag
+ * Dependencies:
+ * - RT-Thread kernel with IPC and mutex support enabled
+ * - Heap availability when testing dynamic mutex creation
+ * - Scheduler operating normally with multi-thread preemption
+ * - Accurate system tick for timeout and delay validation
+ * Expected Results:
+ * - All mutex APIs behave according to RT-Thread specifications
+ * - Static and dynamic mutex tests complete successfully
+ * - Priority inversion resolved via priority inheritance
+ * - Console/log output indicates all UTEST cases pass
+ */
+
 #define __RT_IPC_SOURCE__
 
 #include <rtthread.h>