[docs][utest]:Add standardized utest documentation block for serialv2_tc

components/drivers/serial/utest/v2/posix/uart_posix_echo_block.c

@@ -1,11 +1,39 @@
 /*
- * Copyright (c) 2006-2024 RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
  * Date           Author       Notes
  * 2021-06-16     KyleChan     the first version
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART POSIX Blocking Echo Test
+ *
+ * Test Objectives:
+ * - Validate POSIX blocking serial IO paths with multi-threaded send/receive verification
+ * - Verify APIs: open/close, tcgetattr/tcsetattr, cfsetispeed/cfsetospeed, fcntl clearing O_NONBLOCK,
+ *   read, write, rt_thread_create/startup
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Length Sweep Echo / tc_uart_api):**
+ *   1. Open POSIX serial device, configure canonical settings, and enforce blocking mode.
+ *   2. Launch sender/receiver threads; sender streams sequential byte patterns while receiver checks ordering until quota met.
+ *   3. Iterate through deterministic and random lengths, mirroring behavior of kernel-space blocking tests, and monitor global flags for errors.
+ *
+ * Verification Metrics:
+ * - Received data remains sequential; `uart_result` stays RT_TRUE; `uart_over_flag` raised after completion.
+ * - No termios or fcntl calls fail; thread creation succeeds.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2` with POSIX serial device `RT_SERIAL_POSIX_TC_DEVICE_NAME` looped back.
+ * - Host environment must provide POSIX termios/fcntl APIs; adequate heap for buffers and thread stacks.
+ *
+ * Expected Results:
+ * - Test completes without assertions; logs reflect pass counts for each payload length.
+ * - Utest harness prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_posix_echo_block)`.
  */
 
 #include <rtthread.h>

components/drivers/serial/utest/v2/posix/uart_posix_nonblock.c

@@ -1,11 +1,39 @@
 /*
- * Copyright (c) 2006-2024 RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
  * Date           Author       Notes
  * 2021-06-16     KyleChan     the first version
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART POSIX Non-Blocking Test
+ *
+ * Test Objectives:
+ * - Validate POSIX-layer non-blocking serial operations using termios configuration
+ * - Verify APIs: open/close, tcgetattr/tcsetattr, cfsetispeed/cfsetospeed, fcntl(O_NONBLOCK),
+ *   read, write, rt_thread_mdelay
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Non-Blocking Echo / tc_uart_api):**
+ *   1. Open POSIX device `RT_SERIAL_POSIX_TC_DEVICE_NAME`, configure baud, frame format, and disable flow control.
+ *   2. Enable O_NONBLOCK mode and allocate small TX/RX buffer.
+ *   3. Loop `RT_SERIAL_TC_SEND_ITERATIONS` times, issuing fixed-size and random-length writes, followed by reads after short delays to confirm echo data availability.
+ *
+ * Verification Metrics:
+ * - Each write/read pair returns the expected number of bytes.
+ * - No system calls fail; routine returns RT_TRUE signalling success.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2` with POSIX device exposure (`RT_SERIAL_POSIX_TC_DEVICE_NAME`) and loopback wiring.
+ * - Operating environment must provide termios/fcntl APIs (e.g., RT-Thread POSIX layer or Linux host).
+ *
+ * Expected Results:
+ * - Test executes without assertions; logs remain quiet unless errors occur.
+ * - Utest harness prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_posix_nonblock)`.
  */
 
 #include <rtthread.h>

components/drivers/serial/utest/v2/qemu/uart_qemu_echo.c

@@ -1,3 +1,42 @@
+/*
+ * Copyright (c) 2006-2025 RT-Thread Development Team
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Change Logs:
+ * Date           Author       Notes
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART QEMU Echo Loopback Test
+ *
+ * Test Objectives:
+ * - Validate dual-UART echo behavior under QEMU by cross-linking uart1 and uart2
+ * - Verify APIs: rt_device_find, rt_device_open, rt_device_write, rt_device_read,
+ *   rt_device_control(RT_SERIAL_CTRL_GET_UNREAD_BYTES_COUNT), rt_thread_create/startup
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Cross-Echo Stress / uart_test_nonblocking_tx):**
+ *   1. Open uart1/uart2 in blocking mode and spawn threads to mirror RX→TX on uart2 while recording statistics.
+ *   2. Simultaneously read uart1 in a dedicated thread to monitor inbound bytes.
+ *   3. Send random-length payloads up to 1 KB for 1000 iterations, periodically comparing TX/RX counters across both devices.
+ *   4. Signal threads to exit once validation completes and ensure device handles close cleanly.
+ *
+ * Verification Metrics:
+ * - u1/u2 TX and RX counters remain equal; send total matches aggregated transmit length.
+ * - No allocation failures; `echo_test()` returns RT_TRUE when counters align.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2` running under QEMU with uart1↔uart2 interconnected.
+ * - UART driver must support unread-bytes query and blocking modes.
+ * - Threads need 2 KB stacks; dynamic buffers sized at 1 KB per UART.
+ *
+ * Expected Results:
+ * - Test completes without assertions; logs show synchronized counter updates.
+ * - Utest harness prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_qemu_echo)`.
+ */
+
 #include <rtthread.h>
 #include <rtdevice.h>
 #include "utest.h"

