[utest][serial bypass]:Add standardized documentation for Serial Bypass Test

Author: ChuanN-sudo

components/drivers/serial/utest/bypass/bypass_conflict.c

@@ -6,7 +6,46 @@
  * Change Logs:
  * Date           Author       Notes
  * 2024-11-20     zhujiale     the first version
+ * 2025-11-24     ChuanN-sudo  add standardized utest documentation block
  */
+
+/**
+ * Test Case Name: Serial Bypass Conflict Test
+ *
+ * Test Objectives:
+ * - Validate serial device bypass mechanism under high-concurrency RX interrupt scenarios.
+ * - Verify thread-safe registration/unregistration of upper and lower bypass handlers.
+ * - Ensure correct data reception counting across concurrent ISR triggers and workqueue processing.
+ * - Test core APIs: rt_bypass_upper_register(), rt_bypass_upper_unregister(),
+ *      rt_bypass_lower_register(), rt_bypass_lower_unregister(), rt_hw_serial_isr().
+ *
+ * Test Scenarios:
+ * - bypass_rx_stress_001: Two threads simultaneously trigger RX ISRs with upper bypass handler registered.
+ *      Each thread generates 10 ISR events, expecting 200 total character receptions (10 chars per ISR × 10 ISRs × 2 threads).
+ * - bypass_rx_stress_002: Concurrent ISR triggering and workqueue processing with lower bypass handler.
+ *      Tests interaction between interrupt context and work queue context, expecting 100 total receptions.
+ * - bypass_rx_stress_003: High-priority thread (priority 15, numerically lower = higher priority) dynamically
+ *      registers/unregisters bypass handlers while low-priority thread (priority 20) continuously triggers RX ISRs.
+ *
+ * Verification Metrics:
+ * - Character reception counter matches expected values (200 for test_001, 100 for test_002, 200 for test_003).
+ * - No data loss occurs during concurrent handler registration/unregistration operations.
+ * - Atomic operations ensure thread-safe counter increments without race conditions.
+ * - Mock UART getc function correctly limits character generation to 10 per call sequence.
+ * - System remains stable during priority inversion scenarios (priority 15 vs 20 threads).
+ *
+ * Dependencies:
+ * - Hardware requirements: Platform with serial console device (UART) support.
+ * - Software configuration:
+ *     - RT_USING_UTESTCASES must be enabled (select "RT-Thread Utestcases" in menuconfig).
+ *     - RT_UTEST_SERIAL_BYPASS must be enabled (enable via: RT-Thread Utestcases -> Kernel Components -> Drivers -> Serial Test -> Serial Bypass Test).
+ * - Environmental Assumptions: Serial device initialized and operational before test execution.
+ *
+ * Expected Results:
+ * - Final output: "[ PASSED ] [ result ] testcase (components.drivers.serial.bypass_rx_stress)"
+ * - All atomic counter assertions pass with exact expected values.
+ */
+
 #include <rtthread.h>
 #include <rtdevice.h>
 #include "utest.h"

components/drivers/serial/utest/bypass/bypass_lower_run.c

@@ -6,7 +6,42 @@
  * Change Logs:
  * Date           Author       Notes
  * 2024-11-20     zhujiale     the first version
+ * 2025-11-24     ChuanN-sudo  add standardized utest documentation block
  */
+
+/**
+ * Test Case Name: Serial Bypass Lower Run Test
+ *
+ * Test Objectives:
+ * - Validate serial device bypass lower layer registration and data processing mechanisms.
+ * - Verify correct character reception and callback execution in bypass mode.
+ * - Test core APIs: rt_bypass_lower_register(), rt_bypass_lower_unregister(), rt_hw_serial_isr()
+ *
+ * Test Scenarios:
+ * - Register bypass lower layer callback to intercept serial RX data before normal processing.
+ * - Simulate hardware interrupt with custom getc function returning predefined character sequences.
+ * - Verify repeated character reception, counting mechanism and sequential character reception with incremental validation.
+ * - Temporarily replace serial device operations with mock implementations for controlled testing.
+ *
+ * Verification Metrics:
+ * - Bypass callback executes for each received character with correct character value.
+ * - Character validation assertions pass: bypass_lower_001 validates 10 'a' characters, bypass_lower_002 validates sequential characters 'b' to 'u'.
+ * - Mock getc function returns -1 after 10 iterations (bypass_lower_001) or 20 iterations (bypass_lower_002) to terminate reception.
+ * - Serial device operations restore to original state after test completion.
+ * - Bypass lower layer unregisters successfully without resource leaks.
+ *
+ * Dependencies:
+ * - Hardware requirements: Platform with serial console device (UART) support.
+ * - Software configuration:
+ *     - RT_USING_UTESTCASES must be enabled (select "RT-Thread Utestcases" in menuconfig).
+ *     - RT_UTEST_SERIAL_BYPASS must be enabled (enable via: RT-Thread Utestcases -> Kernel Components -> Drivers -> Serial Test -> Serial Bypass Test).
+ * - Environmental Assumptions: Serial device initialized and operational before test execution.
+ *
+ * Expected Results:
+ * - Final output: "[ PASSED ] [ result ] testcase (components.drivers.serial.bypass_lower)"
+ * - Character validation assertions pass for all test iterations.
+ */
+
 #include <rtthread.h>
 #include <rtdevice.h>
 #include "utest.h"

