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

4.115
Last change on this file since e358088 was e358088, checked in by Sebastian Huber <sebastian.huber@…>, on May 28, 2013 at 8:54:46 AM

smp: New SMP lock API

Move the SMP lock implementation to the CPU port. An optimal SMP lock
implementation is highly architecture dependent. For example the memory
models may be fundamentally different.

The new SMP lock API has a flaw. It does not provide the ability to use
a local context for acquire and release pairs. Such a context is
necessary to implement for example the Mellor-Crummey and Scott (MCS)
locks. The SMP lock is currently used in _Thread_Disable_dispatch() and
_Thread_Enable_dispatch() and makes them to a giant lock acquire and
release. Since these functions do not pass state information via a
local context there is currently no use case for such a feature.

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