[rtems commit] score: Improve _Thread_Start() description

[Sebastian Huber]

Module:    rtems
Branch:    master
Commit:    1fab9726c90235b603957f8ae3d7e81bc2091050
Changeset: http://git.rtems.org/rtems/commit/?id=1fab9726c90235b603957f8ae3d7e81bc2091050

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Tue Jul 21 15:22:55 2020 +0200

score: Improve _Thread_Start() description

---

 cpukit/include/rtems/score/threadimpl.h | 36 +++++++++++++++++++++++++++------
 1 file changed, 30 insertions(+), 6 deletions(-)

diff --git a/cpukit/include/rtems/score/threadimpl.h b/cpukit/include/rtems/score/threadimpl.h
index b4b85ff..0b69caf 100644
--- a/cpukit/include/rtems/score/threadimpl.h
+++ b/cpukit/include/rtems/score/threadimpl.h
@@ -211,14 +211,38 @@ bool _Thread_Initialize(
 );
 
 /**
- * @brief Initializes thread and executes it.
+ * @brief Starts the specified thread.
  *
- * This routine initializes the executable information for a thread
- * and makes it ready to execute.  After this routine executes, the
- * thread competes with all other threads for CPU time.
+ * If the thread is not in the dormant state, the routine returns with a value
+ * of false and performs no actions except enabling interrupts as indicated by
+ * the ISR lock context.
  *
- * @param the_thread The thread to be started.
- * @param entry The thread entry information.
+ * Otherwise, this routine initializes the executable information for the
+ * thread and makes it ready to execute.  After the call of this routine, the
+ * thread competes with all other ready threads for CPU time.
+ *
+ * Then the routine enables the local interrupts as indicated by the ISR lock
+ * context.
+ *
+ * Then the thread start user extensions are called with thread dispatching
+ * disabled and interrupts enabled after making the thread ready.  Please note
+ * that in SMP configurations, the thread switch and begin user extensions may
+ * be called in parallel on another processor.
+ *
+ * Then thread dispatching is enabled and other threads may execute before the
+ * routine returns.
+ *
+ * @param[in, out] the_thread is the thread to start.
+ *
+ * @param entry is the thread entry information.
+ *
+ * @param[in, out] is the ISR lock context which shall be used to disable the
+ *   local interrupts before the call of this routine.
+ *
+ * @retval true The thread was in the dormant state and was sucessefully
+ *   started.
+ *
+ * @retval false Otherwise.
  */
 bool _Thread_Start(
   Thread_Control                 *the_thread,