1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. COMMENT: COPYRIGHT (c) 1988-2008. |
---|
4 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
5 | .. COMMENT: All rights reserved. |
---|
6 | |
---|
7 | .. index:: fatal errors |
---|
8 | |
---|
9 | .. _fatal_error_manager: |
---|
10 | |
---|
11 | Fatal Error Manager |
---|
12 | ******************* |
---|
13 | |
---|
14 | Introduction |
---|
15 | ============ |
---|
16 | |
---|
17 | The fatal error manager processes all fatal or irrecoverable errors and other |
---|
18 | sources of system termination (for example after :c:func:`exit()`). Fatal |
---|
19 | errors are identified by the (fatal source, error code) pair. The directives |
---|
20 | provided by the fatal error manager are: |
---|
21 | |
---|
22 | - rtems_fatal_ - Invoke the fatal error handler |
---|
23 | |
---|
24 | - rtems_panic_ - Print a message and invoke the fatal error handler |
---|
25 | |
---|
26 | - rtems_shutdown_executive_ - Shutdown RTEMS |
---|
27 | |
---|
28 | - rtems_exception_frame_print_ - Print the CPU exception frame |
---|
29 | |
---|
30 | - rtems_fatal_source_text_ - Return the fatal source text |
---|
31 | |
---|
32 | - rtems_internal_error_text_ - Return the error code text |
---|
33 | |
---|
34 | - rtems_fatal_error_occurred_ - Invoke the fatal error handler (deprecated) |
---|
35 | |
---|
36 | Background |
---|
37 | ========== |
---|
38 | |
---|
39 | .. index:: fatal error detection |
---|
40 | .. index:: fatal error processing |
---|
41 | .. index:: fatal error user extension |
---|
42 | |
---|
43 | Overview |
---|
44 | -------- |
---|
45 | |
---|
46 | The fatal error manager is called upon detection of an irrecoverable error |
---|
47 | condition by either RTEMS or the application software. Fatal errors are also |
---|
48 | used in case it is difficult or impossible to return an error condition by |
---|
49 | other means, e.g. a return value of a directive call. Fatal errors can be |
---|
50 | detected from various sources, for example |
---|
51 | |
---|
52 | - the executive (RTEMS), |
---|
53 | - support libraries, |
---|
54 | - user system code, and |
---|
55 | - user application code. |
---|
56 | |
---|
57 | RTEMS automatically invokes the fatal error manager upon detection of an error |
---|
58 | it considers to be fatal. Similarly, the user should invoke the fatal error |
---|
59 | manager upon detection of a fatal error. |
---|
60 | |
---|
61 | Each static or dynamic user extension set may include a fatal error handler. |
---|
62 | The fatal error handler in the static extension set can be used to provide |
---|
63 | access to debuggers and monitors which may be present on the target hardware. |
---|
64 | If any user-supplied fatal error handlers are installed, the fatal error |
---|
65 | manager will invoke them. Usually, the board support package provides a fatal |
---|
66 | error extension which resets the board. If no user handlers are configured or |
---|
67 | if all the user handler return control to the fatal error manager, then the |
---|
68 | RTEMS default fatal error handler is invoked. If the default fatal error |
---|
69 | handler is invoked, then the system state is marked as failed. |
---|
70 | |
---|
71 | Although the precise behavior of the default fatal error handler is processor |
---|
72 | specific, in general, it will disable all maskable interrupts, place the error |
---|
73 | code in a known processor dependent place (generally either on the stack or in |
---|
74 | a register), and halt the processor. The precise actions of the RTEMS fatal |
---|
75 | error are discussed in the Default Fatal Error Processing chapter of the |
---|
76 | Applications Supplement document for a specific target processor. |
---|
77 | |
---|
78 | Fatal Sources |
---|
79 | ------------- |
---|
80 | |
---|
81 | The following fatal sources are defined for RTEMS via the |
---|
82 | :c:type:`rtems_fatal_source` enumeration. Each symbolic name has the |
---|
83 | corresponding numeric fatal source in parenthesis. |
---|
84 | |
---|
85 | INTERNAL_ERROR_CORE (0) |
---|
86 | Errors of the core operating system. See :ref:`internal_errors`. |
---|
87 | |
---|
88 | INTERNAL_ERROR_RTEMS_API (1) |
---|
89 | Errors of the Classic API. |
---|
90 | |
---|
91 | INTERNAL_ERROR_POSIX_API (2) |
---|
92 | Errors of the POSIX API. |
---|
93 | |
---|
94 | RTEMS_FATAL_SOURCE_BDBUF (3) |
---|
95 | Fatal source for the block device cache. See |
---|
96 | :c:type:`rtems_bdbuf_fatal_code`. |
---|
97 | |
---|
98 | RTEMS_FATAL_SOURCE_APPLICATION (4) |
---|
99 | Fatal source for application-specific errors. The fatal code is |
---|
100 | application-specific. |
---|
101 | |
---|
102 | RTEMS_FATAL_SOURCE_EXIT (5) |
---|
103 | Fatal source of :c:func:`exit()`. The fatal code is the :c:func:`exit()` |
---|
104 | status code. |
---|
105 | |
---|
106 | RTEMS_FATAL_SOURCE_BSP (6) |
---|
107 | Fatal source for BSP errors. The fatal codes are defined in |
---|
108 | :file:`<bsp/fatal.h>`. Examples are interrupt and exception |
---|
109 | initialization. See :c:type:`bsp_fatal_code` and :c:func:`bsp_fatal()`. |
---|
110 | |
---|
111 | RTEMS_FATAL_SOURCE_ASSERT (7) |
---|
112 | Fatal source of :c:macro:`assert()`. The fatal code is the pointer value |
---|
113 | of the assert context. See :c:type:`rtems_assert_context`. |
---|
114 | |
---|
115 | RTEMS_FATAL_SOURCE_STACK_CHECKER (8) |
---|
116 | Fatal source of the stack checker. The fatal code is the object name of |
---|
117 | the executing task. |
---|
118 | |
---|
119 | RTEMS_FATAL_SOURCE_EXCEPTION (9) |
---|
120 | Fatal source of the exceptions. The fatal code is the pointer value of the |
---|
121 | exception frame pointer. See :c:type:`rtems_exception_frame` and |
---|
122 | :ref:`rtems_exception_frame_print`. |
---|
123 | |
---|
124 | RTEMS_FATAL_SOURCE_SMP (10) |
---|
125 | Fatal source of SMP domain. See :c:type:`SMP_Fatal_code`. |
---|
126 | |
---|
127 | RTEMS_FATAL_SOURCE_PANIC (11) |
---|
128 | Fatal source of :c:func:`rtems_panic`, see :ref:`rtems_panic`. |
---|
129 | |
---|
130 | RTEMS_FATAL_SOURCE_INVALID_HEAP_FREE (12) |
---|
131 | Fatal source for invalid C program heap frees via :c:func:`free`. The |
---|
132 | fatal code is the bad pointer. |
---|
133 | |
---|
134 | .. _internal_errors: |
---|
135 | |
---|
136 | Internal Error Codes |
---|
137 | -------------------- |
---|
138 | |
---|
139 | The following error codes are defined for the :c:data:`INTERNAL_ERROR_CORE` |
---|
140 | fatal source. Each symbolic name has the corresponding numeric error code in |
---|
141 | parenthesis. |
---|
142 | |
---|
143 | INTERNAL_ERROR_TOO_LITTLE_WORKSPACE (2) |
---|
144 | There is not enough memory for the workspace. This fatal error may occur |
---|
145 | during system initialization. It is an application configuration error. |
---|
146 | |
---|
147 | INTERNAL_ERROR_WORKSPACE_ALLOCATION (3) |
---|
148 | An allocation from the workspace failed. This fatal error may occur during |
---|
149 | system initialization. It is an application configuration error. |
---|
150 | |
---|
151 | INTERNAL_ERROR_INTERRUPT_STACK_TOO_SMALL (4) |
---|
152 | The configured interrupt stack size is too small. This fatal error may |
---|
153 | occur during system initialization. It is an application configuration |
---|
154 | error. |
---|
155 | |
---|
156 | INTERNAL_ERROR_THREAD_EXITTED (5) |
---|
157 | A non-POSIX thread entry function returned. This is an API usage error. |
---|
158 | |
---|
159 | An example code to provoke this fatal error is: |
---|
160 | |
---|
161 | .. code-block:: c |
---|
162 | |
---|
163 | void task( rtems_arg arg ) |
---|
164 | { |
---|
165 | /* Classic API tasks must not return */ |
---|
166 | } |
---|
167 | |
---|
168 | void create_bad_task( void ) |
---|
169 | { |
---|
170 | rtems_status_code sc; |
---|
171 | rtems_id task_id; |
---|
172 | |
---|
173 | sc = rtems_task_create( |
---|
174 | rtems_build_name('T', 'A', 'S', 'K'), |
---|
175 | 1, |
---|
176 | RTEMS_DEFAULT_MODES, |
---|
177 | RTEMS_DEFAULT_ATTRIBUTES, |
---|
178 | &task_id |
---|
179 | ); |
---|
180 | assert( sc == RTEMS_SUCCESSFUL ); |
---|
181 | |
---|
182 | sc = rtems_task_start( task_id, task, 0 ); |
---|
183 | assert( sc == RTEMS_SUCCESSFUL ); |
---|
184 | } |
---|
185 | |
---|
186 | INTERNAL_ERROR_INCONSISTENT_MP_INFORMATION (6) |
---|
187 | This fatal error can only occur on MPCI configurations. The MPCI nodes or |
---|
188 | global objects configuration is inconsistent. This fatal error may occur |
---|
189 | during system initialization. It is an application configuration error. |
---|
190 | |
---|
191 | INTERNAL_ERROR_INVALID_NODE (7) |
---|
192 | This fatal error can only occur on MPCI configurations. The own MPCI node |
---|
193 | number is invalid. This fatal error may occur during system |
---|
194 | initialization. It is an application configuration error. |
---|
195 | |
---|
196 | INTERNAL_ERROR_NO_MPCI (8) |
---|
197 | This fatal error can only occur on MPCI configurations. There is no MPCI |
---|
198 | configuration table. This fatal error may occur during system |
---|
199 | initialization. It is an application configuration error. |
---|
200 | |
---|
201 | INTERNAL_ERROR_BAD_PACKET (9) |
---|
202 | This fatal error can only occur on MPCI configurations. The MPCI server |
---|
203 | thread received a bad packet. |
---|
204 | |
---|
205 | INTERNAL_ERROR_OUT_OF_PACKETS (10) |
---|
206 | This fatal error can only occur on MPCI configurations. The MPCI packet |
---|
207 | pool is empty. It is an application configuration error. |
---|
208 | |
---|
209 | INTERNAL_ERROR_OUT_OF_GLOBAL_OBJECTS (11) |
---|
210 | This fatal error can only occur on MPCI configurations. The MPCI global |
---|
211 | objects pool is empty. It is an application configuration error. |
---|
212 | |
---|
213 | INTERNAL_ERROR_OUT_OF_PROXIES (12) |
---|
214 | This fatal error can only occur on MPCI configurations. The MPCI thread |
---|
215 | proxy pool is empty. It is an application configuration error. |
---|
216 | |
---|
217 | INTERNAL_ERROR_INVALID_GLOBAL_ID (13) |
---|
218 | This fatal error can only occur on MPCI configurations. The system cannot |
---|
219 | find the global object for a specific object identifier. In case this |
---|
220 | happens, then this is probably an operating system bug. |
---|
221 | |
---|
222 | INTERNAL_ERROR_BAD_STACK_HOOK (14) |
---|
223 | The stack allocator hook or stack free hook is NULL. This fatal error may |
---|
224 | occur during system initialization. It is an application configuration |
---|
225 | error. |
---|
226 | |
---|
227 | INTERNAL_ERROR_UNLIMITED_AND_MAXIMUM_IS_0 (19) |
---|
228 | An object class is configured to use the unlimited objects option, however, |
---|
229 | the count of objects for each extension is zero. This fatal error may |
---|
230 | occur during system initialization. It is an application configuration |
---|
231 | error. |
---|
232 | |
---|
233 | INTERNAL_ERROR_NO_MEMORY_FOR_HEAP (23) |
---|
234 | There is not enough memory for the C program heap. This fatal error may |
---|
235 | occur during system initialization. It is an application configuration |
---|
236 | error. |
---|
237 | |
---|
238 | INTERNAL_ERROR_CPU_ISR_INSTALL_VECTOR (24) |
---|
239 | The use of :c:func:`_CPU_ISR_install_vector()` is illegal on this system. |
---|
240 | |
---|
241 | INTERNAL_ERROR_RESOURCE_IN_USE (25) |
---|
242 | This fatal error can only occur on debug configurations. It happens in |
---|
243 | case a thread which owns mutexes is deleted. Mutexes owned by a deleted |
---|
244 | thread are in an inconsistent state. |
---|
245 | |
---|
246 | INTERNAL_ERROR_RTEMS_INIT_TASK_ENTRY_IS_NULL (26) |
---|
247 | An RTEMS initialization task entry function is NULL. This fatal error may |
---|
248 | occur during system initialization. It is an application configuration |
---|
249 | error. |
---|
250 | |
---|
251 | INTERNAL_ERROR_THREAD_QUEUE_DEADLOCK (28) |
---|
252 | A deadlock was detected during a thread queue enqueue operation. |
---|
253 | |
---|
254 | INTERNAL_ERROR_THREAD_QUEUE_ENQUEUE_STICKY_FROM_BAD_STATE (29) |
---|
255 | This fatal error can only happen in SMP configurations. It is not allowed |
---|
256 | to obtain MrsP semaphores in a context with thread dispatching disabled, |
---|
257 | for example interrupt context. |
---|
258 | |
---|
259 | An example code to provoke this fatal error is: |
---|
260 | |
---|
261 | .. code-block:: c |
---|
262 | |
---|
263 | void bad( rtems_id timer_id, void *arg ) |
---|
264 | { |
---|
265 | rtems_id *sem_id; |
---|
266 | |
---|
267 | sem_id = arg; |
---|
268 | |
---|
269 | rtems_semaphore_obtain( *sem_id, RTEMS_WAIT, RTEMS_NO_TIMEOUT ); |
---|
270 | assert( 0 ); |
---|
271 | } |
---|
272 | |
---|
273 | void fire_bad_timer( rtems_task_argument arg ) |
---|
274 | { |
---|
275 | rtems_status_code sc; |
---|
276 | rtems_id sem_id; |
---|
277 | rtems_id timer_id; |
---|
278 | |
---|
279 | sc = rtems_semaphore_create( |
---|
280 | rtems_build_name('M', 'R', 'S', 'P'), |
---|
281 | 1, |
---|
282 | RTEMS_MULTIPROCESSOR_RESOURCE_SHARING |
---|
283 | | RTEMS_BINARY_SEMAPHORE, |
---|
284 | 1, |
---|
285 | &sem_id |
---|
286 | ); |
---|
287 | assert( sc == RTEMS_SUCCESSFUL ); |
---|
288 | |
---|
289 | sc = rtems_timer_create( |
---|
290 | rtems_build_name( 'E', 'V', 'I', 'L' ), |
---|
291 | &timer_id |
---|
292 | ); |
---|
293 | assert( sc == RTEMS_SUCCESSFUL ); |
---|
294 | |
---|
295 | sc = rtems_semaphore_obtain( sem_id, RTEMS_WAIT, RTEMS_NO_TIMEOUT ); |
---|
296 | assert( sc == RTEMS_SUCCESSFUL ); |
---|
297 | |
---|
298 | sc = rtems_timer_fire_after( timer_id, 1, bad, &sem_id ); |
---|
299 | assert( sc == RTEMS_SUCCESSFUL ); |
---|
300 | |
---|
301 | rtems_task_wake_after( 2 ); |
---|
302 | assert( 0 ); |
---|
303 | } |
---|
304 | |
---|
305 | INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL (30) |
---|
306 | It is illegal to call blocking operating system services with thread |
---|
307 | dispatching disabled, for example in interrupt context. |
---|
308 | |
---|
309 | An example code to provoke this fatal error is: |
---|
310 | |
---|
311 | .. code-block:: c |
---|
312 | |
---|
313 | void bad( rtems_id id, void *arg ) |
---|
314 | { |
---|
315 | rtems_task_wake_after( RTEMS_YIELD_PROCESSOR ); |
---|
316 | assert( 0 ); |
---|
317 | } |
---|
318 | |
---|
319 | void fire_bad_timer( void ) |
---|
320 | { |
---|
321 | rtems_status_code sc; |
---|
322 | rtems_id id; |
---|
323 | |
---|
324 | sc = rtems_timer_create( |
---|
325 | rtems_build_name( 'E', 'V', 'I', 'L' ), |
---|
326 | &id |
---|
327 | ); |
---|
328 | assert( sc == RTEMS_SUCCESSFUL ); |
---|
329 | |
---|
330 | sc = rtems_timer_fire_after( id, 1, bad, NULL ); |
---|
331 | assert( sc == RTEMS_SUCCESSFUL ); |
---|
332 | |
---|
333 | rtems_task_wake_after( 2 ); |
---|
334 | assert( 0 ); |
---|
335 | } |
---|
336 | |
---|
337 | INTERNAL_ERROR_BAD_THREAD_DISPATCH_ENVIRONMENT (31) |
---|
338 | In SMP configurations, it is a fatal error to call blocking operating |
---|
339 | system with interrupts disabled, since this prevents delivery of |
---|
340 | inter-processor interrupts. This could lead to executing threads which are |
---|
341 | not allowed to execute resulting in undefined system behaviour. |
---|
342 | |
---|
343 | Some CPU ports, for example the ARM Cortex-M port, have a similar problem, |
---|
344 | since the interrupt state is not a part of the thread context. |
---|
345 | |
---|
346 | This fatal error is detected in the operating system core function |
---|
347 | :c:func:`_Thread_Do_dispatch()` responsible to carry out a thread dispatch. |
---|
348 | |
---|
349 | An example code to provoke this fatal error is: |
---|
350 | |
---|
351 | .. code-block:: c |
---|
352 | |
---|
353 | void bad( void ) |
---|
354 | { |
---|
355 | rtems_interrupt_level level; |
---|
356 | |
---|
357 | rtems_interrupt_local_disable( level ); |
---|
358 | rtems_task_suspend( RTEMS_SELF ); |
---|
359 | rtems_interrupt_local_enable( level ); |
---|
360 | } |
---|
361 | |
---|
362 | INTERNAL_ERROR_RTEMS_INIT_TASK_CREATE_FAILED (32) |
---|
363 | Creation of an RTEMS initialization task failed. This fatal error may |
---|
364 | occur during system initialization. It is an application configuration |
---|
365 | error. |
---|
366 | |
---|
367 | INTERNAL_ERROR_POSIX_INIT_THREAD_CREATE_FAILED (33) |
---|
368 | Creation of a POSIX initialization thread failed. This fatal error may |
---|
369 | occur during system initialization. It is an application configuration |
---|
370 | error. |
---|
371 | |
---|
372 | INTERNAL_ERROR_LIBIO_USER_ENV_KEY_CREATE_FAILED (34) |
---|
373 | Creation of the IO library user environment POSIX key failed. This fatal |
---|
374 | error may occur during system initialization. It is an application |
---|
375 | configuration error. |
---|
376 | |
---|
377 | INTERNAL_ERROR_LIBIO_SEM_CREATE_FAILED (35) |
---|
378 | Creation of the IO library semaphore failed. This fatal error may occur |
---|
379 | during system initialization. It is an application configuration error. |
---|
380 | |
---|
381 | INTERNAL_ERROR_LIBIO_STDOUT_FD_OPEN_FAILED (36) |
---|
382 | Open of the standard output file descriptor failed or resulted in an |
---|
383 | unexpected file descriptor number. This fatal error may occur during |
---|
384 | system initialization. It is an application configuration error. |
---|
385 | |
---|
386 | INTERNAL_ERROR_LIBIO_STDERR_FD_OPEN_FAILED (37) |
---|
387 | Open of the standard error file descriptor failed or resulted in an |
---|
388 | unexpected file descriptor number. This fatal error may occur during |
---|
389 | system initialization. It is an application configuration error. |
---|
390 | |
---|
391 | INTERNAL_ERROR_ILLEGAL_USE_OF_FLOATING_POINT_UNIT (38) |
---|
392 | The floating point unit was used illegally, for example in interrupt |
---|
393 | context on some architectures. |
---|
394 | |
---|
395 | INTERNAL_ERROR_ARC4RANDOM_GETENTROPY_FAIL (39) |
---|
396 | A :c:func:`getentropy` system call failed in one of the `ARC4RANDOM(3) |
---|
397 | <https://man.openbsd.org/arc4random.3>`_ functions. This fatal error can |
---|
398 | only be fixed with a different implementation of :c:func:`getentropy`. |
---|
399 | |
---|
400 | Operations |
---|
401 | ========== |
---|
402 | |
---|
403 | .. index:: _Terminate |
---|
404 | |
---|
405 | .. _Terminate: |
---|
406 | |
---|
407 | Announcing a Fatal Error |
---|
408 | ------------------------ |
---|
409 | |
---|
410 | The :c:func:`_Terminate()` internal error handler is invoked when the |
---|
411 | application or the executive itself determines that a fatal error has occurred |
---|
412 | or a final system state is reached (for example after :c:func:`rtems_fatal()` |
---|
413 | or :c:func:`exit()`). |
---|
414 | |
---|
415 | The first action of the internal error handler is to call the fatal extension of |
---|
416 | the user extensions. For the initial extensions the following conditions are |
---|
417 | required |
---|
418 | |
---|
419 | - a valid stack pointer and enough stack space, |
---|
420 | |
---|
421 | - a valid code memory, and |
---|
422 | |
---|
423 | - valid read-only data. |
---|
424 | |
---|
425 | For the initial extensions the read-write data (including .bss segment) is not |
---|
426 | required on single processor configurations. In SMP configurations, however, |
---|
427 | the read-write data must be initialized since this function must determine the |
---|
428 | state of the other processors and request them to shut-down if necessary. |
---|
429 | |
---|
430 | Non-initial extensions require in addition valid read-write data. The board |
---|
431 | support package (BSP) may install an initial extension that performs a system |
---|
432 | reset. In this case the non-initial extensions will be not called. |
---|
433 | |
---|
434 | The fatal extensions are called with three parameters: |
---|
435 | |
---|
436 | - the fatal source, |
---|
437 | |
---|
438 | - a legacy parameter which is always false, and |
---|
439 | |
---|
440 | - an error code with a fatal source dependent content. |
---|
441 | |
---|
442 | Once all fatal extensions executed, the error information will be stored to |
---|
443 | :c:data:`_Internal_errors_What_happened` and the system state is set to |
---|
444 | :c:macro:`SYSTEM_STATE_TERMINATED`. |
---|
445 | |
---|
446 | The final step is to call the CPU port specific :c:func:`_CPU_Fatal_halt()`. |
---|
447 | |
---|
448 | Directives |
---|
449 | ========== |
---|
450 | |
---|
451 | This section details the fatal error manager's directives. A subsection is |
---|
452 | dedicated to each of this manager's directives and describes the calling |
---|
453 | sequence, related constants, usage, and status codes. |
---|
454 | |
---|
455 | .. raw:: latex |
---|
456 | |
---|
457 | \clearpage |
---|
458 | |
---|
459 | .. index:: announce fatal error |
---|
460 | .. index:: fatal error, announce |
---|
461 | .. index:: rtems_fatal |
---|
462 | |
---|
463 | .. _rtems_fatal: |
---|
464 | |
---|
465 | FATAL - Invoke the fatal error handler |
---|
466 | -------------------------------------- |
---|
467 | |
---|
468 | CALLING SEQUENCE: |
---|
469 | .. code-block:: c |
---|
470 | |
---|
471 | void rtems_fatal( |
---|
472 | rtems_fatal_source fatal_source, |
---|
473 | rtems_fatal_code error_code |
---|
474 | ) RTEMS_NO_RETURN; |
---|
475 | |
---|
476 | DIRECTIVE STATUS CODES: |
---|
477 | NONE - This function will not return to the caller. |
---|
478 | |
---|
479 | DESCRIPTION: |
---|
480 | This directive terminates the system. |
---|
481 | |
---|
482 | NOTE: |
---|
483 | Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not |
---|
484 | called. Use :c:func:`exit()` in case these handlers should be invoked. |
---|
485 | |
---|
486 | .. raw:: latex |
---|
487 | |
---|
488 | \clearpage |
---|
489 | |
---|
490 | .. index:: panic |
---|
491 | .. index:: rtems_panic |
---|
492 | |
---|
493 | .. _rtems_panic: |
---|
494 | |
---|
495 | PANIC - Print a message and invoke the fatal error handler |
---|
496 | ---------------------------------------------------------- |
---|
497 | |
---|
498 | CALLING SEQUENCE: |
---|
499 | .. code-block:: c |
---|
500 | |
---|
501 | void rtems_panic( |
---|
502 | const char *fmt, |
---|
503 | ... |
---|
504 | ) RTEMS_NO_RETURN RTEMS_PRINTFLIKE( 1, 2 ); |
---|
505 | |
---|
506 | DIRECTIVE STATUS CODES: |
---|
507 | NONE - This function will not return to the caller. |
---|
508 | |
---|
509 | DESCRIPTION: |
---|
510 | This directive prints a message via :c:func:`printk` specified by the |
---|
511 | format and optional parameters and then terminates the system with the |
---|
512 | :c:macro:`RTEMS_FATAL_SOURCE_PANIC` fatal source. The fatal code is set to |
---|
513 | the format string address. |
---|
514 | |
---|
515 | NOTE: |
---|
516 | Registered :c:func:`atexit()` or :c:func:`on_exit()` handlers are not |
---|
517 | called. Use :c:func:`exit()` in case these handlers should be invoked. |
---|
518 | |
---|
519 | .. raw:: latex |
---|
520 | |
---|
521 | \clearpage |
---|
522 | |
---|
523 | .. index:: shutdown RTEMS |
---|
524 | .. index:: rtems_shutdown_executive |
---|
525 | |
---|
526 | .. _rtems_shutdown_executive: |
---|
527 | |
---|
528 | SHUTDOWN_EXECUTIVE - Shutdown RTEMS |
---|
529 | ----------------------------------- |
---|
530 | |
---|
531 | CALLING SEQUENCE: |
---|
532 | .. code-block:: c |
---|
533 | |
---|
534 | void rtems_shutdown_executive( |
---|
535 | uint32_t result |
---|
536 | ); |
---|
537 | |
---|
538 | DIRECTIVE STATUS CODES: |
---|
539 | NONE - This function will not return to the caller. |
---|
540 | |
---|
541 | DESCRIPTION: |
---|
542 | This directive is called when the application wishes to shutdown RTEMS. |
---|
543 | The system is terminated with a fatal source of ``RTEMS_FATAL_SOURCE_EXIT`` |
---|
544 | and the specified ``result`` code. |
---|
545 | |
---|
546 | NOTES: |
---|
547 | This directive *must* be the last RTEMS directive invoked by an application |
---|
548 | and it *does not return* to the caller. |
---|
549 | |
---|
550 | This directive may be called any time. |
---|
551 | |
---|
552 | .. raw:: latex |
---|
553 | |
---|
554 | \clearpage |
---|
555 | |
---|
556 | .. index:: exception frame |
---|
557 | .. index:: rtems_exception_frame_print |
---|
558 | |
---|
559 | .. _rtems_exception_frame_print: |
---|
560 | |
---|
561 | EXCEPTION_FRAME_PRINT - Prints the exception frame |
---|
562 | -------------------------------------------------- |
---|
563 | |
---|
564 | CALLING SEQUENCE: |
---|
565 | .. code-block:: c |
---|
566 | |
---|
567 | void rtems_exception_frame_print( |
---|
568 | const rtems_exception_frame *frame |
---|
569 | ); |
---|
570 | |
---|
571 | DIRECTIVE STATUS CODES: |
---|
572 | NONE |
---|
573 | |
---|
574 | DESCRIPTION: |
---|
575 | Prints the exception frame via ``printk()``. |
---|
576 | |
---|
577 | .. raw:: latex |
---|
578 | |
---|
579 | \clearpage |
---|
580 | |
---|
581 | .. index:: fatal error |
---|
582 | .. index:: rtems_fatal_source_text |
---|
583 | |
---|
584 | .. _rtems_fatal_source_text: |
---|
585 | |
---|
586 | FATAL_SOURCE_TEXT - Returns a text for a fatal source |
---|
587 | ----------------------------------------------------- |
---|
588 | |
---|
589 | CALLING SEQUENCE: |
---|
590 | .. code-block:: c |
---|
591 | |
---|
592 | const char *rtems_fatal_source_text( |
---|
593 | rtems_fatal_source source |
---|
594 | ); |
---|
595 | |
---|
596 | DIRECTIVE STATUS CODES: |
---|
597 | The fatal source text or "?" in case the passed fatal source is invalid. |
---|
598 | |
---|
599 | DESCRIPTION: |
---|
600 | Returns a text for a fatal source. The text for fatal source is the |
---|
601 | enumerator constant. |
---|
602 | |
---|
603 | .. raw:: latex |
---|
604 | |
---|
605 | \clearpage |
---|
606 | |
---|
607 | .. index:: fatal error |
---|
608 | .. index:: rtems_internal_error_text |
---|
609 | |
---|
610 | .. _rtems_internal_error_text: |
---|
611 | |
---|
612 | INTERNAL_ERROR_TEXT - Returns a text for an internal error code |
---|
613 | --------------------------------------------------------------- |
---|
614 | |
---|
615 | CALLING SEQUENCE: |
---|
616 | .. code-block:: c |
---|
617 | |
---|
618 | const char *rtems_internal_error_text( |
---|
619 | rtems_fatal_code error |
---|
620 | ); |
---|
621 | |
---|
622 | DIRECTIVE STATUS CODES: |
---|
623 | The error code text or "?" in case the passed error code is invalid. |
---|
624 | |
---|
625 | DESCRIPTION: |
---|
626 | Returns a text for an internal error code. The text for each internal |
---|
627 | error code is the enumerator constant. |
---|
628 | |
---|
629 | .. raw:: latex |
---|
630 | |
---|
631 | \clearpage |
---|
632 | |
---|
633 | .. index:: announce fatal error |
---|
634 | .. index:: fatal error, announce |
---|
635 | .. index:: rtems_fatal_error_occurred |
---|
636 | |
---|
637 | .. _rtems_fatal_error_occurred: |
---|
638 | |
---|
639 | FATAL_ERROR_OCCURRED - Invoke the fatal error handler (deprecated) |
---|
640 | ------------------------------------------------------------------ |
---|
641 | |
---|
642 | CALLING SEQUENCE: |
---|
643 | .. code-block:: c |
---|
644 | |
---|
645 | void rtems_fatal_error_occurred( |
---|
646 | uint32_t the_error |
---|
647 | ) RTEMS_NO_RETURN; |
---|
648 | |
---|
649 | DIRECTIVE STATUS CODES: |
---|
650 | NONE - This function will not return to the caller. |
---|
651 | |
---|
652 | DESCRIPTION: |
---|
653 | This directive processes fatal errors. If the FATAL error extension is |
---|
654 | defined in the configuration table, then the user-defined error extension |
---|
655 | is called. If configured and the provided FATAL error extension returns, |
---|
656 | then the RTEMS default error handler is invoked. This directive can be |
---|
657 | invoked by RTEMS or by the user's application code including initialization |
---|
658 | tasks, other tasks, and ISRs. |
---|
659 | |
---|
660 | NOTES: |
---|
661 | This directive is deprecated and should not be used in new code. |
---|
662 | |
---|
663 | This directive supports local operations only. |
---|
664 | |
---|
665 | Unless the user-defined error extension takes special actions such as |
---|
666 | restarting the calling task, this directive WILL NOT RETURN to the caller. |
---|
667 | |
---|
668 | The user-defined extension for this directive may wish to initiate a global |
---|
669 | shutdown. |
---|