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

Author: CYFS3

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>