Changeset b1e3b75 in rtems-docs


Ignore:
Timestamp:
Jan 26, 2017, 2:10:49 PM (5 years ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
5, am, master
Children:
166d17b
Parents:
0456ee7
Message:

c-user: Rework user extensions chapter

Update #2692.
Update #2752.

Location:
c-user
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • c-user/configuring_a_system.rst

    r0456ee7 rb1e3b75  
    19741974.. COMMENT: === CONFIGURE_INITIAL_EXTENSIONS ===
    19751975
    1976 .. _Specify Application Specific User Extensions:
     1976.. _CONFIGURE_INITIAL_EXTENSIONS:
    19771977
    19781978Specify Application Specific User Extensions
  • c-user/fatal_error.rst

    r0456ee7 rb1e3b75  
    388388==========
    389389
    390 .. _Announcing a Fatal Error:
     390.. _Terminate:
    391391
    392392Announcing a Fatal Error
     
    399399or :c:func:`exit()`).
    400400
    401 The first action of the internal error handler is to call the fatal handler of
     401The first action of the internal error handler is to call the fatal extension of
    402402the user extensions.  For the initial extensions the following conditions are
    403403required
     
    418418reset.  In this case the non-initial extensions will be not called.
    419419
    420 The fatal handler are called with three parameters:
     420The fatal extensions are called with three parameters:
    421421
    422422- the fatal source,
     
    426426- an error code with a fatal source dependent content.
    427427
    428 Once all fatal handler executed, the error information will be stored to
     428Once all fatal extensions executed, the error information will be stored to
    429429:c:data:`_Internal_errors_What_happened` and the system state is set to
    430430:c:macro:`SYSTEM_STATE_TERMINATED`.
  • c-user/user_extensions.rst

    r0456ee7 rb1e3b75  
    1515============
    1616
    17 The RTEMS User Extensions Manager allows the application developer to augment
    18 the executive by allowing them to supply extension routines which are invoked
    19 at critical system events.  The directives provided by the user extensions
    20 manager are:
     17The user extensions manager allows the application developer to augment the
     18executive by allowing them to supply extension routines which are invoked at
     19critical system events.  The directives provided by the user extensions manager
     20are:
    2121
    2222- rtems_extension_create_ - Create an extension set
     
    2929==========
    3030
    31 User extension routines are invoked when the following system events occur:
    32 
    33 - Task creation
    34 
    35 - Task initiation
    36 
    37 - Task reinitiation
    38 
    39 - Task deletion
    40 
    41 - Task context switch
    42 
    43 - Post task context switch
    44 
    45 - Task begin
    46 
    47 - Task exits
    48 
    49 - Fatal error detection
    50 
    51 These extensions are invoked as a function with arguments that are appropriate
    52 to the system event.
     31User extensions are invoked when the following system events occur
     32
     33- thread creation,
     34
     35- thread start,
     36
     37- thread restart,
     38
     39- thread switch,
     40
     41- thread begin,
     42
     43- thread exitted (return from thread entry function),
     44
     45- thread termination,
     46
     47- thread deletion, and
     48
     49- fatal error detection (system termination).
     50
     51The extensions have event-specific arguments, invocation orders and execution
     52contexts.  Extension sets can be installed at run-time via
     53:ref:`rtems_extension_create() <rtems_extension_create>` (dynamic extension
     54sets) or at link-time via the application configuration option
     55:ref:`CONFIGURE_INITIAL_EXTENSIONS <CONFIGURE_INITIAL_EXTENSIONS>` (initial
     56extension sets).
     57
     58The execution context of extensions varies.  Some extensions are invoked with
     59ownership of the allocator mutex.  The allocator mutex protects dynamic memory
     60allocations and object creation/deletion.  Some extensions are invoked with
     61thread dispatching disabled.  The fatal error extension is invoked in an
     62arbitrary context.
    5363
    5464Extension Sets
    5565--------------
    56 .. index:: extension set
    57 
    58 An extension set is defined as a set of routines which are invoked at each of
    59 the critical system events at which user extension routines are invoked.
    60 Together a set of these routines typically perform a specific functionality
    61 such as performance monitoring or debugger support.  RTEMS is informed of the
    62 entry points which constitute an extension set via the following
    63 structure:.. index:: rtems_extensions_table
     66.. index:: user extension set
     67.. index:: rtems_extensions_table
     68
     69User extensions are maintained as a set.  All extensions are optional and may
     70be `NULL`.  Together a set of these extensions typically performs a specific
     71functionality such as performance monitoring or debugger support.  The user
     72extension set is defined via the following structure.
    6473
    6574.. code-block:: c
    6675
    6776    typedef struct {
    68         rtems_task_create_extension      thread_create;
    69         rtems_task_start_extension       thread_start;
    70         rtems_task_restart_extension     thread_restart;
    71         rtems_task_delete_extension      thread_delete;
    72         rtems_task_switch_extension      thread_switch;
    73         rtems_task_begin_extension       thread_begin;
    74         rtems_task_exitted_extension     thread_exitted;
    75         rtems_fatal_extension            fatal;
     77      rtems_task_create_extension    thread_create;
     78      rtems_task_start_extension     thread_start;
     79      rtems_task_restart_extension   thread_restart;
     80      rtems_task_delete_extension    thread_delete;
     81      rtems_task_switch_extension    thread_switch;
     82      rtems_task_begin_extension     thread_begin;
     83      rtems_task_exitted_extension   thread_exitted;
     84      rtems_fatal_extension          fatal;
     85      rtems_task_terminate_extension thread_terminate;
    7686    } rtems_extensions_table;
    77 
    78 RTEMS allows the user to have multiple extension sets active at the same time.
    79 First, a single static extension set may be defined as the application's User
    80 Extension Table which is included as part of the Configuration Table.  This
    81 extension set is active for the entire life of the system and may not be
    82 deleted.  This extension set is especially important because it is the only way
    83 the application can provided a FATAL error extension which is invoked if RTEMS
    84 fails during the initialize_executive directive.  The static extension set is
    85 optional and may be configured as NULL if no static extension set is required.
    86 
    87 Second, the user can install dynamic extensions using the
    88 ``rtems_extension_create`` directive.  These extensions are RTEMS objects in
    89 that they have a name, an ID, and can be dynamically created and deleted.  In
    90 contrast to the static extension set, these extensions can only be created and
    91 installed after the initialize_executive directive successfully completes
    92 execution.  Dynamic extensions are useful for encapsulating the functionality
    93 of an extension set.  For example, the application could use extensions to
    94 manage a special coprocessor, do performance monitoring, and to do stack bounds
    95 checking.  Each of these extension sets could be written and installed
    96 independently of the others.
    97 
    98 All user extensions are optional and RTEMS places no naming restrictions on the
    99 user. The user extension entry points are copied into an internal RTEMS
    100 structure. This means the user does not need to keep the table after creating
    101 it, and changing the handler entry points dynamically in a table once created
    102 has no effect. Creating a table local to a function can save space in space
    103 limited applications.
    104 
    105 Extension switches do not effect the context switch overhead if no switch
    106 handler is installed.
    10787
    10888TCB Extension Area
     
    11090.. index:: TCB extension area
    11191
    112 RTEMS provides for a pointer to a user-defined data area for each extension set
    113 to be linked to each task's control block.  This set of pointers is an
    114 extension of the TCB and can be used to store additional data required by the
    115 user's extension functions.
     92There is no system-provided storage for the initial extension sets.
     93
     94The task control block (TCB) contains a pointer for each dynamic extension set.
     95The pointer is initialized to `NULL` during thread initialization before the
     96thread create extension is invoked.  The pointer may be used by the dynamic
     97extension set to maintain thread-specific data.
    11698
    11799The TCB extension is an array of pointers in the TCB. The index into the table
    118 can be obtained from the extension id returned when the extension is
    119 created:
     100can be obtained from the extension identifier returned when the extension
     101object is created:
    120102
    121103.. index:: rtems extensions table index
     
    123105.. code-block:: c
    124106
    125     index = rtems_object_id_get_index(extension_id);
    126 
    127 The number of pointers in the area is the same as the number of user extension
    128 sets configured.  This allows an application to augment the TCB with
     107    index = rtems_object_id_get_index( extension_id );
     108
     109The number of pointers in the area is the same as the number of dynamic user
     110extension sets configured.  This allows an application to augment the TCB with
    129111user-defined information.  For example, an application could implement task
    130112profiling by storing timing statistics in the TCB's extended memory area.  When
    131 a task context switch is being executed, the ``TASK_SWITCH`` extension could
    132 read a real-time clock to calculate how long the task being swapped out has run
    133 as well as timestamp the starting time for the task being swapped in.
     113a task context switch is being executed, the thread switch extension could read
     114a real-time clock to calculate how long the task being swapped out has run as
     115well as timestamp the starting time for the task being swapped in.
    134116
    135117If used, the extended memory area for the TCB should be allocated and the TCB
    136118extension pointer should be set at the time the task is created or started by
    137 either the ``TASK_CREATE`` or ``TASK_START`` extension.  The application is
     119either the thread create or thread start extension.  The application is
    138120responsible for managing this extended memory area for the TCBs.  The memory
    139 may be reinitialized by the ``TASK_RESTART`` extension and should be
    140 deallocated by the ``TASK_DELETE`` extension when the task is deleted.  Since
    141 the TCB extension buffers would most likely be of a fixed size, the RTEMS
    142 partition manager could be used to manage the application's extended memory
    143 area.  The application could create a partition of fixed size TCB extension
    144 buffers and use the partition manager's allocation and deallocation directives
    145 to obtain and release the extension buffers.
    146 
    147 Extensions
    148 ----------
    149 
    150 The sections that follow will contain a description of each extension.  Each
    151 section will contain a prototype of a function with the appropriate calling
    152 sequence for the corresponding extension.  The names given for the C function
    153 and its arguments are all defined by the user.  The names used in the examples
    154 were arbitrarily chosen and impose no naming conventions on the user.
    155 
    156 TASK_CREATE Extension
    157 ~~~~~~~~~~~~~~~~~~~~~
    158 
    159 The TASK_CREATE extension directly corresponds to the ``rtems_task_create``
    160 directive.  If this extension is defined in any static or dynamic extension set
    161 and a task is being created, then the extension routine will automatically be
    162 invoked by RTEMS.  The extension should have a prototype similar to the
    163 following:
    164 
    165 .. index:: rtems_task_create_extension
    166 .. index:: rtems_extension
    167 
    168 .. code-block:: c
    169 
    170     bool user_task_create(
    171        rtems_tcb *current_task,
    172        rtems_tcb *new_task
    173     );
    174 
    175 where ``current_task`` can be used to access the TCB for the currently
    176 executing task, and new_task can be used to access the TCB for the new task
    177 being created.  This extension is invoked from the ``rtems_task_create``
    178 directive after ``new_task`` has been completely initialized, but before it is
    179 placed on a ready TCB chain.
    180 
    181 The user extension is expected to return the boolean value ``true`` if it
    182 successfully executed and ``false`` otherwise.  A task create user extension
    183 will frequently attempt to allocate resources.  If this allocation fails, then
    184 the extension should return ``false`` and the entire task create operation will
    185 fail.
    186 
    187 TASK_START Extension
    188 ~~~~~~~~~~~~~~~~~~~~
    189 
    190 The ``TASK_START`` extension directly corresponds to the task_start directive.
    191 If this extension is defined in any static or dynamic extension set and a task
    192 is being started, then the extension routine will automatically be invoked by
    193 RTEMS.  The extension should have a prototype similar to the following:
    194 
    195 .. index:: rtems_task_start_extension
    196 
    197 .. code-block:: c
    198 
    199     void user_task_start(
    200         rtems_tcb *current_task,
    201         rtems_tcb *started_task
    202     );
    203 
    204 where current_task can be used to access the TCB for the currently executing
    205 task, and started_task can be used to access the TCB for the dormant task being
    206 started. This extension is invoked from the task_start directive after
    207 started_task has been made ready to start execution, but before it is placed on
    208 a ready TCB chain.
    209 
    210 TASK_RESTART Extension
    211 ~~~~~~~~~~~~~~~~~~~~~~
    212 
    213 The ``TASK_RESTART`` extension directly corresponds to the task_restart
    214 directive.  If this extension is defined in any static or dynamic extension set
    215 and a task is being restarted, then the extension should have a prototype
    216 similar to the following:
    217 
    218 .. index:: rtems_task_restart_extension
    219 
    220 .. code-block:: c
    221 
    222     void user_task_restart(
    223         rtems_tcb *current_task,
    224         rtems_tcb *restarted_task
    225     );
    226 
    227 where current_task can be used to access the TCB for the currently executing
    228 task, and restarted_task can be used to access the TCB for the task being
    229 restarted. This extension is invoked from the task_restart directive after
    230 restarted_task has been made ready to start execution, but before it is placed
    231 on a ready TCB chain.
    232 
    233 TASK_DELETE Extension
    234 ~~~~~~~~~~~~~~~~~~~~~
    235 
    236 The ``TASK_DELETE`` extension is associated with the task_delete directive.  If
    237 this extension is defined in any static or dynamic extension set and a task is
    238 being deleted, then the extension routine will automatically be invoked by
    239 RTEMS.  The extension should have a prototype similar to the
    240 following:
    241 
    242 .. index:: rtems_task_delete_extension
    243 
    244 .. code-block:: c
    245 
    246     void user_task_delete(
    247         rtems_tcb *current_task,
    248         rtems_tcb *deleted_task
    249     );
    250 
    251 where current_task can be used to access the TCB for the currently executing
    252 task, and deleted_task can be used to access the TCB for the task being
    253 deleted. This extension is invoked from the task_delete directive after the TCB
    254 has been removed from a ready TCB chain, but before all its resources including
    255 the TCB have been returned to their respective free pools.  This extension
    256 should not call any RTEMS directives if a task is deleting itself (current_task
    257 is equal to deleted_task).
    258 
    259 TASK_SWITCH Extension
    260 ~~~~~~~~~~~~~~~~~~~~~
    261 
    262 The ``TASK_SWITCH`` extension corresponds to a task context switch.  If this
    263 extension is defined in any static or dynamic extension set and a task context
    264 switch is in progress, then the extension routine will automatically be invoked
    265 by RTEMS.  The extension should have a prototype similar to the following:
    266 
    267 .. index:: rtems_task_switch_extension
    268 
    269 .. code-block:: c
    270 
    271     void user_task_switch(
    272         rtems_tcb *current_task,
    273         rtems_tcb *heir_task
    274     );
    275 
    276 where current_task can be used to access the TCB for the task that is being
    277 swapped out, and heir_task can be used to access the TCB for the task being
    278 swapped in.  This extension is invoked from RTEMS' dispatcher routine after the
    279 current_task context has been saved, but before the heir_task context has been
    280 restored.  This extension should not call any RTEMS directives.
    281 
    282 TASK_BEGIN Extension
    283 ~~~~~~~~~~~~~~~~~~~~
    284 
    285 The ``TASK_BEGIN`` extension is invoked when a task begins execution.  It is
    286 invoked immediately before the body of the starting procedure and executes in
    287 the context in the task.  This user extension have a prototype similar to the
    288 following:
    289 
    290 .. index:: rtems_task_begin_extension
    291 
    292 .. code-block:: c
    293 
    294     void user_task_begin(
    295         rtems_tcb *current_task
    296     );
    297 
    298 where current_task can be used to access the TCB for the currently executing
    299 task which has begun.  The distinction between the ``TASK_BEGIN`` and
    300 TASK_START extension is that the ``TASK_BEGIN`` extension is executed in the
    301 context of the actual task while the TASK_START extension is executed in the
    302 context of the task performing the task_start directive.  For most extensions,
    303 this is not a critical distinction.
    304 
    305 TASK_EXITTED Extension
    306 ~~~~~~~~~~~~~~~~~~~~~~
    307 
    308 The ``TASK_EXITTED`` extension is invoked when a task exits the body of the
    309 starting procedure by either an implicit or explicit return statement.  This
    310 user extension have a prototype similar to the following:
    311 
    312 .. index:: rtems_task_exitted_extension
    313 
    314 .. code-block:: c
    315 
    316     void user_task_exitted(
    317         rtems_tcb *current_task
    318     );
    319 
    320 where current_task can be used to access the TCB for the currently executing
    321 task which has just exitted.
    322 
    323 Although exiting of task is often considered to be a fatal error, this
    324 extension allows recovery by either restarting or deleting the exiting task.
    325 If the user does not wish to recover, then a fatal error may be reported.  If
    326 the user does not provide a ``TASK_EXITTED`` extension or the provided handler
    327 returns control to RTEMS, then the RTEMS default handler will be used.  This
    328 default handler invokes the directive fatal_error_occurred with the
    329 ``RTEMS_TASK_EXITTED`` directive status.
    330 
    331 FATAL Error Extension
    332 ~~~~~~~~~~~~~~~~~~~~~
    333 
    334 The ``FATAL`` error extension is associated with the fatal_error_occurred
    335 directive.  If this extension is defined in any static or dynamic extension set
    336 and the fatal_error_occurred directive has been invoked, then this extension
    337 will be called.  This extension should have a prototype similar to the
    338 following:
    339 
    340 .. index:: rtems_fatal_extension
    341 
    342 .. code-block:: c
    343 
    344     void user_fatal_error(
    345         Internal_errors_Source  the_source,
    346         bool                    always_set_to_false,
    347         uint32_t                the_error
    348     );
    349 
    350 where the_error is the error code passed to the fatal_error_occurred
    351 directive. This extension is invoked from the fatal_error_occurred directive.
    352 
    353 If defined, the user's ``FATAL`` error extension is invoked before RTEMS'
    354 default fatal error routine is invoked and the processor is stopped.  For
    355 example, this extension could be used to pass control to a debugger when a
    356 fatal error occurs.  This extension should not call any RTEMS directives.
     121may be reinitialized by the thread restart extension and should be deallocated
     122by the thread delete extension  when the task is deleted.  Since the TCB
     123extension buffers would most likely be of a fixed size, the RTEMS partition
     124manager could be used to manage the application's extended memory area.  The
     125application could create a partition of fixed size TCB extension buffers and
     126use the partition manager's allocation and deallocation directives to obtain
     127and release the extension buffers.
    357128
    358129Order of Invocation
    359130-------------------
    360131
    361 When one of the critical system events occur, the user extensions are invoked
    362 in either "forward" or "reverse" order.  Forward order indicates that the
    363 static extension set is invoked followed by the dynamic extension sets in the
    364 order in which they were created.  Reverse order means that the dynamic
    365 extension sets are invoked in the opposite of the order in which they were
    366 created followed by the static extension set.  By invoking the extension sets
    367 in this order, extensions can be built upon one another.  At the following
    368 system events, the extensions are invoked in forward order:
    369 
    370 #. Task creation
    371 
    372 #. Task initiation
    373 
    374 #. Task reinitiation
    375 
    376 #. Task deletion
    377 
    378 #. Task context switch
    379 
    380 #. Post task context switch
    381 
    382 #. Task begins to execute
    383 
    384 At the following system events, the extensions are invoked in reverse order:
    385 
    386 #. Task deletion
    387 
    388 #. Fatal error detection
     132The extensions are invoked in either `forward` or `reverse` order.  In forward
     133order the initial extensions are invoked before the dynamic extensions.  The
     134forward order of initial extensions is defined by the initial extensions table
     135index.  The forward order of dynamic extensions is defined by the order in
     136which the dynamic extensions were created.  The reverse order is defined
     137accordingly.  By invoking the dynamic extensions in this order, extensions can
     138be built upon one another.  At the following system events, the extensions are
     139invoked in `forward` order
     140
     141- thread creation,
     142
     143- thread start,
     144
     145- thread restart,
     146
     147- thread switch,
     148
     149- thread begin,
     150
     151- thread exitted (return from thread entry function), and
     152
     153- fatal error detection.
     154
     155At the following system events, the extensions are invoked in `reverse` order:
     156
     157- thread termination, and
     158
     159- thread deletion.
    389160
    390161At these system events, the extensions are invoked in reverse order to insure
    391162that if an extension set is built upon another, the more complicated extension
    392 is invoked before the extension set it is built upon.  For example, by invoking
    393 the static extension set last it is known that the "system" fatal error
    394 extension will be the last fatal error extension executed.  Another example is
    395 use of the task delete extension by the Standard C Library.  Extension sets
    396 which are installed after the Standard C Library will operate correctly even if
    397 they utilize the C Library because the C Library's ``TASK_DELETE`` extension is
     163is invoked before the extension set it is built upon.  An example is use of the
     164thread delete extension by the Standard C Library.  Extension sets which are
     165installed after the Standard C Library will operate correctly even if they
     166utilize the C Library because the C Library's thread delete extension is
    398167invoked after that of the other extensions.
    399168
    400 Operations
    401 ==========
    402 
    403 Creating an Extension Set
    404 -------------------------
    405 
    406 The ``rtems_extension_create`` directive creates and installs an extension set
    407 by allocating a Extension Set Control Block (ESCB), assigning the extension set
    408 a user-specified name, and assigning it an extension set ID.  Newly created
    409 extension sets are immediately installed and are invoked upon the next system
    410 even supporting an extension.
    411 
    412 Obtaining Extension Set IDs
    413 ---------------------------
    414 
    415 When an extension set is created, RTEMS generates a unique extension set ID and
    416 assigns it to the created extension set until it is deleted.  The extension ID
    417 may be obtained by either of two methods.  First, as the result of an
    418 invocation of the ``rtems_extension_create`` directive, the extension set ID is
    419 stored in a user provided location.  Second, the extension set ID may be
    420 obtained later using the ``rtems_extension_ident`` directive.  The extension
    421 set ID is used by other directives to manipulate this extension set.
    422 
    423 Deleting an Extension Set
    424 -------------------------
    425 
    426 The ``rtems_extension_delete`` directive is used to delete an extension set.
    427 The extension set's control block is returned to the ESCB free list when it is
    428 deleted.  An extension set can be deleted by a task other than the task which
    429 created the extension set.  Any subsequent references to the extension's name
    430 and ID are invalid.
     169Thread Create Extension
     170-----------------------
     171
     172The thread create extension is invoked during thread creation, for example
     173via :ref:`rtems_task_create() <rtems_task_create>` or :c:func:`pthread_create`.
     174The thread create extension is defined as follows.
     175
     176.. index:: rtems_task_create_extension
     177
     178.. code-block:: c
     179
     180    typedef bool ( *rtems_task_create_extension )(
     181      rtems_tcb *executing,
     182      rtems_tcb *created
     183    );
     184
     185The :c:data:`executing` is a pointer to the TCB of the currently executing
     186thread.  The :c:data:`created` is a pointer to the TCB of the created thread.
     187The created thread is completely initialized with respect to the operating
     188system.
     189
     190The executing thread is the owner of the allocator mutex except during creation
     191of the idle threads.  Since the allocator mutex allows nesting the normal
     192memory allocation routines can be used.
     193
     194A thread create user extension will frequently attempt to allocate resources.
     195If this allocation fails, then the extension must return :c:data:`false` and
     196the entire thread create operation will fail, otherwise it must return
     197:c:data:`true`.
     198
     199This extension is invoked in forward order with thread dispatching enabled
     200(except during system initialization).
     201
     202Thread Start Extension
     203----------------------
     204
     205The thread start extension is invoked during a thread start, for example
     206via :ref:`rtems_task_start() <rtems_task_start>` or :c:func:`pthread_create`.
     207The thread start extension is defined as follows.
     208
     209.. index:: rtems_task_start_extension
     210
     211.. code-block:: c
     212
     213    typedef void ( *rtems_task_start_extension )(
     214      rtems_tcb *executing,
     215      rtems_tcb *started
     216    );
     217
     218The :c:data:`executing` is a pointer to the TCB of the currently executing
     219thread.  The :c:data:`started` is a pointer to the TCB of the started thread.
     220It is invoked after the environment of the started thread has been loaded and the
     221started thread has been made ready.  So, in SMP configurations, the thread may
     222already run on another processor before the thread start extension is actually
     223invoked.
     224
     225This extension is invoked in forward order with thread dispatching disabled.
     226
     227Thread Restart Extension
     228------------------------
     229
     230The thread restart extension is invoked during a thread restart, for example
     231via :ref:`rtems_task_restart() <rtems_task_start>`.
     232The thread restart extension is defined as follows.
     233
     234.. index:: rtems_task_restart_extension
     235
     236.. code-block:: c
     237
     238    typedef void ( *rtems_task_restart_extension )(
     239      rtems_tcb *executing,
     240      rtems_tcb *restarted
     241    );
     242
     243Both :c:data:`executing` and :c:data:`restarted` are pointers the TCB of the
     244currently executing thread.  It is invoked in the context of the executing
     245thread right before the execution context is reloaded.  The thread stack
     246reflects the previous execution context.
     247
     248This extension is invoked in forward order with thread dispatching enabled
     249(except during system initialization).  The thread life is protected.  Thread
     250restart and delete requests issued by restart extensions lead to recursion.
     251
     252Thread Switch Extension
     253-----------------------
     254
     255The thread switch extension is invoked before the context switch from the
     256currently executing thread to the heir thread.  The thread switch extension is
     257defined as follows.
     258
     259.. index:: rtems_task_switch_extension
     260
     261.. code-block:: c
     262
     263    typedef void ( *rtems_task_switch_extension )(
     264      rtems_tcb *executing,
     265      rtems_tcb *heir
     266    );
     267
     268The :c:data:`executing` is a pointer to the TCB of the currently executing
     269thread.  The :c:data:`heir` is a pointer to the TCB of the heir thread.
     270
     271This extension is invoked in forward order with thread dispatching disabled.
     272In SMP configurations, interrupts are disabled and the per-processor SMP lock
     273is owned.
     274
     275The context switches initiated through the multitasking start are not covered
     276by this extension.
     277
     278Thread Begin Extension
     279----------------------
     280
     281The thread begin extension is invoked during a thread begin before the thread
     282entry function is called.  The thread begin extension is defined as follows.
     283
     284.. index:: rtems_task_begin_extension
     285
     286.. code-block:: c
     287
     288    typedef void ( *rtems_task_begin_extension )(
     289      rtems_tcb *executing
     290    );
     291
     292The :c:data:`executing` is a pointer to the TCB of the currently executing
     293thread.  The thread begin extension executes in a normal thread context and may
     294allocate resources for the thread.  In particular it has access to thread-local
     295storage of the thread.
     296
     297This extension is invoked in forward order with thread dispatching enabled.
     298The thread switch extension may be called multiple times for this thread before
     299the thread begin extension is invoked.
     300
     301Thread Exitted Extension
     302------------------------
     303
     304The thread exitted extension is invoked once the thread entry function returns.
     305The thread exitted extension is defined as follows.
     306
     307.. index:: rtems_task_exitted_extension
     308
     309.. code-block:: c
     310
     311    typedef void ( *rtems_task_exitted_extension )(
     312      rtems_tcb *executing
     313    );
     314
     315The :c:data:`executing` is a pointer to the TCB of the currently executing
     316thread.
     317
     318This extension is invoked in forward order with thread dispatching enabled.
     319
     320Thread Termination Extension
     321----------------------------
     322
     323The thread termination extension is invoked in case a termination request is
     324recognized by the currently executing thread.  Termination requests may result
     325due to calls of :ref:`rtems_task_delete() <rtems_task_delete>`,
     326:c:func:`pthread_exit`, or :c:func:`pthread_cancel`.  The thread termination
     327extension is defined as follows.
     328
     329.. index:: rtems_task_terminate_extension
     330
     331.. code-block:: c
     332
     333    typedef void ( *rtems_task_terminate_extension )(
     334      rtems_tcb *executing
     335    );
     336
     337The :c:data:`executing` is a pointer to the TCB of the currently executing
     338thread.
     339
     340It is invoked in the context of the terminated thread right before the
     341thread dispatch to the heir thread.  The POSIX cleanup and key destructors
     342execute in this context.  The thread termination extension has access to
     343thread-local storage and thread-specific data of POSIX keys.
     344
     345This extension is invoked in reverse order with thread dispatching enabled.
     346The thread life is protected.  Thread restart and delete requests issued by
     347terminate extensions lead to recursion.
     348
     349Thread Delete Extension
     350-----------------------
     351
     352The thread delete extension is invoked in case a zombie thread is killed.  A
     353thread becomes a zombie thread after it terminated.  The thread delete
     354extension is defined as follows.
     355
     356.. index:: rtems_task_delete_extension
     357
     358.. code-block:: c
     359
     360    typedef void ( *rtems_task_delete_extension )(
     361      rtems_tcb *executing,
     362      rtems_tcb *deleted
     363    );
     364
     365The :c:data:`executing` is a pointer to the TCB of the currently executing
     366thread.  The :c:data:`deleted` is a pointer to the TCB of the deleted thread.
     367The :c:data:`executing` and :c:data:`deleted` pointers are never equal.
     368
     369The executing thread is the owner of the allocator mutex.  Since the allocator
     370mutex allows nesting the normal memory allocation routines can be used.
     371
     372This extension is invoked in reverse order with thread dispatching enabled.
     373
     374Please note that a thread delete extension is not immediately invoked with a
     375call to :ref:`rtems_task_delete() <rtems_task_delete>` or similar.  The thread
     376must first terminate and this may take some time.  The thread delete extension
     377is invoked by :ref:`rtems_task_create() <rtems_task_create>` or similar as a
     378result of a lazy garbage collection of zombie threads.
     379
     380Fatal Error Extension
     381---------------------
     382
     383The fatal error extension is invoked during :ref:`system termination
     384<Terminate>`.  The fatal error extension is defined as follows.
     385
     386.. index:: rtems_fatal_extension
     387
     388.. code-block:: c
     389
     390    typedef void( *rtems_fatal_extension )(
     391      rtems_fatal_source source,
     392      bool               always_set_to_false,
     393      rtems_fatal_code   code
     394    );
     395
     396The :c:data:`source` parameter is the fatal source indicating the subsystem the
     397fatal condition originated in.  The :c:data:`always_set_to_false` parameter is
     398always set to :c:data:`false` and provided only for backward compatibility
     399reasons.  The :c:data:`code` parameter is the fatal error code.  This value
     400must be interpreted with respect to the source.
     401
     402This extension is invoked in forward order.
     403
     404It is strongly advised to use initial extensions to install a fatal error
     405extension.  Usually, the initial extensions of board support package provides a
     406fatal error extension which resets the board.  In this case, the dynamic fatal
     407error extensions are not invoked.
    431408
    432409Directives
     
    452429
    453430        rtems_status_code rtems_extension_create(
    454             rtems_name              name,
    455             rtems_extensions_table *table,
    456             rtems_id               *id
     431          rtems_name                    name,
     432          const rtems_extensions_table *table,
     433          rtems_id                     *id
    457434        );
    458435
     
    469446
    470447DESCRIPTION:
    471     This directive creates a extension set.  The assigned extension set id is
    472     returned in id.  This id is used to access the extension set with other
    473     user extension manager directives.  For control and maintenance of the
    474     extension set, RTEMS allocates an ESCB from the local ESCB free pool and
    475     initializes it.
     448
     449    This directive creates an extension set.  The assigned extension set
     450    identifier is returned in :c:data:`id`.  This identifier is used to access
     451    the extension set with other user extension manager directives.  For
     452    control and maintenance of the extension set, RTEMS allocates an Extension
     453    Set Control Block (ESCB) from the local ESCB free pool and initializes it.
     454    The user-specified :c:data:`name` is assigned to the ESCB and may be used
     455    to identify the extension set via :ref:`rtems_extension_ident()
     456    <rtems_extension_ident>`.  The extension set specified by :c:data:`table`
     457    is copied to the ESCB.
    476458
    477459NOTES:
     
    495477
    496478        rtems_status_code rtems_extension_ident(
    497             rtems_name  name,
    498             rtems_id   *id
     479          rtems_name  name,
     480          rtems_id   *id
    499481        );
    500482
     
    509491
    510492DESCRIPTION:
    511     This directive obtains the extension set id associated with the extension
    512     set name to be acquired.  If the extension set name is not unique, then the
    513     extension set id will match one of the extension sets with that name.
    514     However, this extension set id is not guaranteed to correspond to the
    515     desired extension set.  The extension set id is used to access this
     493    This directive obtains the extension set identifier associated with the
     494    extension set :c:data:`name` to be acquired and returns it in :c:data:`id`.
     495    If the extension set name is not unique, then the extension set identifier
     496    will match one of the extension sets with that name.  However, this
     497    extension set identifier is not guaranteed to correspond to the desired
     498    extension set.  The extension set identifier is used to access this
    516499    extension set in other extension set related directives.
    517500
     
    547530
    548531DESCRIPTION:
    549     This directive deletes the extension set specified by ``id``.  If the
     532    This directive deletes the extension set specified by :c:data:`id`.  If the
    550533    extension set is running, it is automatically canceled.  The ESCB for the
    551534    deleted extension set is reclaimed by RTEMS.
     
    556539    A extension set can be deleted by a task other than the task which created
    557540    the extension set.
    558 
    559 NOTES:
    560     This directive will not cause the running task to be preempted.
Note: See TracChangeset for help on using the changeset viewer.