doxygen: add comments for lwp shared memory APIs

Add Doxygen-style comments for the lwp shared memory public APIs
in components/lwp/lwp_shm.c and the related control structure.
This change is documentation-only and does not modify any runtime
behavior or logic.

Signed-off-by: ibvqeibob <2601187225@qq.com>

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>

components/lwp/lwp_shm.c

@@ -7,6 +7,7 @@
  * Date           Author       Notes
  * 2019-10-12     Jesven       first version
  * 2023-02-20     wangxiaoyao  adapt to mm
+ * 2025-11-06     ibvqeibob    add Doxygen comments for lwp shared memory APIs
  */
 #include <rthw.h>
 #include <rtthread.h>
@@ -19,14 +20,21 @@
 #include <lwp_user_mm.h>
 #include <mmu.h>
 
-/* the kernel structure to represent a share-memory */
+/**
+ * @brief Kernel control block for a shared memory segment.
+ *
+ * Each lwp_shm_struct represents one shared memory region. It records
+ * the physical address, size, reference count and key. The embedded
+ * mem_obj is used together with the aspace/varea mechanism to handle
+ * mapping and page faults for this segment.
+ */
 struct lwp_shm_struct
 {
-    struct rt_mem_obj mem_obj;
-    size_t addr;    /* point to the next item in the free list when not used */
-    size_t size;
-    int    ref;
-    size_t key;
+    struct rt_mem_obj mem_obj;  /**< Memory object interface used by aspace/varea */
+    size_t addr;                /**< Physical address of the shared memory; used as next pointer in the free list when unused */
+    size_t size;                /**< Size of the shared memory in bytes, page aligned */
+    int    ref;                 /**< Reference count of mappings to this shared memory */
+    size_t key;                 /**< User-visible key used to look up the shared memory */
 };
 
 static struct lwp_avl_struct *shm_tree_key;
@@ -189,7 +197,22 @@ err:
     return -1;
 }
 
-/* A wrapping function, get the shared memory with interrupts disabled. */
+/**
+ * @brief Get or create a shared memory segment by key.
+ *
+ * Under the memory management lock, this function looks up an existing
+ * shared memory control block by key. If it does not exist and @p create
+ * is non-zero, a new segment is created with the requested size, physical
+ * pages are allocated and the segment is inserted into the internal index
+ * trees.
+ *
+ * @param[in] key    Key used to identify the shared memory segment.
+ * @param[in] size   Requested size in bytes; only effective when creating.
+ * @param[in] create Non-zero to allow creation; zero to only search.
+ *
+ * @return On success, returns a non-negative shared memory id.
+ *         On failure, returns -1.
+ */
 int lwp_shmget(size_t key, size_t size, int create)
 {
     int ret = 0;
@@ -253,7 +276,19 @@ static int _lwp_shmrm(int id)
     return 0;
 }
 
-/* A wrapping function, free the shared memory with interrupt disabled. */
+/**
+ * @brief Remove a shared memory segment by id.
+ *
+ * The internal control block is located by @p id. If the reference count
+ * is zero, the physical pages, control block and AVL index nodes are freed.
+ * If the segment is still referenced, no memory is actually released.
+ *
+ * @param[in] id Shared memory id returned by lwp_shmget().
+ *
+ * @return Returns 0 on success. If @p id is invalid or internal checks
+ *         fail, -1 is returned. When the reference count is non-zero,
+ *         0 is returned but the segment is not freed.
+ */
 int lwp_shmrm(int id)
 {
     int ret = 0;
@@ -300,7 +335,21 @@ static void *_lwp_shmat(int id, void *shm_vaddr)
     return va;
 }
 
