michaelh/zephyr
1
0
Fork 0
Code Releases Activity

tests: kernel: threads: improve doxygen comments, layout

Browse source 
Fix grouping and general doxygen fixups.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif 2025-04-17 10:55:46 -04:00 • committed by Benjamin Cabé
commit d837b644dd
7 changed files with 134 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

70
tests/kernel/threads/thread_apis/src/main.c
View file

@ -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)
{

10
tests/kernel/threads/thread_apis/src/test_essential_thread.c
View file

@ -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

6
tests/kernel/threads/thread_apis/src/test_threads_cancel_abort.c
View file

@ -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()
*/

13
tests/kernel/threads/thread_apis/src/test_threads_cpu_mask.c
View file

@ -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

77
tests/kernel/threads/thread_apis/src/test_threads_set_priority.c
View file

@ -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);
}

2
tests/kernel/threads/thread_apis/src/test_threads_spawn.c
View file

@ -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
*

6
tests/kernel/threads/thread_apis/src/test_threads_suspend_resume.c
View file

@ -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.