blob: 91e7f97bd3b80447fe65010d232348ea4027f50e (
plain) (
tree)
|
|
/**
* @file
*
* @ingroup ScoreUserExt
*
* @brief User Extension Handler API
*/
/*
* 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.org/license/LICENSE.
*/
#ifndef _RTEMS_SCORE_USEREXT_H
#define _RTEMS_SCORE_USEREXT_H
#include <rtems/score/interr.h>
#include <rtems/score/chain.h>
#include <rtems/score/thread.h>
#ifdef __cplusplus
extern "C" {
#endif
typedef void User_extensions_routine RTEMS_COMPILER_DEPRECATED_ATTRIBUTE;
/**
* @defgroup ScoreUserExt User Extension Handler
*
* @ingroup Score
*
* @brief The User Extension Handler provides invocation of application
* dependent routines at critical points in the life of each thread and the
* system as a whole.
*/
/**@{**/
/**
* @brief Task create extension.
*
* It corresponds to _Thread_Initialize() (used by the rtems_task_create()
* directive). The first parameter points to the currently executing thread
* which created the new thread. The second parameter points to the created
* thread.
*
* It is invoked after the new thread has been completely initialized, but
* before it is placed on a ready chain.
*
* Thread dispatching may be disabled. This depends on the context of the
* _Thread_Initialize() call. Thread dispatch is disabled during the creation
* of the idle thread and the initialization threads. It can be considered as
* an invalid API usage, if the application calls _Thread_Initialize() with
* disabled thread dispatching. Disabled thread dispatching is different from
* disabled preemption.
*
* It can be assumed that the executing thread locked the allocator mutex.
* The only exception is the creation of the idle thread. In this case the
* allocator mutex is not locked. Since the allocator mutex is non-recursive,
* it is prohibited to call the normal memory allocation routines. It is
* possible to use internal rountines like _Workspace_Allocate() or
* _Heap_Allocate() for heaps which are protected by the allocator mutex.
*
* @retval true The thread create extension was successful.
* @retval false A thread create user extension will frequently attempt to
* allocate resources. If this allocation fails, then the extension should
* return @a false and the entire thread create operation will fail.
*/
typedef bool ( *User_extensions_thread_create_extension )(
Thread_Control *,
Thread_Control *
);
/**
* @brief Task delete extension.
*
* It corresponds to _Thread_Close() (used by the rtems_task_delete()
* directive). The first parameter points to the currently executing thread
* which deleted the thread. The second parameter points to the deleted
* thread.
*
* It is invoked before all resources of the thread are deleted.
*
* Thread dispatching is enabled. The executing thread locked the allocator
* mutex.
*/
typedef void( *User_extensions_thread_delete_extension )(
Thread_Control *,
Thread_Control *
);
/**
* @brief Task start extension.
*
* It corresponds to _Thread_Start() (used by the rtems_task_start()
* directive). The first parameter points to the currently executing thread
* which started the thread. The second parameter points to the started
* thread.
*
* It is invoked after the environment of the thread has been loaded and the
* thread has been made ready.
*
* Thread dispatching is disabled. The executing thread is not the holder of
* the allocator mutex.
*/
typedef void( *User_extensions_thread_start_extension )(
Thread_Control *,
Thread_Control *
);
/**
* @brief Task restart extension.
*
* It corresponds to _Thread_Restart() (used by the rtems_task_restart()
* directive). The first parameter points to the currently executing thread
* which restarted the thread. The second parameter points to the restarted
* thread.
*
* It is invoked in the context of the restarted thread right before the
* execution context is restarted. The executing and restarted arguments are
* equal. The thread stack reflects the previous execution context.
*
* Thread dispatching is enabled. The thread is not the holder of the
* allocator mutex.
*/
typedef void( *User_extensions_thread_restart_extension )(
Thread_Control *,
Thread_Control *
);
/**
* @brief Task switch extension.
*
* It corresponds to _Thread_Dispatch(). The first parameter points to the
* currently executing thread. The second parameter points to the heir thread.
*
* It is invoked before the context switch from the executing to the heir
* thread.
*
* Thread dispatching is disabled. The state of the allocator mutex is
* arbitrary.
*
* The context switches initiated through _Thread_Start_multitasking() and
* _Thread_Stop_multitasking() are not covered by this extension. The
* executing thread may run with a minimal setup, for example with a freed task
* stack.
*/
typedef void( *User_extensions_thread_switch_extension )(
Thread_Control *,
Thread_Control *
);
/**
* @brief Task begin extension.
*
* It corresponds to _Thread_Handler(). The first parameter points to the
* currently executing thread which begins now execution.
*
* Thread dispatching is disabled. The executing thread is not the holder of
* the allocator mutex.
*/
typedef void( *User_extensions_thread_begin_extension )(
Thread_Control *
);
/**
* @brief Task exitted extension.
*
* It corresponds to _Thread_Handler(). The first parameter points to the
* currently executing thread which exitted before.
*
* Thread dispatching is disabled. The state of the allocator mutex is
* arbitrary.
*/
typedef void( *User_extensions_thread_exitted_extension )(
Thread_Control *
);
/**
* @brief Fatal error extension.
*
* It corresponds to _Terminate() (used by the
* rtems_fatal_error_occurred() directive). The first parameter contains the
* error source. The second parameter indicates if it was an internal error.
* The third parameter contains the error code.
*
* This extension should not call any RTEMS directives.
*/
typedef void( *User_extensions_fatal_extension )(
Internal_errors_Source,
bool,
Internal_errors_t
);
/**
* @brief User extension table.
*/
typedef struct {
User_extensions_thread_create_extension thread_create;
User_extensions_thread_start_extension thread_start;
User_extensions_thread_restart_extension thread_restart;
User_extensions_thread_delete_extension thread_delete;
User_extensions_thread_switch_extension thread_switch;
User_extensions_thread_begin_extension thread_begin;
User_extensions_thread_exitted_extension thread_exitted;
User_extensions_fatal_extension fatal;
} User_extensions_Table;
/**
* @brief Manages the switch callouts.
*
* They are managed separately from other extensions for performance reasons.
*/
typedef struct {
Chain_Node Node;
User_extensions_thread_switch_extension thread_switch;
} User_extensions_Switch_control;
/**
* @brief Manages each user extension set.
*
* The switch control is part of the extensions control even if not used due to
* the extension not having a switch handler.
*/
typedef struct {
Chain_Node Node;
User_extensions_Switch_control Switch;
User_extensions_Table Callouts;
} User_extensions_Control;
/** @} */
#ifdef __cplusplus
}
#endif
#endif
/* end of include file */
|