-/* A wrapping function: attach the shared memory to the specified address. */
+/**
+ * @brief Map a shared memory segment into the current LWP.
+ *
+ * The shared memory control block is located by @p id and mapped into the
+ * user address space of the current LWP. If @p shm_vaddr is not RT_NULL,
+ * the system tries to map the segment at the specified virtual address,
+ * which must be page aligned.
+ *
+ * @param[in] id        Shared memory id returned by lwp_shmget().
+ * @param[in] shm_vaddr Desired user virtual address; if RT_NULL, the
+ *                      system chooses an address. When not RT_NULL it
+ *                      must be page aligned.
+ *
+ * @return The mapped user virtual address on success, or RT_NULL on failure.
+ */
 void *lwp_shmat(int id, void *shm_vaddr)
 {
     void *ret = RT_NULL;
@@ -346,6 +395,19 @@ static int _lwp_shm_ref_inc(struct rt_lwp *lwp, void *shm_vaddr)
     return -1;
 }
 
+/**
+ * @brief Increase the reference count of a shared memory segment.
+ *
+ * The shared memory control block is located according to the given
+ * @p lwp and the user virtual address @p shm_vaddr. If found, its
+ * reference count is increased by one.
+ *
+ * @param[in] lwp        LWP object to operate on.
+ * @param[in] shm_vaddr  User virtual address where the shared memory
+ *                       is mapped in this LWP.
+ *
+ * @return The new reference count on success, or -1 on failure.
+ */
 int lwp_shm_ref_inc(struct rt_lwp *lwp, void *shm_vaddr)
 {
     int ret = 0;
@@ -369,6 +431,19 @@ static int _lwp_shm_ref_dec(struct rt_lwp *lwp, void *shm_vaddr)
     return -1;
 }
 
+/**
+ * @brief Decrease the reference count of a shared memory segment.
+ *
+ * The shared memory control block is located according to the given
+ * @p lwp and the user virtual address @p shm_vaddr. If it exists and
+ * the reference count is greater than zero, the count is decreased by one.
+ *
+ * @param[in] lwp        LWP object to operate on.
+ * @param[in] shm_vaddr  User virtual address where the shared memory
+ *                       is mapped in this LWP.
+ *
+ * @return The new reference count on success, or -1 on failure.
+ */
 int lwp_shm_ref_dec(struct rt_lwp *lwp, void *shm_vaddr)
 {
     int ret = 0;
@@ -400,7 +475,16 @@ int _lwp_shmdt(void *shm_vaddr)
     return ret;
 }
 
-/* A wrapping function: detach the mapped shared memory. */
+/**
+ * @brief Unmap a shared memory segment from the current LWP.
+ *
+ * The mapping at @p shm_vaddr in the current LWP address space is
+ * removed. Internal errors are translated into a generic error code.
+ *
+ * @param[in] shm_vaddr User virtual address of the shared memory mapping.
+ *
+ * @return Returns 0 on success, or -1 on failure.
+ */
 int lwp_shmdt(void *shm_vaddr)
 {
     int ret = 0;
@@ -429,7 +513,17 @@ void *_lwp_shminfo(int id)
     return (void *)((char *)p->addr - PV_OFFSET);     /* get the virtual address */
 }
 
-/* A wrapping function: get the virtual address of a shared memory. */
+/**
+ * @brief Get the kernel virtual address of a shared memory segment.
+ *
+ * The internal control block is located by @p id and the kernel
+ * virtual address corresponding to that shared memory is returned.
+ *
+ * @param[in] id Shared memory id returned by lwp_shmget().
+ *
+ * @return Kernel virtual address of the shared memory on success,
+ *         or RT_NULL on failure.
+ */
 void *lwp_shminfo(int id)
 {
     void *vaddr = RT_NULL;
@@ -451,6 +545,13 @@ static int _shm_info(struct lwp_avl_struct* node_key, void *data)
     return 0;
 }
 
+/**
+ * @brief Print information of all shared memory segments.
+ *
+ * This function prints the key, physical address, size and id of each
+ * shared memory segment to the console. It is exported as the Finsh/Msh
+ * command @c list_shm for debugging and inspection.
+ */
 void list_shm(void)
 {
     rt_kprintf("   key        paddr      size       id\n");