1 /*
2 * Copyright (c) 2008 Texas Instruments. All rights reserved.
3 * This program and the accompanying materials are made available under the
4 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License
5 * v. 1.0 which accompanies this distribution. The Eclipse Public License is
6 * available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
7 * Distribution License is available at
8 * http://www.eclipse.org/org/documents/edl-v10.php.
9 *
10 * Contributors:
11 * Texas Instruments - initial implementation
12 * */
13 /*
14 * ======== SysMin.xdc ========
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 module SysMin inherits xdc.runtime.ISystemSupport {
38
39 metaonlystruct ModuleView {
40 Ptr outBuf;
41 UInt outBufIndex;
42 Bool wrapped; /* has the buffer wrapped */
43 };
44
45 metaonlystruct BufferEntryView {
46 String entry;
47 }
48
49 /*!
50 * ======== rovViewInfo ========
51 * @_nodoc 52 */
53 @Facet
54 metaonlyconfig 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, all output
82 * is dropped, and `{@link SysMin#ready()}` always returns `FALSE`.
83 */
84 config SizeT bufSize = 1024;
85
86 /*!
87 * ======== flushAtExit ========
88 * Flush the internal buffer during `{@link #exit}` or `{@link #abort}`.
89 *
90 * If the application's target is a TI target, the internal buffer is
91 * flushed via the `HOSTwrite` function in the TI C Run Time Support
92 * (RTS) library.
93 *
94 * If the application's target is not a TI target, the internal buffer
95 * is flushed to `stdout` via `fwrite(..., stdout)`.
96 *
97 * Setting this parameter to `false` reduces the footprint of the
98 * application at the expense of not getting output when the application
99 * ends via a `System_exit()`, `System_abort()`, `exit()` or `abort()`.
100 */
101 config Bool flushAtExit = true;
102
103 /*!
104 * ======== sectionName ========
105 * Section where the internal character output buffer is placed
106 *
107 * The default is to have no explicit placement; i.e., the linker is
108 * free to place it anywhere in the memory map.
109 */
110 metaonlyconfig String sectionName = null;
111
112 /*!
113 * ======== OutputFxn ========
114 * Output characters in the specified buffer
115 *
116 * The first parameter is a pointer to a buffer of characters to be
117 * output. The second parameter is the number of characters in the
118 * buffer to output.
119 *
120 * This function may be called with 0 as the second parameter. In this
121 * case, the function should simply return.
122 *
123 */
124 typedef Void (*OutputFxn)(Char *, UInt);
125
126 /*!
127 * ======== outputFxn ========
128 * User supplied character output function
129 *
130 * If this parameter is set to a non-`null` value, the specified
131 * function will be called by `{@link System#flush()}` to output
132 * any characters buffered within `SysMin`.
133 *
134 * For example, if you define a function named `myOutputFxn`, the
135 * following configuration fragment will cause `SysMin` to call
136 * `myOutputFxn` whenever the character buffer is flushed.
137 * @p(code) 138 * var SysMin = xdc.useModule("xdc.runtime.SysMin");
139 * SysMin.outputFxn = "&myOutputFxn";
140 * @p 141 *
142 * If this parameter is not set, a default function will be used which
143 * uses the ANSI C Standard Library function `fwrite()` (or `HOSTwrite`
144 * in the TI C Run Time Support library) to output
145 * accumulated output characters.
146 *
147 * @see #OutputFxn
148 */
149 config OutputFxn outputFxn = null;
150
151 /*!
152 * ======== abort ========
153 * Backend for `{@link System#abort()}`
154 *
155 * This abort function writes the string to the internal
156 * output buffer and then gives all internal output to the
157 * `{@link #outputFxn}` function if the `{@link #flushAtExit}`
158 * configuration parameter is true.
159 *
160 * @param(str) message to output just prior to aborting
161 *
162 * If non-`NULL`, this string should be output just prior to
163 * terminating.
164 *
165 * @see ISystemSupport#abort
166 */
167 override Void abort(CString str);
168
169 /*!
170 * ======== exit ========
171 * Backend for `{@link System#exit()}`
172 *
173 * This exit function gives all internal output to the
174 * `{@link #outputFxn}` function if the `{@link #flushAtExit}`
175 * configuration parameter is true.
176 *
177 * @see ISystemSupport#exit
178 */
179 override Void exit(Int stat);
180
181 /*!
182 * ======== flush ========
183 * Backend for `{@link System#flush()}`
184 *
185 * The `flush` writes the contents of the internal character buffer
186 * via the `{@link #outputFxn}` function.
187 *
188 * @a(Warning) 189 * The `{@link System}` gate is used for thread safety during the
190 * entire flush operation, so care must be taken when flushing with
191 * this `ISystemSupport` module. Depending on the nature of the
192 * `System` gate, your application's interrupt latency
193 * may become a function of the `bufSize` parameter!
194 *
195 * @see ISystemSupport#flush
196 */
197 override Void flush();
198
199 /*!
200 * ======== putch ========
201 * Backend for `{@link System#printf()}` and `{@link System#putch()}`
202 *
203 * Places the character into an internal buffer. The `{@link #flush}`
204 * sends the internal buffer to the `{@link #outputFxn}` function.
205 * The internal buffer is also sent to the `SysMin_outputFxn`
206 * function by `{@link #exit}` and `{@link #abort}` if the
207 * `{@link #flushAtExit}` configuration parameter is true.
208 *
209 * @see ISystemSupport#putch
210 */
211 override Void putch(Char ch);
212
213 /*!
214 * ======== ready ========
215 * Test if character output can proceed
216 *
217 * This function returns true if the internal buffer is non-zero.
218 *
219 * @see ISystemSupport#ready
220 */
221 override Bool ready();
222
223 internal:
224
225 /*
226 * ======== output ========
227 * SysMin_output__I is generated based on bufSize.
228 *
229 * This function is generated so that the code does not contain a call to
230 * HOSTwrite if bufSize is 0. Otherwise, if bufSize is 0, the compiler
231 * would optimize out the HOSTwrite function, leaving a 0-length symbol.
232 * If the a client later tried to pull in HOSTwrite, there would be a
233 * symbol error.
234 *
235 * This generated function is accessed through an internal config so
236 * that it is an indirect call in the ROM case, but optimized to a direct
237 * call in the RAM case.
238 */
239 Void output(Char *buf, UInt size);
240 readonlyconfig OutputFxn outputFunc = '&xdc_runtime_SysMin_output__I';
241
242 struct Module_State {
243 Char outbuf[]; /* the output buffer */
244 UInt outidx; /* index within outbuf to next Char to write */
245 Bool wrapped; /* has the index (outidx) wrapped */
246 }
247 }
248 /*
249 * @(#) xdc.runtime; 2, 1, 0,0; 4-24-2015 12:34:13; /db/ztree/library/trees/xdc/xdc-A71/src/packages/
250 */
251