1 2 3 4 5 6 7 8 9 10 11 12
13 14 15
16
17 /*!
18 * ======== SysMin ========
19 *
20 * Minimal implementation of `{@link ISystemSupport}`.
21 *
22 * This implementation provides a fully functional implementation of
23 * all methods specified by `ISystemSupport`.
24 *
25 * The module maintains an internal buffer (with a configurable size)
26 * that stores on the "output". When full, the data is over-written. When
27 * `System_flush()` is called the characters in the internal buffer are
28 * "output" using the user configuratble `{@link #outputFxn}`.
29 *
30 * As with all `ISystemSupport` modules, this module is the back-end for the
31 * `{@link System}` module; application code does not directly call these
32 * functions.
33 */
34
35 @Template("./SysMin.xdt")
36 @ModuleStartup
37 module SysMin inherits xdc.runtime.ISystemSupport {
38
39 metaonly struct ModuleView {
40 Ptr outBuf;
41 UInt outBufIndex;
42 Bool wrapped;
43 };
44
45 metaonly struct BufferEntryView {
46 String entry;
47 }
48
49 /*!
50 * ======== rovViewInfo ========
51 * @_nodoc
52 */
53 @Facet
54 metaonly config xdc.rov.ViewInfo.Instance rovViewInfo =
55 xdc.rov.ViewInfo.create({
56 viewMap: [
57 ['Module',
58 {
59 type: xdc.rov.ViewInfo.MODULE,
60 viewInitFxn: 'viewInitModule',
61 structName: 'ModuleView'
62 }
63 ],
64 ['OutputBuffer',
65 {
66 type: xdc.rov.ViewInfo.MODULE_DATA,
67 viewInitFxn: 'viewInitOutputBuffer',
68 structName: 'BufferEntryView'
69 }
70 ]
71 ]
72 });
73
74 /*!
75 * ======== bufSize ========
76 * Size (in MAUs) of the output.
77 *
78 * An internal buffer of this size is allocated. All output is stored
79 * in this internal buffer.
80 *
81 * If 0 is specified for the size, no buffer is created.
82 */
83 config SizeT bufSize = 1024;
84
85 /*!
86 * ======== flushAtExit ========
87 * Flush the internal buffer during `{@link #exit}` or `{@link #abort}`.
88 *
89 * If the application's target is a TI target, the internal buffer is
90 * flushed via the `HOSTwrite` function in the TI C Run Time Support
91 * (RTS) library.
92 *
93 * If the application's target is not a TI target, the internal buffer
94 * is flushed to `stdout` via `fwrite(..., stdout)`.
95 *
96 * Setting this parameter to `false` reduces the footprint of the
97 * application at the expense of not getting output when the application
98 * ends via a `System_exit()`, `System_abort()`, `exit()` or `abort()`.
99 */
100 config Bool flushAtExit = true;
101
102 /*!
103 * ======== sectionName ========
104 * Section where the internal character output buffer is placed
105 *
106 * The default is to have no explicit placement; i.e., the linker is
107 * free to place it anywhere in the memory map.
108 */
109 metaonly config String sectionName = null;
110
111 /*!
112 * ======== OutputFxn ========
113 * Output characters in the specified buffer
114 *
115 * The first parameter is a pointer to a buffer of characters to be
116 * output. The second parameter is the number of characters in the
117 * buffer to output.
118 *
119 * This function may be called with 0 as the second parameter. In this
120 * case, the function should simply return.
121 *
122 */
123 typedef Void (*OutputFxn)(Char *, UInt);
124
125 /*!
126 * ======== outputFxn ========
127 * User suplied character output function
128 *
129 * If this parameter is set to a non-`null` value, the specified
130 * function will be called by to output characters buffered within
131 * `SysMin`.
132 *
133 * For example, if you define a function named `myOutputFxn`, the
134 * following configuration fragment will cause `SysMin` to call
135 * `myOutputFxn` whenever the character buffer is flushed.
136 * @p(code)
137 * var SysMin = xdc.useModule("xdc.runtime.SysMin");
138 * SysMin.outputFxn = "&myOutputFxn";
139 * @p
140 *
141 * If this parameter is not set, a default function will be used which
142 * uses the ANSI C Standard Library function `fwrite()` (or `HOSTwrite`
143 * in the TI C Run Time Support library) to output
144 * accumulated output characters.
145 *
146 * @see #OutputFxn
147 */
148 config OutputFxn outputFxn = null;
149
150 /*!
151 * ======== abort ========
152 * Backend for `{@link System#abort()}`
153 *
154 * This abort function writes the string to the internal
155 * output buffer and then gives all internal output to the
156 * `{@link #outputFxn}` function if the `{@link #flushAtExit}`
157 * configuration parameter is true.
158 *
159 * @param(str) message to output just prior to aborting
160 *
161 * If non-`NULL`, this string should be output just prior to
162 * terminating.
163 *
164 * @see ISystemSupport#abort
165 */
166 override Void abort(String str);
167
168 /*!
169 * ======== exit ========
170 * Backend for `{@link System#exit()}`
171 *
172 * This exit function gives all internal output to the
173 * `{@link #outputFxn}` function if the `{@link #flushAtExit}`
174 * configuration parameter is true.
175 *
176 * @see ISystemSupport#exit
177 */
178 override Void exit(Int stat);
179
180 /*!
181 * ======== flush ========
182 * Backend for `{@link System#flush()}`
183 *
184 * The `flush` writes the contents of the internal character buffer
185 * via the `{@link #outputFxn}` function.
186 *
187 * @a(Warning)
188 * The `{@link System}` gate is used for thread safety during the
189 * entire flush operation, so care must be taken when flushing with
190 * this `ISystemSupport` module. Depending on the nature of the
191 * `System` gate, your application's interrupt latency
192 * may become a function of the `bufSize` parameter!
193 *
194 * @see ISystemSupport#flush
195 */
196 override Void flush();
197
198 /*!
199 * ======== putch ========
200 * Backend for `{@link System#printf()}` and `{@link System#putch()}`
201 *
202 * Places the character into an internal buffer. The `{@link #flush}`
203 * sends the internal buffer to the `{@link #outputFxn}` function.
204 * The internal buffer is also sent to the `SysMin_outputFxn`
205 * function by `{@link #exit}` and `{@link #abort}` if the
206 * `{@link #flushAtExit}` configuration parameter is true.
207 *
208 * @see ISystemSupport#putch
209 */
210 override Void putch(Char ch);
211
212 /*!
213 * ======== ready ========
214 * Test if character output can proceed
215 *
216 * This function returns true if the internal buffer is non-zero.
217 *
218 * @see ISystemSupport#ready
219 */
220 override Bool ready();
221
222 internal:
223
224 225 226 227 228 229 230 231 232 233 234 235 236 237
238 Void output(Char *buf, UInt size);
239 readonly config OutputFxn outputFunc = '&xdc_runtime_SysMin_output__I';
240
241 struct Module_State {
242 Char outbuf[];
243 UInt outidx;
244 Bool wrapped;
245 }
246 }
247 248 249
250