LXR 6.1/​cpukit/​include/​rtems/​score/​userext.h	Source navigation Diff markup Identifier search General search
	Version: 6.1 Revert   Change

File indexing completed on 2025-05-11 08:24:13

 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
  * @file
  *
  * @ingroup RTEMSScoreUserExt
  *
  * @brief This header file provides interfaces of the
  *   @ref RTEMSScoreUserExt which are used by the implementation and the
  *   @ref RTEMSImplApplConfig.
  */
 
 /*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
  *
  * 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_USEREXT_H
 #define _RTEMS_SCORE_USEREXT_H
 
 #include <rtems/score/interr.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 struct _Thread_Control;
 
 /**
  * @defgroup RTEMSScoreUserExt User Extensions Handler
  *
  * @ingroup RTEMSScore
  *
  * @brief This group contains the User Extensions Handler implementation.
  *
  * This handler provides the 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 and pthread_create()).
  *
  * 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 allows nesting the
  * normal memory allocation routines can be used.
  *
  * @param[in] executing The executing thread.
  * @param[in] created The created thread.
  *
  * @retval true Successful operation.
  * @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 )(
   struct _Thread_Control *executing,
   struct _Thread_Control *created
 );
 
 /**
  * @brief Task delete extension.
  *
  * It corresponds to _Thread_Close() (used by the rtems_task_delete()
  * directive, pthread_exit() and pthread_cancel()).
  *
  * It is invoked before all resources of the thread are deleted.  The executing
  * and deleted arguments are never equal.
  *
  * Thread dispatching is enabled.  The executing thread locked the allocator
  * mutex.
  *
  * @param[in] executing The executing thread.
  * @param[in] deleted The deleted thread.
  */
 typedef void( *User_extensions_thread_delete_extension )(
   struct _Thread_Control *executing,
   struct _Thread_Control *deleted
 );
 
 /**
  * @brief Task start extension.
  *
  * It corresponds to _Thread_Start() (used by the rtems_task_start()
  * directive).
  *
  * 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.
  *
  * @param[in] executing The executing thread.
  * @param[in] started The started thread.
  */
 typedef void( *User_extensions_thread_start_extension )(
   struct _Thread_Control *executing,
   struct _Thread_Control *started
 );
 
 /**
  * @brief Task restart extension.
  *
  * It corresponds to _Thread_Restart() (used by the rtems_task_restart()
  * directive).
  *
  * It is invoked in the context of the restarted thread right before the
  * execution context is reloaded.  The executing and restarted arguments are
  * always equal.  The thread stack reflects the previous execution context.
  *
  * Thread dispatching is enabled.  The thread is not the holder of the
  * allocator mutex.  The thread life is protected.  Thread restart and delete
  * requests issued by restart extensions lead to recursion.
  *
  * @param[in] executing The executing thread.
  * @param[in] restarted The executing thread.  Yes, the executing thread.
  */
 typedef void( *User_extensions_thread_restart_extension )(
   struct _Thread_Control *executing,
   struct _Thread_Control *restarted
 );
 
 /**
  * @brief Task switch extension.
  *
  * It corresponds to _Thread_Dispatch().
  *
  * 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.  Interrupts are disabled and the per-CPU lock is acquired on SMP
  * configurations.
  *
  * The context switches initiated through _Thread_Start_multitasking() are not
  * covered by this extension.
  *
  * @param[in] executing The executing thread.
  * @param[in] heir The heir thread.
  */
 typedef void( *User_extensions_thread_switch_extension )(
   struct _Thread_Control *executing,
   struct _Thread_Control *heir
 );
 
 /**
  * @brief Task begin extension.
  *
  * It corresponds to _Thread_Handler().
  *
  * Thread dispatching is disabled.  The executing thread is not the holder of
  * the allocator mutex.
  *
  * @param[in] executing The executing thread.
  */
 typedef void( *User_extensions_thread_begin_extension )(
   struct _Thread_Control *executing
 );
 
 /**
  * @brief Task exitted extension.
  *
  * It corresponds to _Thread_Handler() after a return of the entry function.
  *
  * Thread dispatching is disabled.  The state of the allocator mutex is
  * arbitrary.
  *
  * @param[in] executing The executing thread.
  */
 typedef void( *User_extensions_thread_exitted_extension )(
   struct _Thread_Control *executing
 );
 
 /**
  * @brief Fatal error extension.
  *
  * It corresponds to _Terminate() (used by the rtems_fatal() directive).
  *
  * This extension should not call any RTEMS directives.
  *
  * @param[in] source The fatal source indicating the subsystem the fatal
  * condition originated in.
  * @param[in] always_set_to_false This parameter is always set to false and
  * provided only for backward compatibility reasons.
  * @param[in] code The fatal error code.  This value must be interpreted with
  * respect to the source.
  */
 typedef void( *User_extensions_fatal_extension )(
   Internal_errors_Source source,
   bool                   always_set_to_false,
   Internal_errors_t      code
 );
 
 /**
  * @brief Task termination extension.
  *
  * This extension is invoked by _Thread_Life_action_handler() in case a
  * termination request is recognized.
  *
  * It is invoked in the context of the terminated thread right before the
  * thread dispatch to the heir thread.  The POSIX cleanup and key destructors
  * execute in this context.
  *
  * Thread dispatching is enabled.  The thread is not the holder of the
  * allocator mutex.  The thread life is protected.  Thread restart and delete
  * requests issued by terminate extensions lead to recursion.
  *
  * @param[in] terminated The terminated thread.
  */
 typedef void( *User_extensions_thread_terminate_extension )(
   struct _Thread_Control *terminated
 );
 
 /**
  * @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_thread_terminate_extension thread_terminate;
 }   User_extensions_Table;
 
 /** @} */
 
 #ifdef __cplusplus
 }
 #endif
 
 #endif
 /* end of include file */

This page was automatically generated by the 2.3.7 LXR engine. The LXR team