test: context: Refine descriptions for some test cases

Add or refine comments for some test cases for readability

Signed-off-by: Meng xianglin <[email protected]>

Author: mengxianglinx

tests/kernel/common/src/clock.c

@@ -85,8 +85,43 @@ void test_clock_uptime(void)
 /**
  * @brief Test clock cycle functionality
  *
+ * @details
+ * Test Objectve:
+ * - The kernel architecture provide a 32bit monotonically increasing
+ *   cycle counter
+ * - This routine tests the k_cycle_get_32() and k_uptime_get_32()
+ *   k_cycle_get_32() get cycles by accessing hardware clock.
+ *   k_uptime_get_32() return cycles by transforming ticks into cycles.
+ *
+ * Testing techniques
+ * - Functional and black box testing
+ *
+ * Prerequisite Condition:
+ * - N/A
+ *
+ * Input Specifications:
+ * - N/A
+ *
+ * Expected Test Result:
+ * - The timer increases monotonically
+ *
+ * Pass/Fail criteria:
+ * - Success if cycles increase monotonically, failure otherwise.
+ *
+ * Test Procedure:
+ * -# At mili-second boundary, get cycles repeatedly by k_cycle_get_32()
+ *  till cycles increased
+ * -# At mili-second boundary, get cycles repeatedly by k_uptime_get_32()
+ *  till cycles increased
+ * -# Cross check cycles gotten by k_cycle_get_32() and k_uptime_get_32(),
+ *  the delta cycle should be greater than 1 milli-second.
+ *
+ * Assumptions and Constraints
+ * - N/A
+ *
  * @see k_cycle_get_32(), k_uptime_get_32()
  */
+
 void test_clock_cycle(void)
 {
 	uint32_t c32, c0, c1, t32;
@@ -125,7 +160,6 @@ void test_clock_cycle(void)
 	}
 }
 
-
 /*
  *help function
  */

tests/kernel/context/src/main.c

@@ -136,6 +136,84 @@ static struct k_thread thread_data3;
 
 static ISR_INFO isr_info;
 
+/**
+ * @brief Test cpu idle function
+ *
+ * @details
+ * Test Objectve:
+ * - The kernel architecture provide an idle function to be run when the system
+ *   has no work for the current CPU
+ * - This routine tests the k_cpu_idle() routine
+ *
+ * Testing techniques
+ * - Functional and black box testing
+ * - Interface testing
+ *
+ * Prerequisite Condition:
+ * - HAS_POWERSAVE_INSTRUCTION is set
+ *
+ * Input Specifications:
+ * - N/A
+ *
+ * Test Procedure:
+ * -# Record system time before cpu enters idle state
+ * -# Enter cpu idle state by k_cpu_idle()
+ * -# Record system time after cpu idle state is interrupted
+ * -# Compare the two system time values.
+ *
+ * Expected Test Result:
+ * - cpu enters idle state for a given time
+ *
+ * Pass/Fail criteria:
+ * - Success if the cpu enters idle state, failure otherwise.
+ *
+ * Assumptions and Constraints
+ * - N/A
+ *
+ * @see k_cpu_idle()
+ * @ingroup kernel_context_tests
+ */
+static void test_kernel_cpu_idle(void);
+
+/**
+ * @brief Test cpu idle function
+ *
+ * @details
+ * Test Objectve:
+ * - The kernel architecture provide an idle function to be run when the system
+ *   has no work for the current CPU
+ * - This routine tests the k_cpu_atomic_idle() routine
+ *
+ * Testing techniques
+ * - Functional and black box testing
+ * - Interface testing
+ *
+ * Prerequisite Condition:
+ * - HAS_POWERSAVE_INSTRUCTION is set
+ *
+ * Input Specifications:
+ * - N/A
+ *
+ * Test Procedure:
+ * -# Record system time befor cpu enters idle state
+ * -# Enter cpu idle state by k_cpu_atomic_idle()
+ * -# Record system time after cpu idle state is interrupted
+ * -# Compare the two system time values.
+ *
+ * Expected Test Result:
+ * - cpu enters idle state for a given time
+ *
+ * Pass/Fail criteria:
+ * - Success if the cpu enters idle state, failure otherwise.
+ *
+ * Assumptions and Constraints
+ * - N/A
+ *
+ * @see k_cpu_atomic_idle()
+ * @ingroup kernel_context_tests
+ */
+static void test_kernel_cpu_idle_atomic(void);
+
 /**
  * @brief Handler to perform various actions from within an ISR context
  *
@@ -546,16 +624,43 @@ static void test_kernel_timer_interrupts(void)
 }
 
 /**
+ * @brief Test some context routines
  *
- * @brief Test some context routines from a preemptible thread
+ * @details
+ * Test Objectve:
+ * - Thread context handles derived from context switches must be able to be
+ *   restored upon interrupt exit
  *
- * @ingroup kernel_context_tests
+ * Testing techniques
+ * - Functional and black box testing
+ * - Interface testing
  *
- * This routines tests the k_current_get() and
- * k_is_in_isr() routines from both a preemptible thread  and an ISR (that
- * interrupted a preemptible thread). Checking those routines with cooperative
- * threads are done elsewhere.
+ * Prerequisite Condition:
+ * - N/A
+ *
+ * Input Specifications:
+ * - N/A
  *
+ * Test Procedure:
+ * -# Set priority of current thread to 0 as a preemptible thread
+ * -# Trap to interrupt context, get thread id of the interrupted thread and
+ *  pass back to that thread.
+ * -# Return to thread context and make sure this context is interrupted by
+ *  comparing its thread ID and the thread ID passed by isr.
+ * -# Pass command to isr to check whether the isr is executed in interrupt
+ *  context
+ * -# When return to thread context, check the return value of command.
+ *
+ * Expected Test Result:
+ * - Thread context restored upon interrupt exit
+ *
+ * Pass/Fail criteria:
+ * - Success if context of thread restored correctly, failure otherwise.
+ *
+ * Assumptions and Constraints
+ * - N/A
+ *
+ * @ingroup kernel_context_tests
  * @see k_current_get(), k_is_in_isr()
  */
 static void test_kernel_ctx_thread(void)
@@ -1039,6 +1144,7 @@ void test_k_yield(void)
  *
  * @see k_thread_create
  */
+
 void test_kernel_thread(void)
 {