diff options
Diffstat (limited to 'os/kernel/src/chthreads.c')
| -rw-r--r-- | os/kernel/src/chthreads.c | 49 |
1 files changed, 32 insertions, 17 deletions
diff --git a/os/kernel/src/chthreads.c b/os/kernel/src/chthreads.c index ae38dc11a..33ba3741e 100644 --- a/os/kernel/src/chthreads.c +++ b/os/kernel/src/chthreads.c @@ -59,6 +59,7 @@ /**
* @brief Initializes a thread structure.
+ * @note This is an internal functions, do not use it in application code.
*
* @param[in] tp pointer to the thread
* @param[in] prio the priority level for the new thread
@@ -112,6 +113,8 @@ static void memfill(uint8_t *startp, uint8_t *endp, uint8_t v) { * @brief Initializes a new thread.
* @details The new thread is initialized but not inserted in the ready list,
* the initial state is @p THD_STATE_SUSPENDED.
+ * @post The initialized thread can be subsequently started by invoking
+ * @p chThdResume().
* @note A thread can terminate by calling @p chThdExit() or by simply
* returning from its main function.
* @note This function can be invoked from within an interrupt handler
@@ -166,13 +169,12 @@ Thread *chThdCreateStatic(void *wsp, size_t size, #if CH_USE_DYNAMIC && CH_USE_HEAP
/**
* @brief Creates a new thread allocating the memory from the heap.
+ * @pre The configuration options @p CH_USE_DYNAMIC and @p CH_USE_HEAP
+ * must be enabled in order to use this function.
* @note A thread can terminate by calling @p chThdExit() or by simply
* returning from its main function.
* @note The memory allocated for the thread is not released when the thread
* terminates but when a @p chThdWait() is performed.
- * @note The function is available only if the @p CH_USE_DYNAMIC,
- * @p CH_USE_HEAP and @p CH_USE_WAITEXIT options are enabled
- * in @p chconf.h.
*
* @param[in] heapp heap from which allocate the memory or @p NULL for the
* default heap
@@ -202,14 +204,13 @@ Thread *chThdCreateFromHeap(MemoryHeap *heapp, size_t size, #if CH_USE_DYNAMIC && CH_USE_MEMPOOLS
/**
* @brief Creates a new thread allocating the memory from the specified
- * Memory Pool.
+ * memory pool.
+ * @pre The configuration options @p CH_USE_DYNAMIC and @p CH_USE_MEMPOOLS
+ * must be enabled in order to use this function.
* @note A thread can terminate by calling @p chThdExit() or by simply
* returning from its main function.
* @note The memory allocated for the thread is not released when the thread
* terminates but when a @p chThdWait() is performed.
- * @note The function is available only if the @p CH_USE_DYNAMIC,
- * @p CH_USE_MEMPOOLS and @p CH_USE_WAITEXIT options are enabled
- * in @p chconf.h.
*
* @param[in] mp pointer to the memory pool object
* @param[in] prio the priority level for the new thread
@@ -270,7 +271,11 @@ tprio_t chThdSetPriority(tprio_t newprio) { /**
* @brief Resumes a suspended thread.
- * @note Use this function to resume threads created with @p chThdInit().
+ * @pre The specified thread pointer must refer to an initialized thread
+ * in the @p THD_STATE_SUSPENDED state.
+ * @post The specified thread is immediately started or put in the ready
+ * list depending on the relative priority levels.
+ * @note Use this function to start threads created with @p chThdInit().
*
* @param[in] tp pointer to the thread
* @return The pointer to the thread.
@@ -288,9 +293,11 @@ Thread *chThdResume(Thread *tp) { /**
* @brief Requests a thread termination.
- * @note The thread is not terminated but a termination request is added to
- * its @p p_flags field. The thread can read this status by
- * invoking @p chThdShouldTerminate() and then terminate cleanly.
+ * @pre The target thread must be written to invoke periodically
+ * @p chThdShouldTerminate() and terminate cleanly if it returns
+ * @p TRUE.
+ * @post The specified thread will terminate after detecting the termination
+ * condition.
*
* @param[in] tp pointer to the thread
*/
@@ -349,10 +356,14 @@ void chThdYield(void) { }
/**
- * @brief Terminates the current thread by specifying an exit status code.
+ * @brief Terminates the current thread.
+ * @details The thread goes in the @p THD_STATE_FINAL state holding the
+ * specified exit status code, other threads can retrieve the
+ * exit status code by invoking the function @p chThdWait().
+ * @post Eventual code after this function will never be executed,
+ * this function never returns.
*
- * @param[in] msg thread exit code. The code can be retrieved by using
- * @p chThdWait().
+ * @param[in] msg thread exit code
*/
void chThdExit(msg_t msg) {
Thread *tp = currp;
@@ -375,6 +386,8 @@ void chThdExit(msg_t msg) { #if CH_USE_DYNAMIC || defined(__DOXYGEN__)
/**
* @brief Adds a reference to a thread object.
+ * @pre The configuration option @p CH_USE_DYNAMIC must be enabled in order
+ * to use this function.
*
* @param[in] tp pointer to the thread
* @return The same thread pointer passed as parameter
@@ -394,6 +407,8 @@ Thread *chThdAddRef(Thread *tp) { * @details If the references counter reaches zero <b>and</b> the thread
* is in the @p THD_STATE_FINAL state then the thread's memory is
* returned to the proper allocator.
+ * @pre The configuration option @p CH_USE_DYNAMIC must be enabled in order
+ * to use this function.
* @note Static threads are not affected.
*
* @param[in] tp pointer to the thread
@@ -444,10 +459,10 @@ void chThdRelease(Thread *tp) { * then the working area is returned to the owning memory pool.
* .
* Please read the @ref article_lifecycle article for more details.
- * @note After invoking @p chThdWait() the thread pointer becomes invalid
+ * @pre The configuration option @p CH_USE_WAITEXIT must be enabled in
+ * order to use this function.
+ * @post After invoking @p chThdWait() the thread pointer becomes invalid
* and must not be used as parameter for further system calls.
- * @note The function is available only if the @p CH_USE_WAITEXIT
- * option is enabled in @p chconf.h.
* @note If @p CH_USE_DYNAMIC is not specified this function just waits for
* the thread termination, no memory allocators are involved.
*
|