source: rtems-docs/c_user/user_extensions.rst @ 9aafb39

4.115
Last change on this file since 9aafb39 was 9aafb39, checked in by Chris Johns <chrisj@…>, on 10/28/16 at 12:56:02

c_user: Remove errors and warnings.

  • Property mode set to 100644
File size: 19.6 KB
RevLine 
[489740f]1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
[8ef6ea8]3.. COMMENT: COPYRIGHT (c) 1988-2008.
4.. COMMENT: On-Line Applications Research Corporation (OAR).
5.. COMMENT: All rights reserved.
6
[9aafb39]7.. _User Extensions Manager:
8
[fd6dc8c8]9User Extensions Manager
10#######################
11
12.. index:: user extensions
13
14Introduction
15============
16
[8ef6ea8]17The RTEMS User Extensions Manager allows the application developer to augment
18the executive by allowing them to supply extension routines which are invoked
19at critical system events.  The directives provided by the user extensions
[fd6dc8c8]20manager are:
21
[8ef6ea8]22- rtems_extension_create_ - Create an extension set
[fd6dc8c8]23
[8ef6ea8]24- rtems_extension_ident_ - Get ID of an extension set
[fd6dc8c8]25
[8ef6ea8]26- rtems_extension_delete_ - Delete an extension set
[fd6dc8c8]27
28Background
29==========
30
[8ef6ea8]31User extension routines are invoked when the following system events occur:
[fd6dc8c8]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
[8ef6ea8]51These extensions are invoked as a function with arguments that are appropriate
52to the system event.
[fd6dc8c8]53
54Extension Sets
55--------------
56.. index:: extension set
57
[8ef6ea8]58An extension set is defined as a set of routines which are invoked at each of
59the critical system events at which user extension routines are invoked.
60Together a set of these routines typically perform a specific functionality
61such as performance monitoring or debugger support.  RTEMS is informed of the
62entry points which constitute an extension set via the following
63structure:.. index:: rtems_extensions_table
[fd6dc8c8]64
[25d55d4]65.. code-block:: c
[fd6dc8c8]66
67    typedef struct {
[8ef6ea8]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;
[fd6dc8c8]76    } rtems_extensions_table;
77
[8ef6ea8]78RTEMS allows the user to have multiple extension sets active at the same time.
79First, a single static extension set may be defined as the application's User
80Extension Table which is included as part of the Configuration Table.  This
81extension set is active for the entire life of the system and may not be
82deleted.  This extension set is especially important because it is the only way
83the application can provided a FATAL error extension which is invoked if RTEMS
84fails during the initialize_executive directive.  The static extension set is
85optional and may be configured as NULL if no static extension set is required.
86
87Second, the user can install dynamic extensions using the
88``rtems_extension_create`` directive.  These extensions are RTEMS objects in
89that they have a name, an ID, and can be dynamically created and deleted.  In
90contrast to the static extension set, these extensions can only be created and
91installed after the initialize_executive directive successfully completes
92execution.  Dynamic extensions are useful for encapsulating the functionality
93of an extension set.  For example, the application could use extensions to
94manage a special coprocessor, do performance monitoring, and to do stack bounds
95checking.  Each of these extension sets could be written and installed
[fd6dc8c8]96independently of the others.
97
[8ef6ea8]98All user extensions are optional and RTEMS places no naming restrictions on the
99user. The user extension entry points are copied into an internal RTEMS
100structure. This means the user does not need to keep the table after creating
101it, and changing the handler entry points dynamically in a table once created
102has no effect. Creating a table local to a function can save space in space
103limited applications.
[fd6dc8c8]104
[8ef6ea8]105Extension switches do not effect the context switch overhead if no switch
106handler is installed.
[fd6dc8c8]107
108TCB Extension Area
109------------------
110.. index:: TCB extension area
111
[8ef6ea8]112RTEMS provides for a pointer to a user-defined data area for each extension set
113to be linked to each task's control block.  This set of pointers is an
114extension of the TCB and can be used to store additional data required by the
115user's extension functions.
[fd6dc8c8]116
[8ef6ea8]117The TCB extension is an array of pointers in the TCB. The index into the table
118can be obtained from the extension id returned when the extension is
119created:
120
121.. index:: rtems extensions table index
[fd6dc8c8]122
[25d55d4]123.. code-block:: c
[fd6dc8c8]124
125    index = rtems_object_id_get_index(extension_id);
126
[8ef6ea8]127The number of pointers in the area is the same as the number of user extension
128sets configured.  This allows an application to augment the TCB with
129user-defined information.  For example, an application could implement task
130profiling by storing timing statistics in the TCB's extended memory area.  When
131a task context switch is being executed, the ``TASK_SWITCH`` extension could
132read a real-time clock to calculate how long the task being swapped out has run
133as well as timestamp the starting time for the task being swapped in.
134
135If used, the extended memory area for the TCB should be allocated and the TCB
136extension pointer should be set at the time the task is created or started by
137either the ``TASK_CREATE`` or ``TASK_START`` extension.  The application is
138responsible for managing this extended memory area for the TCBs.  The memory
139may be reinitialized by the ``TASK_RESTART`` extension and should be
140deallocated by the ``TASK_DELETE`` extension when the task is deleted.  Since
141the TCB extension buffers would most likely be of a fixed size, the RTEMS
142partition manager could be used to manage the application's extended memory
143area.  The application could create a partition of fixed size TCB extension
144buffers and use the partition manager's allocation and deallocation directives
145to obtain and release the extension buffers.
[fd6dc8c8]146
147Extensions
148----------
149
[8ef6ea8]150The sections that follow will contain a description of each extension.  Each
151section will contain a prototype of a function with the appropriate calling
152sequence for the corresponding extension.  The names given for the C function
153and its arguments are all defined by the user.  The names used in the examples
154were arbitrarily chosen and impose no naming conventions on the user.
[fd6dc8c8]155
156TASK_CREATE Extension
157~~~~~~~~~~~~~~~~~~~~~
158
[8ef6ea8]159The TASK_CREATE extension directly corresponds to the ``rtems_task_create``
160directive.  If this extension is defined in any static or dynamic extension set
161and a task is being created, then the extension routine will automatically be
162invoked by RTEMS.  The extension should have a prototype similar to the
163following:
164
165.. index:: rtems_task_create_extension
[fd6dc8c8]166.. index:: rtems_extension
167
[25d55d4]168.. code-block:: c
[fd6dc8c8]169
170    bool user_task_create(
[8ef6ea8]171       rtems_tcb *current_task,
172       rtems_tcb *new_task
[fd6dc8c8]173    );
174
[8ef6ea8]175where ``current_task`` can be used to access the TCB for the currently
176executing task, and new_task can be used to access the TCB for the new task
177being created.  This extension is invoked from the ``rtems_task_create``
178directive after ``new_task`` has been completely initialized, but before it is
179placed on a ready TCB chain.
[fd6dc8c8]180
[8ef6ea8]181The user extension is expected to return the boolean value ``true`` if it
182successfully executed and ``false`` otherwise.  A task create user extension
183will frequently attempt to allocate resources.  If this allocation fails, then
184the extension should return ``false`` and the entire task create operation will
185fail.
[fd6dc8c8]186
187TASK_START Extension
188~~~~~~~~~~~~~~~~~~~~
189
[8ef6ea8]190The ``TASK_START`` extension directly corresponds to the task_start directive.
191If this extension is defined in any static or dynamic extension set and a task
192is being started, then the extension routine will automatically be invoked by
193RTEMS.  The extension should have a prototype similar to the following:
194
195.. index:: rtems_task_start_extension
[fd6dc8c8]196
[25d55d4]197.. code-block:: c
[fd6dc8c8]198
199    void user_task_start(
[8ef6ea8]200        rtems_tcb *current_task,
201        rtems_tcb *started_task
[fd6dc8c8]202    );
203
[8ef6ea8]204where current_task can be used to access the TCB for the currently executing
205task, and started_task can be used to access the TCB for the dormant task being
206started. This extension is invoked from the task_start directive after
207started_task has been made ready to start execution, but before it is placed on
208a ready TCB chain.
[fd6dc8c8]209
210TASK_RESTART Extension
211~~~~~~~~~~~~~~~~~~~~~~
212
[8ef6ea8]213The ``TASK_RESTART`` extension directly corresponds to the task_restart
214directive.  If this extension is defined in any static or dynamic extension set
215and a task is being restarted, then the extension should have a prototype
216similar to the following:
217
218.. index:: rtems_task_restart_extension
[fd6dc8c8]219
[25d55d4]220.. code-block:: c
[fd6dc8c8]221
222    void user_task_restart(
[8ef6ea8]223        rtems_tcb *current_task,
224        rtems_tcb *restarted_task
[fd6dc8c8]225    );
226
[8ef6ea8]227where current_task can be used to access the TCB for the currently executing
228task, and restarted_task can be used to access the TCB for the task being
229restarted. This extension is invoked from the task_restart directive after
230restarted_task has been made ready to start execution, but before it is placed
231on a ready TCB chain.
[fd6dc8c8]232
233TASK_DELETE Extension
234~~~~~~~~~~~~~~~~~~~~~
235
[8ef6ea8]236The ``TASK_DELETE`` extension is associated with the task_delete directive.  If
237this extension is defined in any static or dynamic extension set and a task is
238being deleted, then the extension routine will automatically be invoked by
[fd6dc8c8]239RTEMS.  The extension should have a prototype similar to the
[8ef6ea8]240following:
241
242.. index:: rtems_task_delete_extension
[fd6dc8c8]243
[25d55d4]244.. code-block:: c
[fd6dc8c8]245
246    void user_task_delete(
[8ef6ea8]247        rtems_tcb *current_task,
248        rtems_tcb *deleted_task
[fd6dc8c8]249    );
250
[8ef6ea8]251where current_task can be used to access the TCB for the currently executing
252task, and deleted_task can be used to access the TCB for the task being
253deleted. This extension is invoked from the task_delete directive after the TCB
254has been removed from a ready TCB chain, but before all its resources including
255the TCB have been returned to their respective free pools.  This extension
256should not call any RTEMS directives if a task is deleting itself (current_task
257is equal to deleted_task).
[fd6dc8c8]258
259TASK_SWITCH Extension
260~~~~~~~~~~~~~~~~~~~~~
261
[8ef6ea8]262The ``TASK_SWITCH`` extension corresponds to a task context switch.  If this
263extension is defined in any static or dynamic extension set and a task context
264switch is in progress, then the extension routine will automatically be invoked
265by RTEMS.  The extension should have a prototype similar to the following:
266
267.. index:: rtems_task_switch_extension
[fd6dc8c8]268
[25d55d4]269.. code-block:: c
[fd6dc8c8]270
271    void user_task_switch(
[8ef6ea8]272        rtems_tcb *current_task,
273        rtems_tcb *heir_task
[fd6dc8c8]274    );
275
[8ef6ea8]276where current_task can be used to access the TCB for the task that is being
277swapped out, and heir_task can be used to access the TCB for the task being
278swapped in.  This extension is invoked from RTEMS' dispatcher routine after the
279current_task context has been saved, but before the heir_task context has been
280restored.  This extension should not call any RTEMS directives.
[fd6dc8c8]281
282TASK_BEGIN Extension
283~~~~~~~~~~~~~~~~~~~~
284
[8ef6ea8]285The ``TASK_BEGIN`` extension is invoked when a task begins execution.  It is
286invoked immediately before the body of the starting procedure and executes in
287the context in the task.  This user extension have a prototype similar to the
288following:
289
290.. index:: rtems_task_begin_extension
[fd6dc8c8]291
[25d55d4]292.. code-block:: c
[fd6dc8c8]293
294    void user_task_begin(
[8ef6ea8]295        rtems_tcb *current_task
[fd6dc8c8]296    );
297
[8ef6ea8]298where current_task can be used to access the TCB for the currently executing
299task which has begun.  The distinction between the ``TASK_BEGIN`` and
300TASK_START extension is that the ``TASK_BEGIN`` extension is executed in the
301context of the actual task while the TASK_START extension is executed in the
302context of the task performing the task_start directive.  For most extensions,
303this is not a critical distinction.
[fd6dc8c8]304
305TASK_EXITTED Extension
306~~~~~~~~~~~~~~~~~~~~~~
307
[8ef6ea8]308The ``TASK_EXITTED`` extension is invoked when a task exits the body of the
309starting procedure by either an implicit or explicit return statement.  This
310user extension have a prototype similar to the following:
311
312.. index:: rtems_task_exitted_extension
[fd6dc8c8]313
[25d55d4]314.. code-block:: c
[fd6dc8c8]315
316    void user_task_exitted(
[8ef6ea8]317        rtems_tcb *current_task
[fd6dc8c8]318    );
319
[8ef6ea8]320where current_task can be used to access the TCB for the currently executing
321task which has just exitted.
[fd6dc8c8]322
[8ef6ea8]323Although exiting of task is often considered to be a fatal error, this
324extension allows recovery by either restarting or deleting the exiting task.
325If the user does not wish to recover, then a fatal error may be reported.  If
326the user does not provide a ``TASK_EXITTED`` extension or the provided handler
327returns control to RTEMS, then the RTEMS default handler will be used.  This
328default handler invokes the directive fatal_error_occurred with the
329``RTEMS_TASK_EXITTED`` directive status.
[fd6dc8c8]330
331FATAL Error Extension
332~~~~~~~~~~~~~~~~~~~~~
333
[8ef6ea8]334The ``FATAL`` error extension is associated with the fatal_error_occurred
335directive.  If this extension is defined in any static or dynamic extension set
336and the fatal_error_occurred directive has been invoked, then this extension
337will be called.  This extension should have a prototype similar to the
338following:
339
340.. index:: rtems_fatal_extension
[fd6dc8c8]341
[25d55d4]342.. code-block:: c
[fd6dc8c8]343
344    void user_fatal_error(
[8ef6ea8]345        Internal_errors_Source  the_source,
346        bool                    is_internal,
347        uint32_t                the_error
[fd6dc8c8]348    );
349
[8ef6ea8]350where the_error is the error code passed to the fatal_error_occurred
351directive. This extension is invoked from the fatal_error_occurred directive.
[fd6dc8c8]352
[8ef6ea8]353If defined, the user's ``FATAL`` error extension is invoked before RTEMS'
354default fatal error routine is invoked and the processor is stopped.  For
355example, this extension could be used to pass control to a debugger when a
356fatal error occurs.  This extension should not call any RTEMS directives.
[fd6dc8c8]357
358Order of Invocation
359-------------------
360
[8ef6ea8]361When one of the critical system events occur, the user extensions are invoked
362in either "forward" or "reverse" order.  Forward order indicates that the
363static extension set is invoked followed by the dynamic extension sets in the
364order in which they were created.  Reverse order means that the dynamic
365extension sets are invoked in the opposite of the order in which they were
366created followed by the static extension set.  By invoking the extension sets
367in this order, extensions can be built upon one another.  At the following
368system events, the extensions are invoked in forward order:
[fd6dc8c8]369
[8ef6ea8]370#. Task creation
[fd6dc8c8]371
[8ef6ea8]372#. Task initiation
[fd6dc8c8]373
[8ef6ea8]374#. Task reinitiation
[fd6dc8c8]375
[8ef6ea8]376#. Task deletion
[fd6dc8c8]377
[8ef6ea8]378#. Task context switch
[fd6dc8c8]379
[8ef6ea8]380#. Post task context switch
[fd6dc8c8]381
[8ef6ea8]382#. Task begins to execute
[fd6dc8c8]383
[8ef6ea8]384At the following system events, the extensions are invoked in reverse order:
[fd6dc8c8]385
[8ef6ea8]386#. Task deletion
[fd6dc8c8]387
[8ef6ea8]388#. Fatal error detection
[fd6dc8c8]389
[8ef6ea8]390At these system events, the extensions are invoked in reverse order to insure
391that if an extension set is built upon another, the more complicated extension
392is invoked before the extension set it is built upon.  For example, by invoking
393the static extension set last it is known that the "system" fatal error
394extension will be the last fatal error extension executed.  Another example is
395use of the task delete extension by the Standard C Library.  Extension sets
396which are installed after the Standard C Library will operate correctly even if
397they utilize the C Library because the C Library's ``TASK_DELETE`` extension is
398invoked after that of the other extensions.
[fd6dc8c8]399
400Operations
401==========
402
403Creating an Extension Set
404-------------------------
405
[8ef6ea8]406The ``rtems_extension_create`` directive creates and installs an extension set
407by allocating a Extension Set Control Block (ESCB), assigning the extension set
408a user-specified name, and assigning it an extension set ID.  Newly created
409extension sets are immediately installed and are invoked upon the next system
[fd6dc8c8]410even supporting an extension.
411
412Obtaining Extension Set IDs
413---------------------------
414
[8ef6ea8]415When an extension set is created, RTEMS generates a unique extension set ID and
416assigns it to the created extension set until it is deleted.  The extension ID
417may be obtained by either of two methods.  First, as the result of an
418invocation of the ``rtems_extension_create`` directive, the extension set ID is
419stored in a user provided location.  Second, the extension set ID may be
420obtained later using the ``rtems_extension_ident`` directive.  The extension
421set ID is used by other directives to manipulate this extension set.
[fd6dc8c8]422
423Deleting an Extension Set
424-------------------------
425
[8ef6ea8]426The ``rtems_extension_delete`` directive is used to delete an extension set.
427The extension set's control block is returned to the ESCB free list when it is
428deleted.  An extension set can be deleted by a task other than the task which
429created the extension set.  Any subsequent references to the extension's name
430and ID are invalid.
[fd6dc8c8]431
432Directives
433==========
434
[8ef6ea8]435This section details the user extension manager's directives.  A subsection is
436dedicated to each of this manager's directives and describes the calling
437sequence, related constants, usage, and status codes.
438
439.. _rtems_extension_create:
[fd6dc8c8]440
441EXTENSION_CREATE - Create a extension set
442-----------------------------------------
443.. index:: create an extension set
444
445**CALLING SEQUENCE:**
446
447.. index:: rtems_extension_create
448
[25d55d4]449.. code-block:: c
[fd6dc8c8]450
451    rtems_status_code rtems_extension_create(
[8ef6ea8]452        rtems_name              name,
453        rtems_extensions_table *table,
454        rtems_id               *id
[fd6dc8c8]455    );
456
457**DIRECTIVE STATUS CODES:**
458
[8ef6ea8]459.. list-table::
460 :class: rtems-table
461
462 * - ``RTEMS_SUCCESSFUL``
463   - extension set created successfully
464 * - ``RTEMS_INVALID_NAME``
465   - invalid extension set name
466 * - ``RTEMS_TOO_MANY``
467   - too many extension sets created
[fd6dc8c8]468
469**DESCRIPTION:**
470
[8ef6ea8]471This directive creates a extension set.  The assigned extension set id is
472returned in id.  This id is used to access the extension set with other user
473extension manager directives.  For control and maintenance of the extension
474set, RTEMS allocates an ESCB from the local ESCB free pool and initializes it.
[fd6dc8c8]475
476**NOTES:**
477
478This directive will not cause the calling task to be
479preempted.
480
[8ef6ea8]481.. _rtems_extension_ident:
482
[fd6dc8c8]483EXTENSION_IDENT - Get ID of a extension set
484-------------------------------------------
485.. index:: get ID of an extension set
486.. index:: obtain ID of an extension set
487
488**CALLING SEQUENCE:**
489
490.. index:: rtems_extension_ident
491
[25d55d4]492.. code-block:: c
[fd6dc8c8]493
494    rtems_status_code rtems_extension_ident(
[8ef6ea8]495        rtems_name  name,
496        rtems_id   *id
[fd6dc8c8]497    );
498
499**DIRECTIVE STATUS CODES:**
500
[8ef6ea8]501.. list-table::
502 :class: rtems-table
503
504 * - ``RTEMS_SUCCESSFUL``
505   - extension set identified successfully
506 * - ``RTEMS_INVALID_NAME``
507   - extension set name not found
[fd6dc8c8]508
509**DESCRIPTION:**
510
[8ef6ea8]511This directive obtains the extension set id associated with the extension set
512name to be acquired.  If the extension set name is not unique, then the
513extension set id will match one of the extension sets with that name.  However,
514this extension set id is not guaranteed to correspond to the desired extension
515set.  The extension set id is used to access this extension set in other
516extension set related directives.
[fd6dc8c8]517
518**NOTES:**
519
[8ef6ea8]520This directive will not cause the running task to be preempted.
521
522.. _rtems_extension_delete:
[fd6dc8c8]523
524EXTENSION_DELETE - Delete a extension set
525-----------------------------------------
526.. index:: delete an extension set
527
528**CALLING SEQUENCE:**
529
530.. index:: rtems_extension_delete
531
[25d55d4]532.. code-block:: c
[fd6dc8c8]533
534    rtems_status_code rtems_extension_delete(
[8ef6ea8]535        rtems_id id
[fd6dc8c8]536    );
537
538**DIRECTIVE STATUS CODES:**
539
[8ef6ea8]540.. list-table::
541 :class: rtems-table
542
543 * - ``RTEMS_SUCCESSFUL``
544   - extension set deleted successfully
545 * - ``RTEMS_INVALID_ID``
546   - invalid extension set id
[fd6dc8c8]547
548**DESCRIPTION:**
549
[8ef6ea8]550This directive deletes the extension set specified by ``id``.  If the extension
551set is running, it is automatically canceled.  The ESCB for the deleted
552extension set is reclaimed by RTEMS.
[fd6dc8c8]553
554**NOTES:**
555
[8ef6ea8]556This directive will not cause the running task to be preempted.
[fd6dc8c8]557
[8ef6ea8]558A extension set can be deleted by a task other than the task which created the
559extension set.
[fd6dc8c8]560
561**NOTES:**
562
[8ef6ea8]563This directive will not cause the running task to be preempted.
Note: See TracBrowser for help on using the repository browser.