components/drivers/serial/utest/v2/uart_blocking_rx.c

@@ -1,3 +1,40 @@
+/*
+ * Copyright (c) 2006-2025 RT-Thread Development Team
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Change Logs:
+ * Date           Author       Notes
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART Blocking Receive Echo Test
+ *
+ * Test Objectives:
+ * - Demonstrate blocking read semantics while capturing multiple user inputs
+ * - Verify APIs: rt_device_find, rt_device_open with RT_DEVICE_FLAG_RX_BLOCKING,
+ *   rt_device_read, rt_device_write, rt_device_close
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Interactive Echo / uart_test_blocking_rx):**
+ *   1. Restart UART in fully blocking RX/TX mode.
+ *   2. Prompt user (or loopback source) for data, then execute several blocking reads of identical size, echoing results to console.
+ *   3. Track cumulative bytes received and log progress after each read.
+ *
+ * Verification Metrics:
+ * - Each blocking read returns the requested buffer length; totals increment accordingly.
+ * - Test helper returns RT_TRUE once sequence completes.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2` with loopback or external stimulus on `RT_SERIAL_TC_DEVICE_NAME`.
+ * - UART driver must support blocking reads and repeated open/close operations.
+ *
+ * Expected Results:
+ * - No assertions triggered; console displays prompts and echo logs.
+ * - Utest harness prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_blocking_rx)`.
+ */
+
 #include <rtthread.h>
 #include <rtdevice.h>
 #include "utest.h"

components/drivers/serial/utest/v2/uart_blocking_tx.c

@@ -1,3 +1,41 @@
+/*
+ * Copyright (c) 2006-2025 RT-Thread Development Team
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Change Logs:
+ * Date           Author       Notes
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART Blocking Transmit Throughput Test
+ *
+ * Test Objectives:
+ * - Measure blocking transmit throughput across varied burst sizes
+ * - Verify APIs: rt_device_find, rt_device_open with RT_DEVICE_FLAG_TX_BLOCKING,
+ *   rt_device_write, rt_device_close, rt_tick_get
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Burst Size Sweep / uart_test_blocking_tx):**
+ *   1. Re-open the UART in blocking TX mode.
+ *   2. Perform 100 iterations of 1024-byte writes followed by single bursts of 8, 32, 128, 512, and 1024 bytes,
+ *      capturing elapsed ticks and bytes transferred.
+ *   3. Log throughput metrics for later comparison against non-blocking mode.
+ *
+ * Verification Metrics:
+ * - Each write call returns the full requested length; accumulated counts match expectations.
+ * - Timing data captured for every burst; helper returns RT_TRUE on success.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2` and loopback wiring on `RT_SERIAL_TC_DEVICE_NAME`.
+ * - UART driver must support blocking writes and open/close sequences.
+ *
+ * Expected Results:
+ * - Test finishes without assertions; logs show per-size timing statistics.
+ * - Utest harness prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_blocking_tx)`.
+ */
+
 #include <rtthread.h>
 #include <rtdevice.h>
 #include "utest.h"

components/drivers/serial/utest/v2/uart_flush_rx.c

