1 /*
2 * Copyright 2013 by Texas Instruments Incorporated.
3 *
4 */
6 /*
7 * Copyright (c) 2013 Texas Instruments Incorporated - http://www.ti.com
8 *
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions
11 * are met:
12 *
13 * Redistributions of source code must retain the above copyright
14 * notice, this list of conditions and the following disclaimer.
15 *
16 * Redistributions in binary form must reproduce the above copyright
17 * notice, this list of conditions and the following disclaimer in the
18 * documentation and/or other materials provided with the distribution.
19 *
20 * Neither the name of Texas Instruments Incorporated nor the names of
21 * its contributors may be used to endorse or promote products derived
22 * from this software without specific prior written permission.
23 *
24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
25 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
26 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
27 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
28 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
29 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
30 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
31 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
32 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
33 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
34 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
35 */
36 /*
37 * ======== SysCBuf.xdc ========
38 */
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 */
73 @Template("./SysCBuf.xdt")
74 @ModuleStartup
75 module SysCBuf inherits xdc.runtime.ISystemSupport {
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;
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;
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;
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);
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;
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);
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);
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();
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);
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();
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);
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);
244 /*!
245 * ======== getSize ========
246 * Return the size of the trace buffer.
247 */
248 UInt32 getSize();
250 internal:
252 /*
253 * ======== output ========
254 * System_output__I is generated based on bufSize.
255 *
256 * This function is generated so that the code does not contain a call to
257 * HOSTwrite if bufSize is 0. Otherwise, if bufSize is 0, the compiler
258 * would optimize out the HOSTwrite function, leaving a 0-length symbol.
259 * If the a client later tried to pull in HOSTwrite, there would be a
260 * symbol error.
261 *
262 * This generated function is accessed through an internal config so
263 * that it is an indirect call in the ROM case, but optimized to a direct
264 * call in the RAM case.
265 */
266 Void output(Char *buf, UInt size);
267 readonly config OutputFxn outputFunc = '&ti_sdo_ce_utils_syscbuf_SysCBuf_output__I';
269 struct Module_State {
270 Char outbuf[]; /* the output buffer */
271 UInt outidx; /* index within outbuf to next Char to write */
272 Bool wrapped; /* has the index (outidx) wrapped */
273 UInt32 bufSize; /* size of the trace buffer */
274 }
275 }
276 /*
277 * @(#) ti.sdo.ce.utils.syscbuf; 1, 0, 0,3; 6-13-2013 00:19:47; /db/atree/library/trees/ce/ce-w08/src/ xlibrary
279 */