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

4.104.114.84.9
Last change on this file since d4696eb was d4696eb, checked in by Joel Sherrill <joel.sherrill@…>, on Jun 28, 2002 at 1:57:18 PM

2002-06-28 Joel Sherrill <joel@…>

  • userext.t: Per PR228, correct the prototype of the task create user extension to indicate it returns a boolean and augment the documentation to explain the purpose of the boolean return value.
  • Property mode set to 100644
File size: 22.3 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
202@code{@value{DIRPREFIX}task_create} directive.  If this extension
203is defined in any
204static or dynamic extension set and a task is being created,
205then the extension routine will automatically be invoked by
206RTEMS.  The extension should have a prototype similar to the
207following:
208
209@findex rtems_task_create_extension
210@findex rtems_extension
211@ifset is-C
212@example
213boolean user_task_create(
214  rtems_tcb *current_task,
215  rtems_tcb *new_task
216);
217@end example
218@end ifset
219
220@ifset is-Ada
221@example
222function User_Task_Create (
223   Current_Task : in     RTEMS.TCB_Pointer;
224   New_Task     : in     RTEMS.TCB_Pointer
225) returns Boolean;
226@end example
227@end ifset
228
229where @code{current_task} can be used to access the TCB for
230the currently executing task, and new_task can be used to access
231the TCB for the new task being created.  This extension is
232invoked from the @code{@value{DIRPREFIX}task_create}
233directive after @code{new_task} has been
234completely initialized, but before it is placed on a ready TCB
235chain.
236
237The user extension is expected to return the boolean
238value @code{TRUE} if it successfully executed and
239@code{FALSE} otherwise.  A task create user extension
240will frequently attempt to allocate resources.  If this
241allocation fails, then the extension should return
242@code{FALSE} and the entire task create operation
243will fail.
244
245@subsubsection TASK_START Extension
246
247The TASK_START extension directly corresponds to the
248task_start directive.  If this extension is defined in any
249static or dynamic extension set and a task is being started,
250then the extension routine will automatically be invoked by
251RTEMS.  The extension should have a prototype similar to the
252following:
253
254@findex rtems_task_start_extension
255@ifset is-C
256@example
257rtems_extension user_task_start(
258  rtems_tcb *current_task,
259  rtems_tcb *started_task
260);
261@end example
262@end ifset
263
264@ifset is-Ada
265@example
266procedure User_Task_Start (
267   Current_Task : in     RTEMS.TCB_Pointer;
268   Started_Task : in     RTEMS.TCB_Pointer
269);
270@end example
271@end ifset
272
273where current_task can be used to access the TCB for
274the currently executing task, and started_task can be used to
275access the TCB for the dormant task being started. This
276extension is invoked from the task_start directive after
277started_task has been made ready to start execution, but before
278it is placed on a ready TCB chain.
279
280@subsubsection TASK_RESTART Extension
281
282The TASK_RESTART extension directly corresponds to
283the task_restart directive.  If this extension is defined in any
284static or dynamic extension set and a task is being restarted,
285then the extension should have a prototype similar to the
286following:
287
288@findex rtems_task_restart_extension
289@ifset is-C
290@example
291rtems_extension user_task_restart(
292  rtems_tcb *current_task,
293  rtems_tcb *restarted_task
294);
295@end example
296@end ifset
297
298@ifset is-Ada
299@example
300procedure User_Task_Restart (
301   Current_Task   : in     RTEMS.TCB_Pointer;
302   Restarted_Task : in     RTEMS.TCB_Pointer
303);
304@end example
305@end ifset
306
307where current_task can be used to access the TCB for
308the currently executing task, and restarted_task can be used to
309access the TCB for the task being restarted. This extension is
310invoked from the task_restart directive after restarted_task has
311been made ready to start execution, but before it is placed on a
312ready TCB chain.
313
314@subsubsection TASK_DELETE Extension
315
316The TASK_DELETE extension is associated with the
317task_delete directive.  If this extension is defined in any
318static or dynamic extension set and a task is being deleted,
319then the extension routine will automatically be invoked by
320RTEMS.  The extension should have a prototype similar to the
321following:
322
323@findex rtems_task_delete_extension
324@ifset is-C
325@example
326rtems_extension user_task_delete(
327  rtems_tcb *current_task,
328  rtems_tcb *deleted_task
329);
330@end example
331@end ifset
332
333@ifset is-Ada
334@example
335procedure User_Task_Delete (
336   Current_Task : in     RTEMS.TCB_Pointer;
337   Deleted_Task : in     RTEMS.TCB_Pointer
338);
339@end example
340@end ifset
341
342where current_task can be used to access the TCB for
343the currently executing task, and deleted_task can be used to
344access the TCB for the task being deleted. This extension is
345invoked from the task_delete directive after the TCB has been
346removed from a ready TCB chain, but before all its resources
347including the TCB have been returned to their respective free
348pools.  This extension should not call any RTEMS directives if a
349task is deleting itself (current_task is equal to deleted_task).
350
351@subsubsection TASK_SWITCH Extension
352
353The TASK_SWITCH extension corresponds to a task
354context switch.  If this extension is defined in any static or
355dynamic extension set and a task context switch is in progress,
356then the extension routine will automatically be invoked by
357RTEMS.  The extension should have a prototype similar to the
358following:
359
360@findex rtems_task_switch_extension
361@ifset is-C
362@example
363rtems_extension user_task_switch(
364  rtems_tcb *current_task,
365  rtems_tcb *heir_task
366);
367@end example
368@end ifset
369
370@ifset is-Ada
371@example
372procedure User_Task_Switch (
373   Current_Task : in     RTEMS.TCB_Pointer;
374   Heir_Task    : in     RTEMS.TCB_Pointer
375);
376@end example
377@end ifset
378
379where current_task can be used to access the TCB for
380the task that is being swapped out, and heir_task can be used to
381access the TCB for the task being swapped in.  This extension is
382invoked from RTEMS' dispatcher routine after the current_task
383context has been saved, but before the heir_task context has
384been restored.  This extension should not call any RTEMS
385directives.
386
387@subsubsection TASK_BEGIN Extension
388
389The TASK_BEGIN extension is invoked when a task
390begins execution.  It is invoked immediately before the body of
391the starting procedure and executes in the context in the task.
392This user extension have a prototype similar to the following:
393
394@findex rtems_task_begin_extension
395@ifset is-C
396@example
397rtems_extension user_task_begin(
398  rtems_tcb *current_task
399);
400@end example
401@end ifset
402
403@ifset is-Ada
404@example
405procedure User_Task_Begin (
406   Current_Task : in     RTEMS.TCB_Pointer
407);
408@end example
409@end ifset
410
411where current_task can be used to access the TCB for
412the currently executing task which has begun.  The distinction
413between the TASK_BEGIN and TASK_START extension is that the
414TASK_BEGIN extension is executed in the context of the actual
415task while the TASK_START extension is executed in the context
416of the task performing the task_start directive.  For most
417extensions, this is not a critical distinction.
418
419@subsubsection TASK_EXITTED Extension
420
421The TASK_EXITTED extension is invoked when a task
422exits the body of the starting procedure by either an implicit
423or explicit return statement.  This user extension have a
424prototype similar to the following:
425
426@findex rtems_task_exitted_extension
427@ifset is-C
428@example
429rtems_extension user_task_exitted(
430  rtems_tcb *current_task
431);
432@end example
433@end ifset
434
435@ifset is-Ada
436@example
437procedure User_Task_Exitted (
438   Current_Task : in     RTEMS.TCB_Pointer
439);
440@end example
441@end ifset
442
443where current_task can be used to access the TCB for
444the currently executing task which has just exitted.
445
446Although exiting of task is often considered to be a
447fatal error, this extension allows recovery by either restarting
448or deleting the exiting task.  If the user does not wish to
449recover, then a fatal error may be reported.  If the user does
450not provide a TASK_EXITTED extension or the provided handler
451returns control to RTEMS, then the RTEMS default handler will be
452used.  This default handler invokes the directive
453fatal_error_occurred with the @code{@value{RPREFIX}TASK_EXITTED} directive status.
454
455@subsubsection FATAL Error Extension
456
457The FATAL error extension is associated with the
458fatal_error_occurred directive.  If this extension is defined in
459any static or dynamic extension set and the fatal_error_occurred
460directive has been invoked, then this extension will be called.
461This extension should have a prototype similar to the following:
462
463@findex rtems_fatal_extension
464@ifset is-C
465@example
466rtems_extension user_fatal_error(
467  Internal_errors_Source  the_source,
468  rtems_boolean           is_internal,
469  rtems_unsigned32        the_error
470);
471@end example
472@end ifset
473
474@ifset is-Ada
475@example
476procedure User_Fatal_Error (
477   Error : in     RTEMS.Unsigned32
478);
479@end example
480@end ifset
481
482where the_error is the error code passed to the
483fatal_error_occurred directive. This extension is invoked from
484the fatal_error_occurred directive.
485
486If defined, the user's FATAL error extension is
487invoked before RTEMS' default fatal error routine is invoked and
488the processor is stopped.  For example, this extension could be
489used to pass control to a debugger when a fatal error occurs.
490This extension should not call any RTEMS directives.
491
492@subsection Order of Invocation
493
494When one of the critical system events occur, the
495user extensions are invoked in either "forward" or "reverse"
496order.  Forward order indicates that the static extension set is
497invoked followed by the dynamic extension sets in the order in
498which they were created.  Reverse order means that the dynamic
499extension sets are invoked in the opposite of the order in which
500they were created followed by the static extension set.  By
501invoking the extension sets in this order, extensions can be
502built upon one another.  At the following system events, the
503extensions are invoked in forward order:
504
505@itemize @bullet
506@item Task creation
507@item Task initiation
508@item Task reinitiation
509@item Task deletion
510@item Task context switch
511@item Post task context switch
512@item Task begins to execute
513@end itemize
514
515
516At the following system events, the extensions are
517invoked in reverse order:
518
519@itemize @bullet
520@item Task deletion
521@item Fatal error detection
522@end itemize
523
524At these system events, the extensions are invoked in
525reverse order to insure that if an extension set is built upon
526another, the more complicated extension is invoked before the
527extension set it is built upon.  For example, by invoking the
528static extension set last it is known that the "system" fatal
529error extension will be the last fatal error extension executed.
530Another example is use of the task delete extension by the
531Standard C Library.  Extension sets which are installed after
532the Standard C Library will operate correctly even if they
533utilize the C Library because the C Library's TASK_DELETE
534extension is invoked after that of the other extensions.
535
536@section Operations
537
538@subsection Creating an Extension Set
539
540The @code{@value{DIRPREFIX}extension_create} directive creates and installs
541an extension set by allocating a Extension Set Control Block
542(ESCB), assigning the extension set a user-specified name, and
543assigning it an extension set ID.  Newly created extension sets
544are immediately installed and are invoked upon the next system
545even supporting an extension.
546
547@subsection Obtaining Extension Set IDs
548
549When an extension set is created, RTEMS generates a
550unique extension set ID and assigns it to the created extension
551set until it is deleted.  The extension ID may be obtained by
552either of two methods.  First, as the result of an invocation of
553the @code{@value{DIRPREFIX}extension_create}
554directive, the extension set ID is stored
555in a user provided location.  Second, the extension set ID may
556be obtained later using the @code{@value{DIRPREFIX}extension_ident}
557directive.  The extension set ID is used by other directives
558to manipulate this extension set.
559
560@subsection Deleting an Extension Set
561
562The @code{@value{DIRPREFIX}extension_delete} directive is used to delete an
563extension set.  The extension set's control block is returned to
564the ESCB free list when it is deleted.  An extension set can be
565deleted by a task other than the task which created the
566extension set.  Any subsequent references to the extension's
567name and ID are invalid.
568
569@section Directives
570
571This section details the user extension manager's
572directives.  A subsection is dedicated to each of this manager's
573directives and describes the calling sequence, related
574constants, usage, and status codes.
575
576@c
577@c
578@c
579@page
580@subsection EXTENSION_CREATE - Create a extension set
581
582@cindex create an extension set
583
584@subheading CALLING SEQUENCE:
585
586@ifset is-C
587@findex rtems_extension_create
588@example
589rtems_status_code rtems_extension_create(
590  rtems_name              name,
591  rtems_extensions_table *table,
592  rtems_id               *id
593);
594@end example
595@end ifset
596
597@ifset is-Ada
598@example
599procedure Extension_Create (
600   Name   : in     RTEMS.Name;
601   Table  : in     RTEMS.Extensions_Table_Pointer;
602   ID     :    out RTEMS.ID;
603   Result :    out RTEMS.Status_Codes
604);
605@end example
606@end ifset
607
608@subheading DIRECTIVE STATUS CODES:
609@code{@value{RPREFIX}SUCCESSFUL} -  extension set created successfully@*
610@code{@value{RPREFIX}INVALID_NAME} - invalid extension set name@*
611@code{@value{RPREFIX}TOO_MANY} - too many extension sets created
612
613@subheading DESCRIPTION:
614
615This directive creates a extension set.  The assigned
616extension set id is returned in id.  This id is used to access
617the extension set with other user extension manager directives.
618For control and maintenance of the extension set, RTEMS
619allocates an ESCB from the local ESCB free pool and initializes
620it.
621
622@subheading NOTES:
623
624This directive will not cause the calling task to be
625preempted.
626
627@c
628@c
629@c
630@page
631@subsection EXTENSION_IDENT - Get ID of a extension set
632
633@cindex get ID of an extension set
634@cindex obtain ID of an extension set
635
636@subheading CALLING SEQUENCE:
637
638@ifset is-C
639@findex rtems_extension_ident
640@example
641rtems_status_code rtems_extension_ident(
642  rtems_name  name,
643  rtems_id   *id
644);
645@end example
646@end ifset
647
648@ifset is-Ada
649@example
650procedure Extension_Ident (
651   Name   : in     RTEMS.Name;
652   ID     :    out RTEMS.ID;
653   Result :    out RTEMS.Status_Codes
654);
655@end example
656@end ifset
657
658@subheading DIRECTIVE STATUS CODES:
659@code{@value{RPREFIX}SUCCESSFUL} -  extension set identified successfully@*
660@code{@value{RPREFIX}INVALID_NAME} - extension set name not found
661
662@subheading DESCRIPTION:
663
664This directive obtains the extension set id
665associated with the extension set name to be acquired.  If the
666extension set name is not unique, then the extension set id will
667match one of the extension sets with that name.  However, this
668extension set id is not guaranteed to correspond to the desired
669extension set.  The extension set id is used to access this
670extension set in other extension set related directives.
671
672@subheading NOTES:
673
674This directive will not cause the running task to be
675preempted.
676
677@c
678@c
679@c
680@page
681@subsection EXTENSION_DELETE - Delete a extension set
682
683@cindex delete an extension set
684
685@subheading CALLING SEQUENCE:
686
687@ifset is-C
688@findex rtems_extension_delete
689@example
690rtems_status_code rtems_extension_delete(
691  rtems_id id
692);
693@end example
694@end ifset
695
696@ifset is-Ada
697@example
698procedure Extension_Delete (
699   ID     : in     RTEMS.ID;
700   Result :    out RTEMS.Status_Codes
701);
702@end example
703@end ifset
704
705@subheading DIRECTIVE STATUS CODES:
706@code{@value{RPREFIX}SUCCESSFUL} -  extension set deleted successfully@*
707@code{@value{RPREFIX}INVALID_ID} - invalid extension set id
708
709@subheading DESCRIPTION:
710
711This directive deletes the extension set specified by
712id.  If the extension set is running, it is automatically
713canceled.  The ESCB for the deleted extension set is reclaimed
714by RTEMS.
715
716@subheading NOTES:
717
718This directive will not cause the running task to be
719preempted.
720
721A extension set can be deleted by a task other than
722the task which created the extension set.
723
724@subheading NOTES:
725
726This directive will not cause the running task to be
727preempted.
Note: See TracBrowser for help on using the repository browser.