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

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                              ( *stack_free )( void * );
  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;

extern const size_t _Thread_Maximum_TLS_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 */