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 * ======== LoggerBuf.xdc ========
15 *
16 *! Revision History
17 *! ================
18 *! 13-Jun-2007 nitya Fixed SDSCM00020303, SDSCM00020305, SDSCM00020304
19 *! 13-Jun-2007 nitya flushAllInternal cannot be in internal section
20 *! 22-Mar-2007 rt Updated with concepts from avala-e02's LoggerBufAtomic
21 */
22
23 /*!
24 * ======== LoggerBuf ========
25 * A logger which stores `Log` events in a buffer.
26 *
27 * This module provides a logger which captures `{@link Log}` events to a
28 * buffer in realtime. The `Log` events stored in the buffer are
29 * unformatted; `Log` event formatting is deferred until some client reads
30 * the raw event data from the buffer. You can use
31 * `{@link #flush LoggerBuf_flush()}` to process the `Log` events stored
32 * in the buffer and stream the formatted output to stdout
33 * (via `{@link System#printf}`). Alternatively, you can read a raw event
34 * (via `{@link #getNextEntry}`) and send it to another client that
35 * has the resources to format the event for display.
36 *
37 * The implementation of this logger is fast with minimal stack usage
38 * making it appropriate for a realtime application.
39 * This logger writes all `Log` events to a circular buffer. As a
40 * result, the execution time of all `Log` methods bound to this type
41 * of logger are deterministic (and quite short) because there are no
42 * additional memory allocation calls after the circular buffer was
43 * allocated.
44 *
45 * If this logger is used in a preemptive environment, then an appropriate
46 * gate must be assigned to the module. For example, if events are generated
47 * from an interrupt context, then a gate that disables interrupts
48 * must be used.
49 *
50 * @p(code) 51 * var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');
52 * LoggerBuf.common$.gate = ...some gate instance...
53 * @p 54 *
55 * If the buffer type is circular, the log buffer of size
56 * `{@link #numEntries}` contains the last `numEntries` of `Log` events. If
57 * the buffer type is fixed, the log buffer contains the first
58 * `numEntries` events.
59 *
60 * @a(Examples) 61 * Configuration example: The following XDC configuration statements
62 * create a logger instance, assign it as the default logger for all
63 * modules, and enable `USER1` logging in all modules of the package
64 * `my.pkg`. See the `{@link Diags#setMaskMeta Diags.setMaskMeta()}` function
65 * for details on specifying the module names.
66 *
67 * @p(code) 68 * var Defaults = xdc.useModule('xdc.runtime.Defaults');
69 * var Diags = xdc.useModule('xdc.runtime.Diags');
70 * var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');
71 *
72 * LoggerBuf.enableFlush = true;
73 * var LoggerBufParams = new LoggerBuf.Params();
74 * LoggerBufParams.exitFlush = true;
75 * Defaults.common$.logger = LoggerBuf.create(LoggerBufParams);
76 * Diags.setMaskMeta("my.pkg.%", Diags.USER1, Diags.RUNTIME_ON);
77 * @p 78 */
79
80 @ModuleStartup /* Initialize static instances */
81 @InstanceFinalize /* this mod has cleanup fxn when instances are deleted */
82 @InstanceInitError /* instance create can fail */
83 @Gated
84
85 module LoggerBuf inherits ILogger {
86
87 /*!
88 * ======== BufType ========
89 * Type of log buffer
90 */
91 enum BufType {
92 BufType_CIRCULAR, /*! The log buffer wraps, overwriting old entries */
93 BufType_FIXED /*! The log buffer halts collection when full */
94 };
95
96 metaonlystruct BasicView {
97 String label;
98 Int lastSerial;
99 Int numEntries;
100 String type;
101 Bool enabledFlag;
102 };
103
104 metaonlystruct RecordView {
105 Int serial;
106 Long timestampRaw;
107 String modName;
108 String text;
109 Int eventId;
110 String eventName;
111 IArg arg0;
112 IArg arg1;
113 IArg arg2;
114 IArg arg3;
115 IArg arg4;
116 IArg arg5;
117 IArg arg6;
118 IArg arg7;
119 }
120
121 /*!
122 * ======== rovViewInfo ========
123 * @_nodoc 124 */
125 @Facet
126 metaonlyconfig xdc.rov.ViewInfo.Instance rovViewInfo =
127 xdc.rov.ViewInfo.create({
128 viewMap: [
129 ['Basic',
130 {
131 type: xdc.rov.ViewInfo.INSTANCE,
132 viewInitFxn: 'viewInitBasic',
133 structName: 'BasicView'
134 }
135 ],
136 ['Records',
137 {
138 type: xdc.rov.ViewInfo.INSTANCE_DATA,
139 viewInitFxn: 'viewInitRecords',
140 structName: 'RecordView'
141 }
142 ]
143 ]
144 });
145
146 /*!
147 * ======== StopModeData ========
148 * This data is added to the RTA MetaData file to support stop mode RTA.
149 */
150 @XmlDtd metaonlystruct StopModeData {
151 String bufferSymbol;
152 Int bufferSize;
153 }
154
155 /*!
156 * ======== TimestampProxy ========
157 * User supplied time-stamp proxy
158 *
159 * This proxy allows `LoggerBuf` to use a timestamp server different
160 * from the server used by `{@link xdc.runtime.Timestamp}`. However, if
161 * not supplied by a user, this proxy defaults to whichever timestamp
162 * server is used by `Timestamp`.
163 */
164 proxy TimestampProxy inherits ITimestampClient;
165
166 /*!
167 * ======== enableFlush ========
168 * Flush all logs at system exit
169 */
170 config Bool enableFlush = false;
171
172 /*!
173 * ======== flushAll ========
174 * Flush logs of all instances of `LoggerBuf`
175 *
176 * The user is responsible for making sure that no `LoggerBuf` instances
177 * are created or deleted while in this API, by using an appropriate gate.
178 */
179 Void flushAll();
180
181 /*!
182 * ======== flushAllInternal ========
183 * @_nodoc 184 */
185 Void flushAllInternal(Int stat);
186
187 /*!
188 * @_nodoc 189 * ======== initDecoder ========
190 * Initialize the LoggerBufDecoder for use in the LoggerBuf 'Records' ROV
191 * view.
192 */
193 function initDecoder();
194
195 instance:
196 /*!
197 * ======== create ========
198 * Create a `LoggerBuf` logger
199 *
200 * @see LoggerBuf#Params
201 */
202 create();
203
204 /*!
205 * ======== numEntries ========
206 * Number of entries in buffer
207 *
208 * Each entry is large enough to store one `Log` event containing up to
209 * 4 optional arguments. Events containing more than 4 arguments (such
210 * as those from `{@link Log#write5}`) use 2 entries.
211 *
212 * `numEntries` must be a power of 2.
213 */
214 config Int numEntries = 64;
215
216 /*!
217 * ======== bufType ========
218 * Log buffer type
219 */
220 config BufType bufType = BufType_CIRCULAR;
221
222 /*!
223 * ======== exitFlush ========
224 * Flush log at system exit
225 *
226 * Only used when module parameter `{@link #enableFlush}` is `true`.
227 */
228 config Bool exitFlush = false;
229
230 /*!
231 * ======== bufSection ========
232 * Section name for the buffer managed by the static instance.
233 *
234 * The default section is the 'dataSection' in the platform.
235 */
236 metaonlyconfig String bufSection = null;
237
238 /*!
239 * ======== bufHeap ========
240 * The heap that contains the `Log` buffer for dynamic instances.
241 *
242 * The default value `null` means the buffer will be allocated from
243 * the `{@link Memory#defaultHeapInstance}` heap.
244 */
245 config IHeap.Handle bufHeap = null;
246
247 /*!
248 * ======== enable ========
249 * Enable a log
250 *
251 * @a(returns) 252 * The function returns the state of the log (`TRUE` if enabled,
253 * `FALSE` if disabled) before the call. That allow clients to restore
254 * the previous state.
255 */
256 Bool enable();
257
258 /*!
259 * ======== disable ========
260 * Disable a log
261 *
262 * Events written to a disabled log are silently discarded.
263 *
264 * @a(returns) 265 * The function returns the state of the log (`TRUE` if enabled,
266 * `FALSE` if disabled) before the call. That allow clients to restore
267 * the previous state.
268 */
269 Bool disable();
270
271 /*!
272 * ======== reset ========
273 * Reset a log to empty state and enable it
274 *
275 * @a(WARNING) This method is not synchronized with other instance
276 * methods and, as a result, it must never be called when there is a
277 * chance that another instance method is currently in operation or
278 * when another method on this instance may preempt this call.
279 */
280 Void reset();
281
282 /*!
283 * ======== flush ========
284 * Read, clear, and output the contents of the log
285 *
286 * This method reads, clears, and "prints" each `Log` event (via
287 * `{@link System#printf}`) in the log.
288 */
289 Void flush();
290
291 /*!
292 * ======== getNextEntry ========
293 * Fills the passed `{@link Log#EventRec}` with the next entry in the log.
294 *
295 * This function is used to read and clear `Log` events from the
296 * buffer maintained by the `LoggerBuf` instance. The `Log` event can
297 * then be transmitted and displayed on a host.
298 *
299 * A read pointer is maintained in the `LoggerBuf` instance and
300 * points to the next record to read. Entries are not necessarily
301 * returned in chronological order, since buffers of type
302 * `{@link #BufType_CIRCULAR}` can wrap.
303 *
304 * @param(evtRec) pointer to a supplied `EventRec` object where the next
305 * entry in the log is copied to
306 *
307 * @a(returns) 308 * This function reports the number of entries actually read. The only
309 * values that can be returned are:
310 * @p(blist) 311 * - 0 no more entries to read
312 * - 1 or 2 read a complete entry written by `write4` or `write8`
313 * - -1 cleared an incomplete/overwritten entry, more entries to read
314 */
315 Int getNextEntry(Log.EventRec *evtRec);
316
317 internal:
318
319 const Int8 FULL = -1;
320 const Int8 WRAP = 0;
321
322 const Int8 NEXT = 1;
323
324 struct Entry {
325 Types.Timestamp64 tstamp;
326 Bits32 serial;
327 Types.Event evt;
328 IArg arg1;
329 IArg arg2;
330 IArg arg3;
331 IArg arg4;
332 };
333
334 struct Instance_State {
335 IHeap.Handle bufHeap;
336 Entry entryArr[];
337 Entry *curEntry;
338 Entry *endEntry;
339 Entry *readEntry;
340 Bits32 serial;
341 Int16 numEntries;
342 Int8 advance;
343 Bool enabled;
344 Bool flush;
345 };
346
347 }
348 /*
349 * @(#) xdc.runtime; 2, 0, 0, 0,240; 6-21-2010 15:09:09; /db/ztree/library/trees/xdc/xdc-u19x/src/packages/
350 */
351