1 2 3 4 5 6 7 8 9 10 11 12
13 14 15 16 17 18 19 20 21
22 package xdc.runtime;
23
24 /*!
25 * ======== ISystemSupport ========
26 * Interface to core system functions.
27 *
28 * Each embedded system requires implementations of these functions but
29 * the behavior of these functions varies depending on the context of the
30 * embedded system. For example, some systems will implement `exit()` as
31 * an infinite loop because the executable is designed to *never* exit.
32 */
33 interface ISystemSupport {
34
35 /*!
36 * ======== abort ========
37 * Backend for `{@link System#abort()}`
38 *
39 * This function is called by `{@link System#abort()}` prior to calling
40 * the ANSI C Standard library function `abort()`. So, to ensure the
41 * abort processing of the system's ANSI C Standard library completes,
42 * this function should return to its caller.
43 *
44 * @param(str) message to output just prior to aborting
45 *
46 * If non-`NULL`, this string should be output just prior to
47 * terminating.
48 */
49 Void abort(String str);
50
51 /*!
52 * ======== exit ========
53 * Backend for `{@link System#exit()}`
54 *
55 * This function is called as part the normal "atexit" processing
56 * performed by the ANSI C Standard Library's `exit()` function;
57 * `{@link System#exit()}` directly calls ANSI `exit()`.
58 *
59 * This function is called after all "atexit" handlers bound via
60 * `{@link System#atexit()}` are run and it
61 * is always called while "inside" the the `System` gate.
62 *
63 * To ensure that all exit processing of the system's ANSI C
64 * Standard Library completes, this function should return to its caller.
65 * Exit handlers bound using the ANSI C Standard Library `atexit()`
66 * function may run before or after this function.
67 *
68 * @param(stat) status value passed to all "atexit" handlers
69 *
70 * This value is passed to all "atexit" handles bound via
71 * `{@link System#atexit()}`. If the application exits via the
72 * ANSI C Standard `exit()` function rather than via System_exit(),
73 * `stat` will be equal to `{@link System#STATUS_UNKNOWN}`.
74 *
75 * @see System#atexit
76 */
77 Void exit(Int stat);
78
79 /*!
80 * ======== flush ========
81 * Backend for `{@link System#flush()}`
82 *
83 * This function is simply called by `{@link System#flush System_flush}`
84 * to output any characters buffered by the underlying `SystemSupport`
85 * module to an output device.
86 */
87 Void flush();
88
89 /*!
90 * ======== putch ========
91 * Backend for `{@link System#printf()}` and `{@link System#putch()}`
92 *
93 * Output a single character. This function is called by
94 * `{@link System#printf System_printf()}` to write each character
95 * of formated output specified by its arguments.
96
97 *
98 * @param(ch) character to output
99 */
100 Void putch(Char ch);
101
102 /*!
103 * ======== ready ========
104 * Test if character output can proceed
105 *
106 * This function is called by `{@link System}` prior to performing
107 * any character output . If this function returns `FALSE`, the `System`
108 * functions that would normally call `putch()` simply return
109 * (with an appropriate error status) without ever calling
110 * `{@link #putch}`.
111 */
112 Bool ready();
113 }
114 115 116
117