@@ -1,11 +1,39 @@
 /*
- * Copyright (c) 2006-2024 RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
  * Date           Author       Notes
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART RX Buffer Flush Test
+ *
+ * Test Objectives:
+ * - Verify RX flush control clears buffered data and preserves integrity of subsequent transfers
+ * - Confirm APIs: rt_device_find, rt_device_control(RT_DEVICE_CTRL_CONFIG / RT_SERIAL_CTRL_RX_FLUSH),
+ *   rt_device_open with RT_DEVICE_FLAG_RX_NON_BLOCKING | RT_DEVICE_FLAG_TX_BLOCKING,
+ *   rt_device_read, rt_device_write
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Flush Validation / tc_uart_api):**
+ *   1. Configure UART buffers and allocate test pattern spanning multiple RX buffer lengths.
+ *   2. Send payload, consume a single byte, invoke RX flush, and ensure next read returns no residual data.
+ *   3. Resend partial payloads of varying sizes to confirm data after flush matches original pattern.
+ *
+ * Verification Metrics:
+ * - Initial read after flush returns zero bytes; subsequent reads match transmitted data byte-for-byte.
+ * - All iterations across deterministic and random lengths complete with RT_EOK.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2`, loopback wiring, and RX flush support on `RT_SERIAL_TC_DEVICE_NAME`.
+ * - Optional DMA ping buffer configuration honored when `RT_SERIAL_USING_DMA` enabled.
  *
+ * Expected Results:
+ * - No assertions triggered; logs show flush operations with payload sizes.
+ * - Utest harness prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_flush_rx)`.
  */
 
 #include <rtthread.h>

components/drivers/serial/utest/v2/uart_flush_txb.c

@@ -1,11 +1,39 @@
 /*
- * Copyright (c) 2006-2024 RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
  * Date           Author       Notes
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART TX Blocking Flush Test
+ *
+ * Test Objectives:
+ * - Validate TX flush completion timing in blocking mode and ensure subsequent RX integrity
+ * - Verify APIs: rt_device_find, rt_device_control(RT_DEVICE_CTRL_CONFIG / RT_SERIAL_CTRL_TX_FLUSH / _SET_TX_TIMEOUT / RT_SERIAL_CTRL_RX_FLUSH),
+ *   rt_device_open with RT_DEVICE_FLAG_RX_BLOCKING | RT_DEVICE_FLAG_TX_BLOCKING,
+ *   rt_device_write, rt_device_read
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Flush Timing & Data Integrity / tc_uart_api):**
+ *   1. Configure enlarged TX buffer and set TX timeout guard.
+ *   2. Perform multiple iterations with varied payload sizes (aligned and unaligned), recording ticks needed to flush queued bytes and verifying they fall within `[expect_time, expect_time + 10]`.
+ *   3. After each flush, resend small samples and confirm received data matches transmitted pattern.
+ *
+ * Verification Metrics:
+ * - `rt_device_write` returns full payload length; measured tick difference respects expected window.
+ * - Post-flush RX comparisons succeed for all sample sizes.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2` with hardware loopback and TX flush capability on `RT_SERIAL_TC_DEVICE_NAME`.
+ * - Optional DMA ping buffer configuration supported.
  *
+ * Expected Results:
+ * - Test completes without assertions; logs show flush durations per payload.
+ * - Utest harness prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_flush_txb)`.
  */
 
 #include <rtthread.h>

components/drivers/serial/utest/v2/uart_flush_txnb.c

@@ -1,11 +1,39 @@
 /*
- * Copyright (c) 2006-2024 RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
  * Date           Author       Notes
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART TX Non-Blocking Flush Test
+ *
+ * Test Objectives:
+ * - Validate flush completion timing for non-blocking transmit mode and verify subsequent RX integrity
+ * - Verify APIs: rt_device_find, rt_device_control(RT_DEVICE_CTRL_CONFIG / RT_SERIAL_CTRL_TX_FLUSH / _SET_TX_TIMEOUT / RT_SERIAL_CTRL_RX_FLUSH),
+ *   rt_device_open with RT_DEVICE_FLAG_RX_BLOCKING | RT_DEVICE_FLAG_TX_NON_BLOCKING,
+ *   rt_device_write, rt_device_read
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Flush Timing & Data Integrity / tc_uart_api):**
+ *   1. Configure UART with expanded buffer sizes and minimal TX timeout to emulate non-blocking semantics.
+ *   2. Iterate across varied payload lengths (including random lengths), measuring ticks between write and flush completion; ensure timing lies within expected band.
+ *   3. After each flush, resend small samples and check received bytes for equality.
+ *
+ * Verification Metrics:
+ * - Flushed transmissions complete within `[expect_time, expect_time + 10]` tick window.
+ * - Post-flush RX comparisons succeed for all sample sizes.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2`, loopback wiring, and TX flush support for non-blocking mode on `RT_SERIAL_TC_DEVICE_NAME`.
+ * - Optional DMA ping buffer configuration honored.
  *
+ * Expected Results:
+ * - Test runs without assertions; logs report flush timing per payload.
+ * - Utest harness prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_flush_txnb)`.
  */
 
 #include <rtthread.h>

