michaelh/zephyr
1
0
Fork 0
Code Releases Activity

kernel/include: Elaborate documentation for k_thread_{abort,join}()

Browse source 
Clarify some edge cases that struck me as important to understand.

Signed-off-by: Andy Ross <andrew.j.ross@intel.com>
This commit is contained in:
Andy Ross 2021-02-23 06:12:17 -08:00 • committed by Anas Nashif
commit 23f699bd90
1 changed files with 14 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

15
include/kernel.h
View file

@ -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 * to being aborted, self-exiting, or taking a fatal error. This API returns
* immediately if the thread isn't running. * 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 thread Thread to wait to exit
* @param timeout upper bound time to wait for the thread 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 * released. It is the responsibility of the caller of this routine to ensure
* all necessary cleanup is performed. * 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. * @param thread ID of thread to abort.
* *
* @return N/A * @return N/A