Changeset 6eef7a4 in rtems-docs


Ignore:
Timestamp:
Aug 24, 2017, 7:56:37 AM (23 months ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
master
Children:
873ba80
Parents:
b6977f7
git-author:
Sebastian Huber <sebastian.huber@…> (08/24/17 07:56:37)
git-committer:
Sebastian Huber <sebastian.huber@…> (08/24/17 07:57:21)
Message:

c-user: Clarify user extensions

Close #2367.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • c-user/user_extensions.rst

    rb6977f7 r6eef7a4  
    2929==========
    3030
    31 User extensions are invoked when the following system events occur
     31User extensions (call-back functions) are invoked by the system when the
     32following events occur
    3233
    3334- thread creation,
     
    4950- fatal error detection (system termination).
    5051
    51 The extensions have event-specific arguments, invocation orders and execution
    52 contexts.  Extension sets can be installed at run-time via
     52The user extensions have event-specific arguments, invocation orders and
     53execution contexts.  Extension sets can be installed at run-time via
    5354:ref:`rtems_extension_create() <rtems_extension_create>` (dynamic extension
    5455sets) or at link-time via the application configuration option
     
    5657extension sets).
    5758
    58 The execution context of extensions varies.  Some extensions are invoked with
    59 ownership of the allocator mutex.  The allocator mutex protects dynamic memory
    60 allocations and object creation/deletion.  Some extensions are invoked with
    61 thread dispatching disabled.  The fatal error extension is invoked in an
    62 arbitrary context.
     59The execution context of user extensions varies.  Some user extensions are
     60invoked with ownership of the allocator mutex.  The allocator mutex protects
     61dynamic memory allocations and object creation/deletion.  Some user extensions
     62are invoked with thread dispatching disabled.  The fatal error extension is
     63invoked in an arbitrary context.
    6364
    6465Extension Sets
     
    6768.. index:: rtems_extensions_table
    6869
    69 User extensions are maintained as a set.  All extensions are optional and may
    70 be `NULL`.  Together a set of these extensions typically performs a specific
    71 functionality such as performance monitoring or debugger support.  The user
     70User extensions are maintained as a set.  All user extensions are optional and
     71may be `NULL`.  Together a set of these user extensions typically performs a
     72specific functionality such as performance monitoring or debugger support.  The
    7273extension set is defined via the following structure.
    7374
     
    130131-------------------
    131132
    132 The extensions are invoked in either `forward` or `reverse` order.  In forward
    133 order the initial extensions are invoked before the dynamic extensions.  The
    134 forward order of initial extensions is defined by the initial extensions table
    135 index.  The forward order of dynamic extensions is defined by the order in
    136 which the dynamic extensions were created.  The reverse order is defined
    137 accordingly.  By invoking the dynamic extensions in this order, extensions can
    138 be built upon one another.  At the following system events, the extensions are
    139 invoked in `forward` order
     133The user extensions are invoked in either `forward` or `reverse` order.  In
     134forward order, the user extensions of initial extension sets are invoked before
     135the user extensions of the dynamic extension sets.  The forward order of
     136initial extension sets is defined by the initial extension sets table index.
     137The forward order of dynamic extension sets is defined by the order in which
     138the dynamic extension sets were created.  The reverse order is defined
     139accordingly.  By invoking the user extensions in this order, extensions can be
     140built upon one another.  At the following system events, the user extensions
     141are invoked in `forward` order
    140142
    141143- thread creation,
     
    153155- fatal error detection.
    154156
    155 At the following system events, the extensions are invoked in `reverse` order:
     157At the following system events, the user extensions are invoked in `reverse`
     158order:
    156159
    157160- thread termination, and
     
    159162- thread deletion.
    160163
    161 At these system events, the extensions are invoked in reverse order to insure
    162 that if an extension set is built upon another, the more complicated extension
    163 is invoked before the extension set it is built upon.  An example is use of the
     164At these system events, the user extensions are invoked in reverse order to insure
     165that if an extension set is built upon another, the more complicated user extension
     166is invoked before the user extension it is built upon.  An example is use of the
    164167thread delete extension by the Standard C Library.  Extension sets which are
    165168installed after the Standard C Library will operate correctly even if they
    166169utilize the C Library because the C Library's thread delete extension is
    167 invoked after that of the other extensions.
     170invoked after that of the other thread delete extensions.
    168171
    169172Thread Create Extension
     
    192195memory allocation routines can be used.
    193196
    194 A thread create user extension will frequently attempt to allocate resources.
    195 If this allocation fails, then the extension must return :c:data:`false` and
    196 the entire thread create operation will fail, otherwise it must return
    197 :c:data:`true`.
    198 
    199 This extension is invoked in forward order with thread dispatching enabled
    200 (except during system initialization).
     197A thread create extension will frequently attempt to allocate resources.  If
     198this allocation fails, then the thread create extension must return
     199:c:data:`false` and the entire thread create operation will fail, otherwise it
     200must return :c:data:`true`.
     201
     202The thread create extension is invoked in forward order with thread dispatching
     203enabled (except during system initialization).
    201204
    202205Thread Start Extension
     
    223226invoked.
    224227
    225 This extension is invoked in forward order with thread dispatching disabled.
     228The thread start extension is invoked in forward order with thread dispatching
     229disabled.
    226230
    227231Thread Restart Extension
     
    246250reflects the previous execution context.
    247251
    248 This extension is invoked in forward order with thread dispatching enabled
    249 (except during system initialization).  The thread life is protected.  Thread
    250 restart and delete requests issued by restart extensions lead to recursion.
     252The thread restart extension is invoked in forward order with thread
     253dispatching enabled (except during system initialization).  The thread life is
     254protected.  Thread restart and delete requests issued by thread restart
     255extensions lead to recursion.
    251256
    252257Thread Switch Extension
     
    269274thread.  The :c:data:`heir` is a pointer to the TCB of the heir thread.
    270275
    271 This extension is invoked in forward order with thread dispatching disabled.
    272 In SMP configurations, interrupts are disabled and the per-processor SMP lock
    273 is owned.
     276The thread switch extension is invoked in forward order with thread dispatching
     277disabled.  In SMP configurations, interrupts are disabled and the per-processor
     278SMP lock is owned.
    274279
    275280The context switches initiated through the multitasking start are not covered
    276 by this extension.
     281by the thread switch extension.
    277282
    278283Thread Begin Extension
     
    295300storage of the thread.
    296301
    297 This extension is invoked in forward order with thread dispatching enabled.
    298 The thread switch extension may be called multiple times for this thread before
    299 the thread begin extension is invoked.
     302The thread begin extension is invoked in forward order with thread dispatching
     303enabled.  The thread switch extension may be called multiple times for this
     304thread before the thread begin extension is invoked.
    300305
    301306Thread Exitted Extension
     
    343348thread-local storage and thread-specific data of POSIX keys.
    344349
    345 This extension is invoked in reverse order with thread dispatching enabled.
    346 The thread life is protected.  Thread restart and delete requests issued by
    347 terminate extensions lead to recursion.
     350The thread terminate extension is invoked in reverse order with thread
     351dispatching enabled.  The thread life is protected.  Thread restart and delete
     352requests issued by thread terminate extensions lead to recursion.
    348353
    349354Thread Delete Extension
     
    370375mutex allows nesting the normal memory allocation routines can be used.
    371376
    372 This extension is invoked in reverse order with thread dispatching enabled.
     377The thread delete extension is invoked in reverse order with thread dispatching
     378enabled.
    373379
    374380Please note that a thread delete extension is not immediately invoked with a
     
    400406must be interpreted with respect to the source.
    401407
    402 This extension is invoked in forward order.
    403 
    404 It is strongly advised to use initial extensions to install a fatal error
    405 extension.  Usually, the initial extensions of board support package provides a
    406 fatal error extension which resets the board.  In this case, the dynamic fatal
    407 error extensions are not invoked.
     408The fatal error extension is invoked in forward order.
     409
     410It is strongly advised to use initial extension sets to install a fatal error
     411extension.  Usually, the initial extension set of board support package
     412provides a fatal error extension which resets the board.  In this case, the
     413dynamic fatal error extensions are not invoked.
    408414
    409415Directives
     
    447453DESCRIPTION:
    448454
    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.
     455    This directive creates an extension set object and initializes it using the
     456    specified extension set table.  The assigned extension set identifier is
     457    returned in :c:data:`id`.  This identifier is used to access the extension
     458    set with other user extension manager directives.  For control and
     459    maintenance of the extension set, RTEMS allocates an Extension Set Control
     460    Block (ESCB) from the local ESCB free pool and initializes it.  The
     461    user-specified :c:data:`name` is assigned to the ESCB and may be used to
     462    identify the extension set via
     463    :ref:`rtems_extension_ident() <rtems_extension_ident>`.  The extension set
     464    specified by :c:data:`table` is copied to the ESCB.
    458465
    459466NOTES:
Note: See TracChangeset for help on using the changeset viewer.