components/drivers/serial/utest/v2/uart_get_unread_bytes_count.c

@@ -1,11 +1,39 @@
 /*
- * Copyright (c) 2006-2024 RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
  * Date           Author       Notes
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART Unread Bytes Count Test
+ *
+ * Test Objectives:
+ * - Validate query of unread RX bytes and flush interaction in non-blocking receive mode
+ * - Verify APIs: rt_device_find, rt_device_control(RT_DEVICE_CTRL_CONFIG / RT_SERIAL_CTRL_GET_UNREAD_BYTES_COUNT / RT_SERIAL_CTRL_RX_FLUSH),
+ *   rt_device_open with RT_DEVICE_FLAG_RX_NON_BLOCKING | RT_DEVICE_FLAG_TX_BLOCKING,
+ *   rt_device_write
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Unread Count Verification / tc_uart_api):**
+ *   1. Configure UART buffers and send varying payload lengths, some exceeding RX buffer capacity.
+ *   2. After each transfer, query unread byte count and ensure it saturates at `min(send_size, RT_SERIAL_TC_RXBUF_SIZE)`.
+ *   3. Flush RX buffer and verify unread count resets to zero before next iteration.
+ *
+ * Verification Metrics:
+ * - `RT_SERIAL_CTRL_GET_UNREAD_BYTES_COUNT` returns expected length; subsequent flush yields zero.
+ * - All iterations covering large and random payloads complete with RT_EOK.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2`, RX count control support, and loopback wiring on `RT_SERIAL_TC_DEVICE_NAME`.
+ * - Optional DMA ping buffer configuration honored.
  *
+ * Expected Results:
+ * - Test ends without assertions; logs may remain silent unless failures occur.
+ * - Utest harness prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_get_unread_bytes_count)`.
  */
 
 #include <rtthread.h>

components/drivers/serial/utest/v2/uart_nonblocking_rx.c

@@ -1,3 +1,40 @@
+/*
+ * Copyright (c) 2006-2025 RT-Thread Development Team
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Change Logs:
+ * Date           Author       Notes
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART Non-Blocking Receive Echo Test
+ *
+ * Test Objectives:
+ * - Demonstrate non-blocking receive behavior paired with blocking transmit output
+ * - Verify APIs: rt_device_find, rt_device_open with RT_DEVICE_FLAG_RX_NON_BLOCKING,
+ *   rt_device_read (non-blocking), rt_device_write, rt_device_close
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Interactive Echo / uart_test_nonblocking_rx):**
+ *   1. Restart UART in RX non-blocking / TX blocking mode.
+ *   2. Prompt user (or loopback peer) to send data while issuing countdown markers to MSH.
+ *   3. Perform successive non-blocking reads of varying sizes (256/128 bytes), echoing captured data back and logging totals.
+ *
+ * Verification Metrics:
+ * - Each read returns immediately with available data (may be zero); totals accumulate without overflow.
+ * - Function returns RT_TRUE after final log, indicating no failures during sequence.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2` with loopback or user-provided input on `RT_SERIAL_TC_DEVICE_NAME`.
+ * - UART driver must support non-blocking reads and reversible open/close.
+ *
+ * Expected Results:
+ * - No assertions triggered; terminal displays countdown prompts and mirrored input.
+ * - Utest harness prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_nonblocking_rx)`.
+ */
+
 #include <rtthread.h>
 #include <rtdevice.h>
 #include "utest.h"

components/drivers/serial/utest/v2/uart_nonblocking_tx.c

