source: rtems/doc/user/userext.t @ b5c5bbcf

4.104.114.84.95
Last change on this file since b5c5bbcf was b5c5bbcf, checked in by Joel Sherrill <joel.sherrill@…>, on Apr 13, 2002 at 4:47:23 PM

2002-04-12 Chris Johns <ccj@…>

  • doc/user/userext.t: Per PR138, updated the documentation to show how to obtain an extension table index. Also provided some extra background on the user extension API.
  • Property mode set to 100644
File size: 21.9 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2002.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter User Extensions Manager
10
11@cindex user extensions
12
13@section Introduction
14
15The RTEMS User Extensions Manager allows the
16application developer to augment the executive by allowing them
17to supply extension routines which are invoked at critical
18system events.  The directives provided by the user extensions
19manager are:
20
21@itemize @bullet
22@item @code{@value{DIRPREFIX}extension_create} - Create an extension set
23@item @code{@value{DIRPREFIX}extension_ident} - Get ID of an extension set
24@item @code{@value{DIRPREFIX}extension_delete} - Delete an extension set
25@end itemize
26
27@section Background
28
29User extension routines are invoked when the
30following system events occur:
31
32@itemize @bullet
33@item Task creation
34@item Task initiation
35@item Task reinitiation
36@item Task deletion
37@item Task context switch
38@item Post task context switch
39@item Task begin
40@item Task exits
41@item Fatal error detection
42@end itemize
43
44These extensions are invoked as a function with
45arguments that are appropriate to the system event.
46
47@subsection Extension Sets
48
49@cindex extension set
50
51An extension set is defined as a set of routines
52which are invoked at each of the critical system events at which
53user extension routines are invoked.  Together a set of these
54routines typically perform a specific functionality such as
55performance monitoring or debugger support.  RTEMS is informed of
56the entry points which constitute an extension set via the
57following @value{STRUCTURE}:
58
59@findex rtems_extensions_table
60@ifset is-C
61@example
62@group
63typedef struct @{
64  rtems_task_create_extension      thread_create;
65  rtems_task_start_extension       thread_start;
66  rtems_task_restart_extension     thread_restart;
67  rtems_task_delete_extension      thread_delete;
68  rtems_task_switch_extension      thread_switch;
69  rtems_task_begin_extension       thread_begin;
70  rtems_task_exitted_extension     thread_exitted;
71  rtems_fatal_extension            fatal;
72@} rtems_extensions_table;
73@end group
74@end example
75@end ifset
76
77@ifset is-Ada
78@example
79type Extensions_Table is
80   record
81      Task_Create      : RTEMS.Task_Create_Extension;
82      Task_Start       : RTEMS.Task_Start_Extension;
83      Task_Restart     : RTEMS.Task_Restart_Extension;
84      Task_Delete      : RTEMS.Task_Delete_Extension;
85      Task_Switch      : RTEMS.Task_Switch_Extension;
86      Task_Post_Switch : RTEMS.Task_Post_Switch_Extension;
87      Task_Begin       : RTEMS.Task_Begin_Extension;
88      Task_Exitted     : RTEMS.Task_Exitted_Extension;
89      Fatal            : RTEMS.Fatal_Error_Extension;
90   end record;
91@end example
92@end ifset
93
94
95RTEMS allows the user to have multiple extension sets
96active at the same time.  First, a single static extension set
97may be defined as the application's User Extension Table which
98is included as part of the Configuration Table.  This extension
99set is active for the entire life of the system and may not be
100deleted.  This extension set is especially important because it
101is the only way the application can provided a FATAL error
102extension which is invoked if RTEMS fails during the
103initialize_executive directive.  The static extension set is
104optional and may be configured as NULL if no static extension
105set is required.
106
107Second, the user can install dynamic extensions using
108the @code{@value{DIRPREFIX}extension_create}
109directive.  These extensions are RTEMS
110objects in that they have a name, an ID, and can be dynamically
111created and deleted.  In contrast to the static extension set,
112these extensions can only be created and installed after the
113initialize_executive directive successfully completes execution.
114Dynamic extensions are useful for encapsulating the
115functionality of an extension set.  For example, the application
116could use extensions to manage a special coprocessor, do
117performance monitoring, and to do stack bounds checking.  Each
118of these extension sets could be written and installed
119independently of the others.
120
121All user extensions are optional and RTEMS places no
122naming  restrictions on the user. The user extension entry points
123are copied into an internal RTEMS structure. This means the user
124does not need to keep the table after creating it, and changing the
125handler entry points dynamically in a table once created has no
126effect. Creating a table local to a function can save space in
127space limited applications.
128
129Extension switches do not effect the context switch overhead if
130no switch handler is installed.
131
132@subsection TCB Extension Area
133
134@cindex TCB extension area
135
136RTEMS provides for a pointer to a user-defined data
137area for each extension set to be linked to each task's control
138block.  This set of pointers is an extension of the TCB and can
139be used to store additional data required by the user's
140extension functions.  It is also possible for a user extension
141to utilize the notepad locations associated with each task
142although this may conflict with application usage of those
143particular notepads.
144
145The TCB extension is an array of pointers in the TCB. The
146index into the table can be obtained from the extension id
147returned when the extension is created:
148
149@findex rtems extensions table index
150@ifset is-C
151@example
152@group
153index = rtems_get_index(extension_id);
154@end group
155@end example
156@end ifset
157
158@ifset is-Ada
159@example
160There is currently no example for Ada.
161@end example
162@end ifset
163
164The number of pointers in the area is the same as the number of
165user extension sets configured.  This allows an application to
166augment the TCB with user-defined information.  For example, an
167application could implement task profiling by storing timing
168statistics in the TCB's extended memory area.  When a task
169context switch is being executed, the TASK_SWITCH extension
170could read a real-time clock to calculate how long the task
171being swapped out has run as well as timestamp the starting time
172for the task being swapped in.
173
174If used, the extended memory area for the TCB should
175be allocated and the TCB extension pointer should be set at the
176time the task is created or started by either the TASK_CREATE or
177TASK_START extension.  The application is responsible for
178managing this extended memory area for the TCBs.  The memory may
179be reinitialized by the TASK_RESTART extension and should be
180deallocated by the TASK_DELETE extension when the task is
181deleted.  Since the TCB extension buffers would most likely be
182of a fixed size, the RTEMS partition manager could be used to
183manage the application's extended memory area.  The application
184could create a partition of fixed size TCB extension buffers and
185use the partition manager's allocation and deallocation
186directives to obtain and release the extension buffers.
187
188@subsection Extensions
189
190The sections that follow will contain a description
191of each extension.  Each section will contain a prototype of a
192function with the appropriate calling sequence for the
193corresponding extension.  The names given for the @value{LANGUAGE}
194@value{ROUTINE} and
195its arguments are all defined by the user.  The names used in
196the examples were arbitrarily chosen and impose no naming
197conventions on the user.
198
199@subsubsection TASK_CREATE Extension
200
201The TASK_CREATE extension directly corresponds to the
202task_create directive.  If this extension is defined in any
203static or dynamic extension set and a task is being created,
204then the extension routine will automatically be invoked by
205RTEMS.  The extension should have a prototype similar to the
206following:
207
208@findex rtems_task_create_extension
209@findex rtems_extension
210@ifset is-C
211@example
212rtems_extension user_task_create(
213  rtems_tcb *current_task,
214  rtems_tcb *new_task
215);
216@end example
217@end ifset
218
219@ifset is-Ada
220@example
221procedure User_Task_Create (
222   Current_Task : in     RTEMS.TCB_Pointer;
223   New_Task     : in     RTEMS.TCB_Pointer
224);
225@end example
226@end ifset
227
228where current_task can be used to access the TCB for
229the currently executing task, and new_task can be used to access
230the TCB for the new task being created.  This extension is
231invoked from the task_create directive after new_task has been
232completely initialized, but before it is placed on a ready TCB
233chain.
234
235@subsubsection TASK_START Extension
236
237The TASK_START extension directly corresponds to the
238task_start directive.  If this extension is defined in any
239static or dynamic extension set and a task is being started,
240then the extension routine will automatically be invoked by
241RTEMS.  The extension should have a prototype similar to the
242following:
243
244@findex rtems_task_start_extension
245@ifset is-C
246@example
247rtems_extension user_task_start(
248  rtems_tcb *current_task,
249  rtems_tcb *started_task
250);
251@end example
252@end ifset
253
254@ifset is-Ada
255@example
256procedure User_Task_Start (
257   Current_Task : in     RTEMS.TCB_Pointer;
258   Started_Task : in     RTEMS.TCB_Pointer
259);
260@end example
261@end ifset
262
263where current_task can be used to access the TCB for
264the currently executing task, and started_task can be used to
265access the TCB for the dormant task being started. This
266extension is invoked from the task_start directive after
267started_task has been made ready to start execution, but before
268it is placed on a ready TCB chain.
269
270@subsubsection TASK_RESTART Extension
271
272The TASK_RESTART extension directly corresponds to
273the task_restart directive.  If this extension is defined in any
274static or dynamic extension set and a task is being restarted,
275then the extension should have a prototype similar to the
276following:
277
278@findex rtems_task_restart_extension
279@ifset is-C
280@example
281rtems_extension user_task_restart(
282  rtems_tcb *current_task,
283  rtems_tcb *restarted_task
284);
285@end example
286@end ifset
287
288@ifset is-Ada
289@example
290procedure User_Task_Restart (
291   Current_Task   : in     RTEMS.TCB_Pointer;
292   Restarted_Task : in     RTEMS.TCB_Pointer
293);
294@end example
295@end ifset
296
297where current_task can be used to access the TCB for
298the currently executing task, and restarted_task can be used to
299access the TCB for the task being restarted. This extension is
300invoked from the task_restart directive after restarted_task has
301been made ready to start execution, but before it is placed on a
302ready TCB chain.
303
304@subsubsection TASK_DELETE Extension
305
306The TASK_DELETE extension is associated with the
307task_delete directive.  If this extension is defined in any
308static or dynamic extension set and a task is being deleted,
309then the extension routine will automatically be invoked by
310RTEMS.  The extension should have a prototype similar to the
311following:
312
313@findex rtems_task_delete_extension
314@ifset is-C
315@example
316rtems_extension user_task_delete(
317  rtems_tcb *current_task,
318  rtems_tcb *deleted_task
319);
320@end example
321@end ifset
322
323@ifset is-Ada
324@example
325procedure User_Task_Delete (
326   Current_Task : in     RTEMS.TCB_Pointer;
327   Deleted_Task : in     RTEMS.TCB_Pointer
328);
329@end example
330@end ifset
331
332where current_task can be used to access the TCB for
333the currently executing task, and deleted_task can be used to
334access the TCB for the task being deleted. This extension is
335invoked from the task_delete directive after the TCB has been
336removed from a ready TCB chain, but before all its resources
337including the TCB have been returned to their respective free
338pools.  This extension should not call any RTEMS directives if a
339task is deleting itself (current_task is equal to deleted_task).
340
341@subsubsection TASK_SWITCH Extension
342
343The TASK_SWITCH extension corresponds to a task
344context switch.  If this extension is defined in any static or
345dynamic extension set and a task context switch is in progress,
346then the extension routine will automatically be invoked by
347RTEMS.  The extension should have a prototype similar to the
348following:
349
350@findex rtems_task_switch_extension
351@ifset is-C
352@example
353rtems_extension user_task_switch(
354  rtems_tcb *current_task,
355  rtems_tcb *heir_task
356);
357@end example
358@end ifset
359
360@ifset is-Ada
361@example
362procedure User_Task_Switch (
363   Current_Task : in     RTEMS.TCB_Pointer;
364   Heir_Task    : in     RTEMS.TCB_Pointer
365);
366@end example
367@end ifset
368
369where current_task can be used to access the TCB for
370the task that is being swapped out, and heir_task can be used to
371access the TCB for the task being swapped in.  This extension is
372invoked from RTEMS' dispatcher routine after the current_task
373context has been saved, but before the heir_task context has
374been restored.  This extension should not call any RTEMS
375directives.
376
377@subsubsection TASK_BEGIN Extension
378
379The TASK_BEGIN extension is invoked when a task
380begins execution.  It is invoked immediately before the body of
381the starting procedure and executes in the context in the task.
382This user extension have a prototype similar to the following:
383
384@findex rtems_task_begin_extension
385@ifset is-C
386@example
387rtems_extension user_task_begin(
388  rtems_tcb *current_task
389);
390@end example
391@end ifset
392
393@ifset is-Ada
394@example
395procedure User_Task_Begin (
396   Current_Task : in     RTEMS.TCB_Pointer
397);
398@end example
399@end ifset
400
401where current_task can be used to access the TCB for
402the currently executing task which has begun.  The distinction
403between the TASK_BEGIN and TASK_START extension is that the
404TASK_BEGIN extension is executed in the context of the actual
405task while the TASK_START extension is executed in the context
406of the task performing the task_start directive.  For most
407extensions, this is not a critical distinction.
408
409@subsubsection TASK_EXITTED Extension
410
411The TASK_EXITTED extension is invoked when a task
412exits the body of the starting procedure by either an implicit
413or explicit return statement.  This user extension have a
414prototype similar to the following:
415
416@findex rtems_task_exitted_extension
417@ifset is-C
418@example
419rtems_extension user_task_exitted(
420  rtems_tcb *current_task
421);
422@end example
423@end ifset
424
425@ifset is-Ada
426@example
427procedure User_Task_Exitted (
428   Current_Task : in     RTEMS.TCB_Pointer
429);
430@end example
431@end ifset
432
433where current_task can be used to access the TCB for
434the currently executing task which has just exitted.
435
436Although exiting of task is often considered to be a
437fatal error, this extension allows recovery by either restarting
438or deleting the exiting task.  If the user does not wish to
439recover, then a fatal error may be reported.  If the user does
440not provide a TASK_EXITTED extension or the provided handler
441returns control to RTEMS, then the RTEMS default handler will be
442used.  This default handler invokes the directive
443fatal_error_occurred with the @code{@value{RPREFIX}TASK_EXITTED} directive status.
444
445@subsubsection FATAL Error Extension
446
447The FATAL error extension is associated with the
448fatal_error_occurred directive.  If this extension is defined in
449any static or dynamic extension set and the fatal_error_occurred
450directive has been invoked, then this extension will be called.
451This extension should have a prototype similar to the following:
452
453@findex rtems_fatal_extension
454@ifset is-C
455@example
456rtems_extension user_fatal_error(
457  Internal_errors_Source  the_source,
458  rtems_boolean           is_internal,
459  rtems_unsigned32        the_error
460);
461@end example
462@end ifset
463
464@ifset is-Ada
465@example
466procedure User_Fatal_Error (
467   Error : in     RTEMS.Unsigned32
468);
469@end example
470@end ifset
471
472where the_error is the error code passed to the
473fatal_error_occurred directive. This extension is invoked from
474the fatal_error_occurred directive.
475
476If defined, the user's FATAL error extension is
477invoked before RTEMS' default fatal error routine is invoked and
478the processor is stopped.  For example, this extension could be
479used to pass control to a debugger when a fatal error occurs.
480This extension should not call any RTEMS directives.
481
482@subsection Order of Invocation
483
484When one of the critical system events occur, the
485user extensions are invoked in either "forward" or "reverse"
486order.  Forward order indicates that the static extension set is
487invoked followed by the dynamic extension sets in the order in
488which they were created.  Reverse order means that the dynamic
489extension sets are invoked in the opposite of the order in which
490they were created followed by the static extension set.  By
491invoking the extension sets in this order, extensions can be
492built upon one another.  At the following system events, the
493extensions are invoked in forward order:
494
495@itemize @bullet
496@item Task creation
497@item Task initiation
498@item Task reinitiation
499@item Task deletion
500@item Task context switch
501@item Post task context switch
502@item Task begins to execute
503@end itemize
504
505
506At the following system events, the extensions are
507invoked in reverse order:
508
509@itemize @bullet
510@item Task deletion
511@item Fatal error detection
512@end itemize
513
514At these system events, the extensions are invoked in
515reverse order to insure that if an extension set is built upon
516another, the more complicated extension is invoked before the
517extension set it is built upon.  For example, by invoking the
518static extension set last it is known that the "system" fatal
519error extension will be the last fatal error extension executed.
520Another example is use of the task delete extension by the
521Standard C Library.  Extension sets which are installed after
522the Standard C Library will operate correctly even if they
523utilize the C Library because the C Library's TASK_DELETE
524extension is invoked after that of the other extensions.
525
526@section Operations
527
528@subsection Creating an Extension Set
529
530The @code{@value{DIRPREFIX}extension_create} directive creates and installs
531an extension set by allocating a Extension Set Control Block
532(ESCB), assigning the extension set a user-specified name, and
533assigning it an extension set ID.  Newly created extension sets
534are immediately installed and are invoked upon the next system
535even supporting an extension.
536
537@subsection Obtaining Extension Set IDs
538
539When an extension set is created, RTEMS generates a
540unique extension set ID and assigns it to the created extension
541set until it is deleted.  The extension ID may be obtained by
542either of two methods.  First, as the result of an invocation of
543the @code{@value{DIRPREFIX}extension_create}
544directive, the extension set ID is stored
545in a user provided location.  Second, the extension set ID may
546be obtained later using the @code{@value{DIRPREFIX}extension_ident}
547directive.  The extension set ID is used by other directives
548to manipulate this extension set.
549
550@subsection Deleting an Extension Set
551
552The @code{@value{DIRPREFIX}extension_delete} directive is used to delete an
553extension set.  The extension set's control block is returned to
554the ESCB free list when it is deleted.  An extension set can be
555deleted by a task other than the task which created the
556extension set.  Any subsequent references to the extension's
557name and ID are invalid.
558
559@section Directives
560
561This section details the user extension manager's
562directives.  A subsection is dedicated to each of this manager's
563directives and describes the calling sequence, related
564constants, usage, and status codes.
565
566@c
567@c
568@c
569@page
570@subsection EXTENSION_CREATE - Create a extension set
571
572@cindex create an extension set
573
574@subheading CALLING SEQUENCE:
575
576@ifset is-C
577@findex rtems_extension_create
578@example
579rtems_status_code rtems_extension_create(
580  rtems_name              name,
581  rtems_extensions_table *table,
582  rtems_id               *id
583);
584@end example
585@end ifset
586
587@ifset is-Ada
588@example
589procedure Extension_Create (
590   Name   : in     RTEMS.Name;
591   Table  : in     RTEMS.Extensions_Table_Pointer;
592   ID     :    out RTEMS.ID;
593   Result :    out RTEMS.Status_Codes
594);
595@end example
596@end ifset
597
598@subheading DIRECTIVE STATUS CODES:
599@code{@value{RPREFIX}SUCCESSFUL} -  extension set created successfully@*
600@code{@value{RPREFIX}INVALID_NAME} - invalid extension set name@*
601@code{@value{RPREFIX}TOO_MANY} - too many extension sets created
602
603@subheading DESCRIPTION:
604
605This directive creates a extension set.  The assigned
606extension set id is returned in id.  This id is used to access
607the extension set with other user extension manager directives.
608For control and maintenance of the extension set, RTEMS
609allocates an ESCB from the local ESCB free pool and initializes
610it.
611
612@subheading NOTES:
613
614This directive will not cause the calling task to be
615preempted.
616
617@c
618@c
619@c
620@page
621@subsection EXTENSION_IDENT - Get ID of a extension set
622
623@cindex get ID of an extension set
624@cindex obtain ID of an extension set
625
626@subheading CALLING SEQUENCE:
627
628@ifset is-C
629@findex rtems_extension_ident
630@example
631rtems_status_code rtems_extension_ident(
632  rtems_name  name,
633  rtems_id   *id
634);
635@end example
636@end ifset
637
638@ifset is-Ada
639@example
640procedure Extension_Ident (
641   Name   : in     RTEMS.Name;
642   ID     :    out RTEMS.ID;
643   Result :    out RTEMS.Status_Codes
644);
645@end example
646@end ifset
647
648@subheading DIRECTIVE STATUS CODES:
649@code{@value{RPREFIX}SUCCESSFUL} -  extension set identified successfully@*
650@code{@value{RPREFIX}INVALID_NAME} - extension set name not found
651
652@subheading DESCRIPTION:
653
654This directive obtains the extension set id
655associated with the extension set name to be acquired.  If the
656extension set name is not unique, then the extension set id will
657match one of the extension sets with that name.  However, this
658extension set id is not guaranteed to correspond to the desired
659extension set.  The extension set id is used to access this
660extension set in other extension set related directives.
661
662@subheading NOTES:
663
664This directive will not cause the running task to be
665preempted.
666
667@c
668@c
669@c
670@page
671@subsection EXTENSION_DELETE - Delete a extension set
672
673@cindex delete an extension set
674
675@subheading CALLING SEQUENCE:
676
677@ifset is-C
678@findex rtems_extension_delete
679@example
680rtems_status_code rtems_extension_delete(
681  rtems_id id
682);
683@end example
684@end ifset
685
686@ifset is-Ada
687@example
688procedure Extension_Delete (
689   ID     : in     RTEMS.ID;
690   Result :    out RTEMS.Status_Codes
691);
692@end example
693@end ifset
694
695@subheading DIRECTIVE STATUS CODES:
696@code{@value{RPREFIX}SUCCESSFUL} -  extension set deleted successfully@*
697@code{@value{RPREFIX}INVALID_ID} - invalid extension set id
698
699@subheading DESCRIPTION:
700
701This directive deletes the extension set specified by
702id.  If the extension set is running, it is automatically
703canceled.  The ESCB for the deleted extension set is reclaimed
704by RTEMS.
705
706@subheading NOTES:
707
708This directive will not cause the running task to be
709preempted.
710
711A extension set can be deleted by a task other than
712the task which created the extension set.
713
714@subheading NOTES:
715
716This directive will not cause the running task to be
717preempted.
Note: See TracBrowser for help on using the repository browser.