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

src/utest/mem_tc.c

@@ -6,6 +6,77 @@
  * Change Logs:
  * Date           Author       Notes
  * 2021-10-14     tyx          the first version
+ * 2025-11-11     CYFS         Add standardized utest documentation block
+ */
+
+/**
+ * Test Case Name: Kernel Core Small Memory Management Test
+ *
+ * Test Objectives:
+ * - Validates the core kernel small memory management module functionality
+ * - Verify core APIs: rt_smem_init, rt_smem_alloc, rt_smem_free, rt_smem_realloc, rt_smem_detach
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Functional Test / mem_functional_test):**
+ * 1. Initialize small memory heap with 1024 bytes test buffer
+ * 2. Allocate entire heap at once and verify complete deallocation
+ * 3. Sequential allocation of multiple blocks followed by sequential release to test forward merging
+ * 4. Interval allocation and release pattern to test bidirectional block merging
+ * 5. Reallocation from small size to large size (requires memory move and data preservation)
+ * 6. Reallocation from large size to small size (in-place shrink verification)
+ * 7. Reallocation with equal size (no-op verification)
+ * - **Scenario 2 (Random Allocation Stress Test / mem_alloc_test):**
+ * 1. Perform random allocation/deallocation operations with 60% allocation probability
+ * 2. Memory size randomization (2-5 blocks of mem_alloc_context size)
+ * 3. Memory exhaustion handling: automatic release of half allocated blocks when allocation fails
+ * 4. Long-duration stress test (5 seconds by default)
+ * 5. Memory content verification using magic number patterns during operations
+ * - **Scenario 3 (Random Reallocation Stress Test / mem_realloc_test):**
+ * 1. Perform random reallocation of multiple memory blocks with size variations (0-5 blocks)
+ * 2. Random selection of target block from context table for reallocation
+ * 3. Memory exhaustion handling: random freeing of other blocks when realloc fails
+ * 4. Reallocation to zero size (free operation) verification
+ * 5. Memory content integrity verification before and after reallocation
+ *
+ * Verification Metrics:
+ * - **Pass (Scenario 1):** All allocation operations return non-NULL pointers
+ * - **Pass (Scenario 1):** Allocated memory is properly aligned (RT_ALIGN_SIZE)
+ * - **Pass (Scenario 1):** Memory content integrity verified using magic number pattern
+ * - **Pass (Scenario 1):** Maximum free block size equals initial total size after all deallocations
+ * - **Pass (Scenario 1):** Memory block merging verified after sequential and interval releases
+ * - **Pass (Scenario 1):** Realloc operations preserve existing data when expanding
+ * - **Pass (Scenario 1):** Realloc operations maintain pointer when shrinking in-place
+ * - **Pass (Scenario 2):** Allocated memory pointers are properly aligned
+ * - **Pass (Scenario 2):** Memory content integrity maintained throughout random operations
+ * - **Pass (Scenario 2):** Memory heap fully recovered (max_block equals initial total_size) after test
+ * - **Pass (Scenario 2):** Test count tracking accurate (head.count equals 0 at end)
+ * - **Pass (Scenario 3):** Realloc operations preserve existing data when size increases or decreases
+ * - **Pass (Scenario 3):** Magic number patterns maintained correctly after reallocation
+ * - **Pass (Scenario 3):** Realloc to zero size properly frees memory blocks
+ *
+ * Dependencies:
+ * - No specific hardware requirements, runs on any RT-Thread supported platform
+ * - Software configuration (e.g., kernel options, driver initialization)
+ * - `RT_USING_UTEST` must be enabled (`RT-Thread Utestcases`).
+ * - `Memory Test` must be enabled (`RT-Thread Utestcases` -> `Kernel Core` -> 'Memory Test').
+ * - RT-Thread kernel with small memory management enabled
+ * - rt_malloc and rt_free functions available for test buffer allocation
+ * - RT_ALIGN_SIZE macro defined for memory alignment
+ * - Random number generator (rand function) available for stress tests
+ * - System tick timer (rt_tick_get) for test duration control
+ * - Environmental assumptions
+ * - TEST_MEM_SIZE (1024 bytes) sufficient for test operations
+ * - System can handle high-frequency memory operations for stress tests
+ * - Run the test case from the msh prompt:
+ * `utest_run core.mem`
+ *
+ * Expected Results:
+ * - The test case completes without errors or failed assertions.
+ * - Memory heap fully recovered to initial state after functional test
+ * - No memory leaks or corruption detected
+ * - The utest framework prints:
+ * `[  PASSED  ] [ result   ] testcase (core.mem)`
+ * - Progress indicators (#) printed at regular intervals during stress tests
  */
 
 #include <rtthread.h>

