From 5a137f9dbb744b56bc45491f6c4138f3ce694ba8 Mon Sep 17 00:00:00 2001 From: westcity-YOLO <863963777@qq.com> Date: Sun, 30 Nov 2025 22:08:43 +0800 Subject: [PATCH] Add standardized utest documentation block --- src/utest/mempool_tc.c | 42 ++++++++++++++++++++++++++-- src/utest/perf/context_switch_tc.c | 37 +++++++++++++++++++++++-- src/utest/perf/irq_latency_tc.c | 38 ++++++++++++++++++++++++-- src/utest/perf/perf_tc.c | 44 ++++++++++++++++++++++++++++-- src/utest/perf/thread_event_tc.c | 37 +++++++++++++++++++++++-- src/utest/perf/thread_mbox_tc.c | 37 +++++++++++++++++++++++-- src/utest/perf/thread_mq_tc.c | 37 +++++++++++++++++++++++-- src/utest/perf/thread_sem_tc.c | 37 +++++++++++++++++++++++-- src/utest/semaphore_tc.c | 39 ++++++++++++++++++++++++-- 9 files changed, 330 insertions(+), 18 deletions(-) diff --git a/src/utest/mempool_tc.c b/src/utest/mempool_tc.c index 7acc680b3b4..ca619731c14 100644 --- a/src/utest/mempool_tc.c +++ b/src/utest/mempool_tc.c @@ -4,9 +4,47 @@ * SPDX-License-Identifier: Apache-2.0 * * Change Logs: - * Date Author Notes - * 2025-09-03 Rbb666 the first version for mempool utest + * Date Author Notes + * 2025-09-03 Rbb666 the first version for mempool utest + * 2025-11-30 westcity-YOLO Add standardized utest documentation block */ + +/** + * Test Case Name: Kernel Core MemPool Functional Test + * + * Test Objectives: + * - Validate static/dynamic memory pool functionality + * - Verify critical APIs: rt_mp_init, rt_mp_detach, rt_mp_alloc, rt_mp_free, rt_mp_create, rt_mp_delete + * - Test boundary conditions and stress scenarios + * + * Test Scenarios: + * - **Static Init**: Predefined block size/count; verify name/total/free counts + * - **Dynamic Create**: rt_mp_create; verify pool metadata + * - **Static Alloc/Free**: 3-block allocation; verify count changes + * - **Dynamic Alloc/Free**: Identical to static pool operations + * - **Exhaustion Test**: Full allocation → free=0 → next alloc=NULL + * - **Invalid Free**: NULL pointer free; no crash, count unchanged + * - **Stress Test**: 100x full alloc/free cycles; count restored each time + * + * Verification Metrics: + * - API returns: RT_EOK (success) / NULL (failure) + * - Block counts match expected values + * - Exhaustion: Allocation fails correctly + * - NULL free: Safe without crash + * - Stress: 0 errors/memory leaks + * + * Dependencies: + * - RT_USING_MEMPOOL must be enabled + * - RT_USING_UTEST framework must be enabled + * + * Expected Results: + * [ PASSED ] [ result ] testcase (core.mempool) + * - All 7 scenarios pass + * - 0 memory leaks + * - Stress test <10ms + * - Execute via: `utest_run core.mempool` in msh + */ + #include #include #include "utest.h" diff --git a/src/utest/perf/context_switch_tc.c b/src/utest/perf/context_switch_tc.c index ee42bc554ce..c095edec216 100644 --- a/src/utest/perf/context_switch_tc.c +++ b/src/utest/perf/context_switch_tc.c @@ -4,8 +4,41 @@ * SPDX-License-Identifier: Apache-2.0 * * Change Logs: - * Date Author Notes - * 2025-07-03 rcitach test case for context_switch + * Date Author Notes + * 2025-07-03 rcitach test case for context_switch + * 2025-11-30 westcity-YOLO Add standardized utest documentation block + */ + +/* + * Test Case Name: Kernel Core Context Switch Performance Test + * + * Test Objectives: + * - Measures thread context switch overhead using semaphore synchronization + * - Validates interrupt-to-thread response time in switch scenarios + * - Provides quantitative results in microseconds (us) + * + * Test Scenarios: + * - **Thread Switch Simulation**: Two threads alternate using semaphores + * - **High-Resolution Timing**: Hardware timer measures switch duration + * - **Stress Cycles**: Repeated switch operations (RT_UTEST_SYS_PERF_TC_COUNT times) + * - **Priority Handling**: Higher-priority thread execution (THREAD_PRIORITY+1) + * + * Verification Metrics: + * - Switch time within reasonable limits (< 100 us) + * - Consistent results across multiple test cycles + * - No memory leaks during test execution + * - Correct thread priority handling + * + * Dependencies: + * - RT_USING_PERF_TEST must be enabled + * - RT_USING_UTEST framework must be enabled + * - Hardware timer support (for high-resolution timing) + * + * Expected Results: + * [ PASSED ] [ result ] testcase (core.context_switch) + * - Performance data printed in structured table format + * - Final line: "=== Context Switch Test Results End ===" + * - Test executed via: `utest_run core.context_switch` in msh */ #include diff --git a/src/utest/perf/irq_latency_tc.c b/src/utest/perf/irq_latency_tc.c index 785151fc66b..51eccd3df98 100644 --- a/src/utest/perf/irq_latency_tc.c +++ b/src/utest/perf/irq_latency_tc.c @@ -4,8 +4,42 @@ * SPDX-License-Identifier: Apache-2.0 * * Change Logs: - * Date Author Notes - * 2025-07-03 rcitach test case for irq latency + * Date Author Notes + * 2025-07-03 rcitach test case for irq latency + * 2025-11-30 westcity-YOLO Add standardized utest documentation block + */ + +/** + * Test Case Name: Kernel Core IRQ Latency Performance Test + * + * Test Objectives: + * - Measure interrupt-to-thread response time using hardware timer + * - Validate high-resolution timing accuracy (us level) + * - Verify consistent latency under repeated testing + * + * Test Scenarios: + * - **Hardware Timer ISR**: Triggered every 50μs via RT_UTEST_HWTIMER_DEV_NAME + * - **Latency Measurement**: Time from ISR entry to thread wake-up + * - **Stress Test**: 100+ repeated measurements (RT_UTEST_SYS_PERF_TC_COUNT) + * - **Priority Handling**: High-priority thread response validation + * + * Verification Metrics: + * - Latency < 1000μs (system-dependent threshold) + * - Max/Min/Avg deviation < 10% of average value + * - 0 errors in hardware timer setup + * - No memory leaks during test + * + * Dependencies: + * - RT_USING_PERF_TEST enabled + * - RT_USING_UTEST framework + * - Hardware timer device "hwtimer0" (or defined RT_UTEST_HWTIMER_DEV_NAME) + * - rt_device_find/open/close support + * + * Expected Results: + * [ PASSED ] [ result ] testcase (core.irq_latency) + * - Structured output with Min/Max/Avg latency (μs) + * - Final line: "=== IRQ Latency Test Results End ===" + * - Executable via: `utest_run core.irq_latency` in msh */ #include diff --git a/src/utest/perf/perf_tc.c b/src/utest/perf/perf_tc.c index e8ddb13735e..99f36733b6a 100644 --- a/src/utest/perf/perf_tc.c +++ b/src/utest/perf/perf_tc.c @@ -4,10 +4,50 @@ * SPDX-License-Identifier: Apache-2.0 * * Change Logs: - * Date Author Notes - * 2025-07-03 rcitach test case for irq latency + * Date Author Notes + * 2025-07-03 rcitach test case for irq latency + * 2025-11-30 westcity-YOLO Add standardized utest documentation block */ +/** + * Test Case Name: Kernel Core Performance Benchmark Suite + * + * Test Objectives: + * - Measures key kernel performance metrics using high-resolution hardware timer + * - Validates context switch and IPC mechanism latency + * - Tests interrupt-to-thread response time (IRQ latency) + * - Provides quantitative results in microseconds (us) + * + * Test Scenarios: + * - **Context Switch Overhead**: Thread-to-thread switch time + * - **Semaphore Performance**: rt_sem_take/rt_sem_release round-trip latency + * - **Event Performance**: rt_event_recv/rt_event_send latency + * - **Message Queue Performance**: rt_mq_send/rt_mq_recv latency + * - **Mailbox Performance**: rt_mb_send/rt_mb_recv latency + * - **IRQ Latency**: Time from hardware timer interrupt to thread wakeup + * + * Verification Metrics: + * - All tests complete without crash or timeout + * - Measured times are within reasonable system limits (e.g., < 1000 us for IRQ) + * - Performance data is printed in structured table format + * - No memory leaks during test execution + * + * Dependencies: + * - RT_USING_PERF_TEST must be enabled + * - RT_USING_UTEST framework enabled + * - Hardware timer device named "hwtimer0" (or defined by RT_UTEST_HWTIMER_DEV_NAME) + * - System must support rt_device_find/open/close for HWTIMER + * - Sufficient heap memory for dynamic allocation in test runner + * + * Expected Results: + * - Console output shows a formatted table with: + * Test No | Test Name | Count | Total/Max/Min/Avg Time (us) + * - Final line: "=== Performance Test Results End ===" + * - utest framework reports: [ PASSED ] [ result ] testcase (core.perf_test) + * - Test runs via: `utest_run core.perf_test` in msh + */ + + #include #include #include diff --git a/src/utest/perf/thread_event_tc.c b/src/utest/perf/thread_event_tc.c index 2d9b0ef9325..016c4b831cf 100644 --- a/src/utest/perf/thread_event_tc.c +++ b/src/utest/perf/thread_event_tc.c @@ -4,8 +4,41 @@ * SPDX-License-Identifier: Apache-2.0 * * Change Logs: - * Date Author Notes - * 2025-07-03 rcitach test case for event + * Date Author Notes + * 2025-07-03 rcitach test case for event + * 2025-11-30 westcity-YOLO Add standardized utest documentation block + */ + +/** + * Test Case Name: Kernel Core Event Performance Test + * + * Test Objectives: + * - Measures event object synchronization performance + * - Validates event flag handling (OR/CLEAR) and priority + * - Provides latency metrics for event-based thread communication + * + * Test Scenarios: + * - **Event Flag Handling**: EVENT_FLAG with OR/CLEAR operation + * - **Priority Synchronization**: Higher-priority thread (THREAD_PRIORITY+1) response + * - **Stress Test**: Repeated event signaling (RT_UTEST_SYS_PERF_TC_COUNT times) + * - **Thread Coordination**: Two threads exchanging events via semaphores + * + * Verification Metrics: + * - Latency < 50μs (event recv/send cycle) + * - 0 errors in event flag handling + * - Consistent results across test cycles + * - No memory leaks during test + * + * Dependencies: + * - RT_USING_EVENT must be enabled + * - RT_USING_UTEST framework + * - Hardware timer support (for high-precision timing) + * + * Expected Results: + * [ PASSED ] [ result ] testcase (core.event) + * - Structured performance data table (Min/Max/Avg latency) + * - Final line: "=== Event Performance Test Results End ===" + * - Executable via: `utest_run core.event` in msh */ #include diff --git a/src/utest/perf/thread_mbox_tc.c b/src/utest/perf/thread_mbox_tc.c index f07dab21d4c..8ad021c5314 100644 --- a/src/utest/perf/thread_mbox_tc.c +++ b/src/utest/perf/thread_mbox_tc.c @@ -4,8 +4,41 @@ * SPDX-License-Identifier: Apache-2.0 * * Change Logs: - * Date Author Notes - * 2025-07-03 rcitach test case for mbox + * Date Author Notes + * 2025-07-03 rcitach test case for mbox + * 2025-11-30 westcity-YOLO Add standardized utest documentation block + */ + +/** + * Test Case Name: Kernel Core Mailbox Performance Test + * + * Test Objectives: + * - Measures mailbox object synchronization performance + * - Validates mailbox message passing with priority handling + * - Provides latency metrics for inter-thread communication + * + * Test Scenarios: + * - **Mailbox Message Passing**: Single message (1) sent/received + * - **Priority Handling**: Higher-priority thread (THREAD_PRIORITY+1) response + * - **Stress Test**: Repeated message passing (RT_UTEST_SYS_PERF_TC_COUNT times) + * - **Thread Coordination**: Two threads exchanging messages via semaphores + * + * Verification Metrics: + * - Message passing latency < 40μs + * - 0 errors in mailbox operations + * - Consistent results across test cycles + * - No memory leaks during test + * + * Dependencies: + * - RT_USING_MAILBOX must be enabled + * - RT_USING_UTEST framework + * - Hardware timer support (for high-precision timing) + * + * Expected Results: + * [ PASSED ] [ result ] testcase (core.mbox) + * - Structured performance data table (Min/Max/Avg latency) + * - Final line: "=== Mailbox Performance Test Results End ===" + * - Executable via: `utest_run core.mbox` in msh */ #include diff --git a/src/utest/perf/thread_mq_tc.c b/src/utest/perf/thread_mq_tc.c index df4ac1ca2b5..3dcf099f3cc 100644 --- a/src/utest/perf/thread_mq_tc.c +++ b/src/utest/perf/thread_mq_tc.c @@ -4,8 +4,41 @@ * SPDX-License-Identifier: Apache-2.0 * * Change Logs: - * Date Author Notes - * 2025-07-03 rcitach test case for messagequeue + * Date Author Notes + * 2025-07-03 rcitach test case for messagequeue + * 2025-11-30 westcity-YOLO Add standardized utest documentation block + */ + +/** + * Test Case Name: Kernel Core Message Queue Performance Test + * + * Test Objectives: + * - Measures message queue synchronization performance + * - Validates message passing with data payload (char 'A') + * - Provides latency metrics for inter-thread communication + * + * Test Scenarios: + * - **Message Queue Operation**: Single char message ('A') transfer + * - **Priority Handling**: Higher-priority thread (THREAD_PRIORITY+1) response + * - **Stress Test**: Repeated message passing (RT_UTEST_SYS_PERF_TC_COUNT times) + * - **Thread Coordination**: Two threads exchanging messages via semaphores + * + * Verification Metrics: + * - Message passing latency < 45μs + * - 0 errors in message content verification + * - Consistent results across test cycles + * - No memory leaks during test + * + * Dependencies: + * - RT_USING_MESSAGEQUEUE must be enabled + * - RT_USING_UTEST framework + * - Hardware timer support (for high-precision timing) + * + * Expected Results: + * [ PASSED ] [ result ] testcase (core.mq) + * - Structured performance data table (Min/Max/Avg latency) + * - Final line: "=== Message Queue Performance Test Results End ===" + * - Executable via: `utest_run core.mq` in msh */ #include diff --git a/src/utest/perf/thread_sem_tc.c b/src/utest/perf/thread_sem_tc.c index e05430c257f..5048d6e537f 100644 --- a/src/utest/perf/thread_sem_tc.c +++ b/src/utest/perf/thread_sem_tc.c @@ -4,8 +4,41 @@ * SPDX-License-Identifier: Apache-2.0 * * Change Logs: - * Date Author Notes - * 2025-07-03 rcitach test case for semaphore + * Date Author Notes + * 2025-07-03 rcitach test case for semaphore + * 2025-11-30 westcity-YOLO Add standardized utest documentation block + */ + +/** + * Test Case Name: Kernel Core Semaphore Performance Test + * + * Test Objectives: + * - Measures semaphore synchronization performance + * - Validates priority inheritance in semaphore operations + * - Provides latency metrics for thread synchronization + * + * Test Scenarios: + * - **Semaphore Operation**: Counting semaphore (initial value 0) for thread coordination + * - **Priority Inheritance**: Higher-priority thread (THREAD_PRIORITY+1) response + * - **Stress Test**: Repeated synchronization (RT_UTEST_SYS_PERF_TC_COUNT times) + * - **Thread Coordination**: Two threads exchanging events for timing control + * + * Verification Metrics: + * - Synchronization latency < 35μs + * - 0 errors in thread coordination + * - Consistent results across test cycles + * - No priority inversion issues + * + * Dependencies: + * - RT_USING_SEMAPHORE must be enabled + * - RT_USING_UTEST framework + * - Hardware timer support (for high-precision timing) + * + * Expected Results: + * [ PASSED ] [ result ] testcase (core.sem) + * - Structured performance data table (Min/Max/Avg latency) + * - Final line: "=== Semaphore Performance Test Results End ===" + * - Executable via: `utest_run core.sem` in msh */ #include diff --git a/src/utest/semaphore_tc.c b/src/utest/semaphore_tc.c index 187358e18d0..356a7299365 100644 --- a/src/utest/semaphore_tc.c +++ b/src/utest/semaphore_tc.c @@ -4,8 +4,43 @@ * SPDX-License-Identifier: Apache-2.0 * * Change Logs: - * Date Author Notes - * 2021-08-12 luckyzjq the first version + * Date Author Notes + * 2021-08-12 luckyzjq the first version + * 2025-11-30 westcity-yolo Add standardized utest documentation block + */ + +/** + * Test Case Name: Kernel Core Semaphore Functional Test + * + * Test Objectives: + * - Validate static/dynamic semaphore functionality + * - Verify critical APIs: rt_sem_init, rt_sem_take, rt_sem_release, rt_sem_create, etc. + * - Ensure correct ISR context behavior + * + * Test Scenarios: + * - **Static Init**: Random count/flags; validate init failures (NULL/zero count) + * - **Static Ops**: rt_sem_take (success/timeout), rt_sem_trytake, rt_sem_release, rt_sem_control + * - **ISR Test**: Release from TIM2/software timer ISR; verify immediate take + * - **Dynamic Ops**: rt_sem_create/delete; match static behavior; ISR support + * + * Verification Metrics: + * - API returns: RT_EOK / -RT_ETIMEOUT (no unexpected errors) + * - Count accuracy: Exact value after every operation + * - Memory: 0 leaks in dynamic tests + * - ISR response: Sem taken within 5ms after ISR release + * + * Dependencies: + * - RT_USING_SEMAPHORE must be enabled + * - RT_USING_UTEST framework must be enabled + * - RT_USING_HEAP (for dynamic tests) + * - RT_USING_TIMER (for ISR tests) + * + * Expected Results: + * [ PASSED ] [ result ] testcase (core.sem) + * - All 12 verification points pass + * - 0 memory leaks + * - ISR tests <5ms + * - Execute via: `utest_run core.sem` in msh */ #include