source: rtems/cpukit/score/include/rtems/score/thread.h @ 5618c37a

4.115
Last change on this file since 5618c37a was 5618c37a, checked in by Sebastian Huber <sebastian.huber@…>, on Jul 24, 2013 at 1:14:48 PM

score: Create thread implementation header

Move implementation specific parts of thread.h and thread.inl into new
header file threadimpl.h. The thread.h contains now only the
application visible API.

Remove superfluous header file includes from various files.

  • Property mode set to 100644
File size: 17.3 KB
Line 
1/**
2 *  @file  rtems/score/thread.h
3 *
4 *  @brief Constants and Structures Related with the Thread Control Block
5 *
6 *  This include file contains all constants and structures associated
7 *  with the thread control block.
8 */
9
10/*
11 *  COPYRIGHT (c) 1989-2009.
12 *  On-Line Applications Research Corporation (OAR).
13 *
14 *  The license and distribution terms for this file may be
15 *  found in the file LICENSE in this distribution or at
16 *  http://www.rtems.com/license/LICENSE.
17 */
18
19#ifndef _RTEMS_SCORE_THREAD_H
20#define _RTEMS_SCORE_THREAD_H
21
22#include <rtems/score/context.h>
23#if defined(RTEMS_MULTIPROCESSING)
24#include <rtems/score/mppkt.h>
25#endif
26#include <rtems/score/object.h>
27#include <rtems/score/percpu.h>
28#include <rtems/score/priority.h>
29#include <rtems/score/stack.h>
30#include <rtems/score/states.h>
31#include <rtems/score/tqdata.h>
32#include <rtems/score/watchdog.h>
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
38/**
39 *  @defgroup ScoreThread Thread Handler
40 *
41 *  @ingroup Score
42 *
43 *  This handler encapsulates functionality related to the management of
44 *  threads.  This includes the creation, deletion, and scheduling of threads.
45 *
46 *  The following variables are maintained as part of the per cpu data
47 *  structure.
48 *
49 *  + Idle thread pointer
50 *  + Executing thread pointer
51 *  + Heir thread pointer
52 */
53/**@{*/
54
55#if defined(RTEMS_POSIX_API)
56  #define RTEMS_SCORE_THREAD_ENABLE_EXHAUST_TIMESLICE
57#endif
58
59/*
60 * With the addition of the Constant Block Scheduler (CBS),
61 * this feature is needed even when POSIX is disabled.
62 */
63#define RTEMS_SCORE_THREAD_ENABLE_SCHEDULER_CALLOUT
64
65#if defined(RTEMS_POSIX_API)
66  #define RTEMS_SCORE_THREAD_ENABLE_USER_PROVIDED_STACK_VIA_API
67#endif
68
69/*
70 *  The user can define this at configure time and go back to ticks
71 *  resolution.
72 */
73#ifndef __RTEMS_USE_TICKS_FOR_STATISTICS__
74  #include <rtems/score/timestamp.h>
75
76  typedef Timestamp_Control Thread_CPU_usage_t;
77#else
78  typedef uint32_t Thread_CPU_usage_t;
79#endif
80
81/**
82 *  The following defines the "return type" of a thread.
83 *
84 *  @note  This cannot always be right.  Some APIs have void
85 *         tasks/threads, others return pointers, others may
86 *         return a numeric value.  Hopefully a pointer is
87 *         always at least as big as an uint32_t  . :)
88 */
89typedef void *Thread;
90
91/**
92 *  @brief Type of the numeric argument of a thread entry function with at
93 *  least one numeric argument.
94 *
95 *  This numeric argument type designates an unsigned integer type with the
96 *  property that any valid pointer to void can be converted to this type and
97 *  then converted back to a pointer to void.  The result will compare equal to
98 *  the original pointer.
99 */
100typedef uintptr_t Thread_Entry_numeric_type;
101
102/**
103 *  The following defines the ways in which the entry point for a
104 *  thread can be invoked.  Basically, it can be passed any
105 *  combination/permutation of a pointer and an uint32_t   value.
106 *
107 *  @note For now, we are ignoring the return type.
108 */
109typedef enum {
110  THREAD_START_NUMERIC,
111  THREAD_START_POINTER,
112  #if defined(FUNCTIONALITY_NOT_CURRENTLY_USED_BY_ANY_API)
113    THREAD_START_BOTH_POINTER_FIRST,
114    THREAD_START_BOTH_NUMERIC_FIRST
115  #endif
116} Thread_Start_types;
117
118/** This type corresponds to a very simple style thread entry point. */
119typedef Thread ( *Thread_Entry )( void );   /* basic type */
120
121/** This type corresponds to a thread entry point which takes a single
122 *  unsigned thirty-two bit integer as an argument.
123 */
124typedef Thread ( *Thread_Entry_numeric )( Thread_Entry_numeric_type );
125
126/** This type corresponds to a thread entry point which takes a single
127 *  untyped pointer as an argument.
128 */
129typedef Thread ( *Thread_Entry_pointer )( void * );
130
131/** This type corresponds to a thread entry point which takes a single
132 *  untyped pointer and an unsigned thirty-two bit integer as arguments.
133 */
134typedef Thread ( *Thread_Entry_both_pointer_first )( void *, Thread_Entry_numeric_type );
135
136/** This type corresponds to a thread entry point which takes a single
137 *  unsigned thirty-two bit integer and an untyped pointer and an
138 *  as arguments.
139 */
140typedef Thread ( *Thread_Entry_both_numeric_first )( Thread_Entry_numeric_type, void * );
141
142/**
143 *  The following lists the algorithms used to manage the thread cpu budget.
144 *
145 *  Reset Timeslice:   At each context switch, reset the time quantum.
146 *  Exhaust Timeslice: Only reset the quantum once it is consumed.
147 *  Callout:           Execute routine when budget is consumed.
148 */
149typedef enum {
150  THREAD_CPU_BUDGET_ALGORITHM_NONE,
151  THREAD_CPU_BUDGET_ALGORITHM_RESET_TIMESLICE,
152  #if defined(RTEMS_SCORE_THREAD_ENABLE_EXHAUST_TIMESLICE)
153    THREAD_CPU_BUDGET_ALGORITHM_EXHAUST_TIMESLICE,
154  #endif
155  #if defined(RTEMS_SCORE_THREAD_ENABLE_SCHEDULER_CALLOUT)
156    THREAD_CPU_BUDGET_ALGORITHM_CALLOUT
157  #endif
158}  Thread_CPU_budget_algorithms;
159
160/**  This defines thes the entry point for the thread specific timeslice
161 *   budget management algorithm.
162 */
163typedef void (*Thread_CPU_budget_algorithm_callout )( Thread_Control * );
164
165/**
166 *  @brief Forward reference to the per task variable structure..
167 *
168 *  Forward reference to the per task variable structure.
169 */
170struct rtems_task_variable_tt;
171
172/**
173 *  @brief Internal structure used to manager per task variables.
174 *
175 *  This is the internal structure used to manager per Task Variables.
176 */
177typedef struct {
178  /** This field points to the next per task variable for this task. */
179  struct rtems_task_variable_tt  *next;
180  /** This field points to the physical memory location of this per
181   *  task variable.
182   */
183  void                          **ptr;
184  /** This field is to the global value for this per task variable. */
185  void                           *gval;
186  /** This field is to this thread's value for this per task variable. */
187  void                           *tval;
188  /** This field points to the destructor for this per task variable. */
189  void                          (*dtor)(void *);
190} rtems_task_variable_t;
191
192/**
193 *  The following structure contains the information which defines
194 *  the starting state of a thread.
195 */
196typedef struct {
197  /** This field is the starting address for the thread. */
198  Thread_Entry                         entry_point;
199  /** This field indicates the how task is invoked. */
200  Thread_Start_types                   prototype;
201  /** This field is the pointer argument passed at thread start. */
202  void                                *pointer_argument;
203  /** This field is the numeric argument passed at thread start. */
204  Thread_Entry_numeric_type            numeric_argument;
205  /*-------------- initial execution modes ----------------- */
206  /** This field indicates whether the thread was preemptible when
207    * it started.
208    */
209  bool                                 is_preemptible;
210  /** This field indicates the CPU budget algorith. */
211  Thread_CPU_budget_algorithms         budget_algorithm;
212  /** This field is the routine to invoke when the CPU allotment is
213   *  consumed.
214   */
215  Thread_CPU_budget_algorithm_callout  budget_callout;
216  /** This field is the initial ISR disable level of this thread. */
217  uint32_t                             isr_level;
218  /** This field is the initial priority. */
219  Priority_Control                     initial_priority;
220  #if defined(RTEMS_SCORE_THREAD_ENABLE_USER_PROVIDED_STACK_VIA_API)
221    /** This field indicates whether the SuperCore allocated the stack. */
222    bool                                 core_allocated_stack;
223  #endif
224  /** This field is the stack information. */
225  Stack_Control                        Initial_stack;
226  #if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )
227    /** This field is the initial FP context area address. */
228    Context_Control_fp                  *fp_context;
229  #endif
230  /** This field is the initial stack area address. */
231  void                                *stack;
232} Thread_Start_information;
233
234/**
235 *  @brief Union type to hold a pointer to an immutable or a mutable object.
236 *
237 *  The main purpose is to enable passing of pointers to read-only send buffers
238 *  in the message passing subsystem.  This approach is somewhat fragile since
239 *  it prevents the compiler to check if the operations on objects are valid
240 *  with respect to the constant qualifier.  An alternative would be to add a
241 *  third pointer argument for immutable objects, but this would increase the
242 *  structure size.
243 */
244typedef union {
245  void       *mutable_object;
246  const void *immutable_object;
247} Thread_Wait_information_Object_argument_type;
248
249/**
250 *  @brief Information required to manage a thread while it is blocked.
251 *
252 *  This contains the information required to manage a thread while it is
253 *  blocked and to return information to it.
254 */
255typedef struct {
256  /** This field is the Id of the object this thread is waiting upon. */
257  Objects_Id            id;
258  /** This field is used to return an integer while when blocked. */
259  uint32_t              count;
260  /** This field is for a pointer to a user return argument. */
261  void                 *return_argument;
262  /** This field is for a pointer to a second user return argument. */
263  Thread_Wait_information_Object_argument_type
264                        return_argument_second;
265  /** This field contains any options in effect on this blocking operation. */
266  uint32_t              option;
267  /** This field will contain the return status from a blocking operation.
268   *
269   *  @note The following assumes that all API return codes can be
270   *        treated as an uint32_t.
271   */
272  uint32_t              return_code;
273
274  /** This field is the chain header for the second through Nth tasks
275   *  of the same priority blocked waiting on the same object.
276   */
277  Chain_Control         Block2n;
278  /** This field points to the thread queue on which this thread is blocked. */
279  Thread_queue_Control *queue;
280}   Thread_Wait_information;
281
282/**
283 *  The following defines the control block used to manage
284 *  each thread proxy.
285 *
286 *  @note It is critical that proxies and threads have identical
287 *        memory images for the shared part.
288 */
289typedef struct {
290  /** This field is the object management structure for each proxy. */
291  Objects_Control          Object;
292  /** This field is the current execution state of this proxy. */
293  States_Control           current_state;
294  /** This field is the current priority state of this proxy. */
295  Priority_Control         current_priority;
296  /** This field is the base priority of this proxy. */
297  Priority_Control         real_priority;
298  /** This field is the number of mutexes currently held by this proxy. */
299  uint32_t                 resource_count;
300
301  /** This field is the blocking information for this proxy. */
302  Thread_Wait_information  Wait;
303  /** This field is the Watchdog used to manage proxy delays and timeouts. */
304  Watchdog_Control         Timer;
305#if defined(RTEMS_MULTIPROCESSING)
306  /** This field is the received response packet in an MP system. */
307  MP_packet_Prefix        *receive_packet;
308#endif
309     /****************** end of common block ********************/
310  /** This field is used to manage the set of proxies in the system. */
311  Chain_Node               Active;
312}   Thread_Proxy_control;
313
314/**
315 *  The following record defines the control block used
316 *  to manage each thread.
317 *
318 *  @note It is critical that proxies and threads have identical
319 *        memory images for the shared part.
320 */
321typedef enum {
322  /** This value is for the Classic RTEMS API. */
323  THREAD_API_RTEMS,
324  /** This value is for the POSIX API. */
325  THREAD_API_POSIX
326}  Thread_APIs;
327
328/** This macro defines the first API which has threads. */
329#define THREAD_API_FIRST THREAD_API_RTEMS
330
331/** This macro defines the last API which has threads. */
332#define THREAD_API_LAST  THREAD_API_POSIX
333
334/**
335 *  This structure defines the Thread Control Block (TCB).
336 */
337struct Thread_Control_struct {
338  /** This field is the object management structure for each thread. */
339  Objects_Control          Object;
340  /** This field is the current execution state of this thread. */
341  States_Control           current_state;
342  /** This field is the current priority state of this thread. */
343  Priority_Control         current_priority;
344  /** This field is the base priority of this thread. */
345  Priority_Control         real_priority;
346  /** This field is the number of mutexes currently held by this thread. */
347  uint32_t                 resource_count;
348  /** This field is the blocking information for this thread. */
349  Thread_Wait_information  Wait;
350  /** This field is the Watchdog used to manage thread delays and timeouts. */
351  Watchdog_Control         Timer;
352#if defined(RTEMS_MULTIPROCESSING)
353  /** This field is the received response packet in an MP system. */
354  MP_packet_Prefix        *receive_packet;
355#endif
356#ifdef __RTEMS_STRICT_ORDER_MUTEX__
357  /** This field is the head of queue of priority inheritance mutex
358   *  held by the thread.
359   */
360  Chain_Control            lock_mutex;
361#endif
362     /*================= end of common block =================*/
363#if defined(RTEMS_MULTIPROCESSING)
364  /** This field is true if the thread is offered globally */
365  bool                                  is_global;
366#endif
367  /** This field is true if the thread is preemptible. */
368  bool                                  is_preemptible;
369#if defined(RTEMS_SMP)
370  /**
371   * @brief This field is true if the thread is scheduled.
372   *
373   * A thread is scheduled if it is ready and the scheduler allocated a
374   * processor for it.  A scheduled thread is assigned to exactly one
375   * processor.  There are exactly processor count scheduled threads in the
376   * system.
377   */
378  bool                                  is_scheduled;
379
380  /**
381   * @brief This field is true if the thread is executing.
382   *
383   * A thread is executing if it executes on a processor.  An executing thread
384   * executes on exactly one processor.  There are exactly processor count
385   * executing threads in the system.  An executing thread may have a heir
386   * thread and thread dispatching is necessary.  On SMP a thread dispatch on a
387   * remote processor needs help from an inter-processor interrupt, thus it
388   * will take some time to complete the state change.  A lot of things can
389   * happen in the meantime.
390   */
391  bool                                  is_executing;
392#endif
393#if __RTEMS_ADA__
394  /** This field is the GNAT self context pointer. */
395  void                                 *rtems_ada_self;
396#endif
397  /** This field is the length of the time quantum that this thread is
398   *  allowed to consume.  The algorithm used to manage limits on CPU usage
399   *  is specified by budget_algorithm.
400   */
401  uint32_t                              cpu_time_budget;
402  /** This field is the algorithm used to manage this thread's time
403   *  quantum.  The algorithm may be specified as none which case,
404   *  no limit is in place.
405   */
406  Thread_CPU_budget_algorithms          budget_algorithm;
407  /** This field is the method invoked with the budgeted time is consumed. */
408  Thread_CPU_budget_algorithm_callout   budget_callout;
409  /** This field is the amount of CPU time consumed by this thread
410   *  since it was created.
411   */
412  Thread_CPU_usage_t                    cpu_time_used;
413
414  /** This pointer holds per-thread data for the scheduler and ready queue. */
415  void                                 *scheduler_info;
416
417#ifdef RTEMS_SMP
418  Per_CPU_Control                      *cpu;
419#endif
420
421  /** This field contains information about the starting state of
422   *  this thread.
423   */
424  Thread_Start_information              Start;
425  /** This field contains the context of this thread. */
426  Context_Control                       Registers;
427#if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )
428  /** This field points to the floating point context for this thread.
429   *  If NULL, the thread is integer only.
430   */
431  Context_Control_fp                   *fp_context;
432#endif
433  /** This field points to the newlib reentrancy structure for this thread. */
434  struct _reent                        *libc_reent;
435  /** This array contains the API extension area pointers. */
436  void                                 *API_Extensions[ THREAD_API_LAST + 1 ];
437  /** This field points to the user extension pointers. */
438  void                                **extensions;
439  /** This field points to the set of per task variables. */
440  rtems_task_variable_t                *task_variables;
441};
442
443#if (CPU_PROVIDES_IDLE_THREAD_BODY == FALSE)
444/**
445 *  This routine is the body of the system idle thread.
446 *
447 *  NOTE: This routine is actually instantiated by confdefs.h when needed.
448 */
449void *_Thread_Idle_body(
450  uintptr_t  ignored
451);
452#endif
453
454/**  This defines the type for a method which operates on a single thread.
455 */
456typedef void (*rtems_per_thread_routine)( Thread_Control * );
457
458/**
459 *  @brief Iterates over all threads.
460 *  This routine iterates over all threads regardless of API and
461 *  invokes the specified routine.
462 */
463void rtems_iterate_over_all_threads(
464  rtems_per_thread_routine routine
465);
466
467/**
468 * @brief Returns the thread control block of the executing thread.
469 *
470 * This function can be called in any context.  On SMP configurations
471 * interrupts are disabled to ensure that the processor index is used
472 * consistently.
473 *
474 * @return The thread control block of the executing thread.
475 */
476RTEMS_INLINE_ROUTINE Thread_Control *_Thread_Get_executing( void )
477{
478  Thread_Control *executing;
479
480  #if defined( RTEMS_SMP )
481    ISR_Level level;
482
483    _ISR_Disable( level );
484  #endif
485
486  executing = _Thread_Executing;
487
488  #if defined( RTEMS_SMP )
489    _ISR_Enable( level );
490  #endif
491
492  return executing;
493}
494
495/**@}*/
496
497#ifdef __cplusplus
498}
499#endif
500
501#endif
502/* end of include file */
Note: See TracBrowser for help on using the repository browser.