diff options
Diffstat (limited to 'os/kernel/include/threads.h')
| -rw-r--r-- | os/kernel/include/threads.h | 281 |
1 files changed, 169 insertions, 112 deletions
diff --git a/os/kernel/include/threads.h b/os/kernel/include/threads.h index 8a3756cb8..253b220fe 100644 --- a/os/kernel/include/threads.h +++ b/os/kernel/include/threads.h @@ -18,8 +18,9 @@ */ /** - * @file threads.h - * @brief Threads macros and structures. + * @file threads.h + * @brief Threads macros and structures. + * * @addtogroup threads * @{ */ @@ -38,115 +39,168 @@ #endif /** - * @brief Structure representing a thread. - * * @extends ThreadsQueue - * @note Not all the listed fields are always needed, by switching off some - * not needed ChibiOS/RT subsystems it is possible to save RAM space by - * shrinking the @p Thread structure. + * + * @brief Structure representing a thread. + * @note Not all the listed fields are always needed, by switching off some + * not needed ChibiOS/RT subsystems it is possible to save RAM space + * by shrinking the @p Thread structure. */ struct Thread { - Thread *p_next; /**< Next @p Thread in the threads - list/queue. */ + Thread *p_next; /**< @brief Next in the list/queue. */ /* End of the fields shared with the ThreadsList structure. */ - Thread *p_prev; /**< Previous @p Thread in the threads - queue. */ + Thread *p_prev; /**< @brief Previous in the queue. */ /* End of the fields shared with the ThreadsQueue structure. */ - tprio_t p_prio; /**< Thread priority. */ - struct context p_ctx; /**< Processor context. */ + tprio_t p_prio; /**< @brief Thread priority. */ + struct context p_ctx; /**< @brief Processor context. */ #if CH_USE_REGISTRY - Thread *p_newer; /**< Newer registry element. */ - Thread *p_older; /**< Older registry element. */ + Thread *p_newer; /**< @brief Newer registry element. */ + Thread *p_older; /**< @brief Older registry element. */ #endif /* End of the fields shared with the ReadyList structure. */ + /** + * @brief Current thread state. + */ + tstate_t p_state; + /** + * @brief Various thread flags. + */ + tmode_t p_flags; #if CH_USE_DYNAMIC - trefs_t p_refs; /**< References to this thread. */ + /** + * @brief References to this thread. + */ + trefs_t p_refs; #endif - tstate_t p_state; /**< Current thread state. */ - tmode_t p_flags; /**< Various thread flags. */ #if CH_USE_NESTED_LOCKS - cnt_t p_locks; /**< Number of nested locks. */ + /** + * @brief Number of nested locks. + */ + cnt_t p_locks; #endif #if CH_DBG_THREADS_PROFILING - volatile systime_t p_time; /**< Thread consumed time in ticks. - @note This field can overflow. */ + /** + * @brief Thread consumed time in ticks. + * @note This field can overflow. + */ + volatile systime_t p_time; #endif + /** + * @brief State-specific fields. + * @note All the fields declared in this union are only valid in the + * specified state or condition and are thus volatile. + */ union { - msg_t rdymsg; /**< Thread wakeup code. */ - msg_t exitcode; /**< The thread exit code - (@p THD_STATE_FINAL state). */ - void *wtobjp; /**< Generic kernel object pointer. */ + /** + * @brief Thread wakeup code. + * @note This field contains the low level message sent to the thread + * by the waking thread or interrupt handler. The value is valid + * after exiting the @p chSchWakeupS() function. + */ + msg_t rdymsg; + /** + * @brief Thread exit code. + * @note The thread termination code is stored in this field in order + * to be retrieved by the thread performing a @p chThdWait() on + * this thread. + */ + msg_t exitcode; + /** + * @brief Pointer to a generic "wait" object. + * @note This field is used to get a generic pointer to a synchronization + * object and is valid when the thread is in one of the wait + * states. + */ + void *wtobjp; #if CH_USE_EVENTS - eventmask_t ewmask; /**< Enabled events mask - (@p THD_STATE_WTOREVT or - @p THD_STATE_WTANDEVT states). */ + /** + * @brief Enabled events mask. + * @note This field is only valied while the thread is in the + * @p THD_STATE_WTOREVT or @p THD_STATE_WTANDEVT states. + */ + eventmask_t ewmask; #endif - } p_u; /**< State-specific fields. */ + } p_u; #if CH_USE_WAITEXIT - ThreadsList p_waiting; /**< Termination waiting list. */ + /** + * @brief Termination waiting list. + */ + ThreadsList p_waiting; #endif #if CH_USE_MESSAGES - ThreadsQueue p_msgqueue; /**< Messages queue. */ - msg_t p_msg; /**< Thread message. */ + /** + * @brief Messages queue. + */ + ThreadsQueue p_msgqueue; + /** + * @brief Thread message. + */ + msg_t p_msg; #endif #if CH_USE_EVENTS - eventmask_t p_epending; /**< Pending events mask. */ + /** + * @brief Pending events mask. + */ + eventmask_t p_epending; #endif #if CH_USE_MUTEXES - Mutex *p_mtxlist; /**< List of the mutexes owned by this - thread, @p NULL terminated. */ - tprio_t p_realprio; /**< Thread's own, non-inherited, - priority. */ + /** + * @brief List of the mutexes owned by this thread. + * @note The list is terminated by a @p NULL in this field. + */ + Mutex *p_mtxlist; + /** + * @brief Thread's own, non-inherited, priority. + */ + tprio_t p_realprio; #endif #if CH_USE_DYNAMIC && CH_USE_MEMPOOLS - void *p_mpool; /**< Memory Pool where the thread - workspace is returned. */ + /** + * @brief Memory Pool where the thread workspace is returned. + */ + void *p_mpool; #endif - /* Extra fields defined in chconf.h */ + /* Extra fields defined in chconf.h.*/ THREAD_EXT_FIELDS }; -/** Thread state: Ready to run, waiting on the ready list.*/ -#define THD_STATE_READY 0 -/** Thread state: Currently running.*/ -#define THD_STATE_CURRENT 1 -/** Thread state: Thread created in suspended state.*/ -#define THD_STATE_SUSPENDED 2 -/** Thread state: Waiting on a semaphore.*/ -#define THD_STATE_WTSEM 3 -/** Thread state: Waiting on a mutex.*/ -#define THD_STATE_WTMTX 4 -/** Thread state: Waiting in @p chCondWait().*/ -#define THD_STATE_WTCOND 5 -/** Thread state: Waiting in @p chThdSleep() or @p chThdSleepUntil().*/ -#define THD_STATE_SLEEPING 6 -/** Thread state: Waiting in @p chThdWait().*/ -#define THD_STATE_WTEXIT 7 -/** Thread state: Waiting in @p chEvtWaitOneTimeout() or - @p chEvtWaitAnyTimeout().*/ -#define THD_STATE_WTOREVT 8 -/** Thread state: Waiting in @p chEvtWaitAllTimeout().*/ -#define THD_STATE_WTANDEVT 9 -/** Thread state: Waiting in @p chMsgSend().*/ -#define THD_STATE_SNDMSG 10 -/** Thread state: Waiting in @p chMsgWait().*/ -#define THD_STATE_WTMSG 11 -/** Thread state: After termination.*/ -#define THD_STATE_FINAL 12 +/** @brief Thread state: Ready to run, waiting on the ready list.*/ +#define THD_STATE_READY 0 +/** @brief Thread state: Currently running.*/ +#define THD_STATE_CURRENT 1 +/** @brief Thread state: Thread created in suspended state.*/ +#define THD_STATE_SUSPENDED 2 +/** @brief Thread state: Waiting on a semaphore.*/ +#define THD_STATE_WTSEM 3 +/** @brief Thread state: Waiting on a mutex.*/ +#define THD_STATE_WTMTX 4 +/** @brief Thread state: Waiting in @p chCondWait().*/ +#define THD_STATE_WTCOND 5 +/** @brief Thread state: Waiting in @p chThdSleep() or @p chThdSleepUntil().*/ +#define THD_STATE_SLEEPING 6 +/** @brief Thread state: Waiting in @p chThdWait().*/ +#define THD_STATE_WTEXIT 7 +/** @brief Thread state: Waiting in @p chEvtWaitXXX().*/ +#define THD_STATE_WTOREVT 8 +/** @brief Thread state: Waiting in @p chEvtWaitAllTimeout().*/ +#define THD_STATE_WTANDEVT 9 +/** @brief Thread state: Waiting in @p chMsgSend().*/ +#define THD_STATE_SNDMSG 10 +/** @brief Thread state: Waiting in @p chMsgWait().*/ +#define THD_STATE_WTMSG 11 +/** @brief Thread state: After termination.*/ +#define THD_STATE_FINAL 12 /* * Various flags into the thread p_flags field. */ -#define THD_MEM_MODE_MASK 3 /**< Thread memory mode mask. */ -#define THD_MEM_MODE_STATIC 0 /**< Thread memory mode: static.*/ -#define THD_MEM_MODE_HEAP 1 /**< Thread memory mode: heap. */ -#define THD_MEM_MODE_MEMPOOL 2 /**< Thread memory mode: pool. */ -#define THD_TERMINATE 4 /**< Termination requested. */ - -/* Not an API, don't use into the application code.*/ -Thread *init_thread(Thread *tp, tprio_t prio); +#define THD_MEM_MODE_MASK 3 /**< @brief Thread memory mode mask. */ +#define THD_MEM_MODE_STATIC 0 /**< @brief Thread memory mode: static. */ +#define THD_MEM_MODE_HEAP 1 /**< @brief Thread memory mode: heap. */ +#define THD_MEM_MODE_MEMPOOL 2 /**< @brief Thread memory mode: pool. */ +#define THD_TERMINATE 4 /**< @brief Termination requested. */ -/** Thread function.*/ +/** @brief Thread function.*/ typedef msg_t (*tfunc_t)(void *); /* @@ -155,6 +209,7 @@ typedef msg_t (*tfunc_t)(void *); #ifdef __cplusplus extern "C" { #endif + Thread *init_thread(Thread *tp, tprio_t prio); Thread *chThdInit(void *wsp, size_t size, tprio_t prio, tfunc_t pf, void *arg); Thread *chThdCreateStatic(void *wsp, size_t size, @@ -186,85 +241,87 @@ extern "C" { #endif /** - * Returns a pointer to the current @p Thread. + * @brief Returns a pointer to the current @p Thread. */ #define chThdSelf() currp /** - * Returns the current thread priority. + * @brief Returns the current thread priority. */ #define chThdGetPriority() (currp->p_prio) /** - * Returns the pointer to the @p Thread local storage area, if any. + * @brief Returns the pointer to the @p Thread local storage area, if any. */ #define chThdLS() (void *)(currp + 1) /** - * Verifies if the specified thread is in the @p THD_STATE_FINAL state. + * @brief Verifies if the specified thread is in the @p THD_STATE_FINAL state. * - * @param[in] tp the pointer to the thread - * @retval TRUE thread terminated. - * @retval FALSE thread not terminated. + * @param[in] tp the pointer to the thread + * @retval TRUE thread terminated. + * @retval FALSE thread not terminated. */ #define chThdTerminated(tp) ((tp)->p_state == THD_STATE_FINAL) /** - * Verifies if the current thread has a termination request pending. + * @brief Verifies if the current thread has a termination request pending. * - * @retval TRUE termination request pended. - * @retval FALSE termination request not pended. + * @retval TRUE termination request pended. + * @retval FALSE termination request not pended. */ #define chThdShouldTerminate() (currp->p_flags & THD_TERMINATE) /** - * Resumes a thread created with @p chThdInit(). + * @brief Resumes a thread created with @p chThdInit(). * - * @param[in] tp the pointer to the thread + * @param[in] tp the pointer to the thread */ #define chThdResumeI(tp) chSchReadyI(tp) /** - * Suspends the invoking thread for the specified time. + * @brief Suspends the invoking thread for the specified time. * - * @param[in] time the delay in system ticks, the special values are handled as - * follow: - * - @a TIME_INFINITE the thread enters an infinite sleep - * state. - * - @a TIME_IMMEDIATE this value is accepted but interpreted - * as a normal time specification not as an immediate timeout - * specification. - * . + * @param[in] time the delay in system ticks, the special values are + * handled as follow: + * - @a TIME_INFINITE the thread enters an infinite sleep + * state. + * - @a TIME_IMMEDIATE this value is accepted but + * interpreted as a normal time specification not as + * an immediate timeout specification. + * . */ #define chThdSleepS(time) chSchGoSleepTimeoutS(THD_STATE_SLEEPING, time) /** - * Delays the invoking thread for the specified number of seconds. + * @brief Delays the invoking thread for the specified number of seconds. + * @note The specified time is rounded up to a value allowed by the real + * system clock. + * @note The maximum specified value is implementation dependent. * - * @param[in] sec the time in seconds - * @note The specified time is rounded up to a value allowed by the real - * system clock. - * @note The maximum specified value is implementation dependent. + * @param[in] sec the time in seconds */ #define chThdSleepSeconds(sec) chThdSleep(S2ST(sec)) /** - * Delays the invoking thread for the specified number of milliseconds. + * @brief Delays the invoking thread for the specified number of + * milliseconds. + * @note The specified time is rounded up to a value allowed by the real + * system clock. + * @note The maximum specified value is implementation dependent. * - * @param[in] msec the time in milliseconds - * @note The specified time is rounded up to a value allowed by the real - * system clock. - * @note The maximum specified value is implementation dependent. + * @param[in] msec the time in milliseconds */ #define chThdSleepMilliseconds(msec) chThdSleep(MS2ST(msec)) /** - * Delays the invoking thread for the specified number of microseconds. + * @brief Delays the invoking thread for the specified number of + * microseconds. + * @note The specified time is rounded up to a value allowed by the real + * system clock. + * @note The maximum specified value is implementation dependent. * - * @param[in] usec the time in microseconds - * @note The specified time is rounded up to a value allowed by the real - * system clock. - * @note The maximum specified value is implementation dependent. + * @param[in] usec the time in microseconds */ #define chThdSleepMicroseconds(usec) chThdSleep(US2ST(usec)) |