From 23f699bd907fbea22ca0e50e1295bb1a94adbca9 Mon Sep 17 00:00:00 2001 From: Andy Ross Date: Tue, 23 Feb 2021 06:12:17 -0800 Subject: [PATCH] kernel/include: Elaborate documentation for k_thread_{abort,join}() Clarify some edge cases that struck me as important to understand. Signed-off-by: Andy Ross --- include/kernel.h | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/include/kernel.h b/include/kernel.h index cb40c2a7b8d..f3e84a60c05 100644 --- a/include/kernel.h +++ b/include/kernel.h @@ -420,7 +420,9 @@ void k_thread_system_pool_assign(struct k_thread *thread); * to being aborted, self-exiting, or taking a fatal error. This API returns * immediately if the thread isn't running. * - * This API may only be called from ISRs with a K_NO_WAIT timeout. + * This API may only be called from ISRs with a K_NO_WAIT timeout, + * where it can be useful as a predicate to detect when a thread has + * aborted. * * @param thread Thread to wait to exit * @param timeout upper bound time to wait for the thread to exit. @@ -537,6 +539,17 @@ __syscall k_tid_t k_current_get(void); * released. It is the responsibility of the caller of this routine to ensure * all necessary cleanup is performed. * + * After k_thread_abort() returns, the thread is guaranteed not to be + * running or to become runnable anywhere on the system. Normally + * this is done via blocking the caller (in the same manner as + * k_thread_join()), but in interrupt context on SMP systems the + * implementation is required to spin for threads that are running on + * other CPUs. Note that as specified, this means that on SMP + * platforms it is possible for application code to create a deadlock + * condition by simultaneously aborting a cycle of threads using at + * least one termination from interrupt context. Zephyr cannot detect + * all such conditions. + * * @param thread ID of thread to abort. * * @return N/A