[utest] Add standardized doc blocks for mm and lwp test cases

examples/utest/testcases/lwp/condvar_broadcast_tc.c

@@ -6,6 +6,40 @@
  * Change Logs:
  * Date           Author       Notes
  * 2023-11-20     Shell        add test suites
+ * 2026-03-19     cl2t         Add standardized utest documentation block
+ */
+
+/**
+ * Test Case Name: Condition Variable Broadcast Test
+ *
+ * Test Objectives:
+ * - Verify that rt_condvar_broadcast() correctly wakes up all threads
+ *   waiting on a condition variable.
+ * - Test core APIs: rt_condvar_broadcast(), rt_condvar_timedwait(),
+ *   rt_mutex_take(), rt_mutex_release(), rt_mutex_get_owner().
+ *
+ * Test Scenarios:
+ * - Creates 8 worker threads, each acquiring a mutex and then waiting on
+ *   a condition variable via rt_condvar_timedwait().
+ * - The main thread calls rt_condvar_broadcast() to wake all waiters.
+ * - Each woken thread verifies it re-acquired the mutex, increments a
+ *   counter, and releases the mutex.
+ * - The main thread verifies all 8 threads were successfully woken.
+ *
+ * Verification Metrics:
+ * - All waiting threads must be woken after broadcast (waken_num == THREAD_NUM).
+ * - Each woken thread must hold the mutex (verified via rt_mutex_get_owner()).
+ * - rt_condvar_timedwait() must return 0 on successful wake.
+ * - Mutex release must succeed for each woken thread.
+ *
+ * Dependencies:
+ * - Software configuration: RT_USING_SMART must be enabled.
+ * - Environmental assumptions: The platform must support multi-threading
+ *   with at least 8 concurrent threads.
+ *
+ * Expected Results:
+ * - Final output: "[ PASSED ] [ result ] testcase (testcases.ipc.condvar.broadcast)"
+ * - No assertion failures during test execution.
  */
 
 #include "common.h"

examples/utest/testcases/lwp/condvar_signal_tc.c

@@ -6,6 +6,40 @@
  * Change Logs:
  * Date           Author       Notes
  * 2023-11-20     Shell        add test suites
+ * 2026-03-19     cl2t         Add standardized utest documentation block
+ */
+
+/**
+ * Test Case Name: Condition Variable Signal Test
+ *
+ * Test Objectives:
+ * - Verify that rt_condvar_signal() correctly wakes up a single thread
+ *   waiting on a condition variable.
+ * - Test core APIs: rt_condvar_signal(), rt_condvar_timedwait(),
+ *   rt_mutex_take(), rt_mutex_release(), rt_thread_create().
+ *
+ * Test Scenarios:
+ * - The main thread acquires a mutex, creates a waker thread, then waits
+ *   on a condition variable with a 100-tick timeout.
+ * - The waker thread acquires the mutex and calls rt_condvar_signal() to
+ *   wake the main thread.
+ * - The main thread verifies it was woken successfully and releases the
+ *   mutex.
+ *
+ * Verification Metrics:
+ * - rt_condvar_signal() must return 0 on success.
+ * - rt_condvar_timedwait() must return 0 when signaled before timeout.
+ * - Timeout (-ETIMEDOUT) or interrupt (-EINTR) are acceptable non-fatal
+ *   outcomes.
+ * - Mutex acquire and release must succeed without errors.
+ *
+ * Dependencies:
+ * - Software configuration: RT_USING_SMART must be enabled.
+ * - Environmental assumptions: The platform must support multi-threading.
+ *
+ * Expected Results:
+ * - Final output: "[ PASSED ] [ result ] testcase (testcases.ipc.condvar.signal)"
+ * - No assertion failures during test execution.
  */
 
 #include "common.h"

examples/utest/testcases/lwp/condvar_timedwait_tc.c

@@ -6,6 +6,38 @@
  * Change Logs:
  * Date           Author       Notes
  * 2023-11-20     Shell        add test suites
