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 import xdc.runtime.ILogger;
39 import ti.uia.runtime.ILoggerSnapshot;
40 import xdc.rov.ViewInfo;
41 import xdc.runtime.Log;
42 import xdc.runtime.Diags;
43 import xdc.runtime.Types;
44 import xdc.runtime.Log;
45 import xdc.runtime.Error;
46
47 import ti.uia.runtime.EventHdr;
48
49 /*!
50 * ======== LoggerStopMode ========
51 * General purpose logger enabling applications to log data that
52 * can be read by an instrumentation host over JTAG, when the
53 * target is halted.
54 *
55 * Each LoggerStopMode instance has its own buffer for events logged to that
56 * instance. By including the header file, ti/uia/runtime/LogUC.h, you
57 * can specify the LoggerStopMode instance that you want the event logged
58 * to.
59 *
60 * The size of the buffer includes a {@link ti.uia.runtime.UIAPacket#Hdr UIAPacket_Hdr}.
61 * LoggerStopMode treats the buffer as a UInt32 array, so the application
62 * must guarantee that buffers are aligned on word addresses. Alignment on
63 * cache line boundaries is recommended for best performance.
64 *
65 * When the buffer is filled, LoggerStopMode will update the QueueDescriptor
66 * data structure (which provides the interface needed by the host's JTAG
67 * transport handler to read the logged event data) and wrap around the buffer's
68 * write pointer.
69 *
70 * LoggerStopMode was designed to have as minimal impact as possible on an
71 * application when calling a Log function. There are several configuration
72 * parameters that allow an application to get the optimal performance in
73 * exchange for certain restrictions.
74 *
75 * Interrupts are disabled during the duration of the log call.
76 *
77 * NOTE: It is recommended that you use {@link ti.uia.sysbios.LoggingSetup LoggingSetup}
78 * to configure the Logger instances. Set
79 * {@link ti.uia.sysbios.LoggingSetup#loggerType LoggingSetup.loggerType}
80 * to {@link ti.uia.sysbios.LoggingSetup#LoggerType_STOPMODE LoggingSetup.LoggerType_STOPMODE}
81 * to specify that the Logger instances are based on LoggerStopMode.
82 *
83 * @a(Examples)
84 * The following XDC configuration statements
85 * create a logger module, and assign it as the default logger for all
86 * modules.
87 *
88 * @p(code)
89 * var Defaults = xdc.useModule('xdc.runtime.Defaults');
90 * var Diags = xdc.useModule('xdc.runtime.Diags');
91 * var LoggerStopMode = xdc.useModule('ti.uia.loggers.LoggerStopMode');
92 *
93 * LoggerStopMode.isTimestampEnabled = true;
94 *
95 * var loggerParams = new LoggerStopMode.Params();
96 * Program.global.logger0 = LoggerStopMode.create(loggerParams);
97 * Defaults.common$.logger = Program.global.logger0;
98 *
99 * Program.global.logger1 = LoggerStopMode.create(loggerParams);
100 *
101 * @p
102 *
103 * @a(Examples)
104 * The following XDC configuration statements show how to use LoggingSetup
105 * with LoggerStopMode. Note that the second line is unnecessary, since
106 * LoggerStopMode is the default logger for LoggingSetup.
107 *
108 * @p(code)
109 *
110 * var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
111 * LoggingSetup.loggerType = LoggingSetup.LoggerType_STOPMODE;
112 *
113 * @p
114 */
115
116 @ModuleStartup
117 @Template("./LoggerStopMode.xdt")
118 @CustomHeader
119 module LoggerStopMode inherits ILoggerSnapshot {
120
121
122 /*!
123 * @_nodoc
124 * ======== ModuleView ========
125 */
126 metaonly struct ModuleView {
127 Bool isEnabled;
128 Bool isTimestampEnabled;
129 }
130
131 /*!
132 * @_nodoc
133 * ======== InstanceView ========
134 */
135 metaonly struct InstanceView {
136 String label;
137 Bool enabled;
138 Int bufferSize;
139 SizeT maxEventSize;
140 }
141
142 metaonly struct RecordView {
143 Int sequence;
144 Long timestampRaw;
145 String modName;
146 String text;
147 Int eventId;
148 String eventName;
149 IArg arg0;
150 IArg arg1;
151 IArg arg2;
152 IArg arg3;
153 IArg arg4;
154 IArg arg5;
155 IArg arg6;
156 IArg arg7;
157 }
158
159 /*!
160 * @_nodoc
161 * ======== rovViewInfo ========
162 */
163 @Facet
164 metaonly config ViewInfo.Instance rovViewInfo =
165 ViewInfo.create({
166 viewMap: [
167 ['Module',
168 {
169 type: ViewInfo.MODULE,
170 viewInitFxn: 'viewInitModule',
171 structName: 'ModuleView'
172 }
173 ],
174 ['Instances',
175 {
176 type: ViewInfo.INSTANCE,
177 viewInitFxn: 'viewInitInstances',
178 structName: 'InstanceView'
179 }
180 ],
181 ['Records',
182 {
183 type: xdc.rov.ViewInfo.INSTANCE_DATA,
184 viewInitFxn: 'viewInitRecords',
185 structName: 'RecordView'
186 }
187 ]
188 ]
189 });
190
191 /*!
192 * ======== RtaData ========
193 * Data added to the RTA MetaData file to support System Analyzer
194 */
195 @XmlDtd metaonly struct RtaData {
196 Int instanceId;
197 }
198
199 /*!
200 * ======== isTimestampEnabled ========
201 * Enable or disable logging the 64-bit local CPU timestamp
202 * at the start of each event
203 *
204 * Having a timestamp allows an instrumentation host (e.g.
205 * System Analyzer) to display events with the correct system time.
206 */
207 config Bool isTimestampEnabled = true;
208
209
210 /*!
211 * ======== supportLoggerDisable ========
212 * Allow LoggerStopMode instances to be enabled/disabled during runtime.
213 *
214 * Setting supportLoggerDisable to true will increase the
215 * LoggerStopMode footprint.
216 */
217 config Bool supportLoggerDisable = false;
218
219 /*!
220 * @_nodoc
221 * ======== statusLogger ========
222 * For backwards compatibility with ti.uia.runtime.LoggerStopMode.
223 */
224 metaonly config xdc.runtime.IFilterLogger.Handle statusLogger = null;
225
226 /*!
227 * @_nodoc
228 * ======== overflowLogger ========
229 * For backwards compatibility with ti.uia.runtime.LoggerStopMode.
230 */
231 metaonly config ILogger.Handle overflowLogger = null;
232
233 /*!
234 * ======== level1Mask ========
235 * Mask of diags categories whose initial filtering level is Diags.LEVEL1
236 *
237 * See '{@link #level4Mask}' for details.
238 */
239 config Diags.Mask level1Mask = 0;
240
241 /*!
242 * ======== level2Mask ========
243 * Mask of diags categories whose initial filtering level is Diags.LEVEL2
244 *
245 * See '{@link #level4Mask}' for details.
246 */
247 config Diags.Mask level2Mask = 0;
248
249 /*!
250 * ======== level3Mask ========
251 * Mask of diags categories whose initial filtering level is Diags.LEVEL3
252 *
253 * See '{@link #level4Mask}' for details.
254 */
255 config Diags.Mask level3Mask = 0;
256
257 /*!
258 * ======== level4Mask ========
259 * Mask of diags categories whose initial filtering level is Diags.LEVEL4
260 *
261 * If 'filterByLevel' is true, then all LoggerBuf instances will filter
262 * incoming events based on their event level.
263 *
264 * The LoggerStopMode module allows for specifying a different filter level
265 * for every Diags bit. These filtering levels are module wide; LoggerBuf
266 * does not support specifying the levels on a per-instance basis.
267 *
268 * The setFilterLevel API can be used to change the filtering levels at
269 * runtime.
270 *
271 * The default filtering levels are assigned using the 'level1Mask' -
272 * 'level4Mask' config parameters. These are used to specify, for each of
273 * the four event levels, the set of bits which should filter at that
274 * level by default.
275 *
276 * The default filtering configuration sets the filter level to
277 * Diags.LEVEL4 for all logging-related diags bits so that all events are
278 * logged by default.
279 */
280 config Diags.Mask level4Mask = Diags.ALL_LOGGING;
281
282 /*!
283 * @_nodoc
284 * ======== moduleToRouteToStatusLogger ========
285 * For backwards compatibility with ti.uia.runtime.LoggerStopMode.
286 */
287 metaonly config String moduleToRouteToStatusLogger = null;
288
289 /*!
290 * @_nodoc
291 * ======== L_test ========
292 * Event used to benchmark write0.
293 */
294 config xdc.runtime.Log.Event L_test = {
295 mask: xdc.runtime.Diags.USER1,
296 msg: "LoggerStopMode Test"
297 };
298
299 /*!
300 * @_nodoc
301 * ======== E_badLevel ========
302 * Error raised if get or setFilterLevel receive a bad level value
303 */
304 config Error.Id E_badLevel = {
305 msg: "E_badLevel: Bad filter level value: %d"
306 };
307
308 metaonly config Int cacheLineSizeInMAUs = 128;
309
310 metaonly Int getNumInstances();
311
312 /*!
313 * ======== numCores ========
314 * Number of C6X cores running the same image with an instance in shared memory
315 *
316 * A common use case is to have the same binary image (e.g. .out file)
317 * run on multiple cores of multi-core device. This causes a problem if the
318 * logger's buffer is in shared memory (e.g. DDR). Since the image is the
319 * same for all the cores, each core will attempt to write to the same
320 * buffer in the shared memory. To avoid this, either place the logger's
321 * buffers in non-shared memory, or set the numCores parameter to
322 * the number of cores on the device.
323 *
324 * Note: Use the `{@link #bufSection}` along with the Program.sectMap to
325 * place a logger instance's buffer into specific memory.
326 *
327 * Setting numCores to a value greater than 1 signals LoggerStopMode to
328 * statically set aside additional memory ((x numCores) to allow each
329 * core to have `{@link #bufSize}` amount of memory.
330 *
331 * Warning: Setting this parameter to a value greater than one should only
332 * be done when there is a single image used on multiple cores of a
333 * multi-core device AND the logger instance's buffer is in shared memory.
334 * While functionally it will still work, memory will be wasted if both
335 * these conditions are not met.
336 *
337 * The default is 1, which means do not reserve any additional memory
338 * for the logger.
339 *
340 */
341 config Int numCores = 1;
342
343 /*!
344 * @_nodoc
345 * ======== initDecoder ========
346 * Initialize the Java LoggerStopModeDecoder for use in the LoggerStopMode
347 * 'Records' ROV view.
348 */
349 function initDecoder();
350
351 instance:
352
353 /*!
354 * ======== create ========
355 * Create a `LoggerStopMode` logger
356 */
357 create();
358
359 /*!
360 * ======== flush ========
361 * Reset the logger's write pointer back to the beginning of the buffer.
362 */
363 Void flush();
364
365
366 /*!
367 * @_nodoc
368 * ======== initQueueDescriptor ========
369 * Initialize the QueueDescriptor Header
370 * @param(mid) the Logger's module ID
371 */
372 @DirectCall
373 Void initQueueDescriptor(xdc.runtime.Types.ModuleId mid);
374
375 /*!
376 * ======== instanceId ========
377 * Unique id of the LoggerStopMode instance.
378 */
379 config Int16 instanceId = 1;
380
381 /*!
382 * @_nodoc
383 * ======== transferBufSize ========
384 * For backwards compatibility with ti.uia.runtime.LoggerStopMode, bufSize
385 * should be used instead.
386 */
387 config SizeT transferBufSize = 0;
388
389 /*!
390 * ======== maxEventSize ========
391 * The maximum event size (in Maus) that can be written with a single
392 * event. Must be less than or equal to bufSize - 64.
393 *
394 * The writeMemoryRange API checks to see if the event size required to
395 * write the block of memory is larger than maxEventSize. If so, it will
396 * split the memory range up into a number of smaller blocks and log the
397 * blocks using separate events with a common snapshot ID in order to
398 * allow the events to be collated and the original memory block to be
399 * reconstructed on the host.
400 */
401 config SizeT maxEventSize = 512;
402
403 /*!
404 * ======== bufSize ========
405 * LoggerStopMode instance's buffer size in MAUs (Minimum Addressable
406 * Units e.g. Bytes)
407 *
408 * NOTE: the buffer size must contain an integer number of 32-bit words
409 * (e.g. if a MAU = 1 byte, then the buffer size must be a multiple of 4).
410 * The buffer size must also be at least maxEventSize + 64.
411 */
412 config SizeT bufSize = 1400;
413
414 /*!
415 * ======== bufSection ========
416 * Section name for the buffer managed by the static instance.
417 *
418 * The default section is the 'dataMemory' in the platform.
419 */
420 metaonly config String bufSection = null;
421
422 /*!
423 * @_nodoc
424 * ======== bufHeap ========
425 * For backwards compatibility with ti.uia.runtime.LoggerStopMode.
426 */
427 metaonly config xdc.runtime.IHeap.Handle bufHeap = null;
428
429 /*!
430 * ======== write0 ========
431 * Process a log event with 0 arguments.
432 */
433 @DirectCall
434 override Void write0(xdc.runtime.Log.Event evt,
435 xdc.runtime.Types.ModuleId mid);
436
437 /*!
438 * ======== write1 ========
439 * Process a log event with 1 argument.
440 */
441 @DirectCall
442 override Void write1(xdc.runtime.Log.Event evt,
443 xdc.runtime.Types.ModuleId mid,
444 IArg a1);
445
446 /*!
447 * ======== write2 ========
448 * Process a log event with 2 arguments.
449 */
450 @DirectCall
451 override Void write2(xdc.runtime.Log.Event evt,
452 xdc.runtime.Types.ModuleId mid,
453 IArg a1, IArg a2);
454
455 /*!
456 * ======== write4 ========
457 * Process a log event with 4 arguments.
458 */
459 @DirectCall
460 override Void write4(xdc.runtime.Log.Event evt,
461 xdc.runtime.Types.ModuleId mid,
462 IArg a1, IArg a2, IArg a3, IArg a4);
463
464 /*!
465 * ======== write8 ========
466 * Process a log event with 8 arguments.
467 */
468 @DirectCall
469 override Void write8(xdc.runtime.Log.Event evt,
470 xdc.runtime.Types.ModuleId mid,
471 IArg a1, IArg a2, IArg a3, IArg a4,
472 IArg a5, IArg a6, IArg a7, IArg a8);
473
474 /*!
475 * ======== setFilterLevel ========
476 * Sets the level of detail that instances will log.
477 *
478 * Events with the specified level or higher will be logged, events
479 * below the specified level will be dropped.
480 *
481 * Events are filtered first by diags category, then by level. If an
482 * event's diags category is disabled in the module's diags mask, then it
483 * will be filtered out regardless of level. The event will not even be
484 * passed to the logger.
485 *
486 * This API allows for setting the filtering level for more than one
487 * diags category at a time. The mask parameter can be a single category
488 * or multiple categories combined, and the level will be set for all of
489 * those categories.
490 *
491 * @param(mask) The diags categories to set the level for
492 * @param(filterLevel) The new filtering level for the specified
493 * categories
494 */
495 @DirectCall
496 override Void setFilterLevel(Diags.Mask mask, Diags.EventLevel filterLevel);
497
498 /*!
499 * ======== getFilterLevel ========
500 * Returns the mask of diags categories currently set to the specified
501 * level.
502 *
503 * See '{@link #setFilterLevel}' for an explanation of level filtering.
504 */
505 @DirectCall
506 override Diags.Mask getFilterLevel(Diags.EventLevel level);
507
508 /*!
509 * ======== getBufSize ========
510 * Returns the Log's configured buffer size.
511 *
512 * @b(returns) Log's configured buffer size.
513 */
514 @DirectCall
515 SizeT getBufSize();
516
517 internal:
518
519 /*!
520 * @_nodoc
521 * ======== initBuffer ========
522 * Initializes the UIA packet header.
523 */
524 Void initBuffer(Object *obj, Ptr buffer, UInt16 src);
525
526 metaonly config Int maxId = 0;
527
528 /*!
529 * ======== filterOutEvent ========
530 */
531 @DirectCall
532 Bool filterOutEvent(Diags.Mask mask);
533
534 struct Module_State {
535 Bool enabled;
536 Diags.Mask level1;
537 Diags.Mask level2;
538 Diags.Mask level3;
539 };
540
541 struct Instance_State {
542 Bool enabled;
543 Int16 instanceId;
544 UInt32 bufSize;
545 UInt32 *buffer;
546 UInt32 *write;
547 UInt32 *end;
548 SizeT maxEventSizeInBits32;
549 SizeT maxEventSize;
550 UInt16 numBytesInPrevEvent;
551 552 553 554
555 Bits32 droppedEvents;
556 UInt16 eventSequenceNum;
557 UInt16 pktSequenceNum;
558 Char hdr[];
559 Char packetArray[];
560 };
561 }