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