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
40 /*!
41 * ======== SysCBuf ========
42 *
43 * Implementation of `{@link ISystemSupport}` with circular buffer for
44 * output.
45 *
46 * This implementation provides a fully functional implementation of
47 * all methods specified by `ISystemSupport`.
48 *
49 * This module maintains a circular buffer where data is written on
50 * SysCBuf_putch(). When the buffer is full, data is overwritten, and
51 * SysCBuf internally keeps track of the number of characters lost
52 * due to overwrite. The output buffer can be statically configured
53 * or dynamically bound to a buffer using SysCBuf_bind().
54 *
55 * When `System_flush()` is called the characters in the internal buffer
56 * are "output" using the user configuratble `{@link #outputFxn}`. There is
57 * also a user configurable "get" function that can be used to copy out a
58 * given amount from the circular buffer.
59 *
60 * The difference between SysCBuf and the xdc.runtime.SysMin module, are
61 * the following additional features:
62 * - SysCBuf_bind() for dynamic binding of the circular output buffer.
63 * - SysCBuf_get() for copying a given amount of data from the output
64 * buffer to another buffer.
65 * - Maintaining the number of characters lost due to overrite, and the
66 * number of characters available for reading with SysCBuf_get().
67 *
68 * As with all `ISystemSupport` modules, this module is the back-end for the
69 * `{@link System}` module; application code does not directly call these
70 * functions.
71 */
72
73 @Template("./SysCBuf.xdt")
74 @ModuleStartup
75 module SysCBuf inherits xdc.runtime.ISystemSupport {
76
77 /*!
78 * ======== bufSize ========
79 * Size (in MAUs) of the output.
80 *
81 * An internal buffer of this size is allocated. All output is stored
82 * in this internal buffer.
83 *
84 * If 0 is specified for the size, no buffer is created.
85 */
86 config SizeT bufSize = 0;
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 suplied character output function
131 *
132 * If this parameter is set to a non-`null` value, the specified
133 * function will be called by to output characters buffered within
134 * `SysCBuf`.
135 *
136 * For example, if you define a function named `myOutputFxn`, the
137 * following configuration fragment will cause `SysCBuf` to call
138 * `myOutputFxn` whenever the character buffer is flushed.
139 * @p(code)
140 * var SysCBuf = xdc.useModule("xdc.runtime.SysCBuf");
141 * SysCBuf.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 * Places the character into an internal buffer. The `{@link #flush}`
206 * sends the internal buffer to the `{@link #outputFxn}` function.
207 * The internal buffer is also sent to the `SysCBuf_outputFxn`
208 * function by `{@link #exit}` and `{@link #abort}` if the
209 * `{@link #flushAtExit}` configuration parameter is true.
210 *
211 * @see ISystemSupport#putch
212 */
213 override Void putch(Char ch);
214
215 /*!
216 * ======== ready ========
217 * Test if character output can proceed
218 *
219 * This function returns true if the internal buffer is non-zero.
220 *
221 * @see ISystemSupport#ready
222 */
223 override Bool ready();
224
225 /*!
226 * ======== bind ========
227 * Bind the buffer 'buf' of size 'size' bytes to the SysCBuf trace buffer.
228 *
229 * Return 0 if successful, -1 otherwise.
230 */
231 Int bind(Char *buf, UInt32 size);
232
233 /*!
234 * ======== get ========
235 * Copy contents of the trace buffer. Return the number of characters
236 * remaining in 'avail'. Return the number of characters lost due to
237 * wrapping in 'lost'.
238 *
239 * Return the number of characters copied.
240 *
241 */
242 UInt32 get(Char *buf, UInt32 size, UInt32 *avail, UInt32 *lost);
243
244 /*!
245 * ======== getSize ========
246 * Return the size of the trace buffer.
247 */
248 UInt32 getSize();
249
250 internal:
251
252 253 254 255 256 257 258 259 260 261 262 263 264 265
266 Void output(Char *buf, UInt size);
267 readonly config OutputFxn outputFunc = '&ti_sdo_ce_utils_syscbuf_SysCBuf_output__I';
268
269 struct Module_State {
270 Char outbuf[];
271 UInt outidx;
272 Bool wrapped;
273 UInt32 bufSize;
274 }
275 }
276 277 278 279
280