thread.h

Go to the documentation of this file.

 
/*
 *  COPYRIGHT (c) 1989-2014.
 *  On-Line Applications Research Corporation (OAR).
 *
 *  Copyright (c) 2014, 2016 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/freechain.h>
#include <rtems/score/isrlock.h>
#include <rtems/score/objectdata.h>
#include <rtems/score/priority.h>
#include <rtems/score/schedulernode.h>
#include <rtems/score/stack.h>
#include <rtems/score/states.h>
#include <rtems/score/threadq.h>
#include <rtems/score/timestamp.h>
#include <rtems/score/watchdog.h>
 
#if defined(RTEMS_SMP)
#include <rtems/score/processormask.h>
#endif
 
struct rtems_user_env_t;
 
struct _pthread_cleanup_context;
 
struct Per_CPU_Control;
 
struct _Scheduler_Control;
 
struct User_extensions_Iterator;
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define RTEMS_SCORE_THREAD_ENABLE_EXHAUST_TIMESLICE
 
/*
 * 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_DEBUG)
#define RTEMS_SCORE_THREAD_ENABLE_RESOURCE_COUNT
#endif
 
/*
 * Only provided for backward compatiblity to not break application
 * configurations.
 */
typedef void *Thread RTEMS_DEPRECATED;
 
typedef CPU_Uint32ptr Thread_Entry_numeric_type;
 
typedef struct {
  void *( *entry )( uintptr_t argument );
} Thread_Entry_idle;
 
typedef struct {
  void ( *entry )( Thread_Entry_numeric_type argument );
  Thread_Entry_numeric_type argument;
} Thread_Entry_numeric;
 
typedef struct {
  void *( *entry )( void *argument  );
  void *argument;
} Thread_Entry_pointer;
 
typedef struct {
  void ( *adaptor )( Thread_Control *executing );
 
  union {
    Thread_Entry_idle Idle;
    Thread_Entry_numeric Numeric;
    Thread_Entry_pointer Pointer;
  } Kinds;
} Thread_Entry_information;
 
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 * );
 
typedef struct {
  Thread_Entry_information             Entry;
  /*-------------- 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;
  void                                *allocated_stack;
  Stack_Control                        Initial_stack;
  #if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )
    Context_Control_fp                  *fp_context;
  #endif
  void                                *tls_area;
} Thread_Start_information;
 
#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)
  ISR_lock_Control Lock;
 
  Thread_Scheduler_state state;
 
  const struct _Scheduler_Control *home_scheduler;
 
  const struct _Scheduler_Control *pinned_scheduler;
 
  struct Per_CPU_Control *cpu;
 
  Chain_Control Wait_nodes;
 
  Chain_Control Scheduler_nodes;
 
  Chain_Node Help_node;
 
  size_t helping_nodes;
 
  Scheduler_Node *requests;
 
  int pin_level;
 
  Processor_mask Affinity;
#endif
 
  Scheduler_Node *nodes;
} Thread_Scheduler_control;
 
typedef union {
  void       *mutable_object;
  const void *immutable_object;
} Thread_Wait_information_Object_argument_type;
 
typedef unsigned int Thread_Wait_flags;
 
typedef struct {
#if defined(RTEMS_MULTIPROCESSING)
  /*
   * @brief This field is the identifier of the remote object this thread is
   * waiting upon.
   */
  Objects_Id            remote_id;
#endif
  uint32_t              count;
  void                 *return_argument;
  Thread_Wait_information_Object_argument_type
                        return_argument_second;
  uint32_t              option;
  uint32_t              return_code;
 
#if defined(RTEMS_SMP)
  Atomic_Uint           flags;
#else
  Thread_Wait_flags     flags;
#endif
 
#if defined(RTEMS_SMP)
  struct {
    ISR_lock_Control Default;
 
    Chain_Control Pending_requests;
 
    Thread_queue_Gate Tranquilizer;
  } Lock;
 
  Thread_queue_Link Link;
#endif
 
  Thread_queue_Queue *queue;
 
  const Thread_queue_Operations *operations;
 
  Thread_queue_Heads *spare_heads;
}   Thread_Wait_information;
 
