[utest][IPC]:Add standardized documentation for IPC Completion Test and IPC Workqueue Test

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)

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.
+ *
+ * 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.
  *
- * Test APIs:
- * - rt_completion_init()
- * - rt_completion_wakeup()
- * - rt_completion_wait_flags()
+ * 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)

components/drivers/ipc/utest/workqueue_tc.c

@@ -7,8 +7,44 @@
  * Date           Author       Notes
  * 2021-02-06     tyx          first commit
  * 2024-12-31     rbb666       Adding Test Cases
+ * 2025-11-16     ChuanN-sudo  add standardized utest documentation block
  */
 
+/**
+ * Test Case Name: IPC Workqueue Test
+ *
+ * Test Objectives:
+ * - Validate rt_workqueue creation, task submission, and execution mechanisms.
+ * - Verify ordered execution of work items under concurrent submission scenarios.
+ * - Ensure proper handling of task dependencies and resource cleanup during workqueue termination.
+ * - Test core APIs: rt_workqueue_create(), rt_workqueue_submit(), rt_workqueue_cancel()
+ *
+ * Test Scenarios:
+ * - Multiple threads submit periodic work items with varying delays to simulate real-world workloads.
+ * - Workqueue processes tasks in FIFO order while handling dynamic task cancellations.
+ * - Test injects random scheduling delays and priority inversions to stress-test queue stability.
+ * - Concurrent submission of high-priority and normal-priority work items to verify scheduling fairness.
+ * - System triggers asynchronous workqueue destruction during active task processing.
+ *
+ * Verification Metrics:
+ * - Submitted work items execute exactly once with correct parameter context.
+ * - Task execution order preserves submission sequence under normal scheduling conditions.
+ * - Cancelled tasks are safely removed from queue without execution or memory leaks.
+ * - Workqueue resource cleanup completes successfully even with pending operations.
+ * - Asynchronous destruction of workqueue handles active tasks gracefully without corruption.
+ *
+ * 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_WORKQUEUE must be enabled (enable via: RT-Thread Utestcases -> Kernel Components -> Drivers -> IPC Test -> IPC Workqueue Test).
+ * - Environmental Assumptions: System scheduler working normally.
+ *
+ * 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.
+ */
 #include "rtthread.h"
 #include "rtdevice.h"
 #include "utest.h"