diff --git a/components/drivers/ipc/utest/completion_tc.c b/components/drivers/ipc/utest/completion_tc.c index 4406153bdc..f9356db3ba 100644 --- a/components/drivers/ipc/utest/completion_tc.c +++ b/components/drivers/ipc/utest/completion_tc.c @@ -6,23 +6,40 @@ * Change Logs: * Date Author Notes * 2024-04-30 Shell init ver. + * 2025-11-16 ChuanN-sudo add standardized utest documentation block */ /** - * Test Case for rt_completion API + * Test Case Name: IPC Completion Basic Test * - * The test simulates a producer-consumer interaction where a producer thread - * generates data, and a consumer thread consumes the data after waiting for its - * availability using rt_completion synchronization primitives. + * Test Objectives: + * - Validate rt_completion initialization, wait, and wake-up mechanisms. + * - Verify thread synchronization in producer-consumer model. + * - Test core APIs: rt_completion_init(), rt_completion_wait_flags(), rt_completion_wakeup() * - * Test Criteria: - * - The producer should correctly increment the test data and signal - * completion. - * - The consumer should correctly wait for data update, consume it, and signal - * completion. + * Test Scenarios: + * - Producer thread generates incrementing data and notifies consumer. + * - Consumer thread waits for data updates and validates integrity. + * - Random delays simulate race conditions in synchronization. + * + * Verification Metrics: + * - The producer should correctly increment the test data and signal completion. + * - The consumer should correctly wait for data update, consume it, and signal completion. * - Data integrity should be maintained between producer and consumer. * - Synchronization is properly done so both can see consistent data. * - Random latency is introduced to simulate racing scenarios. + * + * Dependencies: + * - Hardware requirements: QEMU emulator or any hardware platform that supports RT-Thread. + * - Software configuration: + * - RT_USING_UTEST must be enabled (select "RT-Thread Utestcases" in menuconfig). + * - RT_UTEST_COMPLETION must be enabled (enable via: RT-Thread Utestcases -> Kernel Components -> Drivers -> IPC Test -> IPC Completion Test). + * - Environmental Assumptions: System scheduler working normally. + * + * Expected Results: + * - Progress logs: "[ INFO ] components.drivers.ipc.rt_completion_basic: Summary:...Test times:..." + * - Final output: "[ PASSED ] [ result ] testcase (components.drivers.ipc.rt_completion_basic)" + * - No assertions triggered. */ #define TEST_LATENCY_TICK (1) diff --git a/components/drivers/ipc/utest/completion_timeout_tc.c b/components/drivers/ipc/utest/completion_timeout_tc.c index b7f10959e0..8816c29de5 100644 --- a/components/drivers/ipc/utest/completion_timeout_tc.c +++ b/components/drivers/ipc/utest/completion_timeout_tc.c @@ -6,29 +6,43 @@ * Change Logs: * Date Author Notes * 2024-04-30 Shell init ver. + * 2025-11-16 ChuanN-sudo add standardized utest documentation block */ /** - * Test Case for rt_completion API + * Test Case Name: IPC Completion Timeout Test * - * The test simulates a producer-consumer interaction where a producer thread - * generates data, and a consumer thread consumes the data after waiting for its - * availability using rt_completion synchronization primitives. + * Test Objectives: + * - Validate rt_completion initialization, wait with timeout, and wake-up mechanisms. + * - Verify thread synchronization resilience in producer-consumer model under timing constraints. + * - Test core APIs: rt_completion_init(), rt_completion_wait_flags(), rt_completion_wakeup() + * - Verify proper handling of timeout and interrupt scenarios during synchronization. * - * Test Criteria: + * Test Scenarios: + * - Producer thread generates incrementing data with small delays between productions. + * - Consumer thread waits for data with timeout flags (RT_INTERRUPTIBLE) to simulate real-world interruptions. + * - Test deliberately introduces random thread yields to simulate scheduling variations. + * - Producer-consumer synchronization loop runs for extended duration to expose timing issues. + * - System handles asynchronous interruptions during wait operations. + * + * Verification Metrics: * - The producer produces data correctly and notifies the consumer thread. - * - The consumer receives data correctly and acknowledges receipt to the - * producer. + * - The consumer receives data correctly and acknowledges receipt to the producer. * - The producer and consumer threads synchronize their operations effectively. - * - Verify the correctness of data production and consumption between producer - * and consumer threads. - * - The asynchronous woken of consumer thread was handled properly so the - * consumer don't lose woken from producer. + * - Verify the correctness of data production and consumption between producer and consumer threads. + * - The asynchronous wakeup of consumer thread was handled properly so the consumer don't lose wakeup from producer. * - * Test APIs: - * - rt_completion_init() - * - rt_completion_wakeup() - * - rt_completion_wait_flags() + * Dependencies: + * - Hardware requirements: QEMU emulator or any hardware platform that supports RT-Thread. + * - Software configuration: + * - RT_USING_UTEST must be enabled (select "RT-Thread Utestcases" in menuconfig). + * - RT_UTEST_COMPLETION must be enabled (enable via: RT-Thread Utestcases -> Kernel Components -> Drivers -> IPC Test -> IPC Completion Test). + * - Environmental Assumptions: System clock interrupts and scheduler working normally. + * + * Expected Results: + * - Progress logs: "[ INFO ] components.drivers.ipc.rt_completion_timeout: Summary:...Test times:...Async interruption count:...". + * - Final output: "[ PASSED ] [ result ] testcase (components.drivers.ipc.rt_completion_timeout)". + * - No assertions triggered. */ #define TEST_LATENCY_TICK (1) diff --git a/components/drivers/ipc/utest/workqueue_tc.c b/components/drivers/ipc/utest/workqueue_tc.c index df03cb4d49..df8c93b962 100644 --- a/components/drivers/ipc/utest/workqueue_tc.c +++ b/components/drivers/ipc/utest/workqueue_tc.c @@ -42,8 +42,8 @@ * * Expected Results: * - Final output: "[ PASSED ] [ result ] testcase (components.drivers.ipc.workqueue_tc)" - * - No memory leaks or race condition detections in logs - * - No assertions triggered during test execution + * - No memory leaks or race condition detections in logs. + * - No assertions triggered during test execution. */ #include "rtthread.h" #include "rtdevice.h"