@@ -1,3 +1,41 @@
+/*
+ * Copyright (c) 2006-2025 RT-Thread Development Team
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Change Logs:
+ * Date           Author       Notes
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART Non-Blocking Transmit Throughput Test
+ *
+ * Test Objectives:
+ * - Measure and validate non-blocking transmit behavior across varying burst sizes
+ * - Verify APIs: rt_device_find, rt_device_open with RT_DEVICE_FLAG_TX_NON_BLOCKING,
+ *   rt_device_write, rt_device_close, rt_tick_get
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Burst Size Sweep / uart_test_nonblocking_tx):**
+ *   1. Re-open the UART in fully non-blocking mode after ensuring it is closed.
+ *   2. Issue sequential write loops for payloads of 8, 32, 128, 512, and 1024 bytes, plus 100 iterations of 1024 bytes,
+ *      collecting total bytes written and elapsed ticks.
+ *   3. Log throughput metrics for each run to detect stalls or partial transfers.
+ *
+ * Verification Metrics:
+ * - Each loop writes the exact number of requested bytes; cumulative counters match expectations.
+ * - Measured tick deltas are captured for post-run performance analysis; function returns RT_TRUE.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2` with loopback wiring for `RT_SERIAL_TC_DEVICE_NAME`.
+ * - UART driver must support non-blocking write semantics and allow repeated open/close.
+ *
+ * Expected Results:
+ * - Test completes without assertion failures; logs show per-size throughput data.
+ * - Utest harness prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_nonblocking_tx)`.
+ */
+
 #include <rtthread.h>
 #include <rtdevice.h>
 #include "utest.h"

components/drivers/serial/utest/v2/uart_overflow_rxb_txb.c

@@ -1,11 +1,41 @@
 /*
- * Copyright (c) 2006-2024 RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
  * Date           Author       Notes
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART RX Buffer Overflow Handling Test
+ *
+ * Test Objectives:
+ * - Validate UART behavior when RX FIFO exceeds configured buffer size under blocking operation
+ * - Verify APIs: rt_device_find, rt_device_control(RT_DEVICE_CTRL_CONFIG / RT_SERIAL_CTRL_SET_RX_TIMEOUT),
+ *   rt_device_open with RT_DEVICE_FLAG_RX_BLOCKING | RT_DEVICE_FLAG_TX_BLOCKING,
+ *   rt_device_read, rt_device_write, rt_thread_create/startup
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Overflow Stress / tc_uart_api):**
+ *   1. Configure UART buffers and spawn sender thread to push large monotonic sequences while receiver drains in buffer-sized chunks.
+ *   2. Delay receiver startup to force RX queue saturation, then verify data either restarts from zero (drop strategy) or continues modulo 256.
+ *   3. Iterate across deterministic and random payload lengths, monitoring flags for misordered data.
+ *
+ * Verification Metrics:
+ * - Receiver reads exactly `RT_SERIAL_TC_RXBUF_SIZE` bytes per chunk.
+ * - Data pattern matches expected strategy (`RT_SERIAL_BUF_STRATEGY_DROP` or wraparound).
+ * - `uart_result` remains `RT_TRUE`; `uart_over_flag` set before loop exit.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2` with loopback wiring and optional DMA ping buffer support.
+ * - UART driver must implement overflow strategy macros and blocking modes.
+ * - Adequate heap for large TX/RX buffers and 2 KB thread stacks.
  *
+ * Expected Results:
+ * - No assertions triggered; logs report pass counts for each length.
+ * - Utest harness prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_overflow_rxb_txb)`.
  */
 
 #include <rtthread.h>

components/drivers/serial/utest/v2/uart_rxb_txb.c

@@ -1,11 +1,43 @@
 /*
- * Copyright (c) 2006-2024 RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
  * Date           Author       Notes
  * 2021-06-16     KyleChan     the first version
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART Blocking RX & TX Integration Test
+ *
+ * Test Objectives:
+ * - Validate simultaneous blocking receive/transmit operation with sequential integrity checks
+ * - Verify APIs: rt_device_find, rt_device_control(RT_DEVICE_CTRL_CONFIG / RT_SERIAL_CTRL_SET_RX_TIMEOUT),
+ *   rt_device_open with RT_DEVICE_FLAG_RX_BLOCKING | RT_DEVICE_FLAG_TX_BLOCKING,
+ *   rt_device_read, rt_device_write, rt_thread_create/startup
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Length Sweep & Randomized Payloads / tc_uart_api):**
+ *   1. Reconfigure UART to known buffer sizes (optional DMA ping buffer) and set generous RX timeout.
+ *   2. Spawn paired producer/consumer threads; sender streams monotonically increasing bytes while receiver validates ordering until quota met.
+ *   3. Iterate over deterministic payload lengths based on TX buffer, RX buffer, and random samples until `RT_SERIAL_TC_SEND_ITERATIONS` reached.
+ *   4. Monitor flags for allocation failures or data mismatches; terminate threads once reception quota per iteration satisfied.
+ *
+ * Verification Metrics:
+ * - Each transfer completes with ordered byte sequence and total receive length equals requested count.
+ * - `uart_result` remains `RT_TRUE`; `uart_over_flag` set per iteration before teardown.
+ * - Device open/close succeeds across all iterations without lingering handles.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2` with loopback wiring on `RT_SERIAL_TC_DEVICE_NAME`.
+ * - Blocking mode support plus optional DMA ping buffer configuration.
+ * - Thread stack allocations (2 × 1 KB) and send buffers must be available from heap.
+ *
+ * Expected Results:
+ * - Unit test passes without assertions; logs show progressive length coverage.
+ * - Utest framework prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_rxb_txb)`.
  */
 
 #include <rtthread.h>

