source: rtems/doc/user/userext.t @ 3ac68119

4.11
Last change on this file since 3ac68119 was 3ac68119, checked in by Gedare Bloom <gedare@…>, on Mar 6, 2015 at 5:41:49 PM

cpukit: deprecate notepads

Deprecate Classic API Notepads. Mark task_set/get_note() with
the deprecated attribute, and also mark the notepads field.

Replace disable with enable option for notepads in confdefs.h,
and make notepads disabled by default. The previous option
CONFIGURE_DISABLE_CLASSIC_API_NOTEPADS is now unused and
will emit a compile-time warning. A new option
CONFIGURE_ENABLE_CLASSIC_API_NOTEPADS is available to turn
on notepads, but it also will emit a compile-time warning
to indicate that notepads are deprecated.

Closes #2265

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