From c4b229b5f4d21bb28b8b087693a5b7deb1d3d293 Mon Sep 17 00:00:00 2001 From: Chuan Date: Mon, 24 Nov 2025 23:01:39 +0800 Subject: [PATCH] [utest][serial bypass]:Add standardized documentation for Serial Bypass Test --- .../serial/utest/bypass/bypass_conflict.c | 39 +++++++++++++++++++ .../serial/utest/bypass/bypass_lower_run.c | 35 +++++++++++++++++ .../serial/utest/bypass/bypass_register.c | 39 +++++++++++++++++++ .../serial/utest/bypass/bypass_upper_run.c | 36 +++++++++++++++++ 4 files changed, 149 insertions(+) diff --git a/components/drivers/serial/utest/bypass/bypass_conflict.c b/components/drivers/serial/utest/bypass/bypass_conflict.c index 7b38fd77264..421c83b5d9f 100644 --- a/components/drivers/serial/utest/bypass/bypass_conflict.c +++ b/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 #include #include "utest.h" diff --git a/components/drivers/serial/utest/bypass/bypass_lower_run.c b/components/drivers/serial/utest/bypass/bypass_lower_run.c index 182853cef4d..37fab0b5b4b 100644 --- a/components/drivers/serial/utest/bypass/bypass_lower_run.c +++ b/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 #include #include "utest.h" diff --git a/components/drivers/serial/utest/bypass/bypass_register.c b/components/drivers/serial/utest/bypass/bypass_register.c index 17e6e4aa47c..2859161d47f 100644 --- a/components/drivers/serial/utest/bypass/bypass_register.c +++ b/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 #include #include "utest.h" diff --git a/components/drivers/serial/utest/bypass/bypass_upper_run.c b/components/drivers/serial/utest/bypass/bypass_upper_run.c index b3050e98815..e9446c56299 100644 --- a/components/drivers/serial/utest/bypass/bypass_upper_run.c +++ b/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 #include #include "utest.h"