components/drivers/serial/utest/v2/uart_rxb_txnb.c

@@ -1,11 +1,43 @@
 /*
- * Copyright (c) 2006-2024 RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
  * Date           Author       Notes
  * 2021-06-16     KyleChan     the first version
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART Blocking RX & Non-Blocking TX Integration Test
+ *
+ * Test Objectives:
+ * - Validate receive-blocking / transmit-non-blocking coexistence including TX completion callbacks
+ * - Verify APIs: rt_device_find, rt_device_control(RT_DEVICE_CTRL_CONFIG / RT_SERIAL_CTRL_SET_RX_TIMEOUT),
+ *   rt_device_open with RT_DEVICE_FLAG_RX_BLOCKING | RT_DEVICE_FLAG_TX_NON_BLOCKING,
+ *   rt_device_set_tx_complete, rt_device_read, rt_device_write, rt_sem APIs
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Length Sweep with Callback Synchronization / tc_uart_api):**
+ *   1. Configure UART buffers (optional DMA ping buffer) and create TX completion semaphore.
+ *   2. Register `uart_tx_completion` to release semaphore for each non-blocking write fragment.
+ *   3. Iterate through deterministic and random payload lengths, launching paired sender/receiver threads.
+ *   4. Sender waits on semaphore between partial writes; receiver verifies ordered payload to detect loss or reordering.
+ *
+ * Verification Metrics:
+ * - All expected bytes received in sequence; `uart_result` remains `RT_TRUE`.
+ * - Semaphore operations succeed (`rt_sem_take` returns RT_EOK); `uart_over_flag` toggles once quota met.
+ * - Device configuration/open/close calls complete without error; resources freed in cleanup.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2` and loopback wiring for `RT_SERIAL_TC_DEVICE_NAME`.
+ * - Non-blocking TX mode must support completion callback registration.
+ * - Dynamic memory for payload buffers, semaphore, and two 1 KB threads must be available.
+ *
+ * Expected Results:
+ * - Test finishes without assertions; logs show length coverage and success counts.
+ * - Utest harness prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_rxb_txnb)`.
  */
 
 #include <rtthread.h>

components/drivers/serial/utest/v2/uart_rxnb_txb.c

@@ -1,11 +1,43 @@
 /*
- * Copyright (c) 2006-2024 RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
  * Date           Author       Notes
  * 2021-06-16     KyleChan     the first version
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART Non-Blocking RX & Blocking TX Integration Test
+ *
+ * Test Objectives:
+ * - Validate RX interrupt/callback based reception paired with blocking transmit path
+ * - Verify APIs: rt_device_find, rt_device_control(RT_DEVICE_CTRL_CONFIG / RT_SERIAL_CTRL_SET_RX_TIMEOUT),
+ *   rt_device_open with RT_DEVICE_FLAG_RX_NON_BLOCKING | RT_DEVICE_FLAG_TX_BLOCKING,
+ *   rt_device_set_rx_indicate, rt_device_read, rt_device_write, rt_sem APIs
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Callback-Driven Reception / tc_uart_api):**
+ *   1. Configure UART buffers (optional DMA ping buffer) and create RX semaphore.
+ *   2. Register `uart_rx_indicate` callback to signal semaphore whenever new bytes arrive.
+ *   3. For a sweep of deterministic and random lengths, launch sender/receiver threads.
+ *   4. Receiver waits on semaphore, drains available bytes, and enforces monotonic data ordering until quota met.
+ *
+ * Verification Metrics:
+ * - Received data remains sequential; `uart_result` stays `RT_TRUE`.
+ * - Semaphore take operations succeed; `uart_over_flag` flips upon completion.
+ * - UART open/close and callback registration succeed without leaks; resources cleaned in teardown.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2` with loopback for `RT_SERIAL_TC_DEVICE_NAME`.
+ * - Non-blocking RX must support callback indication.
+ * - Heap must provide buffers and semaphore; two 1 KB thread stacks required.
+ *
+ * Expected Results:
+ * - Test executes without assertion failures; logs show iteration counts and lengths.
+ * - Utest harness prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_rxnb_txb)`.
  */
 
 #include <rtthread.h>

