[utest][smp_call]:Add standardized documentation for SMP Call Smoke Test (#11014)

components/drivers/smp_call/utest/smp_001_tc.c

@@ -7,8 +7,44 @@
  * Date           Author       Notes
  * 2024/9/12      zhujiale     the first version
  * 2024/10/28     Shell        Added more assertions
+ * 2025/12/3      ChuanN-sudo  add standardized utest documentation block
  */
 
+/**
+ * Test Case Name: SMP Call Smoke 001 Test
+ *
+ * Test Objectives:
+ * - Validate rt_smp_call_cpu_mask() with SMP_CALL_WAIT_ALL flag for blocking synchronous calls.
+ * - Verify callback execution on all targeted CPUs.
+ * - Ensure callback runs in interrupt-disabled context.
+ * - Test core APIs: rt_smp_call_cpu_mask().
+ *
+ * Test Scenarios:
+ * - Main thread generates random CPU masks and dispatches callbacks to targeted CPUs.
+ * - Callback function clears corresponding CPU bit from shared mask variable.
+ * - Blocking call waits for all targeted CPUs to complete execution.
+ * - Random CPU selection simulates various multi-core scenarios.
+ *
+ * Verification Metrics:
+ * - rt_smp_call_cpu_mask() must block until all targeted CPUs complete callback execution.
+ * - Shared mask variable must be zero after function returns, confirming all targets executed.
+ * - Callback must execute in interrupt-disabled context.
+ * - All available CPUs must be tested throughout the run.
+ * - Data integrity maintained across CPUs with spinlock protection.
+ *
+ * Dependencies:
+ * - Hardware requirements:  QEMU emulator or any multi-core hardware platform that supports RT-Thread.
+ * - Software configuration:
+ *     - RT_USING_UTEST must be enabled (select "RT-Thread Utestcases" in menuconfig).
+ *     - RT_UTEST_SMP_CALL_FUNC must be enabled(enable via:  RT-Thread Utestcases -> Kernel Components -> Drivers -> SMP-Call Test -> SMP-Call Smoke Test).
+ * - Environmental Assumptions: System scheduler and SMP services working normally.
+ *
+ * Expected Results:
+ * - Final output: "[ PASSED ] [ result ] testcase (components.drivers.smp_call.smoke_001)"
+ * - No assertions triggered during test execution.
+ */
+
+
 #include <rtdevice.h>
 #include <utest.h>
 #include <utest_assert.h>

components/drivers/smp_call/utest/smp_002_tc.c

@@ -6,6 +6,38 @@
  * Change Logs:
  * Date           Author       Notes
  * 2024/10/28     Shell        Added smp.smoke
+ * 2025/12/3      ChuanN-sudo  add standardized utest documentation block
+ */
+
+/**
+ * Test Case Name: SMP Call Smoke 002 Test
+ *
+ * Test Objectives:
+ * - Validate thread-safety of rt_smp_call_cpu_mask() under concurrent calls from multiple CPUs.
+ * - Verify system stability with simultaneous blocking SMP calls.
+ * - Test core APIs: rt_smp_call_cpu_mask().
+ *
+ * Test Scenarios:
+ * - One worker thread pinned to each CPU core.
+ * - All threads simultaneously call rt_smp_call_cpu_mask() with random targets.
+ * - Atomic counter tracks callbacks executed per thread.
+ *
+ * Verification Metrics:
+ * - Callback count must match requested target count.
+ * - Callbacks execute in interrupt-disabled context.
+ * - All threads successfully created and pinned.
+ * - Each thread tests all available CPUs.
+ *
+ * Dependencies:
+ * - Hardware requirements:  QEMU emulator or any multi-core hardware platform that supports RT-Thread.
+ * - Software configuration:
+ *     - RT_USING_UTEST must be enabled (select "RT-Thread Utestcases" in menuconfig).
+ *     - RT_UTEST_SMP_CALL_FUNC must be enabled(enable via:  RT-Thread Utestcases -> Kernel Components -> Drivers -> SMP-Call Test -> SMP-Call Smoke Test).
+ * - Environmental Assumptions: System scheduler and SMP services working normally.
+ *
+ * Expected Results:
+ * - Progress logs: A series of '#' characters indicating callback executions.
+ * - Final output: "[ PASSED ] [ result ] testcase (components.drivers.smp_call.smoke_002)"
  */
 
 #include <rtdevice.h>

components/drivers/smp_call/utest/smp_003_tc.c

@@ -6,6 +6,38 @@
  * Change Logs:
  * Date           Author       Notes
  * 2024/10/28     Shell        Added smp.smoke
+ * 2025/12/3      ChuanN-sudo  add standardized utest documentation block
+ */
+
+/**
+ * Test Case Name: SMP Call Smoke 003 Test
+ *
+ * Test Objectives:
+ * - Validate asynchronous rt_smp_call_cpu_mask() reliability under high-contention.
+ * - Ensure no Inter-Processor Interrupts are lost when fired rapidly without waiting.
+ * - Test core APIs: rt_smp_call_cpu_mask() (with wait_flag=0), rt_thread_control(RT_THREAD_CTRL_BIND_CPU)
+ *
+ * Test Scenarios:
+ * - One worker thread pinned to each CPU core.
+ * - Threads repeatedly call non-blocking rt_smp_call_cpu_mask() with random targets.
+ * - After dispatching Inter-Processor Interrupts, threads migrate across cores to yield processing time.
+ * - Final verification checks eventual consistency.
+ *
+ * Verification Metrics:
+ * - Callback count must eventually match requested count.
+ * - Callbacks execute in interrupt-disabled context.
+ * - All threads successfully created and started.
+ *
+ * Dependencies:
+ * - Hardware requirements:  QEMU emulator or any multi-core hardware platform that supports RT-Thread.
+ * - Software configuration:
+ *     - RT_USING_UTEST must be enabled (select "RT-Thread Utestcases" in menuconfig).
+ *     - RT_UTEST_SMP_CALL_FUNC must be enabled(enable via:  RT-Thread Utestcases -> Kernel Components -> Drivers -> SMP-Call Test -> SMP-Call Smoke Test).
+ * - Environmental Assumptions: System scheduler and SMP services working normally.
+ *
+ * Expected Results:
+ * - Progress logs: A series of '#' characters indicating asynchronous callback executions.
+ * - Final output: "[ PASSED ] [ result ] testcase (components.drivers.smp_call.smoke_003)"
  */
 
 #include <rtdevice.h>

components/drivers/smp_call/utest/smp_004_tc.c

@@ -6,9 +6,43 @@
  * Change Logs:
  * Date           Author       Notes
  * 2024/10/28     Shell        Added smp.smoke
+ * 2025/12/3      ChuanN-sudo  add standardized utest documentation block
  * 2025/12/9      ChuanN-sudo  fix: initialize current_mask variable
  */
 
+/**
+ * Test Case Name: SMP Call Smoke 004 Test
+ *
+ * Test Objectives:
+ * - Validate SMP call mechanism is re-entrant.
+ * - Test rt_smp_call_request robustness from interrupt context.
+ * - Ensure system stability under nested Inter-Processor Interrupts scenarios from multiple cores.
+ * - Test core APIs: rt_smp_call_request(), rt_smp_call_req_init(), rt_smp_request_wait_freed(), rt_smp_call_cpu_mask()
+ *
+ * Test Scenarios:
+ * - Pre-initialized 2D array of rt_smp_call_req objects.
+ * - Worker thread triggers primary Inter-Processor Interrupts to another CPU.
+ * - Primary handler fires secondary Inter-Processor Interrupts to all other CPUs.
+ * - Secondary handlers update shared bitmask.
+ * - Worker thread polls bitmask until all secondary Inter-Processor Interrupts complete.
+ *
+ * Verification Metrics:
+ * - Bitmask must match expected value.
+ * - Callbacks execute in interrupt-disabled context.
+ * - rt_smp_call_request from ISR returns no error.
+ *
+ * Dependencies:
+ * - Hardware requirements:  QEMU emulator or any multi-core hardware platform that supports RT-Thread.
+ * - Software configuration:
+ *     - RT_USING_UTEST must be enabled (select "RT-Thread Utestcases" in menuconfig).
+ *     - RT_UTEST_SMP_CALL_FUNC must be enabled(enable via:  RT-Thread Utestcases -> Kernel Components -> Drivers -> SMP-Call Test -> SMP-Call Smoke Test).
+ * - Environmental Assumptions: System scheduler and SMP services working normally.
+ *
+ * Expected Results:
+ * - Progress logs: A series of characters (0-N) indicating which worker's callbacks are executing.
+ * - Final output: "[ PASSED ] [ result ] testcase (components.drivers.smp_call.smoke_004)"
+ */
+
 #include <rtdevice.h>
 #include <utest.h>
 #include <utest_assert.h>