diff --git a/examples/utest/testcases/lwp/condvar_broadcast_tc.c b/examples/utest/testcases/lwp/condvar_broadcast_tc.c index be35c60605..234ae697a1 100644 --- a/examples/utest/testcases/lwp/condvar_broadcast_tc.c +++ b/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" diff --git a/examples/utest/testcases/lwp/condvar_signal_tc.c b/examples/utest/testcases/lwp/condvar_signal_tc.c index 4bb65d423d..82129560eb 100644 --- a/examples/utest/testcases/lwp/condvar_signal_tc.c +++ b/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" diff --git a/examples/utest/testcases/lwp/condvar_timedwait_tc.c b/examples/utest/testcases/lwp/condvar_timedwait_tc.c index afd9418d56..43cfceb695 100644 --- a/examples/utest/testcases/lwp/condvar_timedwait_tc.c +++ b/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" diff --git a/examples/utest/testcases/mm/mm_memblock_tc.c b/examples/utest/testcases/mm/mm_memblock_tc.c index bf0d4ee1df..e99c951c76 100644 --- a/examples/utest/testcases/mm/mm_memblock_tc.c +++ b/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 diff --git a/examples/utest/testcases/mm/rt_ioremap.c b/examples/utest/testcases/mm/rt_ioremap.c index ca7f172b8e..d61dceec42 100644 --- a/examples/utest/testcases/mm/rt_ioremap.c +++ b/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"