src/utest/memheap_tc.c

@@ -6,8 +6,58 @@
  * Change Logs:
  * Date           Author       Notes
  * 2019-01-16     flybreak     the first version
+ * 2025-11-11     CYFS         Add standardized utest documentation block
  */
 
+/**
+ * Test Case Name: Kernel Core Memory Heap Test
+ *
+ * Test Objectives:
+ * - Validates the core kernel memory heap management module functionality
+ * - Verify core APIs: rt_memheap_init, rt_memheap_alloc, rt_memheap_free, rt_memheap_realloc, rt_memheap_detach
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Memory Heap Stress Test / memheap_test):**
+ * 1. Initialize memory heap with 64KB aligned memory buffer (4-byte alignment)
+ * 2. Allocate 40 memory blocks with random sizes (0 to HEAP_SIZE/SLICE_NUM)
+ * 3. Perform 100000 random operations on the memory heap
+ * 4. Each operation randomly selects one of 40 memory blocks and performs either:
+ *    - Free and reallocate with new random size (50% probability)
+ *    - Reallocate existing block with new random size (50% probability)
+ * 5. Verify memory heap stability and correctness under high-frequency operations
+ *
+ * Verification Metrics:
+ * - **Pass (Scenario 1):** Memory heap initialization succeeds with 64KB aligned buffer
+ * - **Pass (Scenario 1):** All 40 initial allocations complete successfully
+ * - **Pass (Scenario 1):** All 100000 random operations complete without system crash or assertion failure
+ * - **Pass (Scenario 1):** Memory heap operations (alloc/free/realloc) execute correctly throughout stress test
+ * - **Pass (Scenario 1):** Progress indicators (>) printed at regular intervals (every 10000 operations)
+ * - **Pass (Scenario 1):** Test completes successfully with "test OK!" message
+ * - **Pass (Scenario 1):** Memory heap properly detached and resources cleaned up
+ *
+ * Dependencies:
+ * - No specific hardware requirements, runs on any RT-Thread supported platform
+ * - Software configuration (e.g., kernel options, driver initialization)
+ * - `RT_USING_UTEST` must be enabled (`RT-Thread Utestcases`).
+ * - `Memory Heap Test` must be enabled (`RT-Thread Utestcases` -> `Kernel Core` -> 'Memory Heap Test').
+ * - RT-Thread kernel with memory heap management enabled
+ * - rt_malloc_align and rt_free_align functions available for test buffer allocation
+ * - Random number generator (rand function) available for random operations
+ * - Sufficient system memory to allocate 64KB aligned buffer
+ * - Environmental assumptions
+ * - System can handle high-frequency memory operations (100000 operations)
+ * - Memory heap can manage 40 concurrent memory blocks
+ * - Run the test case from the msh prompt:
+ * `utest_run core.memheap`
+ *
+ * Expected Results:
+ * - The test case completes without errors or failed assertions.
+ * - Progress indicators (>) printed at regular intervals during stress test
+ * - "test OK!" message printed upon successful completion
+ * - The utest framework prints:
+ * `[  PASSED  ] [ result   ] testcase (core.memheap)`
+ * - Memory heap properly cleaned up and no memory leaks detected
+ */
 #include <rtthread.h>
 #include <stdlib.h>
 #include "utest.h"

