source: rtems/cpukit/score/include/rtems/score/thread.h @ a936aa49

4.11
Last change on this file since a936aa49 was a936aa49, checked in by Sebastian Huber <sebastian.huber@…>, on Jun 6, 2013 at 1:41:00 PM

scheduler: New simple SMP scheduler implementation

The new Simple SMP Scheduler allocates a processor for the processor
count highest priority ready threads. The thread priority and position
in the ready chain are the only information to determine the scheduling
decision. Threads with an allocated processor are in the scheduled
chain. After initialization the scheduled chain has exactly processor
count nodes. Each processor has exactly one allocated thread after
initialization. All enqueue and extract operations may exchange threads
with the scheduled chain. One thread will be added and another will be
removed. The scheduled and ready chain is ordered according to the
thread priority order. The chain insert operations are O(count of ready
threads), thus this scheduler is unsuitable for most real-time
applications.

The thread preempt mode will be ignored.

  • Property mode set to 100644
File size: 29.2 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/**
23 *  @defgroup ScoreThread Thread Handler
24 *
25 *  @ingroup Score
26 *
27 *  This handler encapsulates functionality related to the management of
28 *  threads.  This includes the creation, deletion, and scheduling of threads.
29 *
30 *  The following variables are maintained as part of the per cpu data
31 *  structure.
32 *
33 *  + Idle thread pointer
34 *  + Executing thread pointer
35 *  + Heir thread pointer
36 */
37/**@{*/
38
39#if defined(RTEMS_POSIX_API)
40  #define RTEMS_SCORE_THREAD_ENABLE_EXHAUST_TIMESLICE
41#endif
42
43/*
44 * With the addition of the Constant Block Scheduler (CBS),
45 * this feature is needed even when POSIX is disabled.
46 */
47#define RTEMS_SCORE_THREAD_ENABLE_SCHEDULER_CALLOUT
48
49#if defined(RTEMS_POSIX_API)
50  #define RTEMS_SCORE_THREAD_ENABLE_USER_PROVIDED_STACK_VIA_API
51#endif
52
53/*
54 *  Deferred floating point context switches are not currently
55 *  supported when in SMP configuration.
56 */
57#if defined(RTEMS_SMP)
58  #undef  CPU_USE_DEFERRED_FP_SWITCH
59  #define CPU_USE_DEFERRED_FP_SWITCH FALSE
60#endif
61
62#ifdef __cplusplus
63extern "C" {
64#endif
65
66#include <rtems/score/percpu.h>
67#include <rtems/score/context.h>
68#include <rtems/score/cpu.h>
69#if defined(RTEMS_MULTIPROCESSING)
70#include <rtems/score/mppkt.h>
71#endif
72#include <rtems/score/object.h>
73#include <rtems/score/priority.h>
74#include <rtems/score/scheduler.h>
75#include <rtems/score/stack.h>
76#include <rtems/score/states.h>
77#include <rtems/score/tod.h>
78#include <rtems/score/tqdata.h>
79#include <rtems/score/watchdog.h>
80
81/*
82 *  The user can define this at configure time and go back to ticks
83 *  resolution.
84 */
85#ifndef __RTEMS_USE_TICKS_FOR_STATISTICS__
86  #include <rtems/score/timestamp.h>
87
88  typedef Timestamp_Control Thread_CPU_usage_t;
89#else
90  typedef uint32_t Thread_CPU_usage_t;
91#endif
92
93/**
94 *  The following defines the "return type" of a thread.
95 *
96 *  @note  This cannot always be right.  Some APIs have void
97 *         tasks/threads, others return pointers, others may
98 *         return a numeric value.  Hopefully a pointer is
99 *         always at least as big as an uint32_t  . :)
100 */
101typedef void *Thread;
102
103/**
104 *  @brief Type of the numeric argument of a thread entry function with at
105 *  least one numeric argument.
106 *
107 *  This numeric argument type designates an unsigned integer type with the
108 *  property that any valid pointer to void can be converted to this type and
109 *  then converted back to a pointer to void.  The result will compare equal to
110 *  the original pointer.
111 */
112typedef uintptr_t Thread_Entry_numeric_type;
113
114/**
115 *  The following defines the ways in which the entry point for a
116 *  thread can be invoked.  Basically, it can be passed any
117 *  combination/permutation of a pointer and an uint32_t   value.
118 *
119 *  @note For now, we are ignoring the return type.
120 */
121typedef enum {
122  THREAD_START_NUMERIC,
123  THREAD_START_POINTER,
124  #if defined(FUNCTIONALITY_NOT_CURRENTLY_USED_BY_ANY_API)
125    THREAD_START_BOTH_POINTER_FIRST,
126    THREAD_START_BOTH_NUMERIC_FIRST
127  #endif
128} Thread_Start_types;
129
130/** This type corresponds to a very simple style thread entry point. */
131typedef Thread ( *Thread_Entry )( void );   /* basic type */
132
133/** This type corresponds to a thread entry point which takes a single
134 *  unsigned thirty-two bit integer as an argument.
135 */
136typedef Thread ( *Thread_Entry_numeric )( Thread_Entry_numeric_type );
137
138/** This type corresponds to a thread entry point which takes a single
139 *  untyped pointer as an argument.
140 */
141typedef Thread ( *Thread_Entry_pointer )( void * );
142
143/** This type corresponds to a thread entry point which takes a single
144 *  untyped pointer and an unsigned thirty-two bit integer as arguments.
145 */
146typedef Thread ( *Thread_Entry_both_pointer_first )( void *, Thread_Entry_numeric_type );
147
148/** This type corresponds to a thread entry point which takes a single
149 *  unsigned thirty-two bit integer and an untyped pointer and an
150 *  as arguments.
151 */
152typedef Thread ( *Thread_Entry_both_numeric_first )( Thread_Entry_numeric_type, void * );
153
154/**
155 *  The following lists the algorithms used to manage the thread cpu budget.
156 *
157 *  Reset Timeslice:   At each context switch, reset the time quantum.
158 *  Exhaust Timeslice: Only reset the quantum once it is consumed.
159 *  Callout:           Execute routine when budget is consumed.
160 */
161typedef enum {
162  THREAD_CPU_BUDGET_ALGORITHM_NONE,
163  THREAD_CPU_BUDGET_ALGORITHM_RESET_TIMESLICE,
164  #if defined(RTEMS_SCORE_THREAD_ENABLE_EXHAUST_TIMESLICE)
165    THREAD_CPU_BUDGET_ALGORITHM_EXHAUST_TIMESLICE,
166  #endif
167  #if defined(RTEMS_SCORE_THREAD_ENABLE_SCHEDULER_CALLOUT)
168    THREAD_CPU_BUDGET_ALGORITHM_CALLOUT
169  #endif
170}  Thread_CPU_budget_algorithms;
171
172/**  This defines thes the entry point for the thread specific timeslice
173 *   budget management algorithm.
174 */
175typedef void (*Thread_CPU_budget_algorithm_callout )( Thread_Control * );
176
177/**
178 *  @brief Forward reference to the per task variable structure..
179 *
180 *  Forward reference to the per task variable structure.
181 */
182struct rtems_task_variable_tt;
183
184/**
185 *  @brief Internal structure used to manager per task variables.
186 *
187 *  This is the internal structure used to manager per Task Variables.
188 */
189typedef struct {
190  /** This field points to the next per task variable for this task. */
191  struct rtems_task_variable_tt  *next;
192  /** This field points to the physical memory location of this per
193   *  task variable.
194   */
195  void                          **ptr;
196  /** This field is to the global value for this per task variable. */
197  void                           *gval;
198  /** This field is to this thread's value for this per task variable. */
199  void                           *tval;
200  /** This field points to the destructor for this per task variable. */
201  void                          (*dtor)(void *);
202} rtems_task_variable_t;
203
204/**
205 *  The following structure contains the information which defines
206 *  the starting state of a thread.
207 */
208typedef struct {
209  /** This field is the starting address for the thread. */
210  Thread_Entry                         entry_point;
211  /** This field indicates the how task is invoked. */
212  Thread_Start_types                   prototype;
213  /** This field is the pointer argument passed at thread start. */
214  void                                *pointer_argument;
215  /** This field is the numeric argument passed at thread start. */
216  Thread_Entry_numeric_type            numeric_argument;
217  /*-------------- initial execution modes ----------------- */
218  /** This field indicates whether the thread was preemptible when
219    * it started.
220    */
221  bool                                 is_preemptible;
222  /** This field indicates the CPU budget algorith. */
223  Thread_CPU_budget_algorithms         budget_algorithm;
224  /** This field is the routine to invoke when the CPU allotment is
225   *  consumed.
226   */
227  Thread_CPU_budget_algorithm_callout  budget_callout;
228  /** This field is the initial ISR disable level of this thread. */
229  uint32_t                             isr_level;
230  /** This field is the initial priority. */
231  Priority_Control                     initial_priority;
232  #if defined(RTEMS_SCORE_THREAD_ENABLE_USER_PROVIDED_STACK_VIA_API)
233    /** This field indicates whether the SuperCore allocated the stack. */
234    bool                                 core_allocated_stack;
235  #endif
236  /** This field is the stack information. */
237  Stack_Control                        Initial_stack;
238  #if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )
239    /** This field is the initial FP context area address. */
240    Context_Control_fp                  *fp_context;
241  #endif
242  /** This field is the initial stack area address. */
243  void                                *stack;
244} Thread_Start_information;
245
246/**
247 *  The following structure contains the information necessary to manage
248 *  a thread which it is  waiting for a resource.
249 */
250#define THREAD_STATUS_PROXY_BLOCKING 0x1111111
251
252/**
253 *  @brief Union type to hold a pointer to an immutable or a mutable object.
254 *
255 *  The main purpose is to enable passing of pointers to read-only send buffers
256 *  in the message passing subsystem.  This approach is somewhat fragile since
257 *  it prevents the compiler to check if the operations on objects are valid
258 *  with respect to the constant qualifier.  An alternative would be to add a
259 *  third pointer argument for immutable objects, but this would increase the
260 *  structure size.
261 */
262typedef union {
263  void       *mutable_object;
264  const void *immutable_object;
265} Thread_Wait_information_Object_argument_type;
266
267/**
268 *  @brief Information required to manage a thread while it is blocked.
269 *
270 *  This contains the information required to manage a thread while it is
271 *  blocked and to return information to it.
272 */
273typedef struct {
274  /** This field is the Id of the object this thread is waiting upon. */
275  Objects_Id            id;
276  /** This field is used to return an integer while when blocked. */
277  uint32_t              count;
278  /** This field is for a pointer to a user return argument. */
279  void                 *return_argument;
280  /** This field is for a pointer to a second user return argument. */
281  Thread_Wait_information_Object_argument_type
282                        return_argument_second;
283  /** This field contains any options in effect on this blocking operation. */
284  uint32_t              option;
285  /** This field will contain the return status from a blocking operation.
286   *
287   *  @note The following assumes that all API return codes can be
288   *        treated as an uint32_t.
289   */
290  uint32_t              return_code;
291
292  /** This field is the chain header for the second through Nth tasks
293   *  of the same priority blocked waiting on the same object.
294   */
295  Chain_Control         Block2n;
296  /** This field points to the thread queue on which this thread is blocked. */
297  Thread_queue_Control *queue;
298}   Thread_Wait_information;
299
300/**
301 *  The following defines the control block used to manage
302 *  each thread proxy.
303 *
304 *  @note It is critical that proxies and threads have identical
305 *        memory images for the shared part.
306 */
307typedef struct {
308  /** This field is the object management structure for each proxy. */
309  Objects_Control          Object;
310  /** This field is the current execution state of this proxy. */
311  States_Control           current_state;
312  /** This field is the current priority state of this proxy. */
313  Priority_Control         current_priority;
314  /** This field is the base priority of this proxy. */
315  Priority_Control         real_priority;
316  /** This field is the number of mutexes currently held by this proxy. */
317  uint32_t                 resource_count;
318
319  /** This field is the blocking information for this proxy. */
320  Thread_Wait_information  Wait;
321  /** This field is the Watchdog used to manage proxy delays and timeouts. */
322  Watchdog_Control         Timer;
323#if defined(RTEMS_MULTIPROCESSING)
324  /** This field is the received response packet in an MP system. */
325  MP_packet_Prefix        *receive_packet;
326#endif
327     /****************** end of common block ********************/
328  /** This field is used to manage the set of proxies in the system. */
329  Chain_Node               Active;
330}   Thread_Proxy_control;
331
332/**
333 *  The following record defines the control block used
334 *  to manage each thread.
335 *
336 *  @note It is critical that proxies and threads have identical
337 *        memory images for the shared part.
338 */
339typedef enum {
340  /** This value is for the Classic RTEMS API. */
341  THREAD_API_RTEMS,
342  /** This value is for the POSIX API. */
343  THREAD_API_POSIX
344}  Thread_APIs;
345
346/** This macro defines the first API which has threads. */
347#define THREAD_API_FIRST THREAD_API_RTEMS
348
349/** This macro defines the last API which has threads. */
350#define THREAD_API_LAST  THREAD_API_POSIX
351
352/**
353 *  This structure defines the Thread Control Block (TCB).
354 */
355struct Thread_Control_struct {
356  /** This field is the object management structure for each thread. */
357  Objects_Control          Object;
358  /** This field is the current execution state of this thread. */
359  States_Control           current_state;
360  /** This field is the current priority state of this thread. */
361  Priority_Control         current_priority;
362  /** This field is the base priority of this thread. */
363  Priority_Control         real_priority;
364  /** This field is the number of mutexes currently held by this thread. */
365  uint32_t                 resource_count;
366  /** This field is the blocking information for this thread. */
367  Thread_Wait_information  Wait;
368  /** This field is the Watchdog used to manage thread delays and timeouts. */
369  Watchdog_Control         Timer;
370#if defined(RTEMS_MULTIPROCESSING)
371  /** This field is the received response packet in an MP system. */
372  MP_packet_Prefix        *receive_packet;
373#endif
374#ifdef __RTEMS_STRICT_ORDER_MUTEX__
375  /** This field is the head of queue of priority inheritance mutex
376   *  held by the thread.
377   */
378  Chain_Control            lock_mutex;
379#endif
380     /*================= end of common block =================*/
381#if defined(RTEMS_MULTIPROCESSING)
382  /** This field is true if the thread is offered globally */
383  bool                                  is_global;
384#endif
385  /** This field is true if the thread is preemptible. */
386  bool                                  is_preemptible;
387#if defined(RTEMS_SMP)
388  /**
389   * @brief This field is true if the thread is scheduled.
390   *
391   * A thread is scheduled if it is ready and the scheduler allocated a
392   * processor for it.  A scheduled thread is assigned to exactly one
393   * processor.  There are exactly processor count scheduled threads in the
394   * system.
395   */
396  bool                                  is_scheduled;
397
398  /**
399   * @brief This field is true if the thread is executing.
400   *
401   * A thread is executing if it executes on a processor.  An executing thread
402   * executes on exactly one processor.  There are exactly processor count
403   * executing threads in the system.  An executing thread may have a heir
404   * thread and thread dispatching is necessary.  On SMP a thread dispatch on a
405   * remote processor needs help from an inter-processor interrupt, thus it
406   * will take some time to complete the state change.  A lot of things can
407   * happen in the meantime.
408   */
409  bool                                  is_executing;
410#endif
411#if __RTEMS_ADA__
412  /** This field is the GNAT self context pointer. */
413  void                                 *rtems_ada_self;
414#endif
415  /** This field is the length of the time quantum that this thread is
416   *  allowed to consume.  The algorithm used to manage limits on CPU usage
417   *  is specified by budget_algorithm.
418   */
419  uint32_t                              cpu_time_budget;
420  /** This field is the algorithm used to manage this thread's time
421   *  quantum.  The algorithm may be specified as none which case,
422   *  no limit is in place.
423   */
424  Thread_CPU_budget_algorithms          budget_algorithm;
425  /** This field is the method invoked with the budgeted time is consumed. */
426  Thread_CPU_budget_algorithm_callout   budget_callout;
427  /** This field is the amount of CPU time consumed by this thread
428   *  since it was created.
429   */
430  Thread_CPU_usage_t                    cpu_time_used;
431
432  /** This pointer holds per-thread data for the scheduler and ready queue. */
433  void                                 *scheduler_info;
434
435#ifdef RTEMS_SMP
436  Per_CPU_Control                      *cpu;
437#endif
438
439  /** This field contains information about the starting state of
440   *  this thread.
441   */
442  Thread_Start_information              Start;
443  /** This field contains the context of this thread. */
444  Context_Control                       Registers;
445#if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )
446  /** This field points to the floating point context for this thread.
447   *  If NULL, the thread is integer only.
448   */
449  Context_Control_fp                   *fp_context;
450#endif
451  /** This field points to the newlib reentrancy structure for this thread. */
452  struct _reent                        *libc_reent;
453  /** This array contains the API extension area pointers. */
454  void                                 *API_Extensions[ THREAD_API_LAST + 1 ];
455  /** This field points to the user extension pointers. */
456  void                                **extensions;
457  /** This field points to the set of per task variables. */
458  rtems_task_variable_t                *task_variables;
459};
460
461/**
462 *  Self for the GNU Ada Run-Time
463 */
464SCORE_EXTERN void *rtems_ada_self;
465
466/**
467 *  The following defines the information control block used to
468 *  manage this class of objects.
469 */
470SCORE_EXTERN Objects_Information _Thread_Internal_information;
471
472/**
473 *  The following context area contains the context of the "thread"
474 *  which invoked the start multitasking routine.  This context is
475 *  restored as the last action of the stop multitasking routine.  Thus
476 *  control of the processor can be returned to the environment
477 *  which initiated the system.
478 */
479SCORE_EXTERN Context_Control _Thread_BSP_context;
480
481/**
482 *  The following holds how many user extensions are in the system.  This
483 *  is used to determine how many user extension data areas to allocate
484 *  per thread.
485 */
486SCORE_EXTERN uint32_t   _Thread_Maximum_extensions;
487
488/**
489 *  The following is used to manage the length of a timeslice quantum.
490 */
491SCORE_EXTERN uint32_t   _Thread_Ticks_per_timeslice;
492
493/**
494 *  The following points to the thread whose floating point
495 *  context is currently loaded.
496 */
497#if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )
498SCORE_EXTERN Thread_Control *_Thread_Allocated_fp;
499#endif
500
501/**
502 * The C library re-enter-rant global pointer. Some C library implementations
503 * such as newlib have a single global pointer that changed during a context
504 * switch. The pointer points to that global pointer. The Thread control block
505 * holds a pointer to the task specific data.
506 */
507SCORE_EXTERN struct _reent **_Thread_libc_reent;
508/**
509 *  @brief Initialize thread handler.
510 *
511 *  This routine performs the initialization necessary for this handler.
512 */
513void _Thread_Handler_initialization(void);
514
515/**
516 *  @brief Create idle thread.
517 *
518 *  This routine creates the idle thread.
519 *
520 *  @warning No thread should be created before this one.
521 */
522void _Thread_Create_idle(void);
523
524/**
525 *  @brief Start thread multitasking.
526 *
527 *  This routine initiates multitasking.  It is invoked only as
528 *  part of initialization and its invocation is the last act of
529 *  the non-multitasking part of the system initialization.
530 *
531 *
532 *  - INTERRUPT LATENCY:
533 *    + ready chain
534 *    + select heir
535 */
536void _Thread_Start_multitasking( void );
537
538/**
539 *  @brief Allocate the requested stack space for the thread.
540 *
541 *  Allocate the requested stack space for the thread.
542 *  Set the Start.stack field to the address of the stack.
543 *
544 *  @param[in] the_thread is the thread where the stack space is requested
545 *
546 *  @retval actual size allocated after any adjustment
547 *  @retval zero if the allocation failed
548 */
549size_t _Thread_Stack_Allocate(
550  Thread_Control *the_thread,
551  size_t          stack_size
552);
553
554/**
555 *  @brief Deallocate thread stack.
556 *
557 *  Deallocate the Thread's stack.
558 */
559void _Thread_Stack_Free(
560  Thread_Control *the_thread
561);
562
563/**
564 *  @brief Initialize thread.
565 *
566 *  This routine initializes the specified the thread.  It allocates
567 *  all memory associated with this thread.  It completes by adding
568 *  the thread to the local object table so operations on this
569 *  thread id are allowed.
570 *
571 *  @note If stack_area is NULL, it is allocated from the workspace.
572 *
573 *  @note If the stack is allocated from the workspace, then it is
574 *        guaranteed to be of at least minimum size.
575 */
576bool _Thread_Initialize(
577  Objects_Information                  *information,
578  Thread_Control                       *the_thread,
579  void                                 *stack_area,
580  size_t                                stack_size,
581  bool                                  is_fp,
582  Priority_Control                      priority,
583  bool                                  is_preemptible,
584  Thread_CPU_budget_algorithms          budget_algorithm,
585  Thread_CPU_budget_algorithm_callout   budget_callout,
586  uint32_t                              isr_level,
587  Objects_Name                          name
588);
589
590/**
591 *  @brief Initializes thread and executes it.
592 *
593 *  This routine initializes the executable information for a thread
594 *  and makes it ready to execute.  After this routine executes, the
595 *  thread competes with all other threads for CPU time.
596 *
597 *  @param the_thread is the thread to be initialized
598 *  @param the_prototype
599 *  @param entry_point
600 *  @param pointer_argument
601 *  @param numeric_argument
602 *  @param[in/out] processor The processor if used to start an idle thread
603 *  during system initialization.  Must be set to @c NULL to start a normal
604 *  thread.
605 */
606bool _Thread_Start(
607  Thread_Control            *the_thread,
608  Thread_Start_types         the_prototype,
609  void                      *entry_point,
610  void                      *pointer_argument,
611  Thread_Entry_numeric_type  numeric_argument,
612  Per_CPU_Control           *processor
613);
614
615/**
616 *  @brief Restarts the specified thread.
617 *
618 *  This support routine restarts the specified task in a way that the
619 *  next time this thread executes, it will begin execution at its
620 *  original starting point.
621 *
622 *  TODO:  multiple task arg profiles
623 */
624bool _Thread_Restart(
625  Thread_Control            *the_thread,
626  void                      *pointer_argument,
627  Thread_Entry_numeric_type  numeric_argument
628);
629
630/**
631 *  @brief Resets a thread to its initial state.
632 *
633 *  This routine resets a thread to its initial state but does
634 *  not restart it. Some APIs do this in separate
635 *  operations and this division helps support this.
636 *
637 *  @param[in] the_thread is the thread to resets
638 *  @param[in] pointer_argument
639 *  @param[in] numeric_argument
640 */
641void _Thread_Reset(
642  Thread_Control            *the_thread,
643  void                      *pointer_argument,
644  Thread_Entry_numeric_type  numeric_argument
645);
646
647/**
648 *  @brief Frees all memory associated with the specified thread.
649 *
650 *  This routine frees all memory associated with the specified
651 *  thread and removes it from the local object table so no further
652 *  operations on this thread are allowed.
653 */
654void _Thread_Close(
655  Objects_Information  *information,
656  Thread_Control       *the_thread
657);
658
659/**
660 *  @brief Removes any set states for @a the_thread.
661 *
662 *  This routine removes any set states for @a the_thread.  It performs
663 *  any necessary scheduling operations including the selection of
664 *  a new heir thread.
665 *
666 *  - INTERRUPT LATENCY:
667 *    + ready chain
668 *    + select heir
669 */
670void _Thread_Ready(
671  Thread_Control *the_thread
672);
673
674/**
675 *  @brief Clears the indicated STATES for @a the_thread.
676 *
677 *  This routine clears the indicated STATES for @a the_thread.  It performs
678 *  any necessary scheduling operations including the selection of
679 *  a new heir thread.
680 *
681 *  - INTERRUPT LATENCY:
682 *    + priority map
683 *    + select heir
684 */
685void _Thread_Clear_state(
686  Thread_Control *the_thread,
687  States_Control  state
688);
689
690/**
691 *  @brief Sets the indicated @a state for @a the_thread.
692 *
693 *  This routine sets the indicated @a state for @a the_thread.  It performs
694 *  any necessary scheduling operations including the selection of
695 *  a new heir thread.
696 *
697 *  @param[in] the_thread is the thread to set the state for.
698 *  @param[in] state is the state to set the_thread to.
699 *
700 *  - INTERRUPT LATENCY:
701 *   + ready chain
702 *   + select map
703 */
704void _Thread_Set_state(
705  Thread_Control *the_thread,
706  States_Control  state
707);
708
709/**
710 *  @brief Sets the transient state for a thread.
711 *
712 *  This routine sets the Transient state for @a the_thread.  It performs
713 *  any necessary scheduling operations including the selection of
714 *  a new heir thread.
715 *
716 *  @param[in] the_thread is the thread to preform the action upon.
717 *
718 *  - INTERRUPT LATENCY:
719 *    + single case
720 */
721void _Thread_Set_transient(
722  Thread_Control *the_thread
723);
724
725/**
726 *  @brief Initializes enviroment for a thread.
727 *
728 *  This routine initializes the context of @a the_thread to its
729 *  appropriate starting state.
730 *
731 *  @param[in] the_thread is the pointer to the thread control block.
732 */
733void _Thread_Load_environment(
734  Thread_Control *the_thread
735);
736
737/**
738 *  @brief Wrapper function for all threads.
739 *
740 *  This routine is the wrapper function for all threads.  It is
741 *  the starting point for all threads.  The user provided thread
742 *  entry point is invoked by this routine.  Operations
743 *  which must be performed immediately before and after the user's
744 *  thread executes are found here.
745 *
746 *  @note On entry, it is assumed all interrupts are blocked and that this
747 *  routine needs to set the initial isr level.  This may or may not
748 *  actually be needed by the context switch routine and as a result
749 *  interrupts may already be at there proper level.  Either way,
750 *  setting the initial isr level properly here is safe.
751 */
752void _Thread_Handler( void );
753
754/**
755 *  @brief Ended the delay of a thread.
756 *
757 *  This routine is invoked when a thread must be unblocked at the
758 *  end of a time based delay (i.e. wake after or wake when).
759 *  It is called by the watchdog handler.
760 *
761 *  @param[in] id is the thread id
762 */
763void _Thread_Delay_ended(
764  Objects_Id  id,
765  void       *ignored
766);
767
768/**
769 *  @brief Change the priority of a thread.
770 *
771 *  This routine changes the current priority of @a the_thread to
772 *  @a new_priority.  It performs any necessary scheduling operations
773 *  including the selection of a new heir thread.
774 *
775 *  @param[in] the_thread is the thread to change
776 *  @param[in] new_priority is the priority to set @a the_thread to
777 *  @param[in] prepend_it is a switch to prepend the thread
778 */
779void _Thread_Change_priority (
780  Thread_Control   *the_thread,
781  Priority_Control  new_priority,
782  bool              prepend_it
783);
784
785/**
786 *  @brief Set thread priority.
787 *
788 *  This routine updates the priority related fields in the_thread
789 *  control block to indicate the current priority is now new_priority.
790 */
791void _Thread_Set_priority(
792  Thread_Control   *the_thread,
793  Priority_Control  new_priority
794);
795
796/**
797 *  This routine updates the related suspend fields in the_thread
798 *  control block to indicate the current nested level.
799 */
800#define _Thread_Suspend( _the_thread ) \
801        _Thread_Set_state( _the_thread, STATES_SUSPENDED )
802
803/**
804 *  This routine updates the related suspend fields in the_thread
805 *  control block to indicate the current nested level.  A force
806 *  parameter of true will force a resume and clear the suspend count.
807 */
808#define _Thread_Resume( _the_thread ) \
809        _Thread_Clear_state( _the_thread, STATES_SUSPENDED )
810
811#if (CPU_PROVIDES_IDLE_THREAD_BODY == FALSE)
812/**
813 *  This routine is the body of the system idle thread.
814 *
815 *  NOTE: This routine is actually instantiated by confdefs.h when needed.
816 */
817void *_Thread_Idle_body(
818  uintptr_t  ignored
819);
820#endif
821
822/**  This defines the type for a method which operates on a single thread.
823 */
824typedef void (*rtems_per_thread_routine)( Thread_Control * );
825
826/**
827 *  @brief Iterates over all threads.
828 *  This routine iterates over all threads regardless of API and
829 *  invokes the specified routine.
830 */
831void rtems_iterate_over_all_threads(
832  rtems_per_thread_routine routine
833);
834
835/**
836 *  @brief Maps thread Id to a TCB pointer.
837 *
838 *  This function maps thread IDs to thread control
839 *  blocks.  If ID corresponds to a local thread, then it
840 *  returns the_thread control pointer which maps to ID
841 *  and @a location is set to OBJECTS_LOCAL.  If the thread ID is
842 *  global and resides on a remote node, then location is set
843 *  to OBJECTS_REMOTE, and the_thread is undefined.
844 *  Otherwise, location is set to OBJECTS_ERROR and
845 *  the_thread is undefined.
846 *
847 *  @param[in] id is the id of the thread.
848 *  @param[in] location is the location of the block.
849 *
850 *  @note  The performance of many RTEMS services depends upon
851 *         the quick execution of the "good object" path in this
852 *         routine.  If there is a possibility of saving a few
853 *         cycles off the execution time, this routine is worth
854 *         further optimization attention.
855 */
856Thread_Control *_Thread_Get (
857  Objects_Id         id,
858  Objects_Locations *location
859);
860
861/**
862 *  @brief Cancel a blocking operation due to ISR.
863 *
864 *  This method is used to cancel a blocking operation that was
865 *  satisfied from an ISR while the thread executing was in the
866 *  process of blocking.
867 *
868 *  This method will restore the previous ISR disable level during the cancel
869 *  operation.  Thus it is an implicit _ISR_Enable().
870 *
871 *  @param[in] sync_state is the synchronization state
872 *  @param[in] the_thread is the thread whose blocking is canceled
873 *  @param[in] level is the previous ISR disable level
874 *
875 *  @note This is a rare routine in RTEMS.  It is called with
876 *        interrupts disabled and only when an ISR completed
877 *        a blocking condition in process.
878 */
879void _Thread_blocking_operation_Cancel(
880  Thread_blocking_operation_States  sync_state,
881  Thread_Control                   *the_thread,
882  ISR_Level                         level
883);
884
885#ifndef __RTEMS_APPLICATION__
886#include <rtems/score/thread.inl>
887#endif
888#if defined(RTEMS_MULTIPROCESSING)
889#include <rtems/score/threadmp.h>
890#endif
891
892#ifdef __cplusplus
893}
894#endif
895
896/**@}*/
897
898#endif
899/* end of include file */
Note: See TracBrowser for help on using the repository browser.