diff options
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 * ); |