src/utest/object_tc.c

@@ -6,6 +6,56 @@
  * Change Logs:
  * Date           Author       Notes
  * 2025-07-18     kurisaW      First commit
+ * 2025-11-13     CYFS         Add standardized documentation block for object_tc
+ */
+
+/**
+ * Test Case Name: Kernel Object Management Test
+ *
+ * Test Objectives:
+ * - Validate RT-Thread object lifecycle, lookup, enumeration, and metadata utilities
+ * - Verify core APIs: rt_object_init, rt_object_allocate, rt_object_delete, rt_object_detach,
+ *   rt_object_find, rt_thread_find, rt_device_find, rt_object_get_information,
+ *   rt_object_get_length, rt_object_get_pointers, rt_object_get_name, rt_object_get_type,
+ *   rt_object_is_systemobject
+ *
+ * Test Scenarios:
+ * - **Scenario 1 (Name Handling / test_object_name_handling):**
+ *   1. Create static objects with maximum-length names to validate truncation and null-termination rules.
+ *   2. Allocate dynamic objects with maximum-length names to confirm dynamic object naming and non-system classification.
+ *   3. Exercise NULL name handling for both static initialization and dynamic allocation paths.
+ *   4. Verify exact-length names remain intact alongside proper detach/cleanup.
+ * - **Scenario 2 (Find Operations / test_object_find_operations):**
+ *   1. Register static thread objects and verify discovery via rt_object_find.
+ *   2. Create runtime threads and confirm rt_thread_find returns expected handles.
+ *   3. (Optional with RT_USING_DEVICE) Register temporary devices, test rt_device_find against multiple entries, and validate deregistration paths.
+ *   4. Test same-prefix device registrations to confirm distinct name resolution.
+ *   5. Validate negative paths for nonexistent and NULL names across object, thread, and device lookup helpers.
+ * - **Scenario 3 (Info Enumeration / test_object_info_enumeration):**
+ *   1. Mix static and dynamic thread objects and query rt_object_get_information for metadata.
+ *   2. Retrieve counts with rt_object_get_length and enumerate pointers with sufficient buffer space.
+ *   3. Probe buffer boundary behavior by providing undersized pointer arrays.
+ *   4. (Optional with RT_USING_SEMAPHORE) Inspect empty semaphore container reporting.
+ * - **Scenario 4 (Type Utilities / test_object_type_handling):**
+ *   1. Inspect object type via rt_object_get_type and verify system-object status.
+ *   2. Retrieve object names using full buffers, truncated buffers, and invalid parameters.
+ *   3. Confirm error codes for NULL object pointers, NULL buffers, and zero-length requests.
+ *
+ * Verification Metrics:
+ * - **Scenario 1:** Name strings must be null-terminated within TEST_RT_NAME_MAX, retain expected contents, and reflect correct system-object classification.
+ * - **Scenario 2:** Lookup helpers return valid handles for registered objects, correctly distinguish between devices with similar name prefixes, and return NULL for missing or invalid names; device deregistration must succeed.
+ * - **Scenario 3:** Enumeration APIs report counts ≥ created objects, populate pointer arrays without overflow, and respect small-buffer contracts.
+ * - **Scenario 4:** Type and name utilities yield correct metadata and error codes across valid/invalid inputs, preserving partial name copies when truncated.
+ *
+ * Dependencies:
+ * - Scheduler availability (`rt_scheduler_is_available`) required before executing the suite.
+ * - Dynamic memory (rt_malloc/rt_free) needed for pointer buffer allocation.
+ * - `RT_USING_UTEST` enabled with test entry registered under `core.object`.
+ * - Optional paths: `RT_USING_DEVICE` for device lookup tests, `RT_USING_SEMAPHORE` for semaphore enumeration checks.
+ *
+ * Expected Results:
+ * - Test runs to completion with all assertions passing in the utest framework.
+ * - Console shows `[  PASSED  ] [ result   ] testcase (core.object)` when invoked via `utest_run core.object`.
  */
 
 #include <utest.h>