1 2 3 4 5 6 7 8 9 10 11 12
13 14 15
16
17 /*!
18 * ======== Error ========
19 * Runtime error manager
20 *
21 * The `Error` module provides mechanisms for raising, checking, and
22 * handling errors in a program. At the configuration time, you can use the
23 * parameters `{@link Error#policy Error.policy}`,
24 * `{@link Error#policyFxn Error.policyFxn}` and
25 * `{@link Error#raiseHook Error.raiseHook}` to specify what happens when an
26 * error takes place. You can control how much debugging information is
27 * available in that case, while also controlling the memory footprint that the
28 * `Error' module adds to the program.
29 *
30 * Module producers use this module to define specific error types and
31 * reference these when raising an error. Each error type has a custom error
32 * message and can be parameterized with up to `{@link #NUMARGS}` arguments. A
33 * generic error type is provided for raising errors when not in a module.
34 *
35 * Use the `{@link #check Error_check()}` function in your application or
36 * module to determine if an error has been raised in a function that takes an
37 * `{@link #Block Error_Block}` as an argument. It is important to understand
38 * that it is the caller's responsibility to check the error block after
39 * calling such a function. Otherwise, a raised error may go undetected, which
40 * could compromise the integrity of the system. For example:
41 *
42 * @p(code)
43 * Task_create(..., &eb);
44 *
45 * if (Error_check(&eb)) {
46 * ...an error has been raised...
47 * }
48 * @p
49 *
50 * The function assigned to the parameter
51 * `{@link Error#policyFxn Error.policyFxn}` is the central part of the
52 * error handling mechanism in this module. Most of the users will either leave
53 * this parameter at its default value, or select one of the alternative
54 * implementations that are included with the `Error` module. However, this
55 * configuration parameter also allows users to completely take over the error
56 * handling by setting this parameter to their own implementation. In that
57 * case, we recommend that users first review the included implementations,
58 * and base their implementation on one of these function. The included
59 * implementations are `{@link #policyDefault}`, `{@link #policyMin}`, and
60 * `{@link #policySpin}`.
61 *
62 * The `{@link #raiseHook Error.raiseHook}` configuration parameter allows
63 * a configured function to be invoked when an error is raised.
64 * This function is invoked from the default implementation of
65 * `{@link Error#policyFxn Error.policyFxn}`. Therefore, if a different
66 * implementation of `Error.policyFxn` is used, the function specified by
67 * `Error.raiseHook` may or may not be called.
68 * This function is passed a pointer to the error's error block and makes it
69 * easy to manage all errors from a common point. For example, you can
70 * trap any error (fatal or not) by simply setting a breakpoint in this
71 * function. You can use the following functions to extract information
72 * from an error block.
73 *
74 * @p(blist)
75 * - `{@link #getData Error_getData()}`
76 * - `{@link #getCode Error_getCode()}`
77 * - `{@link #getId Error_getId()}`
78 * - `{@link #getMsg Error_getMsg()}`
79 * - `{@link #getSite Error_getSite()}`
80 * @p
81 *
82 * The Error module provides facilities for handling errors, but the Log
83 * module also provides features for logging error events. These are separate
84 * concepts; however, to ensure that users do not have to both raise and log
85 * an error, the Error module will automatically log an error event when one
86 * is raised. The Error module logs the standard {@link Log#L_error} event,
87 * passing it the error message and arguments.
88 *
89 * The error event is logged to the Error module's logger using the Error
90 * module's diags mask. Logging of errors is enabled by default in the diags
91 * mask, but the event will not be logged unless a logger is configured for
92 * the Error module as well.
93 *
94 * To make the error event appear as though it is coming from the module which
95 * called Error_raise, the event is logged with the caller's module id and
96 * with the caller's call site information.
97 *
98 * @a(Examples)
99 * Example 1: The following example shows how a module, named ModA,
100 * defines a custom error type and shows how this error is raised by
101 * the module. The module defines an `Id` of `E_notEven` in its module
102 * specification file (in this case, `ModA.xdc`). The error's message
103 * string takes only one argument. The module also defines a `mayFail()`
104 * function that takes an error block. In the module's C source file,
105 * the function checks for the error condition and raises the error if
106 * needed.
107 *
108 * This is part of ModA's XDC specification file for the module:
109 *
110 * @p(code)
111 * config xdc.runtime.Error.Id E_notEven = {
112 * msg: "expected an even number (%d)"
113 * };
114 *
115 * Void mayFail(Int x, xdc.runtime.Error.Block *eb);
116 * @p
117 *
118 * This is part of the C code for the module:
119 *
120 * @p(code)
121 * Void ModA_mayFail(Int x, Error_Block *eb)
122 * {
123 * if ((x % 2) != 0) {
124 * Error_raise(eb, ModA_E_notEven, x, 0);
125 * ...add error handling code here...
126 * return;
127 * }
128 * ...
129 * }
130 * @p
131 *
132 * @p(html)
133 * <hr />
134 * @p
135 *
136 * Example 2: The following C code supplies an error block to a function
137 * that requires one and tests the error block to see if the function
138 * raised an error. Note that an error block must be initialized before
139 * it can be used and same error block may be passed to several functions.
140 *
141 * @p(code)
142 * #include <xdc/runtime/Error.h>
143 * #include <ti/sysbios/knl/Task.h>
144 * Error_Block eb;
145 * Task_Handle tsk;
146 *
147 * Error_init(&eb);
148 * tsk = Task_create(..., &eb);
149 *
150 * if (Error_check(&eb)) {
151 * ...an error has been raised...
152 * }
153 * @p
154 *
155 * @p(html)
156 * <hr />
157 * @p
158 *
159 * Example 3: The following C code shows that you may pass a special constant
160 * `Error_ABORT` in place of an error block to a function requiring an error
161 * block. In this case, if the function raises an error, the program is aborted
162 * (via `{@link System#abort xdc_runtime_System_abort()}`), thus execution
163 * control will never return to the caller.
164 *
165 * @p(code)
166 * #include <xdc/runtime/Error.h>
167 * #include <ti/sysbios/knl/Task.h>
168 *
169 * tsk = Task_create(..., Error_ABORT);
170 * ...will never get here if an error was raised in Task_create...
171 * @p
172 *
173 * @p(html)
174 * <hr />
175 * @p
176 *
177 * Example 4: The following C code shows that you may pass a special constant
178 * `Error_IGNORE` in place of an error block to a function requiring an error
179 * block. The purpose of this constant is to avoid allocating an error block on
180 * stack in the use case where the caller is not checking the error block after
181 * the call returns.
182 * In this example, the caller only checks the returned value but not the error
183 * block. If the function raises an error, the program will return to the
184 * caller, assuming `Error_policy` is set to `{@link #Policy UNWIND}`.
185 *
186 * @p(code)
187 * #include <xdc/runtime/Error.h>
188 * #include <ti/sysbios/knl/Task.h>
189 *
190 * tsk = Task_create(..., Error_IGNORE);
191 * if (tsk != NULL) {
192 * ...
193 * }
194 * @p
195 *
196 * @p(html)
197 * <hr />
198 * @p
199 *
200 * Example 5: The following C code shows how to write a function that is not a
201 * part of a module. The function accepts an error block as a parameter and
202 * raises an error of the generic error type provided by the Error module.
203 * Note that if the caller passes `Error_ABORT` for the error block or if the
204 * error policy is `{@link #Policy TERMINATE}`, then the call to
205 * `{@link #raise Error_raise()}` will call
206 * `{@link System#abort xdc_runtime_System_abort()}` and never return.
207 *
208 * @p(code)
209 * #include <xdc/runtime/Error.h>
210 *
211 * Void myFunc(..., Error_Block *eb)
212 * {
213 * ...
214 *
215 * if (...error condition detected...) {
216 * String myErrorMsg = "my custom error message";
217 * Error_raise(eb, Error_E_generic, myErrorMsg, 0);
218 * ...add error handling code here...
219 * return;
220 * }
221 * }
222 * @p
223 */
224 @DirectCall
225 @Template("./Error.xdt")
226
227 module Error {
228
229 /*!
230 * ======== Policy ========
231 * Error handling policies
232 *
233 * These constants are assigned to `{@link Error#policy Error.policy}` to
234 * control the flow of the program when an error is raised.
235 *
236 * @field(TERMINATE) All raised errors are fatal. A call to
237 * `{@link #raise Error_raise}` will never return to the caller. The
238 * program calls `System_abort` instead.
239 *
240 * @field(UNWIND) Errors are returned to the caller. A call to
241 * `{@link #raise Error_raise}` will return back to the caller.
242 */
243
244 enum Policy {
245 TERMINATE,
246 UNWIND
247 };
248
249 /*!
250 * ======== Desc ========
251 * Error descriptor
252 *
253 * Each type of error is defined with an error descriptor. This
254 * structure groups common information about the errors of this type.
255 *
256 * @field(msg) The error message using a `printf` style format string,
257 * but limited to `{@link #NUMARGS}` arguments.
258 * This format string together with the two arguments passed
259 * to `Error_raise`` are used to create a human readable
260 * error message.
261 *
262 * @field(code) A user assignable code, 0 by default. The user may
263 * optionally set this field during config to give the
264 * error a well-known numeric code.
265 */
266
267 metaonly struct Desc {
268 String msg;
269 UInt16 code;
270 };
271
272 /*!
273 * ======== Id ========
274 * Error identifier
275 *
276 * Each type of error raised is defined with a metaonly
277 * `{@link Error#Desc}`. An `Error_Id` is a 32-bit target value that
278 * encodes the information in the `Desc`. Target programs use
279 * `Error_Id` values to "raise" and check for specific errors.
280 *
281 * @a(Warning) `{@link #Id}` values may vary among different
282 * configurations of an application. For example, the addition of a
283 * new module to a program may result in a different absolute value for
284 * `{@link #E_generic}`. If you need error numbers that remain
285 * invariant, use the user definable `{@link #Desc Desc.code}` field.
286 */
287
288 @Encoded typedef Desc Id;
289
290 /*!
291 * ======== HookFxn ========
292 * Function type for a function called whenever an error is raised
293 *
294 * The only parameter passed to a function of this type is a pointer to an
295 * `Error_Block`. Even if the client passes a `NULL` error block pointer
296 * to `{@link #raise Error_raise}`, the function `Error_raise` will
297 * ensure that the argument passed to this "hook" function is always
298 * `non-NULL`.
299 */
300 typedef Void (*HookFxn)(Block *);
301
302 /*!
303 * ======== NUMARGS ========
304 * Maximum number of arguments supported by an error
305 */
306
307 const Int NUMARGS = 2;
308
309 /*!
310 * ======== Data ========
311 * Error args
312 *
313 * The two arguments (arg1, arg2) passed to `{@link #raise}` are stored
314 * within the associated Error_Block. To access these arguments use
315 * `{@link #getData}` to obtain a pointer to the Error_Block's Data array.
316 *
317 * @see #getData
318 */
319
320 struct Data {
321 IArg arg[NUMARGS];
322 }
323
324 /*!
325 * ======== Block ========
326 * Error block
327 *
328 * An opaque structure used to store information about errors once raised.
329 * This structure must be initialized via `{@link #init Error_init()}`
330 * before being used for the first time.
331 */
332 @Opaque struct Block {
333 UInt16 unused;
334 Data data;
335 Id id;
336 CString msg;
337 Types.Site site;
338 };
339
340 /*!
341 * ======== IGNORE ========
342 * A pointer to a special Error_Block used when the caller does not want to
343 * check Error_Block
344 *
345 * This constant should be used when the caller does not plan to check
346 * `Error_Block` after the call returns, but wants the call to return even
347 * in the case when an error is raised. `{@link #policy Error_policy}` is
348 * still in effect and the application will still terminate when an error
349 * is raised if `Error_policy` is not set to
350 * `{@link #Policy Error_UNWIND}`.
351 */
352
353 const Block IGNORE;
354
355 /*!
356 * ======== ABORT ========
357 * A special Error_Block pointer that terminates the application in case of
358 * an error
359 *
360 * This constant has the same effect as passing `NULL` in place of an
361 * `Error_Block`. If an error is raised when `Error_ABORT` is passed, the
362 * application terminates regardless of `{@link #policy Error_policy}`.
363 */
364
365 const Block ABORT;
366
367 /*!
368 * ======== PolicyFxn ========
369 * Error policy function signature
370 *
371 * @a(Parameters)
372 * A policy function is passed the following parameters:
373 * @p(dlist)
374 * - `eb`
375 * A pointer to an `{@link #Block Error_Block}` structure to be
376 * initialized using the subsequent arguments. This pointer may
377 * be `NULL`.
378 * - `modId`
379 * The module ID of the module calling
380 * `{@link #raise Error_raise()}`
381 * - `fileName`
382 * A string naming the source file which made the call to
383 * `{@link #raise Error_raise()}`
384 * - `lineNumber`
385 * An integer line number within the file named above where
386 * the call `{@link #raise Error_raise()}` occured
387 * - `errId`
388 * The `{@link #Id Error_Id}` of the error being raised
389 * - `arg1` and `arg2`
390 * Two `IArg` arguments associated with the error being raised
391 * @p
392 */
393 typedef Void (*PolicyFxn)(Block *, Types.ModuleId, CString, Int, Id,
394 IArg, IArg);
395
396 /*!
397 * ======== policyFxn ========
398 * Error handler function
399 *
400 * This function is called to handle all raised errors but, unlike
401 * `{@link raiseHook}`, this function is responsible for completely
402 * handling the error (including calling `{@link #raiseHook raiseHook}`
403 * with an appropriately initialized `{@link #Block Error_Block}`, if
404 * `raiseHook` functionality is required).
405 *
406 * The default value is a function which, in addition to calling
407 * `raiseHook` with an initialized `Error_Block` structure, logs the
408 * error using this module's logger.
409 *
410 * Alternately, `{@link #policySpin}`, which simply loops indefinitely, can
411 * be used to minimize target footprint. Note, this function does NOT call
412 * `raiseHook`, and also ignores `{@link Error#policy Error.policy}`.
413 *
414 * The third implementation, `{@link #policyMin}` finds a middle ground
415 * between the two implementations above in terms of memory footprint and
416 * the available error information. Only the `{@link #Id Error_Id}` of the
417 * error being raised is available in the resulting `Error_Block`,
418 * `raiseHook` is not invoked, but `{@link Error#policy Error.policy}` is
419 * observed.
420 *
421 * Implementations of `policyFxn` are allowed to ignore `Error.policy` and
422 * the special `Error_Block` constants `{@link #IGNORE}` and
423 * `{@link #ABORT}`, as well as NULL, passed instead of an initialized
424 * `Error_Block`. However, it is recommended to observe as much as
425 * possible these special cases in order to make the code invoking
426 * `Error_raise` independent from `policyFxn` implementations.
427 * For example, the SYS/BIOS kernel assumes all `Error_raise` calls with
428 * NULL `Error_Block` are going to terminate the application.
429 *
430 */
431
432 config PolicyFxn policyFxn = Error.policyDefault;
433
434 /*!
435 * ======== E_generic ========
436 * Generic error
437 *
438 * This error takes advantage of the $S specifier to allow for recursive
439 * formatting of the error message passed to error raise.
440 *
441 * For example, the following is possible:
442 * @p(code)
443 * Error_raise(eb, Error_E_generic, "Error occurred, code: %d", code);
444 * @p
445 *
446 * @see System#extendedFormats
447 * @see System#printf
448 */
449
450 config Id E_generic = {msg: "%$S"};
451
452 /*!
453 * ======== E_memory ========
454 * Out of memory error
455 *
456 * The first parameter must be the heap instance handle. The second
457 * parameter is the size of the object for which the allocation failed.
458 */
459 config Id E_memory = {msg: "out of memory: heap=0x%x, size=%u"};
460
461 /*!
462 * ======== E_msgCode ========
463 * Generic error that displays a string and a numeric value
464 */
465 config Id E_msgCode = {msg: "%s 0x%x"};
466
467 /*!
468 * ======== policy ========
469 * System-wide error handling policy
470 *
471 * You can use this parameter to decide at the configuration time what
472 * happens when an error is raised. The program can either call
473 * `System_abort()` or return back to the caller. The implementations of
474 * `{@link Error#policyFxn Error.policyFxn}` should consider this
475 * parameter, but some implementations may not do so to save the memory
476 * footprint (`Error_policySpin`, for example).
477 *
478 */
479
480 config Policy policy = UNWIND;
481
482 /*!
483 * ======== raiseHook ========
484 * The function to call whenever an error is raised
485 *
486 * If set to a non-`null` value, the referenced function is always
487 * called when an error is raised, even if the `Error` policy is
488 * `{@link #Policy TERMINATE}`. In rare cases, it is possible that a
489 * raised error does not trigger a call to `raiseHook`; see
490 * `{@link #maxDepth}`.
491 *
492 * Regardless of the current policy in use, raising an error by calling
493 * `{@link #raise Error_raise}` will always invoke the error raise hook
494 * function assigned to the `{@link #raiseHook Error.raiseHook}`
495 * configuration parameter, if the default
496 * `{@link Error#policyFxn Error.policyFxn}` implementation is used.
497 *
498 *
499 * By default, this function is set to `{@link #print Error_print}`
500 * which causes the error to be formatted and output via
501 * `{@link xdc.runtime.System#aprintf System_printf}`. Setting this
502 * configuration parameter to `null` indicates that no function hook
503 * should be called.
504 *
505 * @see #maxDepth
506 * @see #HookFxn
507 * @see #print
508 */
509
510 config HookFxn raiseHook = Error.print;
511
512 /*!
513 * ======== maxDepth ========
514 * Maximum number of concurrent calls to `{@link #raiseHook}`
515 *
516 * To prevent errors that occur in the raiseHook function from
517 * causing an infinite recursion, the maximum number of concurrent
518 * calls to `{@link #raiseHook}` is limited by `Error_maxDepth`. If
519 * the number of concurrent calls exceeds `Error_maxDepth`, the
520 * `raiseHook` function is not called.
521 *
522 * In multi-threaded systems, errors raised by separate threads may
523 * be detected as recursive calls to `raiseHook`. So, setting
524 * `Error.maxDepth` to a small value may - in rare instances - result in
525 * `errorHook` not being called for some raised errors.
526 *
527 * If it is important that all raised errors trigger a call to the
528 * `raiseHook` function, set `Error.maxDepth` to an impossibly large
529 * number (0xffff) and either ensure that the raise hook never calls a
530 * function that can raise an error or add checks in `raiseHook` to
531 * protect against "double faults".
532 */
533
534 config UInt16 maxDepth = 16;
535
536 /*!
537 * ======== check ========
538 * Return TRUE if an error was raised
539 *
540 * @param(eb) pointer to an `Error_Block`, `Error_ABORT` or `Error_IGNORE`
541 *
542 * @a(returns)
543 * If `eb` is non-`NULL` and `{@link #policy Error.policy} == UNWIND` and
544 * an error was raised on `eb`, this function returns `TRUE`. Otherwise,
545 * it returns `FALSE`.
546 */
547
548 Bool check(Block *eb);
549
550 /*!
551 * ======== getData ========
552 * Get an error's argument list
553 *
554 * @param(eb) non-`NULL` pointer to an `Error_Block`
555 *
556 * @a(returns)
557 * `getData` returns an array of type `{@link #Data}` with
558 * `{@link #NUMARGS}` elements containing the arguments provided
559 * at the time the error was raised.
560 *
561 * @see #raise
562 */
563
564 Data *getData(Block *eb);
565
566 /*!
567 * ======== getCode ========
568 * Get an error's code
569 *
570 * @param(eb) non-`NULL` pointer to an `Error_Block`
571 *
572 * @a(returns)
573 * `getCode` returns the error code associated with this error block.
574 *
575 * @see #raise
576 * @see #Desc
577 */
578 UInt16 getCode(Block *eb);
579
580 /*!
581 * ======== getId ========
582 * Get an error's id
583 *
584 * @param(eb) non-`NULL` pointer to an `Error_Block`
585 *
586 * @a(Warning)
587 * `Error_Id` values may vary among different configurations
588 * of an application. For example, the addition of a new module to a
589 * program may result in a different absolute value for
590 * `{@link #E_generic}`. If you need error numbers that remain
591 * invariant, use the user definable `{@link #Desc Desc.code}` field.
592 *
593 * @see #raise
594 * @see #Desc
595 */
596
597 Id getId(Block *eb);
598
599 /*!
600 * ======== getMsg ========
601 * Get an error's "printf" format string
602 *
603 * @param(eb) non-`NULL` pointer to an `Error_Block`
604 *
605 * @see #raise
606 * @see #Desc
607 */
608
609 CString getMsg(Block *eb);
610
611 /*!
612 * ======== getSite ========
613 * Get an error's call site info
614 *
615 * @param(eb) non-`NULL` pointer to an `Error_Block`
616 *
617 * @a(returns)
618 * `getSite` returns a pointer to an initialized
619 * `{@link Types#Site Types.Site}` structure. However, in the
620 * event that the call site was compiled with `xdc_FILE` defined to
621 * be `NULL` (to minimize string space overhead) the `file`
622 * field may be set to `NULL`.
623 *
624 * @see #raise
625 * @see #Desc
626 */
627
628 Types.Site *getSite(Block *eb);
629
630 /*!
631 * ======== idToCode ========
632 * Extract the user's error code associated with an `Error_Id`
633 *
634 * @param(id) `Error_Id` from which to extract the user defined
635 * code
636 * @_nodoc
637 */
638 @Macro UInt16 idToCode(Id id);
639
640 /*!
641 * ======== idToUid ========
642 * Extract the unique error id associated with an `Error_Id`
643 *
644 * @param(id) `Error_Id` from which to extract the system unique
645 * id associated with the specified `Error_Id`
646 * @_nodoc
647 */
648 @Macro UInt16 idToUid(Id id);
649
650 /*!
651 * ======== init ========
652 * Put an error block into its initial state
653 *
654 * To ensure reliable error detection, clients must call `init` for
655 * an `Error_Block` prior to any use.
656 *
657 * If the same Error Block is used multiple times, only the last error
658 * raised is retained.
659 *
660 * @param(eb) pointer to an `Error_Block`, `Error_ABORT` or `Error_IGNORE`
661 *
662 * If `eb` is `NULL` this function simply returns.
663 */
664 Void init(Block *eb);
665
666 /*!
667 * ======== print ========
668 * Print error using System.printf()
669 *
670 * This function prints the error using `System_printf()`. The output
671 * is on a single line terminated with a new line character and has the
672 * following form:
673 * @p(code)
674 * <site>: <file>, line <line_num>: <err_msg>
675 * @p
676 * where `<site>` is the module that raised the error, `<file>` and
677 * `<line_num>` are the file and line number of the containing the call
678 * site of the `Error_raise()`, and `<err_msg>` is the error message
679 * rendered with the arguments associated with the error.
680 *
681 * @param(eb) pointer to an `Error_Block`, `Error_ABORT` or `Error_IGNORE`
682 *
683 * If `eb` is `Error_ABORT` or `Error_IGNORE`, this function simply
684 * returns with no output.
685 *
686 * @a(Warning)
687 * This function is not protected by a gate and, as a result,
688 * if two threads call this method concurrently, the output of the two
689 * calls will be intermingled. To prevent intermingled error output,
690 * you can either wrap all calls to this method with an appropriate
691 * `Gate_enter`/`Gate_leave` pair or simply ensure that only one
692 * thread in the system ever calls this method.
693 */
694
695 Void print(Block *eb);
696
697 /*!
698 * ======== policyDefault ========
699 * Default implementation of the policyFxn
700 *
701 * This function is the implementation which is plugged in by default to
702 * the `{@link #policyFxn}`. It processes the error and logs it before
703 * returning to the caller or aborting - depending on the error policy
704 * `{@link #policy}`.
705 */
706
707 Void policyDefault(Block *eb, Types.ModuleId mod, CString file, Int line,
708 Id id, IArg arg1, IArg arg2);
709
710 /*!
711 * ======== policyMin ========
712 * Implementation of the policyFxn with a smaller footprint
713 *
714 * This function is a compromise between a debug-friendly
715 * `{@link #policyDefault}`, which offers more details about any raised
716 * errors, but requires a larger footprint, and `{@link #policySpin}`,
717 * which is small but does not display any debug information.
718 *
719 * This function returns to the caller, unless `{@link #policy}` is set to
720 * `TERMINATE`, or the `Error_Block` passed to it is `NULL`. If it returns,
721 * the only information available in the returned `Error_Block` is the
722 * error ID.
723 */
724
725 Void policyMin(Block *eb, Types.ModuleId mod, CString file, Int line,
726 Id id, IArg arg1, IArg arg2);
727
728 /*!
729 * ======== policySpin ========
730 * Lightweight implementation of the policyFxn
731 *
732 * This function is a lightweight alternative which can be plugged in to
733 * the `{@link #policyFxn}`. It just loops infinitely.
734 *
735 * @a(Warning)
736 * This function does not call `{@link #raiseHook}` and never returns to
737 * the caller. As a result, ANY error raised by the application will cause
738 * it to indefinitly hang.
739 */
740
741 Void policySpin(Block *eb, Types.ModuleId mod, CString file, Int line,
742 Id id, IArg arg1, IArg arg2);
743
744 /*!
745 * ======== raise ========
746 * Raise an error
747 *
748 * This function is used to raise an `Error` by writing call site,
749 * error ID, and error argument information into the `Error_Block`
750 * pointed to by `eb`.
751 *
752 * If `Error_raise` is called more than once on an `Error_Block` object,
753 * the previous error information is overwritten; only the last error
754 * is retained in the `Error_Block` object.
755 *
756 * In all cases, any configured `{@link #raiseHook Error.raiseHook}`
757 * function is called with a non-`NULL` pointer to a fully
758 * initialized `Error_Block` object.
759 *
760 * @param(eb) pointer to an `Error_Block`, `Error_ABORT` or `Error_IGNORE`
761 *
762 * If `eb` is `Error_ABORT` or
763 * `{@link #policy Error.policy} == TERMINATE`,
764 * this function does not return to the caller; after calling any
765 * configured `{@link #raiseHook}`, `System_abort` is called with the
766 * string `"xdc.runtime.Error.raise: terminating execution\n"`.
767 *
768 * @param(id) the error to raise
769 *
770 * This pointer identifies the class of error being raised; the error
771 * class indicates how to interpret any subsequent arguments passed to
772 * `{@link #raise}`.
773 *
774 * @param(arg1) error's first argument
775 *
776 * The argument interpreted by the first control character
777 * in the error message format string. It is ignored if not needed.
778 *
779 * @param(arg2) error's second argument
780 *
781 * The argument interpreted by the second control character
782 * in the error message format string. It is ignored if not needed.
783 */
784 @Macro Void raise(Block *eb, Id id, IArg arg1, IArg arg2);
785
786 /*! @_nodoc */
787 Void raiseX(Block *eb, Types.ModuleId mod, CString file, Int line,
788 Id id, IArg arg1, IArg arg2);
789
790 /*! @_nodoc EXPERIMENTAL */
791 Void setX(Block *eb, Types.ModuleId mod, CString file, Int line,
792 Id id, IArg arg1, IArg arg2);
793
794 internal:
795
796 /*!
797 * ======== policyLog ========
798 * @_nodoc
799 */
800 Void policyLog(Types.ModuleId mod, CString file, Int line, CString msg,
801 IArg arg1, IArg arg2);
802
803 struct Module_State {
804 UInt16 count;
805 };
806
807 }
808 809 810
811