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