components/drivers/serial/utest/v2/uart_rxnb_txnb.c

@@ -1,11 +1,42 @@
 /*
- * Copyright (c) 2006-2024 RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
  * Date           Author       Notes
  * 2021-06-16     KyleChan     the first version
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART Non-Blocking RX & TX Integration Test
+ *
+ * Test Objectives:
+ * - Validate fully non-blocking UART workflow leveraging TX completion and RX indication callbacks
+ * - Verify APIs: rt_device_find, rt_device_control(RT_DEVICE_CTRL_CONFIG / RT_SERIAL_CTRL_SET_RX_TIMEOUT),
+ *   rt_device_open with RT_DEVICE_FLAG_RX_NON_BLOCKING | RT_DEVICE_FLAG_TX_NON_BLOCKING,
+ *   rt_device_set_rx_indicate, rt_device_set_tx_complete, rt_device_read, rt_device_write, rt_sem APIs
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Callback-Synchronized Duplex Transfer / tc_uart_api):**
+ *   1. Configure UART buffers (optional DMA ping buffer) and create paired RX/TX semaphores.
+ *   2. Register RX indication and TX completion callbacks to release semaphores on asynchronous events.
+ *   3. Launch sender/receiver threads for deterministic and random payload sizes; sender fragments writes, waiting on TX semaphore, while receiver waits on RX semaphore before draining data.
+ *   4. Verify data ordering continuously and stop once requested byte count satisfied per iteration.
+ *
+ * Verification Metrics:
+ * - Received bytes maintain sequential increments; `uart_result` never flips to RT_FALSE.
+ * - Semaphore waits succeed; non-blocking read/write calls progress without deadlock.
+ * - UART handles close cleanly; semaphores deleted during cleanup.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2`, loopback on `RT_SERIAL_TC_DEVICE_NAME`, and callback-capable UART driver.
+ * - Adequate heap for buffers, semaphores, and two 1 KB thread stacks.
+ *
+ * Expected Results:
+ * - Unit test completes without assertions; logs reflect pass counts across length sweep.
+ * - Utest harness prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_rxnb_txnb)`.
  */
 
 #include <rtthread.h>

components/drivers/serial/utest/v2/uart_timeout_rxb.c

@@ -1,11 +1,42 @@
 /*
- * Copyright (c) 2006-2024 RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
  * Date           Author       Notes
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART Blocking RX Timeout Test
+ *
+ * Test Objectives:
+ * - Validate blocking receive timeout behavior while TX operates non-blocking
+ * - Verify APIs: rt_device_find, rt_device_control(RT_SERIAL_CTRL_SET_RX_TIMEOUT / _TX_FLUSH),
+ *   rt_device_open with RT_DEVICE_FLAG_RX_BLOCKING | RT_DEVICE_FLAG_TX_NON_BLOCKING,
+ *   rt_device_write, rt_device_read
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (RX Timeout Sweep / tc_uart_api):**
+ *   1. Reconfigure UART buffers (optional DMA ping buffer) and open in RX blocking / TX non-blocking mode.
+ *   2. Allocate reusable TX buffer and iterate `RT_SERIAL_TC_SEND_ITERATIONS` times.
+ *   3. For each iteration, randomize burst length (1024~2047 bytes), program RX timeout, transmit payload,
+ *      then read back and ensure received size reflects timeout truncation.
+ *   4. Flush TX FIFO and delay to allow residual bytes to drain before next iteration.
+ *
+ * Verification Metrics:
+ * - Each receive length lies within `[rx_timeout_send_size - 70, send_size - 80]`.
+ * - Transmission always completes full burst; overall loop exits with RT_EOK and device closes successfully.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2` with UART loopback (`RT_SERIAL_TC_DEVICE_NAME` TX shorted to RX).
+ * - Serial driver must support RX timeout control and optional DMA ping buffer configuration.
+ * - Random number generator and system tick used for timeout computation.
  *
+ * Expected Results:
+ * - No assertions triggered; log traces show per-iteration timeout measurements.
+ * - Utest framework prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_timeout_rxb)`.
  */
 
 #include <rtthread.h>

