Changeset c42d1a4 in rtems


Ignore:
Timestamp:
09/25/09 17:51:46 (14 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 5, master
Children:
e1c9abd
Parents:
e89faf3e
Message:

2009-09-25 Sebastian Huber <Sebastian.Huber@…>

  • sapi/include/rtems/extension.h, sapi/src/extensiondelete.c, sapi/src/extensionident.c, sapi/src/extensioncreate.c, sapi/inline/rtems/extension.inl, score/include/rtems/score/userext.h, score/src/userextthreaddelete.c, score/src/userext.c, score/src/userextthreadcreate.c, score/src/userextremoveset.c, score/src/userextthreadbegin.c, score/src/userextaddset.c, score/src/userextthreadstart.c, score/src/userextthreadswitch.c, score/src/userextthreadrestart.c: Documentation. The types User_extensions_routine and rtems_extension are now deprecated. Removed unused types User_extensions_thread_post_switch_extension and rtems_task_post_switch_extension. Renamed _User_extensions_Add_API_set() in _User_extensions_Add_set(). Renamed _User_extensions_Add_set() in _User_extensions_Add_set_with_table().
  • score/src/userextaddapiset.c: Removed file.
  • score/Makefile.am: Update.
Location:
cpukit
Files:
17 edited

Legend:

Unmodified
Added
Removed
  • cpukit/ChangeLog

    re89faf3e rc42d1a4  
     12009-09-25      Sebastian Huber <Sebastian.Huber@embedded-brains.de>
     2
     3        * sapi/include/rtems/extension.h, sapi/src/extensiondelete.c,
     4        sapi/src/extensionident.c, sapi/src/extensioncreate.c,
     5        sapi/inline/rtems/extension.inl, score/include/rtems/score/userext.h,
     6        score/src/userextthreaddelete.c, score/src/userext.c,
     7        score/src/userextthreadcreate.c, score/src/userextremoveset.c,
     8        score/src/userextthreadbegin.c, score/src/userextaddset.c,
     9        score/src/userextthreadstart.c, score/src/userextthreadswitch.c,
     10        score/src/userextthreadrestart.c: Documentation. The types
     11        User_extensions_routine and rtems_extension are now deprecated.
     12        Removed unused types User_extensions_thread_post_switch_extension and
     13        rtems_task_post_switch_extension. Renamed _User_extensions_Add_API_set()
     14        in _User_extensions_Add_set(). Renamed _User_extensions_Add_set() in
     15        _User_extensions_Add_set_with_table().
     16        * score/src/userextaddapiset.c: Removed file.
     17        * score/Makefile.am: Update.
     18
    1192009-09-25      Sebastian Huber <Sebastian.Huber@embedded-brains.de>
    220
  • cpukit/sapi/include/rtems/extension.h

    re89faf3e rc42d1a4  
    11/**
    2  * @file rtems/extension.h
     2 * @file
     3 *
     4 * @ingroup ClassicUserExtensions
     5 *
     6 * @brief User Extensions API.
    37 */
    48 
    59/*
    6  *  This include file contains all the constants, structures, and
    7  *  prototypes associated with the User Extension Manager.  This manager
    8  *  provides a mechanism for manipulating sets of user-defined extensions.
    9  *
    10  *  Directives provided are:
    11  *
    12  *     + create user extension set
    13  *     + get ID of user extension set
    14  *     + delete user extension set
    15  *
    1610 *  COPYRIGHT (c) 1989-2008.
    1711 *  On-Line Applications Research Corporation (OAR).
     
    4034#include <rtems/rtems/types.h>
    4135
    42 /*
    43  *  Extension related types
    44  */
    45 
    46 typedef User_extensions_routine                   rtems_extension;
     36SAPI_EXT_EXTERN Objects_Information  _Extension_Information;
     37
     38typedef struct {
     39  Objects_Control          Object;
     40  User_extensions_Control  Extension;
     41}   Extension_Control;
     42
     43void _Extension_Manager_initialization(void);
     44
     45typedef User_extensions_routine
     46  rtems_extension RTEMS_COMPILER_DEPRECATED_ATTRIBUTE;
     47
     48/**
     49 * @defgroup ClassicUserExtensions User Extensions
     50 *
     51 * @ingroup ClassicRTEMS
     52 *
     53 * @brief The User Extensions Manager allows the application developer to
     54 * augment the executive by allowing them to supply extension routines which
     55 * are invoked at critical system events.
     56 *
     57 * @section ClassicUserExtensionsSets Extension Sets
     58 *
     59 * An @ref User_extensions_Table "extension set" is defined as a set of
     60 * routines which are invoked at each of the critical system events at which
     61 * user extension routines are invoked.  Together a set of these routines
     62 * typically perform a specific functionality such as performance monitoring or
     63 * debugger support.
     64 *
     65 * RTEMS allows the user to have multiple extension sets active at the same
     66 * time. First, a single static extension set may be defined as the
     67 * application's User Extension Table which is included as part of the
     68 * Configuration Table. This extension set is active for the entire life of the
     69 * system and may not be deleted. This extension set is especially important
     70 * because it is the only way the application can provided a fatal error
     71 * extension which is invoked if RTEMS fails during the
     72 * rtems_initialize_data_structures() directive. The static extension set is
     73 * optional and may be configured as @c NULL if no static extension set is
     74 * required.
     75 *
     76 * Second, the user can install dynamic extensions using the
     77 * rtems_extension_create() directive. These extensions are RTEMS objects in
     78 * that they have a name, an ID, and can be dynamically created and deleted. In
     79 * contrast to the static extension set, these extensions can only be created
     80 * and installed after the rtems_initialize_data_structures() directive
     81 * successfully completes execution. Dynamic extensions are useful for
     82 * encapsulating the functionality of an extension set. For example, the
     83 * application could use extensions to manage a special coprocessor, do
     84 * performance monitoring, and to do stack bounds checking. Each of these
     85 * extension sets could be written and installed independently of the others.
     86 *
     87 * All user extensions are optional and RTEMS places no naming restrictions on
     88 * the user. The user extension entry points are copied into an internal RTEMS
     89 * structure. This means the user does not need to keep the table after
     90 * creating it, and changing the handler entry points dynamically in a table
     91 * once created has no effect. Creating a table local to a function can save
     92 * space in space limited applications.
     93 *
     94 * Extension switches do not effect the context switch overhead if no switch
     95 * handler is installed.
     96 *
     97 * @section ClassicUserExtensionsTCB Task Control Block Area
     98 *
     99 * RTEMS provides for a pointer to a user-defined data area for each extension
     100 * set to be linked to each task's control block (TCB). This area is only
     101 * available for the dynamic extensions. This set of pointers is an extension
     102 * of the TCB and can be used to store additional data required by the user's
     103 * extension functions. It is also possible for a user extension to utilize the
     104 * notepad locations associated with each task although this may conflict with
     105 * application usage of those particular notepads.
     106 *
     107 * The TCB extension is an array of pointers in the TCB. The index into the
     108 * table can be obtained from the extension identifier returned when the
     109 * extension is created:
     110 *
     111 * @code
     112 * rtems_tcb *task = some_task;
     113 * size_t index = rtems_object_id_get_index(extension_id);
     114 * void *extension_data = task->extensions [index];
     115 * @endcode
     116 *
     117 * The number of pointers in the area is the same as the number of user
     118 * extension sets configured. This allows an application to augment the TCB
     119 * with user-defined information. For example, an application could implement
     120 * task profiling by storing timing statistics in the TCB's extended memory
     121 * area. When a task context switch is being executed, the task switch
     122 * extension could read a real-time clock to calculate how long the task being
     123 * swapped out has run as well as timestamp the starting time for the task
     124 * being swapped in.
     125 *
     126 * If used, the extended memory area for the TCB should be allocated and the
     127 * TCB extension pointer should be set at the time the task is created or
     128 * started by either the task create or task start extension. The application
     129 * is responsible for managing this extended memory area for the TCBs. The
     130 * memory may be reinitialized by the task restart extension and should be
     131 * deallocated by the task delete extension when the task is deleted. Since the
     132 * TCB extension buffers would most likely be of a fixed size, the RTEMS
     133 * partition manager could be used to manage the application's extended memory
     134 * area. The application could create a partition of fixed size TCB extension
     135 * buffers and use the partition manager's allocation and deallocation
     136 * directives to obtain and release the extension buffers.
     137 *
     138 * @section ClassicUserExtensionsOrder Order of Invokation
     139 *
     140 * When one of the critical system events occur, the user extensions are
     141 * invoked in either @a forward or @a reverse order. Forward order indicates
     142 * that the static extension set is invoked followed by the dynamic extension
     143 * sets in the order in which they were created. Reverse order means that the
     144 * dynamic extension sets are invoked in the opposite of the order in which
     145 * they were created followed by the static extension set. By invoking the
     146 * extension sets in this order, extensions can be built upon one another. At
     147 * the following system events, the extensions are invoked in forward order:
     148 *
     149 * - Task creation
     150 * - Task initiation
     151 * - Task reinitiation
     152 * - Task deletion
     153 * - Task context switch
     154 * - Post task context switch
     155 * - Task begins to execute
     156 *
     157 * At the following system events, the extensions are invoked in reverse order:
     158 *
     159 * - Task deletion
     160 * - Fatal error detection
     161 *
     162 * At these system events, the extensions are invoked in reverse order to
     163 * insure that if an extension set is built upon another, the more complicated
     164 * extension is invoked before the extension set it is built upon. For example,
     165 * by invoking the static extension set last it is known that the "system"
     166 * fatal error extension will be the last fatal error extension executed.
     167 * Another example is use of the task delete extension by the Standard C
     168 * Library. Extension sets which are installed after the Standard C Library
     169 * will operate correctly even if they utilize the C Library because the C
     170 * Library's task delete extension is invoked after that of the other
     171 * extensions.
     172 *
     173 * @{
     174 */
     175
    47176typedef User_extensions_thread_create_extension   rtems_task_create_extension;
    48177typedef User_extensions_thread_delete_extension   rtems_task_delete_extension;
     
    50179typedef User_extensions_thread_restart_extension  rtems_task_restart_extension;
    51180typedef User_extensions_thread_switch_extension   rtems_task_switch_extension;
    52 typedef User_extensions_thread_post_switch_extension
    53                                               rtems_task_post_switch_extension;
    54181typedef User_extensions_thread_begin_extension    rtems_task_begin_extension;
    55182typedef User_extensions_thread_exitted_extension  rtems_task_exitted_extension;
     
    58185typedef User_extensions_Table                     rtems_extensions_table;
    59186
    60 /*
    61  *  The following defines the information control block used to manage
    62  *  this class of objects.
    63  */
    64 
    65 SAPI_EXT_EXTERN Objects_Information  _Extension_Information;
    66 
    67 /*
    68  *  The following records define the control block used to manage
    69  *  each extension.
    70  */
    71 
    72 typedef struct {
    73   Objects_Control          Object;
    74   User_extensions_Control  Extension;
    75 }   Extension_Control;
    76 
    77 /*
    78  *  _Extension_Manager_initialization
    79  *
    80  *  DESCRIPTION:
    81  *
    82  *  This routine performs the initialization necessary for this manager.
    83  */
    84 
    85 void _Extension_Manager_initialization(void);
    86 
    87 /*
    88  *  rtems_extension_create
    89  *
    90  *  DESCRIPTION:
    91  *
    92  *  This routine implements the rtems_extension_create directive.  The
    93  *  extension will have the name name.   The entry points of the
    94  *  routines which constitute this extension set are in EXTENSION_TABLE.
    95  *  It returns the id of the created extension in ID.
    96  */
    97 
     187/**
     188 * @brief Creates an extension set object.
     189 *
     190 * This directive creates a extension set object from the extension table
     191 * @a extension_table.  The assigned extension set identifier is returned in
     192 * @a id.  The identifier is used to access this extension set in other
     193 * extension set related directives.  The name @a name will be assigned to the
     194 * extension set object.
     195 *
     196 * Newly created extension sets are immediately installed and are invoked upon
     197 * the next system event supporting an extension.
     198 *
     199 * This directive will not cause the calling task to be preempted.
     200 *
     201 * @retval RTEMS_SUCCESSFUL Extension set created successfully.
     202 * @retval RTEMS_INVALID_ADDRESS Identifier pointer is @c NULL.
     203 * @retval RTEMS_INVALID_NAME Invalid extension set name.
     204 * @retval RTEMS_TOO_MANY Too many extension sets created.
     205 */
    98206rtems_status_code rtems_extension_create(
    99207  rtems_name              name,
    100208  rtems_extensions_table *extension_table,
    101   Objects_Id              *id
     209  rtems_id               *id
    102210);
    103211
    104 /*
    105  *  rtems_extension_ident
    106  *
    107  *  DESCRIPTION:
    108  *
    109  *  This routine implements the rtems_extension_ident directive.
    110  *  This directive returns the extension ID associated with name.
    111  *  If more than one extension is named name, then the extension
    112  *  to which the ID belongs is arbitrary.
    113  */
    114 
     212/**
     213 * @brief Identifies an extension set object by a name.
     214 *
     215 * This directive obtains an extension set identifier in @a id associated with
     216 * the extension set name @a name. If the extension set name is not unique,
     217 * then the extension set identifier will match one of the extension sets with
     218 * that name.  However, this extension set identifier is not guaranteed to
     219 * correspond to the desired extension set. The extension set identifier is
     220 * used to access this extension set in other extension set related directives.
     221 *
     222 * This directive will not cause the calling task to be preempted.
     223 *
     224 * @retval RTEMS_SUCCESSFUL Extension set identified successfully.
     225 * @retval RTEMS_INVALID_ADDRESS Identifier pointer is @c NULL.
     226 * @retval RTEMS_INVALID_NAME Extension set name not found or invalid name.
     227 */
    115228rtems_status_code rtems_extension_ident(
    116   rtems_name    name,
    117   Objects_Id   *id
     229  rtems_name  name,
     230  rtems_id   *id
    118231);
    119232
    120 /*
    121  *  rtems_extension_delete
    122  *
    123  *  DESCRIPTION:
    124  *
    125  *  This routine implements the rtems_extension_delete directive.  The
    126  *  extension indicated by ID is deleted.
    127  */
    128 
     233/**
     234 * @brief Deletes an extension set object specified by the identifier @a id.
     235 *
     236 * Any subsequent references to the extension's name and identifier are
     237 * invalid.
     238 *
     239 * This directive will not cause the calling task to be preempted.
     240 *
     241 * @retval RTEMS_SUCCESSFUL Extension set deleted successfully.
     242 * @retval RTEMS_INVALID_ID Invalid extension set identifier.
     243 */
    129244rtems_status_code rtems_extension_delete(
    130   Objects_Id id
     245  rtems_id id
    131246);
     247
     248/** @} */
    132249
    133250#ifndef __RTEMS_APPLICATION__
  • cpukit/sapi/inline/rtems/extension.inl

    re89faf3e rc42d1a4  
    11/**
    2  *  @file rtems/extension.inl
     2 * @file
    33 *
    4  *  This file contains the static inline implementation of the inlined routines
    5  *  from the Extension Manager.
     4 * @ingroup ClassicUserExtensions
     5 *
     6 * @brief User Extensions API.
    67 */
    78
     
    2021#define __EXTENSION_MANAGER_inl
    2122
    22 /*PAGE
    23  *
    24  *  _Extension_Allocate
    25  *
    26  *  DESCRIPTION:
    27  *
    28  *  This function allocates a extension control block from
    29  *  the inactive chain of free extension control blocks.
    30  */
    31 
    3223RTEMS_INLINE_ROUTINE Extension_Control *_Extension_Allocate( void )
    3324{
    3425  return (Extension_Control *) _Objects_Allocate( &_Extension_Information );
    3526}
    36 
    37 /*PAGE
    38  *
    39  *  _Extension_Free
    40  *
    41  *  DESCRIPTION:
    42  *
    43  *  This routine frees a extension control block to the
    44  *  inactive chain of free extension control blocks.
    45  */
    4627
    4728RTEMS_INLINE_ROUTINE void _Extension_Free (
     
    5132  _Objects_Free( &_Extension_Information, &the_extension->Object );
    5233}
    53 
    54 /*PAGE
    55  *
    56  *  _Extension_Get
    57  *
    58  *  DESCRIPTION:
    59  *
    60  *  This function maps extension IDs to extension control blocks.
    61  *  If ID corresponds to a local extension, then it returns
    62  *  the extension control pointer which maps to ID and location
    63  *  is set to OBJECTS_LOCAL.  Otherwise, location is set
    64  *  to OBJECTS_ERROR and the returned value is undefined.
    65  */
    6634
    6735RTEMS_INLINE_ROUTINE Extension_Control *_Extension_Get (
     
    7442}
    7543
    76 /*PAGE
    77  *
    78  *  _Extension_Is_null
    79  *
    80  *  DESCRIPTION:
    81  *
    82  *  This function returns TRUE if the_extension is NULL and FALSE otherwise.
    83  */
    84 
    8544RTEMS_INLINE_ROUTINE bool _Extension_Is_null (
    8645  Extension_Control *the_extension
  • cpukit/sapi/src/extensioncreate.c

    re89faf3e rc42d1a4  
     1/**
     2 * @file
     3 *
     4 * @ingroup ClassicUserExtensions
     5 *
     6 * @brief User Extensions Implementation.
     7 */
     8 
    19/*
    2  *  Extension Manager -- rtems_extension_create
    3  *
    410 *  COPYRIGHT (c) 1989-2007.
    511 *  On-Line Applications Research Corporation (OAR).
     
    2228#include <rtems/extension.h>
    2329
    24 /*PAGE
    25  *
    26  *  rtems_extension_create
    27  *
    28  *  This directive creates a extension and performs some initialization.
    29  *
    30  *  Input parameters:
    31  *    name            - extension name
    32  *    extension_table - pointer to extension set information
    33  *    id              - pointer to extension id
    34  *
    35  *  Output parameters:
    36  *    id                - extension id
    37  *    RTEMS_SUCCESSFUL - if successful
    38  *    error code        - if unsuccessful
    39  */
    40 
    4130rtems_status_code rtems_extension_create(
    4231  rtems_name              name,
    4332  rtems_extensions_table *extension_table,
    44   Objects_Id             *id
     33  rtems_id               *id
    4534)
    4635{
     
    6251  }
    6352
    64   _User_extensions_Add_set( &the_extension->Extension, extension_table );
     53  _User_extensions_Add_set_with_table( &the_extension->Extension, extension_table );
    6554
    6655  _Objects_Open(
  • cpukit/sapi/src/extensiondelete.c

    re89faf3e rc42d1a4  
     1/**
     2 * @file
     3 *
     4 * @ingroup ClassicUserExtensions
     5 *
     6 * @brief User Extensions Implementation.
     7 */
     8 
    19/*
    2  *  Extension Manager -- rtems_extension_delete
    3  *
    410 *  COPYRIGHT (c) 1989-2007.
    511 *  On-Line Applications Research Corporation (OAR).
     
    2228#include <rtems/extension.h>
    2329
    24 /*PAGE
    25  *
    26  *  rtems_extension_delete
    27  *
    28  *  This directive allows a thread to delete a extension.
    29  *
    30  *  Input parameters:
    31  *    id - extension id
    32  *
    33  *  Output parameters:
    34  *    RTEMS_SUCCESSFUL - if successful
    35  *    error code - if unsuccessful
    36  */
    37 
    3830rtems_status_code rtems_extension_delete(
    39   Objects_Id id
     31  rtems_id id
    4032)
    4133{
  • cpukit/sapi/src/extensionident.c

    re89faf3e rc42d1a4  
     1/**
     2 * @file
     3 *
     4 * @ingroup ClassicUserExtensions
     5 *
     6 * @brief User Extensions Implementation.
     7 */
     8 
    19/*
    2  *  Extension Manager -- rtems_extension_ident
    3  *
    410 *  COPYRIGHT (c) 1989-2007.
    511 *  On-Line Applications Research Corporation (OAR).
     
    2228#include <rtems/extension.h>
    2329
    24 /*PAGE
    25  *
    26  *  rtems_extension_ident
    27  *
    28  *  This directive returns the system ID associated with
    29  *  the extension name.
    30  *
    31  *  Input parameters:
    32  *    name - user defined message queue name
    33  *    id   - pointer to extension id
    34  *
    35  *  Output parameters:
    36  *    *id               - message queue id
    37  *    RTEMS_SUCCESSFUL - if successful
    38  *    error code        - if unsuccessful
    39  */
    40 
    4130rtems_status_code rtems_extension_ident(
    4231  rtems_name    name,
    43   Objects_Id   *id
     32  rtems_id     *id
    4433)
    4534{
  • cpukit/score/Makefile.am

    re89faf3e rc42d1a4  
    197197
    198198## USEREXT_C_FILES
    199 libscore_a_SOURCES += src/userextaddapiset.c src/userextaddset.c \
     199libscore_a_SOURCES += src/userextaddset.c \
    200200    src/userext.c src/userextremoveset.c src/userextthreadbegin.c \
    201201    src/userextthreadcreate.c src/userextthreaddelete.c \
  • cpukit/score/include/rtems/score/userext.h

    re89faf3e rc42d1a4  
    1 /** 
    2  *  @file  rtems/score/userext.h
    3  *
    4  *  This include file contains all information about user extensions.  This
    5  *  Handler provides mechanisms which can be used to initialize and manipulate
    6  *  all user extensions.
     1/**
     2 * @file
     3 *
     4 * @ingroup ScoreUserExt
     5 *
     6 * @brief User Extension Handler API.
    77 */
    88
     
    2121#define _RTEMS_SCORE_USEREXT_H
    2222
    23 /**
    24  *  @defgroup ScoreUserExt User Extension Handler
    25  *
    26  *  This handler encapsulates functionality related to the management of
    27  *  the user extensions to the SuperCore that are available to the user.
    28  */
    29 /**@{*/
    30 
    3123#ifdef __cplusplus
    3224extern "C" {
     
    3729#include <rtems/score/thread.h>
    3830
    39 /*@}*/
    40 
    41 /** @defgroup ScoreUserExtStruct User Extension Handler Structures
    42  *
    43  *  The following records defines the User Extension Table.
    44  *  This table defines the application dependent routines which
    45  *  are invoked at critical points in the life of each thread and
    46  *  the system as a whole.
    47  */
    48 /*@{*/
    49 
    50 /**
    51  *  This type indicates the return type of a user extension method.
    52  */
    53 typedef void User_extensions_routine;
    54 
    55 /**
    56  *  This type defines the prototype of a thread creation extension handler.
    57  *  The handler is passed the thread executing and the thread being created.
    58  */
    59 typedef bool    ( *User_extensions_thread_create_extension )(
    60                  Thread_Control *,
    61                  Thread_Control *
    62              );
    63 
    64 /**
    65  *  This type defines the prototype of a thread deletion extension handler.
    66  *  The handler is passed the thread executing and the thread being deleted.
    67  */
    68 typedef User_extensions_routine ( *User_extensions_thread_delete_extension )(
    69                  Thread_Control *,
    70                  Thread_Control *
    71              );
    72 
    73 /**
    74  *  This type defines the prototype of thread starting extension handler.
    75  *  The handler is passed the thread executing and the thread being started.
    76  */
    77 typedef User_extensions_routine ( *User_extensions_thread_start_extension )(
    78                  Thread_Control *,
    79                  Thread_Control *
    80              );
    81 
    82 /**
    83  *  This type defines the prototype of a thread restarting extension handler.
    84  *  The handler is passed the thread executing and the thread being restarted.
    85  */
    86 typedef User_extensions_routine ( *User_extensions_thread_restart_extension )(
    87                  Thread_Control *,
    88                  Thread_Control *
    89              );
    90 
    91 /**
    92  *  This type defines the prototype of thread context switch extension handler.
    93  *  The handler is passed the thread currently executing and the thread being
    94  *  switched to.
    95  */
    96 typedef User_extensions_routine ( *User_extensions_thread_switch_extension )(
    97                  Thread_Control *,
    98                  Thread_Control *
    99              );
    100 
    101 /**
    102  *  This type defines the prototype of a post context switch extension handler.
    103  *  The handler is passed the thread thread being switched to.
    104  */
    105 typedef User_extensions_routine (*User_extensions_thread_post_switch_extension)(
    106                  Thread_Control *
    107              );
    108 
    109 /**
    110  *  This type defines the prototype of a thread beginning to execute
    111  *  extension handler.  The handler is passed the thread executing.  This
    112  *  extension is executed in the context of the beginning thread.
    113  */
    114 typedef User_extensions_routine ( *User_extensions_thread_begin_extension )(
    115                  Thread_Control *
    116              );
    117 
    118 /**
    119  *  This type defines the prototype of a thread exiting extension handler.
    120  *  The handler is passed the thread exiting.
    121  */
    122 typedef User_extensions_routine ( *User_extensions_thread_exitted_extension )(
    123                  Thread_Control *
    124              );
    125 
    126 /**
    127  *  This type defines the prototype of the fatal error extension handler.
    128  *  The handler is passed an indicator of the source of the fatal error,
    129  *  whether it is internal to RTEMS and an error code.
    130  */
    131 typedef User_extensions_routine ( *User_extensions_fatal_extension )(
    132                  Internal_errors_Source  /* the_source  */,
    133                  bool                    /* is_internal */,
    134                  uint32_t                /* the_error   */
    135              );
    136 
    137 /**
    138  *  This type defines a set of user extensions.
     31typedef void User_extensions_routine RTEMS_COMPILER_DEPRECATED_ATTRIBUTE;
     32
     33/**
     34 * @defgroup ScoreUserExt User Extension Handler
     35 *
     36 * @ingroup Score
     37 *
     38 * @brief The User Extension Handler provides invocation of application
     39 * dependent routines at critical points in the life of each thread and the
     40 * system as a whole.
     41 *
     42 * @{
     43 */
     44
     45/**
     46 * @brief Task create extension.
     47 *
     48 * It corresponds to _Thread_Initialize() (used by the rtems_task_create()
     49 * directive).  The first parameter points to the currently executing thread
     50 * which created the new thread.  The second parameter points to the created
     51 * thread.
     52 *
     53 * It is invoked after the new thread has been completely initialized, but
     54 * before it is placed on a ready chain.
     55 *
     56 * Thread dispatching may be disabled.  It can be assumed that the executing
     57 * thread locked the allocator mutex.  They only exception is the creation of
     58 * the idle thread.  In this case the allocator mutex is not locked.
     59 *
     60 * The user extension is expected to return @c true if it successfully
     61 * executed, and @c false otherwise. A thread create user extension will
     62 * frequently attempt to allocate resources. If this allocation fails, then the
     63 * extension should return @c false and the entire task create operation will
     64 * fail.
     65 */
     66typedef bool ( *User_extensions_thread_create_extension )(
     67  Thread_Control *,
     68  Thread_Control *
     69);
     70
     71/**
     72 * @brief Task delete extension.
     73 *
     74 * It corresponds to _Thread_Close() (used by the rtems_task_delete()
     75 * directive).  The first parameter points to the currently executing thread
     76 * which deleted the thread.  The second parameter points to the deleted
     77 * thread.
     78 *
     79 * It is invoked before all resources of the thread are deleted.
     80 *
     81 * Thread dispatching is enabled.  The executing thread locked the allocator
     82 * mutex.
     83 */
     84typedef void( *User_extensions_thread_delete_extension )(
     85  Thread_Control *,
     86  Thread_Control *
     87);
     88
     89/**
     90 * @brief Task start extension.
     91 *
     92 * It corresponds to _Thread_Start() (used by the rtems_task_start()
     93 * directive).  The first parameter points to the currently executing thread
     94 * which started the thread.  The second parameter points to the started
     95 * thread.
     96 *
     97 * It is invoked after the environment of the thread has been loaded and the
     98 * thread has been made ready.
     99 *
     100 * Thread dispatching is disabled.  The executing thread is not the holder of
     101 * the allocator mutex.
     102 */
     103typedef void( *User_extensions_thread_start_extension )(
     104  Thread_Control *,
     105  Thread_Control *
     106);
     107
     108/**
     109 * @brief Task restart extension.
     110 *
     111 * It corresponds to _Thread_Restart() (used by the rtems_task_restart()
     112 * directive).  The first parameter points to the currently executing thread
     113 * which restarted the thread.  The second parameter points to the restarted
     114 * thread.
     115 *
     116 * It is invoked after the environment of the thread has been loaded and the
     117 * thread has been made ready.
     118 *
     119 * Thread dispatching is disabled.  The executing thread is not the holder of
     120 * the allocator mutex.
     121 */
     122typedef void( *User_extensions_thread_restart_extension )(
     123  Thread_Control *,
     124  Thread_Control *
     125);
     126
     127/**
     128 * @brief Task switch extension.
     129 *
     130 * It corresponds to _Thread_Dispatch().  The first parameter points to the
     131 * currently executing thread.  The second parameter points to the heir thread.
     132 *
     133 * It is invoked before the context switch from the executing to the heir
     134 * thread.
     135 *
     136 * Thread dispatching is disabled.  The state of the allocator mutex is
     137 * arbitrary.
     138 *
     139 * The context switches initiated through _Thread_Start_multitasking() and
     140 * _Thread_Stop_multitasking() are not covered by this extension.  The
     141 * executing thread may run with a minimal setup, for example with a freed task
     142 * stack.
     143 */
     144typedef void( *User_extensions_thread_switch_extension )(
     145  Thread_Control *,
     146  Thread_Control *
     147);
     148
     149/**
     150 * @brief Task begin extension.
     151 *
     152 * It corresponds to _Thread_Handler().  The first parameter points to the
     153 * currently executing thread which begins now execution.
     154 *
     155 * Thread dispatching is disabled.  The executing thread is not the holder of
     156 * the allocator mutex.
     157 */
     158typedef void( *User_extensions_thread_begin_extension )(
     159  Thread_Control *
     160);
     161
     162/**
     163 * @brief Task exitted extension.
     164 *
     165 * It corresponds to _Thread_Handler().  The first parameter points to the
     166 * currently executing thread which exitted before.
     167 *
     168 * Thread dispatching is disabled.  The state of the allocator mutex is
     169 * arbitrary.
     170 */
     171typedef void( *User_extensions_thread_exitted_extension )(
     172  Thread_Control *
     173);
     174
     175/**
     176 * @brief Task fatal error extension.
     177 *
     178 * It corresponds to _Internal_error_Occurred() (used by the
     179 * rtems_fatal_error_occurred() directive).  The first parameter contains the
     180 * internal error source.  The second parameter indicates if it was an internal
     181 * error.  The third parameter contains the error code.
     182 *
     183 * This extension should not call any RTEMS directives.
     184 */
     185typedef void( *User_extensions_fatal_extension )(
     186  Internal_errors_Source,
     187  bool,
     188  uint32_t
     189);
     190
     191/**
     192 * @brief User extension table.
    139193 */
    140194typedef struct {
    141   /** This field is the thread creation handler. */
    142   User_extensions_thread_create_extension       thread_create;
    143   /** This field is the thread starting handler. */
    144   User_extensions_thread_start_extension        thread_start;
    145   /** This field is the thread restarting handler. */
    146   User_extensions_thread_restart_extension      thread_restart;
    147   /** This field is the thread deleting handler */
    148   User_extensions_thread_delete_extension       thread_delete;
    149   /** This field is thread context switch handler. */
    150   User_extensions_thread_switch_extension       thread_switch;
    151   /** This field is the thread beginning handler. */
    152   User_extensions_thread_begin_extension        thread_begin;
    153   /** This field is thread exiting handler. */
    154   User_extensions_thread_exitted_extension      thread_exitted;
    155   /** This field is the fatal error extension. */
    156   User_extensions_fatal_extension               fatal;
     195  User_extensions_thread_create_extension  thread_create;
     196  User_extensions_thread_start_extension   thread_start;
     197  User_extensions_thread_restart_extension thread_restart;
     198  User_extensions_thread_delete_extension  thread_delete;
     199  User_extensions_thread_switch_extension  thread_switch;
     200  User_extensions_thread_begin_extension   thread_begin;
     201  User_extensions_thread_exitted_extension thread_exitted;
     202  User_extensions_fatal_extension          fatal;
    157203}   User_extensions_Table;
    158204
    159205/**
    160  *  This is used to manage the list of switch handlers.  They are managed
    161  *  separately from other extensions for performance reasons.
     206 * @brief Manages the switch callouts.
     207 *
     208 * They are managed separately from other extensions for performance reasons.
    162209 */
    163210typedef struct {
    164   /** This field is a Chain Node structure and allows this to be placed on
    165    *  chains for set management.
    166    */
    167211  Chain_Node                              Node;
    168   /** This field is the thread switch extension. */
    169212  User_extensions_thread_switch_extension thread_switch;
    170213}   User_extensions_Switch_control;
    171214
    172215/**
    173  *  This is used to manage each user extension set.
    174  *  The switch control is part of the extensions control even
    175  *  if not used due to the extension not having a switch
    176  * handler.
     216 * @brief Manages each user extension set.
     217 *
     218 * The switch control is part of the extensions control even if not used due to
     219 * the extension not having a switch handler.
    177220 */
    178221typedef struct {
    179   /** This field is a Chain Node structure and allows this to be placed on
    180    *  chains for set management.
    181    */
    182222  Chain_Node                     Node;
    183   /** This field is the thread switch user extension. */
    184223  User_extensions_Switch_control Switch;
    185   /** This field is the rest of this user extension's entry points.  */
    186224  User_extensions_Table          Callouts;
    187225}   User_extensions_Control;
    188226
    189227/**
    190  *  This is used to manage the list of active extensions.
     228 * @brief List of active extensions.
    191229 */
    192230SCORE_EXTERN Chain_Control _User_extensions_List;
    193231
    194232/**
    195  *  This is used to manage a chain of user extension task
    196  *  switch nodes.
     233 * @brief List of active task switch extensions.
    197234 */
    198235SCORE_EXTERN Chain_Control _User_extensions_Switches_list;
    199236
    200 /*@}*/
    201 /** @addtogroup ScoreUserExt */
    202 
    203 /*@{*/
    204 
    205 /** @brief User extensions Handler Initialization
    206  *
    207  *  This routine performs the initialization necessary for this handler.
    208  */
    209 void _User_extensions_Handler_initialization(void);
    210 
    211 /** @brief User extensions Add to API extension set
    212  *
    213  *  This routine is used to add an API extension set to the active list.
    214  *
    215  *  @param[in] the_extension is the extension set to add
    216  */
    217 void _User_extensions_Add_API_set (
    218   User_extensions_Control *the_extension
    219 );
    220 
    221 /** @brief User extensions Add extension set
    222  *
    223  *  This routine is used to add a user extension set to the active list.
    224  *
    225  *  @param[in] the_extension is the extension set to add
    226  *  @param[in] extension_table is the user's extension set
    227  */
    228 void _User_extensions_Add_set (
    229   User_extensions_Control *the_extension,
     237/**
     238 * @name Extension Maintainance
     239 *
     240 * @{
     241 */
     242
     243void _User_extensions_Handler_initialization( void );
     244
     245void _User_extensions_Add_set(
     246  User_extensions_Control *extension
     247);
     248
     249RTEMS_INLINE_ROUTINE void _User_extensions_Add_set_with_table(
     250  User_extensions_Control *extension,
    230251  User_extensions_Table   *extension_table
    231 );
    232 
    233 /**
    234  *  This routine is used to remove a user extension set from the active list.
    235  */
    236 void _User_extensions_Remove_set (
    237   User_extensions_Control  *the_extension
    238 );
    239 
    240 /** @brief  User extensions Thread create
    241  *
    242  *  This routine is used to invoke the user extension for
    243  *  the thread creation operate.
    244  *
    245  *  @param[in] the_thread is the thread being created.
    246  *
    247  *  @return This method returns true if the user extension executed
    248  *          successfully.
    249  */
    250 bool _User_extensions_Thread_create (
    251   Thread_Control *the_thread
    252 );
    253 
    254 /** @brief  User extensions Thread delete
    255  *
    256  *  This routine is used to invoke the user extension for
    257  *  the thread deletion operation.
    258  *
    259  *  @param[in] the_thread is the thread being deleted.
    260  */
    261 void _User_extensions_Thread_delete (
    262   Thread_Control *the_thread
    263 );
    264 
    265 /** @brief  User extensions Thread start
    266  *
    267  *  This routine is used to invoke the user extension for
    268  *  the thread start operation.
    269  *
    270  *  @param[in] the_thread is the thread being started.
    271  */
    272 void _User_extensions_Thread_start (
    273   Thread_Control *the_thread
    274 );
    275 
    276 /** @brief  User extensions Thread restart
    277  *
    278  *  This routine is used to invoke the user extension for
    279  *  the thread restart operation.
    280  *
    281  *  @param[in] the_thread is the thread being restarted.
    282  */
    283 void _User_extensions_Thread_restart (
    284   Thread_Control *the_thread
    285 );
    286 
    287 /** @brief  User extensions Thread begin
    288  *
    289  *  This routine is used to invoke the user extension which
    290  *  is invoked when a thread begins.
    291  *
    292  *  @param[in] executing is the thread beginning to execute.
    293  */
    294 void _User_extensions_Thread_begin (
     252)
     253{
     254  extension->Callouts = *extension_table;
     255
     256  _User_extensions_Add_set( extension );
     257}
     258
     259void _User_extensions_Remove_set(
     260  User_extensions_Control *extension
     261);
     262
     263/** @} */
     264
     265/**
     266 * @name Extension Callout Dispatcher
     267 *
     268 * @{
     269 */
     270
     271bool _User_extensions_Thread_create(
     272  Thread_Control *created
     273);
     274
     275void _User_extensions_Thread_delete(
     276  Thread_Control *deleted
     277);
     278
     279void _User_extensions_Thread_start(
     280  Thread_Control *started
     281);
     282
     283void _User_extensions_Thread_restart(
     284  Thread_Control *restarted
     285);
     286
     287void _User_extensions_Thread_begin(
    295288  Thread_Control *executing
    296289);
    297290
    298 
    299 /** @brief  User extensions Thread switch
    300  *
    301  *  This routine is used to invoke the user extension which
    302  *  is invoked when a context switch occurs.
    303  *
    304  *  @param[in] executing is the thread currently executing.
    305  *  @param[in] heir is the thread which will execute.
    306  */
    307 void _User_extensions_Thread_switch (
     291void _User_extensions_Thread_switch(
    308292  Thread_Control *executing,
    309293  Thread_Control *heir
    310294);
    311295
    312 /** @brief  User extensions Thread exitted
    313  *
    314  *  This routine is used to invoke the user extension which
    315  *  is invoked when a thread exits.
    316  *
    317  *  @param[in] executing is the thread voluntarily exiting.
    318  */
    319 void _User_extensions_Thread_exitted (
     296void _User_extensions_Thread_exitted(
    320297  Thread_Control *executing
    321298);
    322299
    323 /** @brief  User extensions Fatal
    324  *
    325  *  This routine is used to invoke the user extension invoked
    326  *  when a fatal error occurs.
    327  *
    328  *  @param[in] the_source is the source of the fatal error.
    329  *  @param[in] is_internal is true if the error originated inside RTEMS.
    330  *  @param[in] the_error is an indication of the actual error.
    331  */
    332 void _User_extensions_Fatal (
    333   Internal_errors_Source  the_source,
    334   bool                    is_internal,
    335   uint32_t                the_error
    336 );
     300void _User_extensions_Fatal(
     301  Internal_errors_Source source,
     302  bool                   is_internal,
     303  uint32_t               error
     304);
     305
     306/** @} */
     307
     308/** @} */
    337309
    338310#ifdef __cplusplus
     
    340312#endif
    341313
    342 /**@}*/
    343 
    344314#endif
    345315/* end of include file */
  • cpukit/score/src/userext.c

    re89faf3e rc42d1a4  
     1/**
     2 * @file
     3 *
     4 * @ingroup ScoreUserExt
     5 *
     6 * @brief User Extension Handler implementation.
     7 */
     8
    19/*
    210 *  COPYRIGHT (c) 1989-2008.
     
    1927#include <rtems/score/wkspace.h>
    2028#include <string.h>
    21 
    22 /**
    23  *  This routine performs the initialization necessary for this handler.
    24  */
    2529
    2630void _User_extensions_Handler_initialization(void)
     
    5054 
    5155    for ( i = 0 ; i < number_of_extensions ; i++ ) {
    52       _User_extensions_Add_set (extension, &initial_extensions[i]);
     56      _User_extensions_Add_set_with_table (extension, &initial_extensions[i]);
    5357      extension++;
    5458    }
  • cpukit/score/src/userextaddset.c

    re89faf3e rc42d1a4  
     1/**
     2 * @file
     3 *
     4 * @ingroup ScoreUserExt
     5 *
     6 * @brief User Extension Handler implementation.
     7 */
     8
    19/*
    210 *  COPYRIGHT (c) 1989-2007.
     
    1725#include <rtems/score/userext.h>
    1826
    19 /**
    20  *  This routine is used to add a user extension set to the active list.
    21  *
    22  *  @note Must be before _User_extensions_Handler_initialization to
    23  *        ensure proper inlining.
    24  */
    25 
    26 void _User_extensions_Add_set (
    27   User_extensions_Control *the_extension,
    28   User_extensions_Table   *extension_table
     27void _User_extensions_Add_set(
     28  User_extensions_Control *the_extension
    2929)
    3030{
    31   the_extension->Callouts = *extension_table;
    32 
    3331  _Chain_Append( &_User_extensions_List, &the_extension->Node );
    3432
     
    3735   */
    3836
    39   if ( extension_table->thread_switch != NULL ) {
    40     the_extension->Switch.thread_switch = extension_table->thread_switch;
     37  if ( the_extension->Callouts.thread_switch != NULL ) {
     38    the_extension->Switch.thread_switch =
     39      the_extension->Callouts.thread_switch;
    4140    _Chain_Append(
    4241      &_User_extensions_Switches_list,
  • cpukit/score/src/userextremoveset.c

    re89faf3e rc42d1a4  
     1/**
     2 * @file
     3 *
     4 * @ingroup ScoreUserExt
     5 *
     6 * @brief User Extension Handler implementation.
     7 */
     8
    19/*
    210 *  COPYRIGHT (c) 1989-2007.
     
    1725#include <rtems/score/userext.h>
    1826
    19 /**
    20  *  This routine is used to remove a user extension set from the active list.
    21  */
    22 
    2327void _User_extensions_Remove_set (
    2428  User_extensions_Control  *the_extension
  • cpukit/score/src/userextthreadbegin.c

    re89faf3e rc42d1a4  
     1/**
     2 * @file
     3 *
     4 * @ingroup ScoreUserExt
     5 *
     6 * @brief User Extension Handler implementation.
     7 */
     8
    19/*
    210 *  COPYRIGHT (c) 1989-2007.
     
    1624#include <rtems/system.h>
    1725#include <rtems/score/userext.h>
    18 
    19 /*PAGE
    20  *
    21  *  _User_extensions_Thread_begin
    22  *
    23  */
    2426
    2527void _User_extensions_Thread_begin (
     
    4143}
    4244
    43 /*PAGE
    44  *
    45  *  _User_extensions_Thread_exitted
    46  */
    47 
    4845void _User_extensions_Thread_exitted (
    4946  Thread_Control *executing
     
    6360  }
    6461}
    65 
    66 /*PAGE
    67  *
    68  *  _User_extensions_Fatal
    69  */
    7062
    7163void _User_extensions_Fatal (
  • cpukit/score/src/userextthreadcreate.c

    re89faf3e rc42d1a4  
     1/**
     2 * @file
     3 *
     4 * @ingroup ScoreUserExt
     5 *
     6 * @brief User Extension Handler implementation.
     7 */
     8
    19/*
    210 *  COPYRIGHT (c) 1989-2007.
     
    1624#include <rtems/system.h>
    1725#include <rtems/score/userext.h>
    18 
    19 /*PAGE
    20  *
    21  *  _User_extensions_Thread_create
    22  */
    2326
    2427bool _User_extensions_Thread_create (
  • cpukit/score/src/userextthreaddelete.c

    re89faf3e rc42d1a4  
     1/**
     2 * @file
     3 *
     4 * @ingroup ScoreUserExt
     5 *
     6 * @brief User Extension Handler implementation.
     7 */
     8
    19/*
    210 *  COPYRIGHT (c) 1989-2007.
     
    1624#include <rtems/system.h>
    1725#include <rtems/score/userext.h>
    18 
    19 /*PAGE
    20  *
    21  *  _User_extensions_Thread_delete
    22  */
    2326
    2427void _User_extensions_Thread_delete (
  • cpukit/score/src/userextthreadrestart.c

    re89faf3e rc42d1a4  
     1/**
     2 * @file
     3 *
     4 * @ingroup ScoreUserExt
     5 *
     6 * @brief User Extension Handler implementation.
     7 */
     8
    19/*
    210 *  COPYRIGHT (c) 1989-2007.
     
    1624#include <rtems/system.h>
    1725#include <rtems/score/userext.h>
    18 
    19 /*PAGE
    20  *
    21  *  _User_extensions_Thread_restart
    22  *
    23  */
    2426
    2527void _User_extensions_Thread_restart (
  • cpukit/score/src/userextthreadstart.c

    re89faf3e rc42d1a4  
     1/**
     2 * @file
     3 *
     4 * @ingroup ScoreUserExt
     5 *
     6 * @brief User Extension Handler implementation.
     7 */
     8
    19/*
    210 *  COPYRIGHT (c) 1989-2007.
     
    1624#include <rtems/system.h>
    1725#include <rtems/score/userext.h>
    18 
    19 /*PAGE
    20  *
    21  *  _User_extensions_Thread_start
    22  *
    23  */
    2426
    2527void _User_extensions_Thread_start (
  • cpukit/score/src/userextthreadswitch.c

    re89faf3e rc42d1a4  
     1/**
     2 * @file
     3 *
     4 * @ingroup ScoreUserExt
     5 *
     6 * @brief User Extension Handler implementation.
     7 */
     8
    19/*
    210 *  COPYRIGHT (c) 1989-2007.
     
    1725#include <rtems/score/userext.h>
    1826
    19 /**
    20  *  This routine is used to invoke the user extension which
    21  *  is invoked when a context switch occurs.
    22  */
    2327void _User_extensions_Thread_switch (
    2428  Thread_Control *executing,
Note: See TracChangeset for help on using the changeset viewer.