rtems/score/thread.h

Go to the documentation of this file.

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

#ifndef _RTEMS_SCORE_THREAD_H
#define _RTEMS_SCORE_THREAD_H

#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

#if defined(RTEMS_SMP) || \
    defined(RTEMS_HEAVY_STACK_DEBUG) || \
    defined(RTEMS_HEAVY_MALLOC_DEBUG)
  #define __THREAD_DO_NOT_INLINE_DISABLE_DISPATCH__
#endif

#if defined(RTEMS_SMP) || \
   (CPU_INLINE_ENABLE_DISPATCH == FALSE) || \
   (__RTEMS_DO_NOT_INLINE_THREAD_ENABLE_DISPATCH__ == 1)
  #define __THREAD_DO_NOT_INLINE_ENABLE_DISPATCH__
#endif

/*
 *  Deferred floating point context switches are not currently
 *  supported when in SMP configuration.
 */
#if defined(RTEMS_SMP)
  #undef  CPU_USE_DEFERRED_FP_SWITCH
  #define CPU_USE_DEFERRED_FP_SWITCH FALSE
#endif

#ifdef __cplusplus
extern "C" {
#endif

#include <rtems/score/percpu.h>
#include <rtems/score/context.h>
#include <rtems/score/cpu.h>
#if defined(RTEMS_MULTIPROCESSING)
#include <rtems/score/mppkt.h>
#endif
#include <rtems/score/object.h>
#include <rtems/score/priority.h>
#include <rtems/score/scheduler.h>
#include <rtems/score/stack.h>
#include <rtems/score/states.h>
#include <rtems/score/tod.h>
#include <rtems/score/tqdata.h>
#include <rtems/score/watchdog.h>

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

  typedef Timestamp_Control Thread_CPU_usage_t;
#else
  typedef uint32_t Thread_CPU_usage_t;
#endif

typedef void *Thread;

typedef uintptr_t 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 * );

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;

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;
} Thread_Start_information;

#define THREAD_STATUS_PROXY_BLOCKING 0x1111111

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

typedef struct {
  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;

  Chain_Control         Block2n;
  Thread_queue_Control *queue;
}   Thread_Wait_information;

typedef struct {
  Objects_Control          Object;
  States_Control           current_state;
  Priority_Control         current_priority;
  Priority_Control         real_priority;
  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

struct Thread_Control_struct {
  Objects_Control          Object;
  States_Control           current_state;
  Priority_Control         current_priority;
  Priority_Control         real_priority;
  uint32_t                 resource_count;
  Thread_Wait_information  Wait;
  Watchdog_Control         Timer;
#if defined(RTEMS_MULTIPROCESSING)

  MP_packet_Prefix        *receive_packet;
#endif
#ifdef __RTEMS_STRICT_ORDER_MUTEX__

  Chain_Control            lock_mutex;
#endif
     /*================= end of common block =================*/
#if defined(RTEMS_MULTIPROCESSING)

  bool                                  is_global;
#endif

  bool                                  is_preemptible;
#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;

  void                                 *scheduler_info;

  Thread_Start_information              Start;
  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 ];
  void                                **extensions;
  rtems_task_variable_t                *task_variables;
};

SCORE_EXTERN void *rtems_ada_self;

SCORE_EXTERN Objects_Information _Thread_Internal_information;

SCORE_EXTERN Context_Control _Thread_BSP_context;

SCORE_EXTERN volatile uint32_t   _Thread_Dispatch_disable_level;

#if defined(RTEMS_SMP)

  SCORE_EXTERN SMP_lock_spinlock_nested_Control _Thread_Dispatch_disable_level_lock;
#endif

SCORE_EXTERN uint32_t   _Thread_Maximum_extensions;

SCORE_EXTERN uint32_t   _Thread_Ticks_per_timeslice;

#if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )
SCORE_EXTERN Thread_Control *_Thread_Allocated_fp;
#endif

SCORE_EXTERN struct _reent **_Thread_libc_reent;
void _Thread_Handler_initialization(void);

void _Thread_Create_idle(void);

void _Thread_Start_multitasking( void );

void _Thread_Dispatch( void );

size_t _Thread_Stack_Allocate(
  Thread_Control *the_thread,
  size_t          stack_size
);

void _Thread_Stack_Free(
  Thread_Control *the_thread
);

bool _Thread_Initialize(
  Objects_Information                  *information,
  Thread_Control                       *the_thread,
  void                                 *stack_area,
  size_t                                stack_size,
  bool                                  is_fp,
  Priority_Control                      priority,
  bool                                  is_preemptible,
  Thread_CPU_budget_algorithms          budget_algorithm,
  Thread_CPU_budget_algorithm_callout   budget_callout,
  uint32_t                              isr_level,
  Objects_Name                          name
);

bool _Thread_Start(
  Thread_Control            *the_thread,
  Thread_Start_types         the_prototype,
  void                      *entry_point,
  void                      *pointer_argument,
  Thread_Entry_numeric_type  numeric_argument
);

bool _Thread_Restart(
  Thread_Control            *the_thread,
  void                      *pointer_argument,
  Thread_Entry_numeric_type  numeric_argument
);

void _Thread_Reset(
  Thread_Control            *the_thread,
  void                      *pointer_argument,
  Thread_Entry_numeric_type  numeric_argument
);

void _Thread_Close(
  Objects_Information  *information,
  Thread_Control       *the_thread
);

void _Thread_Ready(
  Thread_Control *the_thread
);

void _Thread_Clear_state(
  Thread_Control *the_thread,
  States_Control  state
);

void _Thread_Set_state(
  Thread_Control *the_thread,
  States_Control  state
);

void _Thread_Set_transient(
  Thread_Control *the_thread
);

void _Thread_Load_environment(
  Thread_Control *the_thread
);

void _Thread_Handler( void );

void _Thread_Delay_ended(
  Objects_Id  id,
  void       *ignored
);

void _Thread_Change_priority (
  Thread_Control   *the_thread,
  Priority_Control  new_priority,
  bool              prepend_it
);

void _Thread_Set_priority(
  Thread_Control   *the_thread,
  Priority_Control  new_priority
);

#define _Thread_Suspend( _the_thread ) \
        _Thread_Set_state( _the_thread, STATES_SUSPENDED )

#define _Thread_Resume( _the_thread ) \
        _Thread_Clear_state( _the_thread, STATES_SUSPENDED )

#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
);

Thread_Control *_Thread_Get (
  Objects_Id         id,
  Objects_Locations *location
);

void _Thread_blocking_operation_Cancel(
  Thread_blocking_operation_States  sync_state,
  Thread_Control                   *the_thread,
  ISR_Level                         level
);
#if defined(RTEMS_SMP)

  void _Thread_Dispatch_initialization(void);

  bool _Thread_Dispatch_in_critical_section(void);

  uint32_t _Thread_Dispatch_get_disable_level(void);

  uint32_t _Thread_Dispatch_set_disable_level(uint32_t value);

  uint32_t _Thread_Dispatch_increment_disable_level(void);

  uint32_t _Thread_Dispatch_decrement_disable_level(void);

#else
  /*
   * The _Thread_Dispatch_... functions are in thread.inl
   */
#endif

#ifndef __RTEMS_APPLICATION__
#include <rtems/score/thread.inl>
#endif
#if defined(RTEMS_MULTIPROCESSING)
#include <rtems/score/threadmp.h>
#endif

#ifdef __cplusplus
}
#endif

#endif
/* end of include file */