components/drivers/serial/utest/bypass/bypass_register.c

@@ -6,7 +6,46 @@
  * Change Logs:
  * Date           Author       Notes
  * 2024-11-20     zhujiale     the first version
+ * 2025-11-24     ChuanN-sudo  add standardized utest documentation block
  */
+
+/**
+ * Test Case Name: Serial Bypass Register Test
+ *
+ * Test Objectives:
+ * - Validate serial bypass function registration and unregistration mechanisms.
+ * - Verify correct ordering of bypass functions by priority level in concurrent scenarios.
+ * - Ensure thread-safe registration of upper and lower bypass handlers.
+ * - Test core APIs: rt_bypass_upper_register(), rt_bypass_lower_register(),
+ *   rt_bypass_upper_unregister(), rt_bypass_lower_unregister()
+ *
+ * Test Scenarios:
+ * - bypass_register_001: Main thread and worker thread concurrently register upper bypass
+ *   functions with even/odd priority levels to test insertion ordering and thread safety.
+ * - bypass_register_002: Two worker threads simultaneously register upper and lower bypass
+ *   functions with levels 1-9 to verify independent queue management.
+ * - Tests validate that registered functions maintain strict ascending order by level.
+ * - Unregistration operations verify complete cleanup of bypass function chains.
+ *
+ * Verification Metrics:
+ * - Bypass functions are inserted in correct priority order (level 0-9 ascending).
+ * - Concurrent registrations from multiple threads maintain list integrity.
+ * - Upper and lower bypass chains operate independently without interference.
+ * - All registered bypass functions can be successfully unregistered by level.
+ * - No memory leaks or list corruption after registration/unregistration cycles.
+ *
+ * Dependencies:
+ * - Hardware requirements: Platform with serial console device (UART) support.
+ * - Software configuration:
+ *     - RT_USING_UTESTCASES must be enabled (select "RT-Thread Utestcases" in menuconfig).
+ *     - RT_UTEST_SERIAL_BYPASS must be enabled (enable via: RT-Thread Utestcases -> Kernel Components -> Drivers -> Serial Test -> Serial Bypass Test).
+ * - Environmental Assumptions: Serial device initialized and operational before test execution.
+ *
+ * Expected Results:
+ * - Final output: "[ PASSED ] [ result ] testcase (components.drivers.serial.bypass_register)"
+ * - All uassert_true() checks pass, confirming correct level ordering.
+ */
+
 #include <rtthread.h>
 #include <rtdevice.h>
 #include "utest.h"

components/drivers/serial/utest/bypass/bypass_upper_run.c

@@ -6,7 +6,43 @@
  * Change Logs:
  * Date           Author       Notes
  * 2024-11-20     zhujiale     the first version
+ * 2025-11-24     ChuanN-sudo  add standardized utest documentation block
  */
+
+/**
+ * Test Case Name: Serial Bypass Upper Run Test
+ *
+ * Test Objectives:
+ * - Validate serial device bypass upper layer registration and data processing mechanisms.
+ * - Verify correct character reception and filtering through bypass callback functions.
+ * - Ensure proper handling of bypass level priorities and callback execution order.
+ * - Test core APIs: rt_bypass_upper_register(), rt_bypass_upper_unregister(), rt_hw_serial_isr()
+ *
+ * Test Scenarios:
+ * - Register bypass callback at RT_BYPASS_LEVEL_1 to intercept incoming serial data.
+ * - Verify bypass callback receives expected character values and executes correct number of times.
+ * - Register bypass callback at RT_BYPASS_MAX_LEVEL with different character sequence.
+ * - Test bypass unregistration and verify proper cleanup of callback handlers.
+ *
+ * Verification Metrics:
+ * - Bypass callback executes exactly 10 times for first test case with character 'a'.
+ * - Second test case processes 20 characters in ascending sequence ('b' to 'u').
+ * - Character values received in callback match expected values from mock getc function.
+ * - Bypass registration and unregistration complete without memory leaks or errors.
+ * - Serial device operations restore to original state after test completion.
+ *
+ * Dependencies:
+ * - Hardware requirements: Platform with serial console device (UART) support.
+ * - Software configuration:
+ *     - RT_USING_UTESTCASES must be enabled (select "RT-Thread Utestcases" in menuconfig).
+ *     - RT_UTEST_SERIAL_BYPASS must be enabled (enable via: RT-Thread Utestcases -> Kernel Components -> Drivers -> Serial Test -> Serial Bypass Test).
+ * - Environmental Assumptions: Serial device initialized and operational before test execution.
+ *
+ * Expected Results:
+ * - Final output: "[ PASSED ] [ result ] testcase (components.drivers.serial.bypass_upper)"
+ * - No assertions triggered during character validation or callback execution.
+ */
+
 #include <rtthread.h>
 #include <rtdevice.h>
 #include "utest.h"