diff options
author | Joel Sherrill <joel.sherrill@OARcorp.com> | 2006-01-16 15:13:58 +0000 |
---|---|---|
committer | Joel Sherrill <joel.sherrill@OARcorp.com> | 2006-01-16 15:13:58 +0000 |
commit | 6a074363a2657a86b5f1ea0fc1185f68ad9f3c08 (patch) | |
tree | 3785d2da164f2c26988014ad5dbae6e35aa24147 /cpukit/score/include/rtems/score/thread.h | |
parent | 2006-01-16 Joel Sherrill <joel@OARcorp.com> (diff) | |
download | rtems-6a074363a2657a86b5f1ea0fc1185f68ad9f3c08.tar.bz2 |
2006-01-16 Joel Sherrill <joel@OARcorp.com>
Large patch to improve Doxygen output. As a side-effect, grammar and
spelling errors were corrected, spacing errors were address, and some
variable names were improved.
* libmisc/monitor/mon-object.c, libmisc/monitor/monitor.h:
Account for changing OBJECTS_NO_CLASS to OBJECTS_CLASSIC_NO_CLASS.
* score/Doxyfile: Set output directory. Predefine some macro values.
Turn on graphical output.
* score/include/rtems/debug.h, score/include/rtems/seterr.h,
score/include/rtems/system.h, score/include/rtems/score/address.h,
score/include/rtems/score/apiext.h,
score/include/rtems/score/apimutex.h,
score/include/rtems/score/bitfield.h,
score/include/rtems/score/chain.h,
score/include/rtems/score/context.h,
score/include/rtems/score/coremsg.h,
score/include/rtems/score/coremutex.h,
score/include/rtems/score/coresem.h,
score/include/rtems/score/heap.h, score/include/rtems/score/interr.h,
score/include/rtems/score/isr.h, score/include/rtems/score/mpci.h,
score/include/rtems/score/mppkt.h,
score/include/rtems/score/object.h,
score/include/rtems/score/objectmp.h,
score/include/rtems/score/priority.h,
score/include/rtems/score/stack.h,
score/include/rtems/score/states.h,
score/include/rtems/score/sysstate.h,
score/include/rtems/score/thread.h,
score/include/rtems/score/threadmp.h,
score/include/rtems/score/threadq.h, score/include/rtems/score/tod.h,
score/include/rtems/score/tqdata.h,
score/include/rtems/score/userext.h,
score/include/rtems/score/watchdog.h,
score/include/rtems/score/wkspace.h,
score/inline/rtems/score/address.inl,
score/inline/rtems/score/chain.inl,
score/inline/rtems/score/coremutex.inl,
score/inline/rtems/score/coresem.inl,
score/inline/rtems/score/heap.inl,
score/inline/rtems/score/object.inl,
score/inline/rtems/score/stack.inl,
score/inline/rtems/score/thread.inl,
score/inline/rtems/score/tqdata.inl, score/macros/README,
score/src/heap.c, score/src/threadmp.c, score/src/threadready.c,
score/src/threadstartmultitasking.c: Improve generated Doxygen
output. Fix spelling and grammar errors in comments. Correct names of
some variables and propagate changes.
Diffstat (limited to 'cpukit/score/include/rtems/score/thread.h')
-rw-r--r-- | cpukit/score/include/rtems/score/thread.h | 151 |
1 files changed, 111 insertions, 40 deletions
diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h index 02bf0cbd86..7fbae11397 100644 --- a/cpukit/score/include/rtems/score/thread.h +++ b/cpukit/score/include/rtems/score/thread.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,8 @@ /** * @defgroup ScoreThread Thread Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality related to the management of + * threads. This includes the creation, deletion, and scheduling of threads. */ /**@{*/ @@ -67,21 +68,27 @@ typedef enum { THREAD_START_BOTH_NUMERIC_FIRST } Thread_Start_types; -/** - */ +/** This type corresponds to a very simple style thread entry point. */ typedef Thread ( *Thread_Entry )(); /* basic type */ +/** This type corresponds to a thread entry point which takes a single + * unsigned thirty-two bit integer as an argument. + */ typedef Thread ( *Thread_Entry_numeric )( uint32_t ); -/** +/** This type corresponds to a thread entry point which takes a single + * untyped pointer as an argument. */ typedef Thread ( *Thread_Entry_pointer )( void * ); -/** +/** This type corresponds to a thread entry point which takes a single + * untyped pointer and an unsigned thirty-two bit integer as arguments. */ typedef Thread ( *Thread_Entry_both_pointer_first )( void *, uint32_t ); -/** +/** This type corresponds to a thread entry point which takes a single + * unsigned thirty-two bit integer and an untyped pointer and an + * as arguments. */ typedef Thread ( *Thread_Entry_both_numeric_first )( uint32_t , void * ); @@ -99,11 +106,12 @@ typedef enum { THREAD_CPU_BUDGET_ALGORITHM_CALLOUT } Thread_CPU_budget_algorithms; -/** +/** This type defines the Thread Control Block structure. */ typedef struct Thread_Control_struct Thread_Control; -/** +/** This defines thes the entry point for the thread specific timeslice + * budget management algorithm. */ typedef void (*Thread_CPU_budget_algorithm_callout )( Thread_Control * ); @@ -117,7 +125,7 @@ struct rtems_task_variable_tt; * * This is the internal structure used to manager per Task Variables. */ -struct rtems_task_variable_tt { +typedef struct { /** This field points to the next per task variable for this task. */ struct rtems_task_variable_tt *next; /** This field points to the physical memory location of this per @@ -130,33 +138,46 @@ struct rtems_task_variable_tt { void *tval; /** This field points to the destructor for this per task variable. */ void (*dtor)(void *); -}; - -/** - */ -typedef struct rtems_task_variable_tt rtems_task_variable_t; +} rtems_task_variable_t; /** * The following structure contains the information which defines * the starting state of a thread. */ typedef struct { - Thread_Entry entry_point; /* starting thread address */ - Thread_Start_types prototype; /* how task is invoked */ - void *pointer_argument; /* pointer argument */ - uint32_t numeric_argument; /* numeric argument */ - /* initial execution modes */ + /** This field is the starting address for the thread. */ + Thread_Entry entry_point; + /** This field indicatres the how task is invoked. */ + Thread_Start_types prototype; + /** This field is the pointer argument passed at thread start. */ + void *pointer_argument; + /** This field is the numeric argument passed at thread start. */ + uint32_t numeric_argument; + /*-------------- initial execution modes ----------------- */ + /** This field indicates whether the thread was preemptible when + * it started. + */ boolean is_preemptible; + /** This field indicates the CPU budget algorith. */ Thread_CPU_budget_algorithms budget_algorithm; + /** This field is the routine to invoke when the CPU allotment is + * consumed. + */ Thread_CPU_budget_algorithm_callout budget_callout; + /** This field is the initial ISR disable level of this thread. */ uint32_t isr_level; - Priority_Control initial_priority; /* initial priority */ + /** This field is the initial priority. */ + Priority_Control initial_priority; + /** This field indicates whether the SuperCore allocated the stack. */ boolean core_allocated_stack; - Stack_Control Initial_stack; /* stack information */ + /** This field is the stack information. */ + Stack_Control Initial_stack; #if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE ) - void *fp_context; /* initial FP context area address */ + /** This field is the initial FP context area address. */ + void *fp_context; #endif - void *stack; /* initial stack area address */ + /** This field is the initial stack area address. */ + void *stack; } Thread_Start_information; /** @@ -204,17 +225,26 @@ typedef struct { * memory images for the shared part. */ typedef struct { + /** This field is the object management structure for each proxy. */ Objects_Control Object; + /** This field is the current execution state of this proxy. */ States_Control current_state; + /** This field is the current priority state of this proxy. */ Priority_Control current_priority; + /** This field is the base priority of this proxy. */ Priority_Control real_priority; + /** This field is the number of mutexes currently held by this proxy. */ uint32_t resource_count; + /** This field is the blocking information for this proxy. */ Thread_Wait_information Wait; + /** This field is the Watchdog used to manage proxy delays and timeouts. */ Watchdog_Control Timer; #if defined(RTEMS_MULTIPROCESSING) + /** This field is the received response packet in an MP system. */ MP_packet_Prefix *receive_packet; #endif /****************** end of common block ********************/ + /** This field is used to manage the set of proxies in the system. */ Chain_Node Active; } Thread_Proxy_control; @@ -226,54 +256,95 @@ typedef struct { * memory images for the shared part. */ typedef enum { + /** This value is for the Classic RTEMS API. */ THREAD_API_RTEMS, + /** This value is for the POSIX API. */ THREAD_API_POSIX, + /** This value is for the ITRON API. */ THREAD_API_ITRON } Thread_APIs; -/** - */ +/** This macro defines the first API which has threads. */ #define THREAD_API_FIRST THREAD_API_RTEMS -/** - */ +/** This macro defines the last API which has threads. */ #define THREAD_API_LAST THREAD_API_ITRON /** + * This structure defines the Thread Control Block (TCB). */ struct Thread_Control_struct { - Objects_Control Object; - States_Control current_state; - Priority_Control current_priority; - Priority_Control real_priority; - uint32_t resource_count; - Thread_Wait_information Wait; - Watchdog_Control Timer; + /** This field is the object management structure for each thread. */ + Objects_Control Object; + /** This field is the current execution state of this thread. */ + States_Control current_state; + /** This field is the current priority state of this thread. */ + Priority_Control current_priority; + /** This field is the base priority of this thread. */ + Priority_Control real_priority; + /** This field is the number of mutexes currently held by this thread. */ + uint32_t resource_count; + /** This field is the blocking information for this thread. */ + Thread_Wait_information Wait; + /** This field is the Watchdog used to manage thread delays and timeouts. */ + Watchdog_Control Timer; #if defined(RTEMS_MULTIPROCESSING) - MP_packet_Prefix *receive_packet; + /** This field is the received response packet in an MP system. */ + MP_packet_Prefix *receive_packet; #endif - /****************** end of common block ********************/ + /*================= end of common block =================*/ + /** This field is the number of nested suspend calls. */ uint32_t suspend_count; + /** This field is true if the thread is offered globally */ boolean is_global; + /** This field is is true if the post task context switch should be + * executed for this thread at the next context switch. + */ boolean do_post_task_switch_extension; - + /** This field is true if the thread is preemptible. */ boolean is_preemptible; + /** This field is the GNAT self context pointer. */ void *rtems_ada_self; + /** This field is the length of the time quantum that this thread is + * allowed to consume. The algorithm used to manage limits on CPU usage + * is specified by budget_algorithm. + */ uint32_t cpu_time_budget; + /** This field is the algorithm used to manage this thread's time + * quantum. The algorithm may be specified as none which case, + * no limit is in place. + */ Thread_CPU_budget_algorithms budget_algorithm; + /** This field is the method invoked with the budgeted time is consumed. */ Thread_CPU_budget_algorithm_callout budget_callout; + /** This field is the number of clock ticks executed by this thread + * since it was created. + */ uint32_t ticks_executed; + /** This field points to the Ready FIFO for this priority. */ Chain_Control *ready; + /** This field contains precalculated priority map indices. */ Priority_Information Priority_map; + /** This field contains information about the starting state of + * this thread. + */ Thread_Start_information Start; + /** This field contains the context of this thread. */ Context_Control Registers; #if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE ) + /** This field points to the floating point context for this thread. + * If NULL, the thread is integer only. + */ void *fp_context; #endif + /** This field points to the newlib reentrancy structure for this thread. */ struct _reent *libc_reent; + /** This array contains the API extension area pointers. */ void *API_Extensions[ THREAD_API_LAST + 1 ]; + /** This field points to the user extension pointers. */ void **extensions; + /** This field points to the set of per task variables. */ rtems_task_variable_t *task_variables; }; @@ -303,7 +374,7 @@ SCORE_EXTERN Thread_Control *_Thread_Idle; */ SCORE_EXTERN Context_Control _Thread_BSP_context; -/*** +/** * The following declares the dispatch critical section nesting * counter which is used to prevent context switches at inopportune * moments. @@ -651,7 +722,7 @@ Thread _Thread_Idle_body( ); #endif -/** +/** This defines the type for a method which operates on a single thread. */ typedef void (*rtems_per_thread_routine)( Thread_Control * ); |