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