[c42d1a4] | 1 | /** |
---|
| 2 | * @file |
---|
| 3 | * |
---|
| 4 | * @ingroup ScoreUserExt |
---|
[ac7d5ef0] | 5 | * |
---|
[c42d1a4] | 6 | * @brief User Extension Handler API. |
---|
[baff4da] | 7 | */ |
---|
| 8 | |
---|
| 9 | /* |
---|
[3f727f98] | 10 | * COPYRIGHT (c) 1989-2009. |
---|
[ac7d5ef0] | 11 | * On-Line Applications Research Corporation (OAR). |
---|
| 12 | * |
---|
[98e4ebf5] | 13 | * The license and distribution terms for this file may be |
---|
| 14 | * found in the file LICENSE in this distribution or at |
---|
[dd687d97] | 15 | * http://www.rtems.com/license/LICENSE. |
---|
[ac7d5ef0] | 16 | * |
---|
| 17 | * $Id$ |
---|
| 18 | */ |
---|
| 19 | |
---|
[092f142a] | 20 | #ifndef _RTEMS_SCORE_USEREXT_H |
---|
| 21 | #define _RTEMS_SCORE_USEREXT_H |
---|
[ac7d5ef0] | 22 | |
---|
| 23 | #ifdef __cplusplus |
---|
| 24 | extern "C" { |
---|
| 25 | #endif |
---|
| 26 | |
---|
[5e9b32b] | 27 | #include <rtems/score/interr.h> |
---|
| 28 | #include <rtems/score/chain.h> |
---|
| 29 | #include <rtems/score/thread.h> |
---|
[3a4ae6c] | 30 | |
---|
[c42d1a4] | 31 | typedef void User_extensions_routine RTEMS_COMPILER_DEPRECATED_ATTRIBUTE; |
---|
[05279b84] | 32 | |
---|
[baff4da] | 33 | /** |
---|
[c42d1a4] | 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 | * @{ |
---|
[baff4da] | 43 | */ |
---|
[05279b84] | 44 | |
---|
[baff4da] | 45 | /** |
---|
[c42d1a4] | 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. |
---|
[baff4da] | 65 | */ |
---|
[c42d1a4] | 66 | typedef bool ( *User_extensions_thread_create_extension )( |
---|
| 67 | Thread_Control *, |
---|
| 68 | Thread_Control * |
---|
| 69 | ); |
---|
[05279b84] | 70 | |
---|
[baff4da] | 71 | /** |
---|
[c42d1a4] | 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. |
---|
[baff4da] | 83 | */ |
---|
[c42d1a4] | 84 | typedef void( *User_extensions_thread_delete_extension )( |
---|
| 85 | Thread_Control *, |
---|
| 86 | Thread_Control * |
---|
| 87 | ); |
---|
[05279b84] | 88 | |
---|
[baff4da] | 89 | /** |
---|
[c42d1a4] | 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. |
---|
[baff4da] | 102 | */ |
---|
[c42d1a4] | 103 | typedef void( *User_extensions_thread_start_extension )( |
---|
| 104 | Thread_Control *, |
---|
| 105 | Thread_Control * |
---|
| 106 | ); |
---|
[05279b84] | 107 | |
---|
[baff4da] | 108 | /** |
---|
[c42d1a4] | 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. |
---|
[baff4da] | 121 | */ |
---|
[c42d1a4] | 122 | typedef void( *User_extensions_thread_restart_extension )( |
---|
| 123 | Thread_Control *, |
---|
| 124 | Thread_Control * |
---|
| 125 | ); |
---|
[05279b84] | 126 | |
---|
[baff4da] | 127 | /** |
---|
[c42d1a4] | 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. |
---|
[baff4da] | 143 | */ |
---|
[c42d1a4] | 144 | typedef void( *User_extensions_thread_switch_extension )( |
---|
| 145 | Thread_Control *, |
---|
| 146 | Thread_Control * |
---|
| 147 | ); |
---|
[05279b84] | 148 | |
---|
[baff4da] | 149 | /** |
---|
[c42d1a4] | 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. |
---|
[baff4da] | 157 | */ |
---|
[c42d1a4] | 158 | typedef void( *User_extensions_thread_begin_extension )( |
---|
| 159 | Thread_Control * |
---|
| 160 | ); |
---|
[05279b84] | 161 | |
---|
[baff4da] | 162 | /** |
---|
[c42d1a4] | 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. |
---|
[baff4da] | 170 | */ |
---|
[c42d1a4] | 171 | typedef void( *User_extensions_thread_exitted_extension )( |
---|
| 172 | Thread_Control * |
---|
| 173 | ); |
---|
[05279b84] | 174 | |
---|
[baff4da] | 175 | /** |
---|
[c42d1a4] | 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. |
---|
[baff4da] | 184 | */ |
---|
[c42d1a4] | 185 | typedef void( *User_extensions_fatal_extension )( |
---|
| 186 | Internal_errors_Source, |
---|
| 187 | bool, |
---|
| 188 | uint32_t |
---|
| 189 | ); |
---|
[3a4ae6c] | 190 | |
---|
[baff4da] | 191 | /** |
---|
[c42d1a4] | 192 | * @brief User extension table. |
---|
[baff4da] | 193 | */ |
---|
[3a4ae6c] | 194 | typedef struct { |
---|
[c42d1a4] | 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; |
---|
[3a4ae6c] | 203 | } User_extensions_Table; |
---|
[ac7d5ef0] | 204 | |
---|
[baff4da] | 205 | /** |
---|
[c42d1a4] | 206 | * @brief Manages the switch callouts. |
---|
| 207 | * |
---|
| 208 | * They are managed separately from other extensions for performance reasons. |
---|
[baff4da] | 209 | */ |
---|
[40c24d32] | 210 | typedef struct { |
---|
| 211 | Chain_Node Node; |
---|
| 212 | User_extensions_thread_switch_extension thread_switch; |
---|
| 213 | } User_extensions_Switch_control; |
---|
| 214 | |
---|
[baff4da] | 215 | /** |
---|
[c42d1a4] | 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. |
---|
[ac7d5ef0] | 220 | */ |
---|
| 221 | typedef struct { |
---|
[40c24d32] | 222 | Chain_Node Node; |
---|
| 223 | User_extensions_Switch_control Switch; |
---|
| 224 | User_extensions_Table Callouts; |
---|
[ac7d5ef0] | 225 | } User_extensions_Control; |
---|
| 226 | |
---|
[baff4da] | 227 | /** |
---|
[c42d1a4] | 228 | * @brief List of active extensions. |
---|
[ac7d5ef0] | 229 | */ |
---|
[c627b2a3] | 230 | SCORE_EXTERN Chain_Control _User_extensions_List; |
---|
[ac7d5ef0] | 231 | |
---|
[baff4da] | 232 | /** |
---|
[c42d1a4] | 233 | * @brief List of active task switch extensions. |
---|
[40c24d32] | 234 | */ |
---|
| 235 | SCORE_EXTERN Chain_Control _User_extensions_Switches_list; |
---|
| 236 | |
---|
[c42d1a4] | 237 | /** |
---|
| 238 | * @name Extension Maintainance |
---|
[c3db01d0] | 239 | * |
---|
[c42d1a4] | 240 | * @{ |
---|
[c3db01d0] | 241 | */ |
---|
| 242 | |
---|
[c42d1a4] | 243 | void _User_extensions_Handler_initialization( void ); |
---|
| 244 | |
---|
| 245 | void _User_extensions_Add_set( |
---|
| 246 | User_extensions_Control *extension |
---|
[c3db01d0] | 247 | ); |
---|
| 248 | |
---|
[3f727f98] | 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 | */ |
---|
| 255 | void _User_extensions_Add_API_set ( |
---|
| 256 | User_extensions_Control *the_extension |
---|
| 257 | ); |
---|
| 258 | |
---|
[c42d1a4] | 259 | RTEMS_INLINE_ROUTINE void _User_extensions_Add_set_with_table( |
---|
| 260 | User_extensions_Control *extension, |
---|
[c3db01d0] | 261 | User_extensions_Table *extension_table |
---|
[c42d1a4] | 262 | ) |
---|
| 263 | { |
---|
| 264 | extension->Callouts = *extension_table; |
---|
[c3db01d0] | 265 | |
---|
[c42d1a4] | 266 | _User_extensions_Add_set( extension ); |
---|
| 267 | } |
---|
| 268 | |
---|
| 269 | void _User_extensions_Remove_set( |
---|
| 270 | User_extensions_Control *extension |
---|
[c3db01d0] | 271 | ); |
---|
| 272 | |
---|
[c42d1a4] | 273 | /** @} */ |
---|
| 274 | |
---|
| 275 | /** |
---|
| 276 | * @name Extension Callout Dispatcher |
---|
[6a07436] | 277 | * |
---|
[c42d1a4] | 278 | * @{ |
---|
[ac7d5ef0] | 279 | */ |
---|
[c42d1a4] | 280 | |
---|
| 281 | bool _User_extensions_Thread_create( |
---|
| 282 | Thread_Control *created |
---|
[ac7d5ef0] | 283 | ); |
---|
| 284 | |
---|
[c42d1a4] | 285 | void _User_extensions_Thread_delete( |
---|
| 286 | Thread_Control *deleted |
---|
[ac7d5ef0] | 287 | ); |
---|
| 288 | |
---|
[c42d1a4] | 289 | void _User_extensions_Thread_start( |
---|
| 290 | Thread_Control *started |
---|
[ac7d5ef0] | 291 | ); |
---|
| 292 | |
---|
[c42d1a4] | 293 | void _User_extensions_Thread_restart( |
---|
| 294 | Thread_Control *restarted |
---|
[ac7d5ef0] | 295 | ); |
---|
| 296 | |
---|
[c42d1a4] | 297 | void _User_extensions_Thread_begin( |
---|
[ac7d5ef0] | 298 | Thread_Control *executing |
---|
| 299 | ); |
---|
| 300 | |
---|
[c42d1a4] | 301 | void _User_extensions_Thread_switch( |
---|
[c3db01d0] | 302 | Thread_Control *executing, |
---|
| 303 | Thread_Control *heir |
---|
| 304 | ); |
---|
| 305 | |
---|
[c42d1a4] | 306 | void _User_extensions_Thread_exitted( |
---|
[ac7d5ef0] | 307 | Thread_Control *executing |
---|
| 308 | ); |
---|
| 309 | |
---|
[c42d1a4] | 310 | void _User_extensions_Fatal( |
---|
| 311 | Internal_errors_Source source, |
---|
| 312 | bool is_internal, |
---|
| 313 | uint32_t error |
---|
[ac7d5ef0] | 314 | ); |
---|
| 315 | |
---|
[c42d1a4] | 316 | /** @} */ |
---|
| 317 | |
---|
| 318 | /** @} */ |
---|
| 319 | |
---|
[ac7d5ef0] | 320 | #ifdef __cplusplus |
---|
| 321 | } |
---|
| 322 | #endif |
---|
| 323 | |
---|
| 324 | #endif |
---|
| 325 | /* end of include file */ |
---|