diff --git a/tests/kernel/threads/thread_apis/src/main.c b/tests/kernel/threads/thread_apis/src/main.c index a39565758e7..e073e0a8725 100644 --- a/tests/kernel/threads/thread_apis/src/main.c +++ b/tests/kernel/threads/thread_apis/src/main.c @@ -78,7 +78,7 @@ static void customdata_entry(void *p1, void *p2, void *p3) /** * @ingroup kernel_thread_tests - * @brief test thread custom data get/set from coop thread + * @brief Test thread custom data get/set from coop thread * * @see k_thread_custom_data_get(), k_thread_custom_data_set() */ @@ -101,7 +101,7 @@ static void thread_name_entry(void *p1, void *p2, void *p3) /** * @ingroup kernel_thread_tests - * @brief test thread name get/set from supervisor thread + * @brief Test thread name get/set from supervisor thread * @see k_thread_name_get(), k_thread_name_copy(), k_thread_name_set() */ ZTEST(threads_lifecycle, test_thread_name_get_set) @@ -142,7 +142,7 @@ struct k_sem sem; /** * @ingroup kernel_thread_tests - * @brief test thread name get/set from user thread + * @brief Test thread name get/set from user thread * @see k_thread_name_copy(), k_thread_name_set() */ ZTEST_USER(threads_lifecycle, test_thread_name_user_get_set) @@ -211,7 +211,7 @@ ZTEST_USER(threads_lifecycle, test_thread_name_user_get_set) /** * @ingroup kernel_thread_tests - * @brief test thread custom data get/set from preempt thread + * @brief Test thread custom data get/set from preempt thread * @see k_thread_custom_data_get(), k_thread_custom_data_set() */ ZTEST_USER(threads_lifecycle_1cpu, test_customdata_get_set_preempt) @@ -243,7 +243,7 @@ static void umode_entry(void *thread_id, void *p2, void *p3) /** * @ingroup kernel_thread_tests - * @brief Test k_thread_user_mode_enter() to cover when userspace + * @brief Test k_thread_user_mode_enter to cover when userspace * is not supported/enabled * @see k_thread_user_mode_enter() */ @@ -392,6 +392,11 @@ static inline int join_scenario(enum control_method m) return join_scenario_interval(m, NULL); } +/** + * @ingroup kernel_thread_tests + * @brief Test thread join + * + */ ZTEST_USER(threads_lifecycle, test_thread_join) { int64_t interval; @@ -415,6 +420,13 @@ ZTEST_USER(threads_lifecycle, test_thread_join) } +/** + * @ingroup kernel_thread_tests + * @brief Test thread join from ISR + * + * @see k_thread_join() + * @see k_thread_abort() + */ ZTEST(threads_lifecycle, test_thread_join_isr) { zassert_equal(join_scenario(ISR_RUNNING), -EBUSY, "failed isr running"); @@ -447,6 +459,21 @@ static void deadlock2_entry(void *p1, void *p2, void *p3) zassert_equal(ret, 0, "couldn't join deadlock2_thread"); } + + +/** + * @brief Test case for thread join deadlock scenarios. + * + * This test verifies the behavior of the `k_thread_join` API in scenarios + * that could lead to deadlocks. It includes the following checks: + * + * - Ensures that a thread cannot join itself, which would result in a + * self-deadlock. The API should return `-EDEADLK` in this case. + * - Creates two threads (`deadlock1_thread` and `deadlock2_thread`) and + * verifies that they can be joined successfully without causing a deadlock. + * + * @ingroup kernel_thread_tests + */ ZTEST_USER(threads_lifecycle, test_thread_join_deadlock) { /* Deadlock scenarios */ @@ -476,6 +503,11 @@ static void user_start_thread(void *p1, void *p2, void *p3) { /* do nothing */ } +/** + * @brief Test case for verifying thread timeout expiration and remaining time. + * + * @ingroup kernel_thread_tests + */ ZTEST_USER(threads_lifecycle, test_thread_timeout_remaining_expires) { @@ -528,10 +560,16 @@ static void foreach_callback(const struct k_thread *thread, void *user_data) stats.execution_cycles; } -/* This case accumulates every thread's execution_cycles first, then +/** + * @brief Test case for thread runtime statistics retrieval in Zephyr kernel + * + * This case accumulates every thread's execution_cycles first, then * get the total execution_cycles from a global * k_thread_runtime_stats_t to see that all time is reflected in the * total. + * + * @ingroup kernel_thread_tests + * @see k_thread_runtime_stats_get() */ ZTEST(threads_lifecycle, test_thread_runtime_stats_get) { @@ -551,6 +589,13 @@ ZTEST(threads_lifecycle, test_thread_runtime_stats_get) zassert_true(stats.execution_cycles <= stats_all.execution_cycles); } + +/** + * @brief Test the behavior of k_busy_wait with thread runtime statistics. + * + * This test verifies the accuracy of the `k_busy_wait` function by checking + * the thread's execution cycle statistics before and after calling the function. + */ ZTEST(threads_lifecycle, test_k_busy_wait) { uint64_t cycles, dt; @@ -589,6 +634,12 @@ static void tp_entry(void *p1, void *p2, void *p3) tp = 100; } +/** + * @brief Test the behavior of k_busy_wait with thread runtime statistics + * in user mode. + * + * @ingroup kernel_thread_tests + */ ZTEST_USER(threads_lifecycle_1cpu, test_k_busy_wait_user) { @@ -624,9 +675,14 @@ static int small_stack(size_t *space) return k_thread_stack_space_get(k_current_get(), space); } -/* test k_thread_stack_sapce_get(), unused stack space in large_stack_space() +/** + * @brief Test k_thread_stack_sapce_get + * + * Test k_thread_stack_sapce_get unused stack space in large_stack_space() * is smaller than that in small_stack() because the former function has a * large local variable + * + * @ingroup kernel_thread_tests */ ZTEST_USER(threads_lifecycle, test_k_thread_stack_space_get_user) { diff --git a/tests/kernel/threads/thread_apis/src/test_essential_thread.c b/tests/kernel/threads/thread_apis/src/test_essential_thread.c index 1803c56758f..5fb316d51e5 100644 --- a/tests/kernel/threads/thread_apis/src/test_essential_thread.c +++ b/tests/kernel/threads/thread_apis/src/test_essential_thread.c @@ -114,6 +114,16 @@ ZTEST(threads_lifecycle, test_essential_thread_abort) zassert_true(fatal_error_signaled, "fatal error was not signaled"); } +/** + * @brief Abort an essential thread from itself + * + * @details The kernel shall raise a fatal system error if an essential thread + * aborts, implement k_sys_fatal_error_handler to handle this error. + * + * @ingroup kernel_thread_tests + * + * @see #K_ESSENTIAL(x) + */ ZTEST(threads_lifecycle, test_essential_thread_abort_self) { /* This test case needs to be able to handle a k_panic() call diff --git a/tests/kernel/threads/thread_apis/src/test_threads_cancel_abort.c b/tests/kernel/threads/thread_apis/src/test_threads_cancel_abort.c index b99347a404f..b79f237d7a7 100644 --- a/tests/kernel/threads/thread_apis/src/test_threads_cancel_abort.c +++ b/tests/kernel/threads/thread_apis/src/test_threads_cancel_abort.c @@ -32,7 +32,7 @@ static void thread_entry_abort(void *p1, void *p2, void *p3) } /** * @ingroup kernel_thread_tests - * @brief Validate k_thread_abort() when called by current thread + * @brief Validate aborting a thread when called by current thread * * @details Create a user thread and let the thread execute. * Then call k_thread_abort() and check if the thread is terminated. @@ -52,7 +52,7 @@ ZTEST_USER(threads_lifecycle, test_threads_abort_self) /** * @ingroup kernel_thread_tests - * @brief Validate k_thread_abort() when called by other thread + * @brief Validate aborting a thread when called by other thread * * @details Create a user thread and abort the thread before its * execution. Create a another user thread and abort the thread @@ -85,7 +85,7 @@ ZTEST_USER(threads_lifecycle, test_threads_abort_others) /** * @ingroup kernel_thread_tests - * @brief Test abort on a terminated thread + * @brief Test abort on an already terminated thread * * @see k_thread_abort() */ diff --git a/tests/kernel/threads/thread_apis/src/test_threads_cpu_mask.c b/tests/kernel/threads/thread_apis/src/test_threads_cpu_mask.c index dd521cbbf57..574bcd5aeee 100644 --- a/tests/kernel/threads/thread_apis/src/test_threads_cpu_mask.c +++ b/tests/kernel/threads/thread_apis/src/test_threads_cpu_mask.c @@ -22,6 +22,19 @@ void child_fn(void *a, void *b, void *c) child_has_run = true; } + +/** + * @brief Test the CPU mask APIs for thread lifecycle management + * + * This test verifies the behavior of the CPU mask APIs in the Zephyr kernel + * for thread lifecycle management. It ensures that the APIs behave as expected + * when operating on both running and non-running threads. + * + * @note This test is only executed if `CONFIG_SCHED_CPU_MASK` is enabled. + * Otherwise, the test is skipped. + * + * @ingroup kernel_thread_tests + */ ZTEST(threads_lifecycle_1cpu, test_threads_cpu_mask) { #ifdef CONFIG_SCHED_CPU_MASK diff --git a/tests/kernel/threads/thread_apis/src/test_threads_set_priority.c b/tests/kernel/threads/thread_apis/src/test_threads_set_priority.c index 06672af99d1..1d022a3e28b 100644 --- a/tests/kernel/threads/thread_apis/src/test_threads_set_priority.c +++ b/tests/kernel/threads/thread_apis/src/test_threads_set_priority.c @@ -23,7 +23,7 @@ struct isr_arg { static struct isr_arg prio_args; /** - * @brief Test ISR used to change a thread's priority + * @brief Test changing a thread's priority from an ISR */ static void test_isr(const void *arg) { @@ -33,9 +33,7 @@ static void test_isr(const void *arg) } /** - * - * @brief thread2 portion to test setting the priority - * + * @brief Test thread behavior when its priority is changed */ void thread2_set_prio_test(void *p1, void *p2, void *p3) { @@ -61,7 +59,11 @@ void thread2_set_prio_test(void *p1, void *p2, void *p3) /** * @ingroup kernel_thread_tests - * @brief Test the k_thread_priority_set() API + * @brief Test setting and verifying thread priorities + * + * @details This test creates a thread with a lower priority than the + * current thread. It then sets the priority of the thread to a + * higher value, and checks that the priority has been set correctly. * * @see k_thread_priority_set(), k_thread_priority_get() */ @@ -74,61 +76,64 @@ ZTEST(threads_lifecycle, test_threads_priority_set) k_thread_priority_set(k_current_get(), prio + 2); rv = k_thread_priority_get(k_current_get()); zassert_equal(rv, prio + 2, - "Expected priority to be changed to %d, not %d\n", - prio + 2, rv); + "Expected priority to be changed to %d, not %d\n", + prio + 2, rv); /* Raise the priority of the current thread (thread1) */ k_thread_priority_set(k_current_get(), prio - 2); rv = k_thread_priority_get(k_current_get()); zassert_equal(rv, prio - 2, - "Expected priority to be changed to %d, not %d\n", - prio - 2, rv); + "Expected priority to be changed to %d, not %d\n", + prio - 2, rv); /* Restore the priority of the current thread (thread1) */ k_thread_priority_set(k_current_get(), prio); rv = k_thread_priority_get(k_current_get()); zassert_equal(rv, prio, - "Expected priority to be changed to %d, not %d\n", - prio, rv); + "Expected priority to be changed to %d, not %d\n", + prio, rv); /* create thread with lower priority */ int thread2_prio = prio + 1; k_tid_t thread2_id = k_thread_create(&tdata, tstack, STACK_SIZE, - thread2_set_prio_test, - NULL, NULL, NULL, thread2_prio, 0, - K_NO_WAIT); + thread2_set_prio_test, + NULL, NULL, NULL, thread2_prio, 0, + K_NO_WAIT); /* Lower the priority of thread2 */ k_thread_priority_set(thread2_id, thread2_prio + 2); k_sem_give(&sem_thread2); k_sem_take(&sem_thread1, K_FOREVER); zassert_equal(thread2_data, thread2_prio + 2, - "Expected priority to be changed to %d, not %d\n", - thread2_prio + 2, thread2_data); + "Expected priority to be changed to %d, not %d\n", + thread2_prio + 2, thread2_data); /* Raise the priority of thread2 */ k_thread_priority_set(thread2_id, thread2_prio - 2); k_sem_give(&sem_thread2); k_sem_take(&sem_thread1, K_FOREVER); zassert_equal(thread2_data, thread2_prio - 2, - "Expected priority to be changed to %d, not %d\n", - thread2_prio - 2, thread2_data); + "Expected priority to be changed to %d, not %d\n", + thread2_prio - 2, thread2_data); /* Restore the priority of thread2 */ k_thread_priority_set(thread2_id, thread2_prio); k_sem_give(&sem_thread2); k_sem_take(&sem_thread1, K_FOREVER); zassert_equal(thread2_data, thread2_prio, - "Expected priority to be changed to %d, not %d\n", - thread2_prio, thread2_data); + "Expected priority to be changed to %d, not %d\n", + thread2_prio, thread2_data); k_thread_join(thread2_id, K_FOREVER); } /** * @ingroup kernel_thread_tests - * @brief Test the k_thread_priority_set() API from an ISR + * @brief Test changing thread priorities from an ISR + * + * @details This test verifies that thread priorities can be changed + * correctly when invoked from an interrupt service routine (ISR). * * @see k_thread_priority_set(), k_thread_priority_get() */ @@ -143,32 +148,32 @@ ZTEST(threads_lifecycle, test_isr_threads_priority_set_) irq_offload(test_isr, &prio_args); rv = k_thread_priority_get(k_current_get()); zassert_equal(rv, prio + 2, - "Expected priority to be changed to %d, not %d\n", - prio + 2, rv); + "Expected priority to be changed to %d, not %d\n", + prio + 2, rv); /* Raise the priority of the current thread (thread1) */ prio_args.prio = prio - 2; irq_offload(test_isr, &prio_args); rv = k_thread_priority_get(k_current_get()); zassert_equal(rv, prio - 2, - "Expected priority to be changed to %d, not %d\n", - prio - 2, rv); + "Expected priority to be changed to %d, not %d\n", + prio - 2, rv); /* Restore the priority of the current thread (thread1) */ prio_args.prio = prio; irq_offload(test_isr, &prio_args); rv = k_thread_priority_get(k_current_get()); zassert_equal(rv, prio, - "Expected priority to be changed to %d, not %d\n", - prio, rv); + "Expected priority to be changed to %d, not %d\n", + prio, rv); /* create thread with lower priority */ int thread2_prio = prio + 1; k_tid_t thread2_id = k_thread_create(&tdata, tstack, STACK_SIZE, - thread2_set_prio_test, - NULL, NULL, NULL, thread2_prio, 0, - K_NO_WAIT); + thread2_set_prio_test, + NULL, NULL, NULL, thread2_prio, 0, + K_NO_WAIT); /* Lower the priority of thread2 */ prio_args.thread = thread2_id; @@ -177,8 +182,8 @@ ZTEST(threads_lifecycle, test_isr_threads_priority_set_) k_sem_give(&sem_thread2); k_sem_take(&sem_thread1, K_FOREVER); zassert_equal(thread2_data, thread2_prio + 2, - "Expected priority to be changed to %d, not %d\n", - thread2_prio + 2, thread2_data); + "Expected priority to be changed to %d, not %d\n", + thread2_prio + 2, thread2_data); /* Raise the priority of thread2 */ prio_args.prio = thread2_prio - 2; @@ -186,8 +191,8 @@ ZTEST(threads_lifecycle, test_isr_threads_priority_set_) k_sem_give(&sem_thread2); k_sem_take(&sem_thread1, K_FOREVER); zassert_equal(thread2_data, thread2_prio - 2, - "Expected priority to be changed to %d, not %d\n", - thread2_prio - 2, thread2_data); + "Expected priority to be changed to %d, not %d\n", + thread2_prio - 2, thread2_data); /* Restore the priority of thread2 */ prio_args.prio = thread2_prio; @@ -195,7 +200,7 @@ ZTEST(threads_lifecycle, test_isr_threads_priority_set_) k_sem_give(&sem_thread2); k_sem_take(&sem_thread1, K_FOREVER); zassert_equal(thread2_data, thread2_prio, - "Expected priority to be changed to %d, not %d\n", - thread2_prio, thread2_data); + "Expected priority to be changed to %d, not %d\n", + thread2_prio, thread2_data); k_thread_join(thread2_id, K_FOREVER); } diff --git a/tests/kernel/threads/thread_apis/src/test_threads_spawn.c b/tests/kernel/threads/thread_apis/src/test_threads_spawn.c index 7d4847c44d7..893ccaa1f6d 100644 --- a/tests/kernel/threads/thread_apis/src/test_threads_spawn.c +++ b/tests/kernel/threads/thread_apis/src/test_threads_spawn.c @@ -129,7 +129,7 @@ ZTEST(threads_lifecycle, test_threads_spawn_forever) /** * @ingroup kernel_thread_tests - * @brief Validate behavior of multiple calls to k_thread_start() + * @brief Validate behavior of multiple calls to k_thread_start * * @details Call k_thread_start() on an already terminated thread * diff --git a/tests/kernel/threads/thread_apis/src/test_threads_suspend_resume.c b/tests/kernel/threads/thread_apis/src/test_threads_suspend_resume.c index bc23b5f6774..a5810bad4fd 100644 --- a/tests/kernel/threads/thread_apis/src/test_threads_suspend_resume.c +++ b/tests/kernel/threads/thread_apis/src/test_threads_suspend_resume.c @@ -86,7 +86,7 @@ void suspend_myself(void *arg0, void *arg1, void *arg2) /** * @ingroup kernel_thread_tests * - * @brief Check that k_thread_suspend() is a schedule point when + * @brief Check that suspending a thread is a schedule point when * called on the current thread. */ ZTEST(threads_lifecycle, test_threads_suspend) @@ -121,7 +121,7 @@ void sleep_suspended(void *arg0, void *arg1, void *arg2) /** * @ingroup kernel_thread_tests - * @brief Check that k_thread_suspend() cancels a preexisting thread timeout + * @brief Check that suspending a thread cancels a preexisting thread timeout * * @details Suspended threads should not wake up unexpectedly if they * happened to have been sleeping when suspended. @@ -149,7 +149,7 @@ ZTEST(threads_lifecycle, test_threads_suspend_timeout) /** * @ingroup kernel_thread_tests - * @brief Check resume an unsuspend thread + * @brief Check resuming a thread that is not suspended * * @details Use k_thread_state_str() to get thread state. * Resume an unsuspend thread will not change the thread state.