+ * 2026-03-19     cl2t         Add standardized utest documentation block
+ */
+
+/**
+ * Test Case Name: Condition Variable Timed Wait Test
+ *
+ * Test Objectives:
+ * - Verify that rt_condvar_timedwait() correctly times out when no signal
+ *   is received within the specified timeout period.
+ * - Test core APIs: rt_condvar_timedwait(), rt_mutex_take(),
+ *   rt_mutex_init(), rt_condvar_init().
+ *
+ * Test Scenarios:
+ * - The main thread acquires a mutex and calls rt_condvar_timedwait()
+ *   with a 100-tick timeout.
+ * - Since no other thread signals the condition variable, the call is
+ *   expected to time out with -ETIMEDOUT or be interrupted with -EINTR.
+ *
+ * Verification Metrics:
+ * - rt_condvar_timedwait() must return -ETIMEDOUT or -EINTR when no
+ *   signal is received.
+ * - Any other non-zero return value indicates a test failure.
+ * - Mutex initialization and acquisition must succeed.
+ *
+ * Dependencies:
+ * - Software configuration: RT_USING_SMART must be enabled.
+ * - Environmental assumptions: The platform must support condition
+ *   variables and mutexes.
+ *
+ * Expected Results:
+ * - Final output: "[ PASSED ] [ result ] testcase (testcases.ipc.condvar.timedwait)"
+ * - No assertion failures during test execution.
  */
 
 #include "common.h"

examples/utest/testcases/mm/mm_memblock_tc.c

@@ -6,6 +6,42 @@
  * Change Logs:
  * Date           Author       Notes
  * 2023-09-28     zmshahaha    the first version
+ * 2026-03-19     cl2t         Add standardized utest documentation block
+ */
+
+/**
+ * Test Case Name: Memory Block Management Test
+ *
+ * Test Objectives:
+ * - Validate the memblock subsystem for early boot memory region management.
+ * - Test core APIs: rt_memblock_add_memory(), rt_memblock_reserve_memory(),
+ *   rt_memblock_merge(), rt_memblock_next_free_region().
+ *
+ * Test Scenarios:
+ * - Add Test (test_memblock_add): Verifies adding memory regions in various
+ *   configurations including simple addition, adjacent regions (top/bottom),
+ *   insertion between existing regions, and merging of contiguous regions
+ *   with the same flags.
+ * - Reserve Test (test_memblock_reserve): Verifies reserving memory within
+ *   existing regions at start/end positions, multiple reservations within
+ *   a single region, and large reservations spanning multiple regions.
+ *   Also validates free region iteration with MEMBLOCK_NOMAP filtering.
+ *
+ * Verification Metrics:
+ * - Region count after add/merge operations matches expected value.
+ * - Region start/end addresses and flags are correctly maintained.
+ * - Merge correctly combines adjacent regions with identical flags.
+ * - Free region iterator correctly skips reserved and NOMAP regions.
+ *
+ * Dependencies:
+ * - Software configuration: RT_USING_SMART and RT_UTEST_MM_MEMBLOCK must
+ *   be enabled.
+ * - Environmental assumptions: MMU support must be available on the target
+ *   platform.
+ *
+ * Expected Results:
+ * - Final output: "[ PASSED ] [ result ] testcase (testcases.mm.memblock_tc)"
+ * - No assertion failures during test execution.
  */
 
 #include <mm_memblock.h>

examples/utest/testcases/mm/rt_ioremap.c

@@ -7,6 +7,37 @@
  * Date           Author       Notes
  * 2022-12-14     WangXiaoyao  the first version
  * 2023-03-20     WangXiaoyao  Format & add more testcases for API under mm_aspace.h
+ * 2026-03-19     cl2t         Add standardized utest documentation block
+ */
+
+/**
+ * Test Case Name: I/O Remap Test
+ *
+ * Test Objectives:
+ * - Verify the rt_ioremap_cached() API for mapping physical addresses to
+ *   virtual addresses with cached memory access.
+ * - Test core APIs: rt_pages_alloc(), rt_ioremap_cached(), rt_iounmap(),
+ *   rt_pages_free().
+ *
+ * Test Scenarios:
+ * - Allocates a physical page (4KB), maps it to a virtual address using
+ *   rt_ioremap_cached(), verifies data consistency between the physical
+ *   and virtual addresses, then unmaps and frees the resources.
+ *
+ * Verification Metrics:
+ * - The value read through the virtual address must equal the value at the
+ *   corresponding physical address.
+ * - No memory leaks after unmap and free operations (validated via
+ *   CONSIST_HEAP wrapper).
+ *
+ * Dependencies:
+ * - Software configuration: RT_USING_SMART must be enabled.
+ * - Environmental assumptions: MMU support must be available on the target
+ *   platform.
+ *
+ * Expected Results:
+ * - Final output: "[ PASSED ] [ result ] testcase (testcases.mm.ioremap)"
+ * - No assertion failures during test execution.
  */
 
 #include "common.h"