1 /* --COPYRIGHT--,ESD
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 * --/COPYRIGHT--*/
13 /*
14 * ======== SysMin.xdc ========
15 *
16 *! Revision History
17 *! ================
18 *! 24-Jul-2007 toddm Code review comments. Removed user fxns and added
19 *! startup
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 metaonlystruct ModuleView {
45 Ptr outBuf;
46 UInt outBufIndex;
47 Bool wrapped; /* has the buffer wrapped */
48 };
49
50 metaonlystruct BufferEntryView {
51 String entry;
52 }
53
54 /*!
55 * ======== rovViewInfo ========
56 * @_nodoc 57 */
58 @Facet
59 metaonlyconfig 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 metaonlyconfig 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 * ======== output ========
231 * SysMin_output__I is generated based on bufSize.
232 *
233 * This function is generated so that the code does not contain a call to
234 * HOSTwrite if bufSize is 0. Otherwise, if bufSize is 0, the compiler
235 * would optimize out the HOSTwrite function, leaving a 0-length symbol.
236 * If the a client later tried to pull in HOSTwrite, there would be a
237 * symbol error.
238 *
239 * This generated function is accessed through an internal config so
240 * that it is an indirect call in the ROM case, but optimized to a direct
241 * call in the RAM case.
242 */
243 Void output(Char *buf, UInt size);
244 readonlyconfig OutputFxn outputFunc = '&xdc_runtime_SysMin_output__I';
245
246 struct Module_State {
247 Char outbuf[]; /* the output buffer */
248 UInt outidx; /* index within outbuf to next Char to write */
249 Bool wrapped; /* has the index (outidx) wrapped */
250 }
251 }
252 /*
253 * @(#) xdc.runtime; 2, 0, 0, 0,239; 6-9-2010 16:24:58; /db/ztree/library/trees/xdc/xdc-u18x/src/packages/
254 */
255