typedef struct {
  ISR_LOCK_MEMBER( Lock )
  Watchdog_Header *header;
  Watchdog_Control Watchdog;
} Thread_Timer_information;
 
typedef struct {
  Objects_Control          Object;
 
  Thread_queue_Control     Join_queue;
 
  States_Control           current_state;
 
  Priority_Node            Real_priority;
 
#if defined(RTEMS_SCORE_THREAD_ENABLE_RESOURCE_COUNT)
  uint32_t                 resource_count;
#endif
 
  Thread_Scheduler_control Scheduler;
 
  Thread_Wait_information  Wait;
  Thread_Timer_information Timer;
#if defined(RTEMS_MULTIPROCESSING)
  MP_packet_Prefix        *receive_packet;
     /****************** end of common block ********************/
 
  Thread_queue_MP_callout  thread_queue_callout;
 
  RBTree_Node              Active;
 
  Scheduler_Node           Scheduler_node;
 
  Thread_queue_Heads       Thread_queue_heads[ RTEMS_ZERO_LENGTH_ARRAY ];
#endif
}   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   *the_thread,
  Thread_Action    *action,
  ISR_lock_Context *lock_context
);
 
struct Thread_Action {
  Chain_Node            Node;
  Thread_Action_handler handler;
};
 
typedef struct {
  RBTree_Control Key_value_pairs;
 
  ISR_LOCK_MEMBER( Lock )
} Thread_Keys_information;
 
typedef struct {
  Chain_Control Chain;
} Thread_Action_control;
 
typedef enum {
  THREAD_LIFE_PROTECTED = 0x1,
  THREAD_LIFE_RESTARTING = 0x2,
  THREAD_LIFE_TERMINATING = 0x4,
  THREAD_LIFE_CHANGE_DEFERRED = 0x8,
  THREAD_LIFE_DETACHED = 0x10
} Thread_Life_state;
 
typedef struct {
  Thread_Action      Action;
 
  Thread_Life_state  state;
 
  uint32_t pending_life_change_requests;
 
  void *exit_value;
} Thread_Life_control;
 
typedef struct  {
  uint32_t      flags;
  void *        control;
}Thread_Capture_control;
 
struct _Thread_Control {
  Objects_Control          Object;
 
  Thread_queue_Control     Join_queue;
 
  States_Control           current_state;
 
  Priority_Node            Real_priority;
 
#if defined(RTEMS_SCORE_THREAD_ENABLE_RESOURCE_COUNT)
  uint32_t                 resource_count;
#endif
 
  Thread_Scheduler_control Scheduler;
 
  Thread_Wait_information  Wait;
  Thread_Timer_information Timer;
#if defined(RTEMS_MULTIPROCESSING)
  MP_packet_Prefix        *receive_packet;
#endif
     /*================= end of common block =================*/
 
#if defined(RTEMS_SMP) && defined(RTEMS_PROFILING)
  SMP_lock_Stats Potpourri_stats;
#endif
 
  bool                                  is_idle;
#if defined(RTEMS_MULTIPROCESSING)
  bool                                  is_global;
#endif
  bool                                  is_preemptible;
  bool                                  is_fp;
 
  bool was_created_with_inherited_scheduler;
 
  uint32_t                              cpu_time_budget;
  Thread_CPU_budget_algorithms          budget_algorithm;
  Thread_CPU_budget_algorithm_callout   budget_callout;
  Timestamp_Control                     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 ];
 
  Thread_Keys_information               Keys;
 
  Thread_Life_control                   Life;
 
  Thread_Capture_control                Capture;
 
  struct rtems_user_env_t *user_environment;
 
  struct _pthread_cleanup_context *last_cleanup_context;
 
  struct User_extensions_Iterator *last_user_extensions_iterator;
 
  void                                 *extensions[ RTEMS_ZERO_LENGTH_ARRAY ];
};
 