components/drivers/serial/utest/v2/uart_timeout_rxb_txb.c

@@ -1,11 +1,41 @@
 /*
- * Copyright (c) 2006-2024 RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
  * Date           Author       Notes
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART Blocking Timeout RX/TX Test
+ *
+ * Test Objectives:
+ * - Validate combined blocking receive/transmit timeout behavior for the serial v2 driver
+ * - Verify APIs: rt_device_find, rt_device_control(RT_SERIAL_CTRL_SET_RX_TIMEOUT / _SET_TX_TIMEOUT / _RX_FLUSH / _TX_FLUSH),
+ *   rt_device_open with RT_DEVICE_FLAG_RX_BLOCKING | RT_DEVICE_FLAG_TX_BLOCKING, rt_device_read, rt_device_write
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Timeout Verification / tc_uart_api):**
+ *   1. Discover and reconfigure the target UART with loopback (TX shorted to RX) and known buffer sizes.
+ *   2. Spawn concurrent TX and RX worker threads; RX thread configures 100-tick blocking timeout and repeatedly validates measured wait time.
+ *   3. Switch to TX timeout mode (10 ticks) and push oversized bursts to ensure write calls block for the configured window.
+ *   4. Monitor status flags to detect allocation failures, timeout violations, or thread termination.
+ *
+ * Verification Metrics:
+ * - RX blocking reads must complete within [100, 101] ticks and return expected lengths across 10 iterations.
+ * - TX blocking writes must complete within [10, 11] ticks with successful flush between iterations.
+ * - No allocation or control failures occur; master loop exits with `uart_over_flag == RT_TRUE`.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2` enabled and a loopbacked UART defined by `RT_SERIAL_TC_DEVICE_NAME`.
+ * - Serial driver must support blocking mode and timeout controls; optional RX DMA segment size is set via `RT_SERIAL_USING_DMA`.
+ * - Two 2 KB threads plus dynamic buffers (~RT_SERIAL_TC_RXBUF_SIZE*10) must be allocatable from the heap.
  *
+ * Expected Results:
+ * - Test completes without assertions, device handles close cleanly, logs show timeout measurements within tolerance.
+ * - Utest harness prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_timeout_rxb_txb)`.
  */
 
 #include <rtthread.h>

components/drivers/serial/utest/v2/uart_timeout_txb.c

@@ -1,11 +1,41 @@
 /*
- * Copyright (c) 2006-2024 RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
  * Date           Author       Notes
+ * 2025-11-13     CYFS         Add standardized utest documentation block
+*/
+
+/**
+ * Test Case Name: UART Blocking TX Timeout Test
+ *
+ * Test Objectives:
+ * - Validate blocking transmit timeout handling when RX operates non-blocking
+ * - Verify APIs: rt_device_find, rt_device_control(RT_SERIAL_CTRL_SET_TX_TIMEOUT / _TX_FLUSH),
+ *   rt_device_open with RT_DEVICE_FLAG_RX_NON_BLOCKING | RT_DEVICE_FLAG_TX_BLOCKING, rt_device_write
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (TX Timeout Sweep / tc_uart_api):**
+ *   1. Configure UART buffers and open the device in RX non-blocking / TX blocking mode.
+ *   2. Allocate a reusable TX buffer and iterate `RT_SERIAL_TC_SEND_ITERATIONS` times.
+ *   3. For each iteration, randomize burst length (1024~2047 bytes), set expected TX timeout,
+ *      issue write, and ensure returned write size falls into tolerated range.
+ *   4. Flush TX FIFO and delay to allow loopback RX to complete reception.
+ *
+ * Verification Metrics:
+ * - Each write returns size within `[tx_timeout_send_size - 70, send_size - 80]`.
+ * - No allocation failures; all iterations exit via RT_EOK and device closes cleanly.
+ *
+ * Dependencies:
+ * - Requires `RT_UTEST_SERIAL_V2` enabled and loopback wiring of `RT_SERIAL_TC_DEVICE_NAME`.
+ * - Excludes configurations with `BSP_UART2_TX_USING_DMA` (DMA write timeout unsupported).
+ * - Needs random number generator and system tick for duration calculations.
  *
+ * Expected Results:
+ * - Test completes without assertion failures; logs show sequence of timeout send sizes.
+ * - Utest framework prints `[  PASSED  ] [ result   ] testcase (components.drivers.serial.v2.uart_timeout_txb)`.
  */
 
 #include <rtthread.h>