source: rtems/cpukit/score/include/rtems/score/userext.h @ 749d64a

4.104.115
Last change on this file since 749d64a was 749d64a, checked in by Ralf Corsepius <ralf.corsepius@…>, on Oct 12, 2009 at 12:16:23 PM

Reflect having introduced Internal_errors_t.

  • Property mode set to 100644
File size: 8.3 KB
Line 
1/**
2 * @file
3 *
4 * @ingroup ScoreUserExt
5 *
6 * @brief User Extension Handler API.
7 */
8
9/*
10 *  COPYRIGHT (c) 1989-2009.
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 *  $Id$
18 */
19
20#ifndef _RTEMS_SCORE_USEREXT_H
21#define _RTEMS_SCORE_USEREXT_H
22
23#include <rtems/score/interr.h>
24#include <rtems/score/chain.h>
25#include <rtems/score/thread.h>
26
27#ifdef __cplusplus
28extern "C" {
29#endif
30
31typedef void User_extensions_routine RTEMS_COMPILER_DEPRECATED_ATTRIBUTE;
32
33/**
34 * @defgroup ScoreUserExt User Extension Handler
35 *
36 * @ingroup Score
37 *
38 * @brief The User Extension Handler provides invocation of application
39 * dependent routines at critical points in the life of each thread and the
40 * system as a whole.
41 *
42 * @{
43 */
44
45/**
46 * @brief Task create extension.
47 *
48 * It corresponds to _Thread_Initialize() (used by the rtems_task_create()
49 * directive).  The first parameter points to the currently executing thread
50 * which created the new thread.  The second parameter points to the created
51 * thread.
52 *
53 * It is invoked after the new thread has been completely initialized, but
54 * before it is placed on a ready chain.
55 *
56 * Thread dispatching may be disabled.  It can be assumed that the executing
57 * thread locked the allocator mutex.  They only exception is the creation of
58 * the idle thread.  In this case the allocator mutex is not locked.
59 *
60 * The user extension is expected to return @c true if it successfully
61 * executed, and @c false otherwise. A thread create user extension will
62 * frequently attempt to allocate resources. If this allocation fails, then the
63 * extension should return @c false and the entire task create operation will
64 * fail.
65 */
66typedef bool ( *User_extensions_thread_create_extension )(
67  Thread_Control *,
68  Thread_Control *
69);
70
71/**
72 * @brief Task delete extension.
73 *
74 * It corresponds to _Thread_Close() (used by the rtems_task_delete()
75 * directive).  The first parameter points to the currently executing thread
76 * which deleted the thread.  The second parameter points to the deleted
77 * thread.
78 *
79 * It is invoked before all resources of the thread are deleted.
80 *
81 * Thread dispatching is enabled.  The executing thread locked the allocator
82 * mutex.
83 */
84typedef void( *User_extensions_thread_delete_extension )(
85  Thread_Control *,
86  Thread_Control *
87);
88
89/**
90 * @brief Task start extension.
91 *
92 * It corresponds to _Thread_Start() (used by the rtems_task_start()
93 * directive).  The first parameter points to the currently executing thread
94 * which started the thread.  The second parameter points to the started
95 * thread.
96 *
97 * It is invoked after the environment of the thread has been loaded and the
98 * thread has been made ready.
99 *
100 * Thread dispatching is disabled.  The executing thread is not the holder of
101 * the allocator mutex.
102 */
103typedef void( *User_extensions_thread_start_extension )(
104  Thread_Control *,
105  Thread_Control *
106);
107
108/**
109 * @brief Task restart extension.
110 *
111 * It corresponds to _Thread_Restart() (used by the rtems_task_restart()
112 * directive).  The first parameter points to the currently executing thread
113 * which restarted the thread.  The second parameter points to the restarted
114 * thread.
115 *
116 * It is invoked after the environment of the thread has been loaded and the
117 * thread has been made ready.
118 *
119 * Thread dispatching is disabled.  The executing thread is not the holder of
120 * the allocator mutex.
121 */
122typedef void( *User_extensions_thread_restart_extension )(
123  Thread_Control *,
124  Thread_Control *
125);
126
127/**
128 * @brief Task switch extension.
129 *
130 * It corresponds to _Thread_Dispatch().  The first parameter points to the
131 * currently executing thread.  The second parameter points to the heir thread.
132 *
133 * It is invoked before the context switch from the executing to the heir
134 * thread.
135 *
136 * Thread dispatching is disabled.  The state of the allocator mutex is
137 * arbitrary.
138 *
139 * The context switches initiated through _Thread_Start_multitasking() and
140 * _Thread_Stop_multitasking() are not covered by this extension.  The
141 * executing thread may run with a minimal setup, for example with a freed task
142 * stack.
143 */
144typedef void( *User_extensions_thread_switch_extension )(
145  Thread_Control *,
146  Thread_Control *
147);
148
149/**
150 * @brief Task begin extension.
151 *
152 * It corresponds to _Thread_Handler().  The first parameter points to the
153 * currently executing thread which begins now execution.
154 *
155 * Thread dispatching is disabled.  The executing thread is not the holder of
156 * the allocator mutex.
157 */
158typedef void( *User_extensions_thread_begin_extension )(
159  Thread_Control *
160);
161
162/**
163 * @brief Task exitted extension.
164 *
165 * It corresponds to _Thread_Handler().  The first parameter points to the
166 * currently executing thread which exitted before.
167 *
168 * Thread dispatching is disabled.  The state of the allocator mutex is
169 * arbitrary.
170 */
171typedef void( *User_extensions_thread_exitted_extension )(
172  Thread_Control *
173);
174
175/**
176 * @brief Task fatal error extension.
177 *
178 * It corresponds to _Internal_error_Occurred() (used by the
179 * rtems_fatal_error_occurred() directive).  The first parameter contains the
180 * internal error source.  The second parameter indicates if it was an internal
181 * error.  The third parameter contains the error code.
182 *
183 * This extension should not call any RTEMS directives.
184 */
185typedef void( *User_extensions_fatal_extension )(
186  Internal_errors_Source,
187  bool,
188  Internal_errors_t
189);
190
191/**
192 * @brief User extension table.
193 */
194typedef struct {
195  User_extensions_thread_create_extension  thread_create;
196  User_extensions_thread_start_extension   thread_start;
197  User_extensions_thread_restart_extension thread_restart;
198  User_extensions_thread_delete_extension  thread_delete;
199  User_extensions_thread_switch_extension  thread_switch;
200  User_extensions_thread_begin_extension   thread_begin;
201  User_extensions_thread_exitted_extension thread_exitted;
202  User_extensions_fatal_extension          fatal;
203}   User_extensions_Table;
204
205/**
206 * @brief Manages the switch callouts.
207 *
208 * They are managed separately from other extensions for performance reasons.
209 */
210typedef struct {
211  Chain_Node                              Node;
212  User_extensions_thread_switch_extension thread_switch;
213}   User_extensions_Switch_control;
214
215/**
216 * @brief Manages each user extension set.
217 *
218 * The switch control is part of the extensions control even if not used due to
219 * the extension not having a switch handler.
220 */
221typedef struct {
222  Chain_Node                     Node;
223  User_extensions_Switch_control Switch;
224  User_extensions_Table          Callouts;
225}   User_extensions_Control;
226
227/**
228 * @brief List of active extensions.
229 */
230SCORE_EXTERN Chain_Control _User_extensions_List;
231
232/**
233 * @brief List of active task switch extensions.
234 */
235SCORE_EXTERN Chain_Control _User_extensions_Switches_list;
236
237/**
238 * @name Extension Maintainance
239 *
240 * @{
241 */
242
243void _User_extensions_Handler_initialization( void );
244
245void _User_extensions_Add_set(
246  User_extensions_Control *extension
247);
248
249/** @brief User extensions Add to API extension set
250 *
251 *  This routine is used to add an API extension set to the active list.
252 *
253 *  @param[in] the_extension is the extension set to add
254 */
255void _User_extensions_Add_API_set (
256  User_extensions_Control *the_extension
257);
258
259RTEMS_INLINE_ROUTINE void _User_extensions_Add_set_with_table(
260  User_extensions_Control *extension,
261  User_extensions_Table   *extension_table
262)
263{
264  extension->Callouts = *extension_table;
265
266  _User_extensions_Add_set( extension );
267}
268
269void _User_extensions_Remove_set(
270  User_extensions_Control *extension
271);
272
273/** @} */
274
275/**
276 * @name Extension Callout Dispatcher
277 *
278 * @{
279 */
280
281bool _User_extensions_Thread_create(
282  Thread_Control *created
283);
284
285void _User_extensions_Thread_delete(
286  Thread_Control *deleted
287);
288
289void _User_extensions_Thread_start(
290  Thread_Control *started
291);
292
293void _User_extensions_Thread_restart(
294  Thread_Control *restarted
295);
296
297void _User_extensions_Thread_begin(
298  Thread_Control *executing
299);
300
301void _User_extensions_Thread_switch(
302  Thread_Control *executing,
303  Thread_Control *heir
304);
305
306void _User_extensions_Thread_exitted(
307  Thread_Control *executing
308);
309
310void _User_extensions_Fatal(
311  Internal_errors_Source source,
312  bool                   is_internal,
313  Internal_errors_t      error
314);
315
316/** @} */
317
318/** @} */
319
320#ifdef __cplusplus
321}
322#endif
323
324#endif
325/* end of include file */
Note: See TracBrowser for help on using the repository browser.