thread.h

Go to the documentation of this file.

/* SPDX-License-Identifier: BSD-2-Clause */

 
/*
 *  COPYRIGHT (c) 1989-2014.
 *  On-Line Applications Research Corporation (OAR).
 *
 *  Copyright (C) 2014, 2016 embedded brains GmbH & Co. KG
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */
 
#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

 
#if defined(RTEMS_DEBUG)
#define RTEMS_SCORE_THREAD_ENABLE_RESOURCE_COUNT
#endif
 
#if defined(RTEMS_POSIX_API)
#define RTEMS_SCORE_THREAD_REAL_PRIORITY_MAY_BE_INACTIVE
#endif
 
#if defined(RTEMS_POSIX_API) && defined(RTEMS_SMP)
#define RTEMS_SCORE_THREAD_HAS_SCHEDULER_CHANGE_INHIBITORS
#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 struct {
  void ( *at_tick )( Thread_Control * );

  void ( *at_context_switch )( Thread_Control * );

  void ( *initialize )( Thread_Control * );
} Thread_CPU_budget_operations;

typedef struct {
  const Thread_CPU_budget_operations *operations;

  uint32_t available;
} Thread_CPU_budget_control;

typedef struct {
  Thread_Entry_information             Entry;
  /*-------------- initial execution modes ----------------- */
  bool                                 is_preemptible;

  const Thread_CPU_budget_operations *cpu_budget_operations;

  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;

  struct Per_CPU_Control *ask_for_help_cpu;

  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 {
#if ISR_LOCK_NEEDS_OBJECT
  ISR_lock_Control Lock;
#endif
  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;
 
#if defined(RTEMS_SMP)
  ISR_lock_Control Lock;
#endif
} Thread_Keys_information;

typedef struct {
  Chain_Control Chain;
} Thread_Action_control;

typedef unsigned int Thread_Life_state;

#define THREAD_LIFE_PROTECTED 0x1U

#define THREAD_LIFE_RESTARTING 0x2U

#define THREAD_LIFE_TERMINATING 0x4U

#define THREAD_LIFE_CHANGE_DEFERRED 0x8U

#define THREAD_LIFE_DETACHED 0x10U

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 =================*/

  Context_Control Registers;
 
#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;
 
#if defined(RTEMS_SCORE_THREAD_HAS_SCHEDULER_CHANGE_INHIBITORS)
  bool is_scheduler_change_inhibited;
#endif

  Thread_CPU_budget_control CPU_budget;

  Timestamp_Control cpu_time_used;

  Timestamp_Control cpu_time_used_at_last_reset;

  Thread_Start_information              Start;
 
  Thread_Action_control                 Post_switch_actions;
 
#if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )
  Context_Control_fp                   *fp_context;
#endif
 
#ifndef _REENT_THREAD_LOCAL
  struct _reent                        *libc_reent;
#endif

  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 RTEMS_SECTION( ".noinit.rtems.content.objects." #name ) \
Thread_Configured_control \
name##_Objects[ _Objects_Maximum_per_allocation( max ) ]; \
static RTEMS_SECTION( ".noinit.rtems.content.objects." #name ) \
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 ] \
  } \
}
 
#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 */