thread.h

Go to the documentation of this file.

/*
 *  COPYRIGHT (c) 1989-2014.
 *  On-Line Applications Research Corporation (OAR).
 *
 *  Copyright (c) 2014 embedded brains GmbH.
 *
 *  The license and distribution terms for this file may be
 *  found in the file LICENSE in this distribution or at
 *  http://www.rtems.org/license/LICENSE.
 */

#ifndef _RTEMS_SCORE_THREAD_H
#define _RTEMS_SCORE_THREAD_H

#include <rtems/score/atomic.h>
#include <rtems/score/context.h>
#if defined(RTEMS_MULTIPROCESSING)
#include <rtems/score/mppkt.h>
#endif
#include <rtems/score/isrlock.h>
#include <rtems/score/object.h>
#include <rtems/score/priority.h>
#include <rtems/score/resource.h>
#include <rtems/score/stack.h>
#include <rtems/score/states.h>
#include <rtems/score/threadq.h>
#include <rtems/score/watchdog.h>

#if defined(RTEMS_SMP)
  #include <rtems/score/cpuset.h>
#endif

struct Per_CPU_Control;

struct Scheduler_Control;

struct Scheduler_Node;

#ifdef __cplusplus
extern "C" {
#endif

#if defined(RTEMS_POSIX_API)
  #define RTEMS_SCORE_THREAD_ENABLE_EXHAUST_TIMESLICE
#endif

/*
 * With the addition of the Constant Block Scheduler (CBS),
 * this feature is needed even when POSIX is disabled.
 */
#define RTEMS_SCORE_THREAD_ENABLE_SCHEDULER_CALLOUT

#if defined(RTEMS_POSIX_API)
  #define RTEMS_SCORE_THREAD_ENABLE_USER_PROVIDED_STACK_VIA_API
#endif

/*
 *  The user can define this at configure time and go back to ticks
 *  resolution.
 */
#include <rtems/score/timestamp.h>

typedef Timestamp_Control Thread_CPU_usage_t;

typedef void *Thread;

typedef CPU_Uint32ptr Thread_Entry_numeric_type;

typedef enum {
  THREAD_START_NUMERIC,
  THREAD_START_POINTER,
  #if defined(FUNCTIONALITY_NOT_CURRENTLY_USED_BY_ANY_API)
    THREAD_START_BOTH_POINTER_FIRST,
    THREAD_START_BOTH_NUMERIC_FIRST
  #endif
} Thread_Start_types;

typedef Thread ( *Thread_Entry )( void );   /* basic type */

typedef Thread ( *Thread_Entry_numeric )( Thread_Entry_numeric_type );

typedef Thread ( *Thread_Entry_pointer )( void * );

typedef Thread ( *Thread_Entry_both_pointer_first )( void *, Thread_Entry_numeric_type );

typedef Thread ( *Thread_Entry_both_numeric_first )( Thread_Entry_numeric_type, void * );

typedef enum {
  THREAD_CPU_BUDGET_ALGORITHM_NONE,
  THREAD_CPU_BUDGET_ALGORITHM_RESET_TIMESLICE,
  #if defined(RTEMS_SCORE_THREAD_ENABLE_EXHAUST_TIMESLICE)
    THREAD_CPU_BUDGET_ALGORITHM_EXHAUST_TIMESLICE,
  #endif
  #if defined(RTEMS_SCORE_THREAD_ENABLE_SCHEDULER_CALLOUT)
    THREAD_CPU_BUDGET_ALGORITHM_CALLOUT
  #endif
}  Thread_CPU_budget_algorithms;

typedef void (*Thread_CPU_budget_algorithm_callout )( Thread_Control * );

#if !defined(RTEMS_SMP)

struct rtems_task_variable_tt;

typedef struct {
  struct rtems_task_variable_tt  *next;
  void                          **ptr;
  void                           *gval;
  void                           *tval;
  void                          (*dtor)(void *);
} rtems_task_variable_t;
#endif

typedef struct {
  Thread_Entry                         entry_point;
  Thread_Start_types                   prototype;
  void                                *pointer_argument;
  Thread_Entry_numeric_type            numeric_argument;
  /*-------------- initial execution modes ----------------- */
  bool                                 is_preemptible;
  Thread_CPU_budget_algorithms         budget_algorithm;
  Thread_CPU_budget_algorithm_callout  budget_callout;
  uint32_t                             isr_level;
  Priority_Control                     initial_priority;
  #if defined(RTEMS_SCORE_THREAD_ENABLE_USER_PROVIDED_STACK_VIA_API)

    bool                                 core_allocated_stack;
  #endif

  Stack_Control                        Initial_stack;
  #if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )

    Context_Control_fp                  *fp_context;
  #endif

  void                                *stack;
  void                                *tls_area;
} Thread_Start_information;

typedef union {
  void       *mutable_object;
  const void *immutable_object;
} Thread_Wait_information_Object_argument_type;

typedef unsigned int Thread_Wait_flags;

typedef struct {
  union {
    Chain_Node Chain;

    RBTree_Node RBTree;
  } Node;

  Objects_Id            id;
  uint32_t              count;
  void                 *return_argument;
  Thread_Wait_information_Object_argument_type
                        return_argument_second;
  uint32_t              option;
  uint32_t              return_code;

  uint32_t timeout_code;

  Thread_queue_Control *queue;

#if defined(RTEMS_SMP)
  Atomic_Uint           flags;
#else
  Thread_Wait_flags     flags;
#endif

  const Thread_queue_Operations *operations;
}   Thread_Wait_information;

typedef struct {
  Objects_Control          Object;
  States_Control           current_state;

  Priority_Control         current_priority;

  Priority_Control         real_priority;

  uint32_t                 priority_generation;

  bool                     priority_restore_hint;

  uint32_t                 resource_count;

  Thread_Wait_information  Wait;
  Watchdog_Control         Timer;
#if defined(RTEMS_MULTIPROCESSING)

  MP_packet_Prefix        *receive_packet;
#endif
     /****************** end of common block ********************/
  Chain_Node               Active;
}   Thread_Proxy_control;

typedef enum {
  THREAD_API_RTEMS,
  THREAD_API_POSIX
}  Thread_APIs;

#define THREAD_API_FIRST THREAD_API_RTEMS

#define THREAD_API_LAST  THREAD_API_POSIX

typedef struct Thread_Action Thread_Action;

typedef void ( *Thread_Action_handler )(
  Thread_Control         *thread,
  Thread_Action          *action,
  struct Per_CPU_Control *cpu,
  ISR_Level               level
);

struct Thread_Action {
  Chain_Node            Node;
  Thread_Action_handler handler;
};

typedef struct {
  Chain_Control Chain;
} Thread_Action_control;

typedef enum {
  THREAD_LIFE_NORMAL = 0x0,
  THREAD_LIFE_PROTECTED = 0x1,
  THREAD_LIFE_RESTARTING = 0x2,
  THREAD_LIFE_PROTECTED_RESTARTING = 0x3,
  THREAD_LIFE_TERMINATING = 0x4,
  THREAD_LIFE_PROTECTED_TERMINATING = 0x5,
  THREAD_LIFE_RESTARTING_TERMINATING = 0x6,
  THREAD_LIFE_PROTECTED_RESTARTING_TERMINATING = 0x7
} Thread_Life_state;

typedef struct {
  Thread_Action      Action;

  Thread_Life_state  state;

  Thread_Control    *terminator;
} Thread_Life_control;

#if defined(RTEMS_SMP)

typedef enum {
  THREAD_SCHEDULER_BLOCKED,

  THREAD_SCHEDULER_SCHEDULED,

  THREAD_SCHEDULER_READY
} Thread_Scheduler_state;
#endif

typedef struct {
#if defined(RTEMS_SMP)

  Thread_Scheduler_state state;

  const struct Scheduler_Control *own_control;

  const struct Scheduler_Control *control;

  struct Scheduler_Node *own_node;
#endif

  struct Scheduler_Node *node;

#if defined(RTEMS_SMP)

  struct Per_CPU_Control *cpu;

#if defined(RTEMS_DEBUG)

  struct Per_CPU_Control *debug_real_cpu;
#endif
#endif
} Thread_Scheduler_control;

typedef struct  {
  uint32_t      flags;
  void *        control;
}Thread_Capture_control;

#if defined(RTEMS_SMP)

typedef struct {
  ISR_lock_Control *current;

  ISR_lock_Control Default;

  Atomic_Uint generation;
} Thread_Lock_control;
#endif

struct Thread_Control {
  Objects_Control          Object;
  States_Control           current_state;

  Priority_Control         current_priority;

  Priority_Control         real_priority;

  uint32_t                 priority_generation;

  bool                     priority_restore_hint;

  uint32_t                 resource_count;
  Thread_Wait_information  Wait;
  Watchdog_Control         Timer;
#if defined(RTEMS_MULTIPROCESSING)

  MP_packet_Prefix        *receive_packet;
#endif
     /*================= end of common block =================*/

#if defined(RTEMS_SMP)

  Thread_Lock_control Lock;
#endif

#ifdef __RTEMS_STRICT_ORDER_MUTEX__

  Chain_Control            lock_mutex;
#endif
#if defined(RTEMS_SMP)

  Resource_Node            Resource_node;
#endif
#if defined(RTEMS_MULTIPROCESSING)

  bool                                  is_global;
#endif

  bool                                  is_preemptible;
  bool                                  is_fp;

  Thread_Scheduler_control              Scheduler;

#if __RTEMS_ADA__

  void                                 *rtems_ada_self;
#endif

  uint32_t                              cpu_time_budget;
  Thread_CPU_budget_algorithms          budget_algorithm;
  Thread_CPU_budget_algorithm_callout   budget_callout;
  Thread_CPU_usage_t                    cpu_time_used;

  Thread_Start_information              Start;

  Thread_Action_control                 Post_switch_actions;

  Context_Control                       Registers;
#if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )

  Context_Control_fp                   *fp_context;
#endif

  struct _reent                        *libc_reent;
  void                                 *API_Extensions[ THREAD_API_LAST + 1 ];

#if !defined(RTEMS_SMP)

  rtems_task_variable_t                *task_variables;
#endif

  Chain_Control           Key_Chain;

  Thread_Life_control                   Life;

  Thread_Capture_control                Capture;

  void                                 *extensions[ RTEMS_ZERO_LENGTH_ARRAY ];
};

#if (CPU_PROVIDES_IDLE_THREAD_BODY == FALSE)

void *_Thread_Idle_body(
  uintptr_t  ignored
);
#endif

typedef void (*rtems_per_thread_routine)( Thread_Control * );

void rtems_iterate_over_all_threads(
  rtems_per_thread_routine routine
);

typedef struct {
  size_t destination_offset;

  size_t source_offset;
} Thread_Control_add_on;

extern const Thread_Control_add_on _Thread_Control_add_ons[];

extern const size_t _Thread_Control_add_on_count;

extern const size_t _Thread_Control_size;

#ifdef __cplusplus
}
#endif

#endif
/* end of include file */