From 4d6bc47ac31cd6d94f6315925cadbbeae3136e67 Mon Sep 17 00:00:00 2001 From: Andrew Boie Date: Sat, 24 Oct 2020 13:11:35 -0700 Subject: [PATCH] kernel: improve k_thread_user_mode_enter() docs Note the stack and TLS wipe when this function runs. Signed-off-by: Andrew Boie --- include/kernel.h | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/include/kernel.h b/include/kernel.h index 381af790724..e305c8a1c82 100644 --- a/include/kernel.h +++ b/include/kernel.h @@ -558,6 +558,19 @@ __syscall k_tid_t k_thread_create(struct k_thread *new_thread, /** * @brief Drop a thread's privileges permanently to user mode * + * This allows a supervisor thread to be re-used as a user thread. + * This function does not return, but control will transfer to the provided + * entry point as if this was a new user thread. + * + * The implementation ensures that the stack buffer contents are erased. + * Any thread-local storage will be reverted to a pristine state. + * + * Memory domain membership, resource pool assignment, kernel object + * permissions, priority, and thread options are preserved. + * + * A common use of this function is to re-use the main thread as a user thread + * once all supervisor mode-only tasks have been completed. + * * @param entry Function to start executing from * @param p1 1st entry point parameter * @param p2 2nd entry point parameter