source: rtems/doc/user/userext.t @ 880e2f37

4.11
Last change on this file since 880e2f37 was 880e2f37, checked in by Joel Sherrill <joel.sherrill@…>, on Oct 2, 2012 at 4:45:09 PM

User's Guide: Correct typos in return status bullets

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