typedef void (*rtems_per_thread_routine)( Thread_Control * );
 
void rtems_iterate_over_all_threads(
  rtems_per_thread_routine routine
) RTEMS_DEPRECATED;
 
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_Initial_thread_count;
 
#define THREAD_DEFAULT_MAXIMUM_NAME_SIZE 16
 
extern const size_t _Thread_Maximum_name_size;
 
typedef struct Thread_Configured_control Thread_Configured_control;
 
#if defined(RTEMS_SMP)
typedef struct Thread_queue_Configured_heads Thread_queue_Configured_heads;
#else
typedef Thread_queue_Heads Thread_queue_Configured_heads;
#endif
 
#if defined(RTEMS_SMP)
extern const size_t _Thread_queue_Heads_size;
#else
#define _Thread_queue_Heads_size sizeof(Thread_queue_Heads)
#endif
 
typedef struct {
  Objects_Information Objects;
 
  union {
    Thread_queue_Configured_heads *initial;
 
    Freechain_Control Free;
  } Thread_queue_heads;
} Thread_Information;
 
extern Thread_Information _Thread_Information;
 
#define THREAD_INFORMATION_DEFINE_ZERO( name, api, cls ) \
Thread_Information name##_Information = { \
  { \
    _Objects_Build_id( api, cls, 1, 0 ), \
    NULL, \
    _Objects_Allocate_none, \
    NULL, \
    0, \
    0, \
    0, \
    0, \
    CHAIN_INITIALIZER_EMPTY( name##_Information.Objects.Inactive ), \
    NULL, \
    NULL, \
    NULL \
    OBJECTS_INFORMATION_MP( name##_Information.Objects, NULL ), \
  }, { \
    NULL \
  } \
}
 
Objects_Control *_Thread_Allocate_unlimited( Objects_Information *information );
 
#define THREAD_INFORMATION_DEFINE( name, api, cls, max ) \
static Objects_Control * \
name##_Local_table[ _Objects_Maximum_per_allocation( max ) ]; \
static Thread_Configured_control \
name##_Objects[ _Objects_Maximum_per_allocation( max ) ]; \
static Thread_queue_Configured_heads \
name##_Heads[ _Objects_Maximum_per_allocation( max ) ]; \
Thread_Information name##_Information = { \
  { \
    _Objects_Build_id( api, cls, 1, _Objects_Maximum_per_allocation( max ) ), \
    name##_Local_table, \
    _Objects_Is_unlimited( max ) ? \
      _Thread_Allocate_unlimited : _Objects_Allocate_static, \
    _Objects_Is_unlimited( max ) ? \
      _Objects_Free_unlimited : _Objects_Free_static, \
    0, \
    _Objects_Is_unlimited( max ) ? _Objects_Maximum_per_allocation( max ) : 0, \
    sizeof( Thread_Configured_control ), \
    OBJECTS_NO_STRING_NAME, \
    CHAIN_INITIALIZER_EMPTY( name##_Information.Objects.Inactive ), \
    NULL, \
    NULL, \
    &name##_Objects[ 0 ].Control.Object \
    OBJECTS_INFORMATION_MP( name##_Information.Objects, NULL ) \
  }, { \
    &name##_Heads[ 0 ] \
  } \
}
 
extern char _Thread_Idle_stacks[];
 
#if defined(RTEMS_MULTIPROCESSING)
typedef struct Thread_Configured_proxy_control Thread_Configured_proxy_control;
 
extern Thread_Configured_proxy_control * const _Thread_MP_Proxies;
#endif
 
#ifdef __cplusplus
}
#endif
 
#endif
/* end of include file */