source: rtems/cpukit/sapi/include/rtems/extension.h @ e4b40531

4.11
Last change on this file since e4b40531 was e4b40531, checked in by Sebastian Huber <sebastian.huber@…>, on Nov 14, 2012 at 11:37:24 AM

sapi: Add rtems_fatal_source and rtems_fatal_code

  • Property mode set to 100644
File size: 10.5 KB
Line 
1/**
2 * @file
3 *
4 * @ingroup ClassicUserExtensions
5 *
6 * @brief User Extensions API.
7 */
8
9/*
10 *  COPYRIGHT (c) 1989-2008.
11 *  On-Line Applications Research Corporation (OAR).
12 *
13 *  The license and distribution terms for this file may be
14 *  found in the file LICENSE in this distribution or at
15 *  http://www.rtems.com/license/LICENSE.
16 */
17
18#ifndef _RTEMS_EXTENSION_H
19#define _RTEMS_EXTENSION_H
20
21#ifndef SAPI_EXT_EXTERN
22#define SAPI_EXT_EXTERN extern
23#endif
24
25#ifdef __cplusplus
26extern "C" {
27#endif
28
29#include <rtems/score/object.h>
30#include <rtems/score/userext.h>
31#include <rtems/rtems/status.h>
32#include <rtems/rtems/types.h>
33
34SAPI_EXT_EXTERN Objects_Information  _Extension_Information;
35
36typedef struct {
37  Objects_Control          Object;
38  User_extensions_Control  Extension;
39}   Extension_Control;
40
41void _Extension_Manager_initialization(void);
42
43typedef User_extensions_routine
44  rtems_extension RTEMS_COMPILER_DEPRECATED_ATTRIBUTE;
45
46/**
47 * @defgroup ClassicUserExtensions User Extensions
48 *
49 * @ingroup ClassicRTEMS
50 *
51 * @brief The User Extensions Manager allows the application developer to
52 * augment the executive by allowing them to supply extension routines which
53 * are invoked at critical system events.
54 *
55 * @section ClassicUserExtensionsSets Extension Sets
56 *
57 * An @ref User_extensions_Table "extension set" is defined as a set of
58 * routines which are invoked at each of the critical system events at which
59 * user extension routines are invoked.  Together a set of these routines
60 * typically perform a specific functionality such as performance monitoring or
61 * debugger support.
62 *
63 * RTEMS allows the user to have multiple extension sets active at the same
64 * time. First, a single static extension set may be defined as the
65 * application's User Extension Table which is included as part of the
66 * Configuration Table. This extension set is active for the entire life of the
67 * system and may not be deleted. This extension set is especially important
68 * because it is the only way the application can provided a fatal error
69 * extension which is invoked if RTEMS fails during the
70 * rtems_initialize_data_structures() directive. The static extension set is
71 * optional and may be configured as @c NULL if no static extension set is
72 * required.
73 *
74 * Second, the user can install dynamic extensions using the
75 * rtems_extension_create() directive. These extensions are RTEMS objects in
76 * that they have a name, an ID, and can be dynamically created and deleted. In
77 * contrast to the static extension set, these extensions can only be created
78 * and installed after the rtems_initialize_data_structures() directive
79 * successfully completes execution. Dynamic extensions are useful for
80 * encapsulating the functionality of an extension set. For example, the
81 * application could use extensions to manage a special coprocessor, do
82 * performance monitoring, and to do stack bounds checking. Each of these
83 * extension sets could be written and installed independently of the others.
84 *
85 * All user extensions are optional and RTEMS places no naming restrictions on
86 * the user. The user extension entry points are copied into an internal RTEMS
87 * structure. This means the user does not need to keep the table after
88 * creating it, and changing the handler entry points dynamically in a table
89 * once created has no effect. Creating a table local to a function can save
90 * space in space limited applications.
91 *
92 * Extension switches do not effect the context switch overhead if no switch
93 * handler is installed.
94 *
95 * @section ClassicUserExtensionsTCB Task Control Block Area
96 *
97 * RTEMS provides for a pointer to a user-defined data area for each extension
98 * set to be linked to each task's control block (TCB). This area is only
99 * available for the dynamic extensions. This set of pointers is an extension
100 * of the TCB and can be used to store additional data required by the user's
101 * extension functions. It is also possible for a user extension to utilize the
102 * notepad locations associated with each task although this may conflict with
103 * application usage of those particular notepads.
104 *
105 * The TCB extension is an array of pointers in the TCB. The index into the
106 * table can be obtained from the extension identifier returned when the
107 * extension is created:
108 *
109 * @code
110 * rtems_tcb *task = some_task;
111 * size_t index = rtems_object_id_get_index(extension_id);
112 * void *extension_data = task->extensions [index];
113 * @endcode
114 *
115 * The number of pointers in the area is the same as the number of user
116 * extension sets configured. This allows an application to augment the TCB
117 * with user-defined information. For example, an application could implement
118 * task profiling by storing timing statistics in the TCB's extended memory
119 * area. When a task context switch is being executed, the task switch
120 * extension could read a real-time clock to calculate how long the task being
121 * swapped out has run as well as timestamp the starting time for the task
122 * being swapped in.
123 *
124 * If used, the extended memory area for the TCB should be allocated and the
125 * TCB extension pointer should be set at the time the task is created or
126 * started by either the task create or task start extension. The application
127 * is responsible for managing this extended memory area for the TCBs. The
128 * memory may be reinitialized by the task restart extension and should be
129 * deallocated by the task delete extension when the task is deleted. Since the
130 * TCB extension buffers would most likely be of a fixed size, the RTEMS
131 * partition manager could be used to manage the application's extended memory
132 * area. The application could create a partition of fixed size TCB extension
133 * buffers and use the partition manager's allocation and deallocation
134 * directives to obtain and release the extension buffers.
135 *
136 * @section ClassicUserExtensionsOrder Order of Invokation
137 *
138 * When one of the critical system events occur, the user extensions are
139 * invoked in either @a forward or @a reverse order. Forward order indicates
140 * that the static extension set is invoked followed by the dynamic extension
141 * sets in the order in which they were created. Reverse order means that the
142 * dynamic extension sets are invoked in the opposite of the order in which
143 * they were created followed by the static extension set. By invoking the
144 * extension sets in this order, extensions can be built upon one another. At
145 * the following system events, the extensions are invoked in forward order:
146 *
147 * - Task creation
148 * - Task start
149 * - Task restart
150 * - Task context switch
151 * - Post task context switch
152 * - Task begins to execute
153 *
154 * At the following system events, the extensions are invoked in reverse order:
155 *
156 * - Task exit
157 * - Task deletion
158 * - Fatal error detection
159 *
160 * At these system events, the extensions are invoked in reverse order to
161 * insure that if an extension set is built upon another, the more complicated
162 * extension is invoked before the extension set it is built upon. For example,
163 * by invoking the static extension set last it is known that the "system"
164 * fatal error extension will be the last fatal error extension executed.
165 * Another example is use of the task delete extension by the Standard C
166 * Library. Extension sets which are installed after the Standard C Library
167 * will operate correctly even if they utilize the C Library because the C
168 * Library's task delete extension is invoked after that of the other
169 * extensions.
170 *
171 * @{
172 */
173
174typedef User_extensions_thread_create_extension   rtems_task_create_extension;
175typedef User_extensions_thread_delete_extension   rtems_task_delete_extension;
176typedef User_extensions_thread_start_extension    rtems_task_start_extension;
177typedef User_extensions_thread_restart_extension  rtems_task_restart_extension;
178typedef User_extensions_thread_switch_extension   rtems_task_switch_extension;
179typedef User_extensions_thread_begin_extension    rtems_task_begin_extension;
180typedef User_extensions_thread_exitted_extension  rtems_task_exitted_extension;
181typedef User_extensions_fatal_extension           rtems_fatal_extension;
182
183typedef User_extensions_Table                     rtems_extensions_table;
184
185typedef Internal_errors_Source rtems_fatal_source;
186
187typedef Internal_errors_t rtems_fatal_code;
188
189/**
190 * @brief Creates an extension set object.
191 *
192 * This directive creates a extension set object from the extension table
193 * @a extension_table.  The assigned extension set identifier is returned in
194 * @a id.  The identifier is used to access this extension set in other
195 * extension set related directives.  The name @a name will be assigned to the
196 * extension set object.
197 *
198 * Newly created extension sets are immediately installed and are invoked upon
199 * the next system event supporting an extension.
200 *
201 * This directive will not cause the calling task to be preempted.
202 *
203 * @retval RTEMS_SUCCESSFUL Extension set created successfully.
204 * @retval RTEMS_INVALID_ADDRESS Identifier pointer is @c NULL.
205 * @retval RTEMS_INVALID_NAME Invalid extension set name.
206 * @retval RTEMS_TOO_MANY Too many extension sets created.
207 */
208rtems_status_code rtems_extension_create(
209  rtems_name                    name,
210  const rtems_extensions_table *extension_table,
211  rtems_id                     *id
212);
213
214/**
215 * @brief Identifies an extension set object by a name.
216 *
217 * This directive obtains an extension set identifier in @a id associated with
218 * the extension set name @a name. If the extension set name is not unique,
219 * then the extension set identifier will match one of the extension sets with
220 * that name.  However, this extension set identifier is not guaranteed to
221 * correspond to the desired extension set. The extension set identifier is
222 * used to access this extension set in other extension set related directives.
223 *
224 * This directive will not cause the calling task to be preempted.
225 *
226 * @retval RTEMS_SUCCESSFUL Extension set identified successfully.
227 * @retval RTEMS_INVALID_ADDRESS Identifier pointer is @c NULL.
228 * @retval RTEMS_INVALID_NAME Extension set name not found or invalid name.
229 */
230rtems_status_code rtems_extension_ident(
231  rtems_name  name,
232  rtems_id   *id
233);
234
235/**
236 * @brief Deletes an extension set object specified by the identifier @a id.
237 *
238 * Any subsequent references to the extension's name and identifier are
239 * invalid.
240 *
241 * This directive will not cause the calling task to be preempted.
242 *
243 * @retval RTEMS_SUCCESSFUL Extension set deleted successfully.
244 * @retval RTEMS_INVALID_ID Invalid extension set identifier.
245 */
246rtems_status_code rtems_extension_delete(
247  rtems_id id
248);
249
250/** @} */
251
252#ifndef __RTEMS_APPLICATION__
253#include <rtems/extension.inl>
254#endif
255
256#ifdef __cplusplus
257}
258#endif
259
260#endif
261/* end of include file */
Note: See TracBrowser for help on using the repository browser.