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
48 /*!
49 * ======== LoggerRunMode ========
50 * General purpose logger enabling applications to stream data
51 * to an instrumentation host through JTAG or ethernet.
52 *
53 * LoggerRunMode events can be streamed to an instrumentation
54 * host in real-time, for targets that support either real-time
55 * JTAG or UIA Ethernet transport. Events can be uploaded without
56 * having to halt the target.
57 *
58 * Each LoggerRunMode instance has its own buffer for events logged to that
59 * instance. By including the header file, ti/uia/runtime/LogUC.h, you
60 * can specify the LoggerRunMode instance that you want the event logged
61 * to.
62 *
63 * The logger's buffer is split up into three or more 'packets' for
64 * more efficient streaming to the host. While one packet is being
65 * read by the host, the others can be written to. When a packet
66 * is filled, the logger starts writing to the next available packet.
67 * Each packet must be large enough to hold {@link #maxEventSize}
68 * bytes, plus an additional number of bytes (64) for a header.
69 * If the configured {@link #bufSize} is not big enough for three
70 * packets of this minimum size, {@link #bufSize} will be increased
71 * automatically.
72 *
73 * The logger stores the events in a {@link ti.uia.runtime.UIAPacket#Hdr UIAPacket_Hdr}
74 * structure that allows them to be sent directly to System Analyzer (e.g. via
75 * UDP), enabling
76 * efficient streaming of the data from the target to the host. The first
77 * four 32-bit words contain a `{@link ti.uia.runtime.UIAPacket#Hdr UIAPacket_Hdr}`
78 * structure. This struct is used by the host (e.g. System Analyzer in CCS)
79 * to help decode the data (e.g. endianess, length of data, etc.).
80 *
81 * The size of the buffer includes the {@link ti.uia.runtime.UIAPacket#Hdr UIAPacket_Hdr}.
82 * LoggerRunMode treats the buffer as a UInt32 array, so the application
83 * must guarantee the buffers are aligned on word addresses. Alignment on
84 * cache line boundaries is recommended for best performance.
85 *
86 * LoggerRunMode will overwrite older events if the host is not able
87 * to upload events quickly enough.
88 *
89 * LoggerRunMode was designed to have as minimal impact as possible on an
90 * application when calling a Log function. There are several configuration
91 * parameters that allow an application to get the optimal performance in
92 * exchange for certain restrictions.
93 *
94 * Interrupts are disabled during the duration of the log call.
95 *
96 * NOTE: It is recommended that you use {@link ti.uia.sysbios.LoggingSetup LoggingSetup}
97 * to configure the Logger instances. For example to use LoggerRunMode with
98 * real-time JTAG transport, set
99 * {@link ti.uia.sysbios.LoggingSetup#loggerType LoggingSetup.loggerType}
100 * to {@link ti.uia.sysbios.LoggingSetup#LoggerType_JTAGRUNMODE LoggingSetup.LoggerType_JTAGRUNMODE}.
101 *
102 * @a(Examples)
103 * The following XDC configuration statements
104 * create a logger module, and assign it as the default logger for all
105 * modules.
106 *
107 * @p(code)
108 * var Defaults = xdc.useModule('xdc.runtime.Defaults');
109 * var Diags = xdc.useModule('xdc.runtime.Diags');
110 * var LoggerRunMode = xdc.useModule('ti.uia.loggers.LoggerRunMode');
111 *
112 * LoggerRunMode.isTimestampEnabled = true;
113 *
114 * var loggerParams = new LoggerRunMode.Params();
115 *
116 * Program.global.logger0 = LoggerRunMode.create(loggerParams);
117 * Defaults.common$.logger = Program.global.logger0;
118 *
119 * @p
120 *
121 * @a(Examples)
122 * The following C code demonstrates logging to different LoggerRunMode
123 * instances.
124 *
125 * @p(code)
126 * #include <xdc/std.h>
127 * #include <xdc/runtime/Diags.h>
128 * #include <xdc/runtime/Log.h>
129 * #include <ti/uia/loggers/LoggerRunMode.h>
130 * #include <ti/uia/runtime/LogUC.h>
131 *
132 * Int main(Int argc, String argv[])
133 * {
134 * Log_iwriteUC0(logger0, LoggerRunMode_L_test);
135 * Log_iwriteUC1(logger1, LoggerRunMode_L_test, 0x1000);
136 * }
137 *
138 * @p
139 *
140 * @a(Examples)
141 * The following XDC configuration statements show how to use LoggingSetup
142 * with LoggerRunMode.
143 *
144 * @p(code)
145 *
146 * var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
147 * LoggingSetup.loggerType = LoggingSetup.LoggingSetup_JTAGRUNMODE;
148 *
149 * @p
150 */
151
152 @ModuleStartup
153 @Template("./LoggerRunMode.xdt")
154 @CustomHeader
155 module LoggerRunMode inherits ILoggerSnapshot {
156
157 /*!
158 * ======== TransportType ========
159 * This enum is used by the instrumentation host to determine what
160 * the transport is.
161 */
162 enum TransportType {
163 TransportType_JTAG = 0,
164 TransportType_ETHERNET = 1
165 };
166
167 /*!
168 * @_nodoc
169 * ======== ModuleView ========
170 */
171 metaonly struct ModuleView {
172 Bool isEnabled;
173 Bool isTimestampEnabled;
174 String transportType;
175 }
176
177 /*!
178 * @_nodoc
179 * ======== InstanceView ========
180 */
181 metaonly struct InstanceView {
182 String label;
183 Bool enabled;
184 Int bufferSize;
185 SizeT maxEventSize;
186 }
187
188 metaonly struct RecordView {
189 Int sequence;
190 Long timestampRaw;
191 String modName;
192 String text;
193 Int eventId;
194 String eventName;
195 IArg arg0;
196 IArg arg1;
197 IArg arg2;
198 IArg arg3;
199 IArg arg4;
200 IArg arg5;
201 IArg arg6;
202 IArg arg7;
203 }
204
205 /*!
206 * @_nodoc
207 * ======== rovViewInfo ========
208 */
209 @Facet
210 metaonly config ViewInfo.Instance rovViewInfo =
211 ViewInfo.create({
212 viewMap: [
213 ['Module',
214 {
215 type: ViewInfo.MODULE,
216 viewInitFxn: 'viewInitModule',
217 structName: 'ModuleView'
218 }
219 ],
220 ['Instances',
221 {
222 type: ViewInfo.INSTANCE,
223 viewInitFxn: 'viewInitInstances',
224 structName: 'InstanceView'
225 }
226 ],
227 ['Records',
228 {
229 type: xdc.rov.ViewInfo.INSTANCE_DATA,
230 viewInitFxn: 'viewInitRecords',
231 structName: 'RecordView'
232 }
233 ]
234 ]
235 });
236
237 /*!
238 * ======== RtaData ========
239 * Data added to the RTA MetaData file to support System Analyzer
240 */
241 @XmlDtd metaonly struct RtaData {
242 Int instanceId;
243 }
244
245 /*!
246 * ======== transportType ========
247 * Transport used to send the records to an instrumentation host
248 *
249 * This parameter is used to specify the transport that will
250 * be used to send the buffer to an instrumentation host (e.g. System
251 * Analyzer in CCS).
252 *
253 * This parameter is placed into the generated UIA XML file. The
254 * instrumentation host can use the XML file to help it auto-detect as
255 * much as possible and act accordingly.
256 */
257 metaonly config TransportType transportType = TransportType_JTAG;
258
259 /*!
260 * @_nodoc
261 * ======== customTransportType ========
262 * Custom transport used to send the records to an instrumentation host
263 *
264 * If the desired transport is not in the `{@link #TransportType}` enum,
265 * and `{@link #transportType}` is set to `{@link #TransportType_CUSTOM}`,
266 * this parameter must be filled in with the correct transport name.
267 *
268 * If `{@link #transportType}` is NOT set to
269 * `{@link #TransportType_CUSTOM}`, this parameter is ignored.
270 */
271 config String customTransportType = null;
272
273 /*!
274 * ======== isTimestampEnabled ========
275 * Enable or disable logging the 64-bit local CPU timestamp
276 * at the start of each event
277 *
278 * Having a timestamp allows an instrumentation host (e.g.
279 * System Analyzer) to display events with the correct system time.
280 */
281 config Bool isTimestampEnabled = true;
282
283 /*!
284 * ======== supportLoggerDisable ========
285 * Allow LoggerRunMode instances to be enabled/disabled during runtime.
286 *
287 * Setting supportLoggerDisable to true will increase the
288 * footprint of LoggerRunMode.
289 */
290 config Bool supportLoggerDisable = false;
291
292 /*!
293 * @_nodoc
294 * ======== statusLogger ========
295 * For backwards compatibility with ti.uia.runtime.LoggerStopMode.
296 */
297 metaonly config xdc.runtime.IFilterLogger.Handle statusLogger = null;
298
299 /*!
300 * @_nodoc
301 * ======== overflowLogger ========
302 * For backwards compatibility with ti.uia.runtime.LoggerStopMode.
303 */
304 metaonly config ILogger.Handle overflowLogger = null;
305
306 /*!
307 * ======== level1Mask ========
308 * Mask of diags categories whose initial filtering level is Diags.LEVEL1
309 *
310 * See '{@link #level4Mask}' for details.
311 */
312 config Diags.Mask level1Mask = 0;
313
314 /*!
315 * ======== level2Mask ========
316 * Mask of diags categories whose initial filtering level is Diags.LEVEL2
317 *
318 * See '{@link #level4Mask}' for details.
319 */
320 config Diags.Mask level2Mask = 0;
321
322 /*!
323 * ======== level3Mask ========
324 * Mask of diags categories whose initial filtering level is Diags.LEVEL3
325 *
326 * See '{@link #level4Mask}' for details.
327 */
328 config Diags.Mask level3Mask = 0;
329
330 /*!
331 * ======== level4Mask ========
332 * Mask of diags categories whose initial filtering level is Diags.LEVEL4
333 *
334 * If 'filterByLevel' is true, then all LoggerBuf instances will filter
335 * incoming events based on their event level.
336 *
337 * The LoggerRunMode module allows for specifying a different filter level
338 * for every Diags bit. These filtering levels are module wide; LoggerBuf
339 * does not support specifying the levels on a per-instance basis.
340 *
341 * The setFilterLevel API can be used to change the filtering levels at
342 * runtime.
343 *
344 * The default filtering levels are assigned using the 'level1Mask' -
345 * 'level4Mask' config parameters. These are used to specify, for each of
346 * the four event levels, the set of bits which should filter at that
347 * level by default.
348 *
349 * The default filtering configuration sets the filter level to
350 * Diags.LEVEL4 for all logging-related diags bits so that all events are
351 * logged by default.
352 */
353 config Diags.Mask level4Mask = Diags.ALL_LOGGING;
354
355 /*!
356 * @_nodoc
357 * ======== moduleToRouteToStatusLogger ========
358 * For backwards compatibility with ti.uia.runtime.LoggerStopMode.
359 */
360 metaonly config String moduleToRouteToStatusLogger = null;
361
362 /*!
363 * @_nodoc
364 * ======== L_test ========
365 * Event used to benchmark write0.
366 */
367 config xdc.runtime.Log.Event L_test = {
368 mask: xdc.runtime.Diags.USER1,
369 msg: "LoggerRunMode Test"
370 };
371
372 /*!
373 * @_nodoc
374 * ======== E_badLevel ========
375 * Error raised if get or setFilterLevel receive a bad level value
376 */
377 config Error.Id E_badLevel = {
378 msg: "E_badLevel: Bad filter level value: %d"
379 };
380
381 metaonly config Int cacheLineSizeInMAUs = 128;
382
383 metaonly Int getNumInstances();
384
385 /*!
386 * ======== numCores ========
387 * The number of C6X cores running the same image with an instance in
388 * shared memory.
389 *
390 * A common use case is to have the same binary image (e.g. .out file)
391 * run on multiple cores of multi-core device. This causes a problem if the
392 * logger's buffer is in shared memory (e.g. DDR). Since the image is the
393 * same for all the cores, each core will attempt to write to the same
394 * buffer in the shared memory. To avoid this, either place the logger's
395 * buffers in non-shared memory, or set the numCores parameter to
396 * the number of cores on the device.
397 *
398 * Note: Use the `{@link #bufSection}` along with the Program.sectMap to
399 * place a logger instance's buffer into specific memory.
400 *
401 * Setting numCores to a value greater than 1 signals LoggerRunMode to
402 * statically set aside additional memory ((x numCores) to allow each
403 * core to have `{@link #transferBufSize}` amount of memory.
404 *
405 * Warning: Setting this parameter to a value greater than one should only
406 * be done when there is a single image used on multiple cores of a
407 * multi-core device AND the logger instance's buffer is in shared memory.
408 * While functionally it will still work, memory will be wasted if both
409 * these conditions are not met.
410 *
411 * The default is 1, which means do not reserve any additional memory
412 * for the logger.
413 *
414 */
415 config Int numCores = 1;
416
417 /*!
418 * @_nodoc
419 * ======== initDecoder ========
420 * Initialize the Java LoggerRunModeDecoder for use in the LoggerRunMode
421 * 'Records' ROV view.
422 */
423 function initDecoder();
424
425
426 /*!
427 * ======== cpuId=========
428 * CPU ID to put in the packet header as the endpoint ID.
429 *
430 * Not required for C6X or C7X devices (uses DNUM).
431 */
432 metaonly config Int cpuId = 0;
433
434 /*!
435 * @_nodoc
436 * ======== isUploadRequired ========
437 * Returns true if aprox. 1 second has elapsed since the last call to flush()
438 */
439 @DirectCall
440 Bool isUploadRequired();
441
442 /*!
443 * ======== idleHook ========
444 * Hook function that can be called by SysBios's Idle loop.
445 * This function ensures that events are uploaded in a timely manner even if
446 * they are logged infrequently.
447 */
448 @DirectCall
449 Void idleHook();
450
451 /*!
452 * ======== enableAutoConfigOfIdleHook ========
453 * If true, the ti.sysbios.knl.Idle module will automatically be
454 * configured to call LoggerRunMode\s idleHook function.
455 * This function ensures that events are uploaded in a timely manner even if
456 * they are logged infrequently. Set to false if you do not
457 * wish to use the ti.sysbios.nk.Idle module.
458 */
459 metaonly config Bool enableAutoConfigOfIdleHook = true;
460
461 instance:
462
463 /*!
464 * ======== create ========
465 * Create a `LoggerRunMode` logger
466 */
467 create();
468
469 /*!
470 * @_nodoc
471 * ======== initBuffer ========
472 * Initializes the UIA packet header.
473 *
474 * This API is used to initialize a buffer before it is given to
475 * LoggerRunMode (via priming or exchange). The function initializes
476 * the {@link ti.uia.runtime.UIAPacket#Hdr UIAPacket_Hdr} portion of the buffer.
477 *
478 * @param(buffer) Pointer to the buffer that LoggerRunMode will
479 * fill with Log events. The first four 32-bit words
480 * will contain the UIAPacket_Hdr structure.
481 *
482 * @param(src) Used to initialize the UIA source address. For
483 * a single core device, this will generally be 0.
484 * For multi-core devices, it generally corresponds
485 * to the DNUM (on C6xxxx deviecs) or the Ipc
486 * MultiProc id. It must be unique for all cores and
487 * match the configuration in the System Analyzer
488 * endpoint configuration.
489 */
490 Void initBuffer(Ptr buffer, UInt16 src);
491
492 /*!
493 * @_nodoc
494 * ======== flush ========
495 * Force LoggerRunMode to use the next packet.
496 */
497 Void flush();
498
499 /*!
500 * @_nodoc
501 * ======== prime ========
502 * Initializes the event buffer prior to event logging
503 */
504 @DirectCall
505 Ptr prime();
506
507 /*!
508 * @_nodoc
509 * ======== exchange ========
510 * Set the logger's write pointer to the next packet.
511 */
512 @DirectCall
513 Ptr exchange(Ptr full, Ptr lastWritePtr);
514
515
516 /*!
517 * @_nodoc
518 * ======== initQueueDescriptor ========
519 * Initialize the QueueDescriptor Header (for use
520 * with JTAGRUNMODE transport)
521 * @param(mid) the Logger's module ID
522 */
523 @DirectCall
524 Void initQueueDescriptor(xdc.runtime.Types.ModuleId mid);
525
526 /*!
527 * ======== instanceId ========
528 * Unique id of the LoggerRunMode instance.
529 */
530 config Int16 instanceId = 1;
531
532 /*!
533 * @_nodoc
534 * ======== transferBufSize ========
535 * For backwards compatibility with ti.uia.runtime.LoggerStopMode, bufSize
536 * should be used instead.
537 */
538 config SizeT transferBufSize = 0;
539
540 /*!
541 * ======== maxEventSize ========
542 * The maximum event size (in Maus) that can be written with a single
543 * event. Must be less than or equal to bufSize - 64.
544 *
545 * The writeMemoryRange API checks to see if the event size required to
546 * write the block of memory is larger than maxEventSize. If so, it will
547 * split the memory range up into a number of smaller blocks and log the
548 * blocks using separate events with a common snapshot ID in order to
549 * allow the events to be collated and the original memory block to be
550 * reconstructed on the host.
551 */
552 config SizeT maxEventSize = 512;
553
554 /*!
555 * ======== bufSize ========
556 * LoggerRunMode instance's buffer size in MAUs (Minimum Addressable
557 * Units e.g. Bytes)
558 *
559 * NOTE: the buffer size must contain an integer number of 32-bit words
560 * (e.g. if a MAU = 1 byte, then the buffer size must be a multiple of 4).
561 * The buffer size must also be at least maxEventSize + 64.
562 */
563 config SizeT bufSize = 1024;
564
565 /*!
566 * ======== bufSection ========
567 * Section name for the buffer managed by the static instance.
568 *
569 * The default section is the 'dataMemory' in the platform.
570 */
571 metaonly config String bufSection = null;
572
573 /*!
574 * @_nodoc
575 * ======== bufHeap ========
576 * For backwards compatibility with ti.uia.runtime.LoggerStopMode.
577 */
578 metaonly config xdc.runtime.IHeap.Handle bufHeap = null;
579
580 /*!
581 * ======== write0 ========
582 * Process a log event with 0 arguments.
583 */
584 @DirectCall
585 override Void write0(xdc.runtime.Log.Event evt,
586 xdc.runtime.Types.ModuleId mid);
587
588 /*!
589 * ======== write1 ========
590 * Process a log event with 1 argument.
591 */
592 @DirectCall
593 override Void write1(xdc.runtime.Log.Event evt,
594 xdc.runtime.Types.ModuleId mid,
595 IArg a1);
596
597 /*!
598 * ======== write2 ========
599 * Process a log event with 2 arguments.
600 */
601 @DirectCall
602 override Void write2(xdc.runtime.Log.Event evt,
603 xdc.runtime.Types.ModuleId mid,
604 IArg a1, IArg a2);
605
606 /*!
607 * ======== write4 ========
608 * Process a log event with 4 arguments.
609 */
610 @DirectCall
611 override Void write4(xdc.runtime.Log.Event evt,
612 xdc.runtime.Types.ModuleId mid,
613 IArg a1, IArg a2, IArg a3, IArg a4);
614
615 /*!
616 * ======== write8 ========
617 * Process a log event with 8 arguments.
618 */
619 @DirectCall
620 override Void write8(xdc.runtime.Log.Event evt,
621 xdc.runtime.Types.ModuleId mid,
622 IArg a1, IArg a2, IArg a3, IArg a4,
623 IArg a5, IArg a6, IArg a7, IArg a8);
624
625 /*!
626 * ======== setFilterLevel ========
627 * Sets the level of detail that instances will log.
628 *
629 * Events with the specified level or higher will be logged, events
630 * below the specified level will be dropped.
631 *
632 * Events are filtered first by diags category, then by level. If an
633 * event's diags category is disabled in the module's diags mask, then it
634 * will be filtered out regardless of level. The event will not even be
635 * passed to the logger.
636 *
637 * This API allows for setting the filtering level for more than one
638 * diags category at a time. The mask parameter can be a single category
639 * or multiple categories combined, and the level will be set for all of
640 * those categories.
641 *
642 * @param(mask) The diags categories to set the level for
643 * @param(filterLevel) The new filtering level for the specified
644 * categories
645 */
646 @DirectCall
647 override Void setFilterLevel(Diags.Mask mask, Diags.EventLevel filterLevel);
648
649 /*!
650 * ======== getFilterLevel ========
651 * Returns the mask of diags categories currently set to the specified
652 * level.
653 *
654 * See '{@link #setFilterLevel}' for an explanation of level filtering.
655 */
656 @DirectCall
657 override Diags.Mask getFilterLevel(Diags.EventLevel level);
658
659 /*!
660 * ======== getBufSize ========
661 * Returns the Log's configured buffer size.
662 *
663 * @b(returns) Log's configured buffer size.
664 */
665 @DirectCall
666 SizeT getBufSize();
667
668 internal:
669 metaonly config Int maxId = 0;
670
671 /*!
672 * ======== filterOutEvent ========
673 */
674 @DirectCall
675 Bool filterOutEvent(Diags.Mask mask);
676
677 /*!
678 * ======== writeStart ========
679 */
680 @DirectCall
681 Ptr writeStart(Object *obj, xdc.runtime.Log.Event evt,
682 xdc.runtime.Types.ModuleId mid, UInt16 numBytes);
683
684 struct Module_State {
685 Bool enabled;
686 Diags.Mask level1;
687 Diags.Mask level2;
688 Diags.Mask level3;
689 Bits32 lastUploadTstamp;
690 };
691
692 struct Instance_State {
693 Bool enabled;
694 Int16 instanceId;
695 Bool primeStatus;
696 UInt32 bufSize;
697 UInt32 *buffer;
698 UInt32 *write;
699 UInt32 *end;
700 SizeT maxEventSizeInBits32;
701 SizeT maxEventSize;
702 UInt16 numBytesInPrevEvent;
703 704 705 706
707 Bits32 droppedEvents;
708 UInt16 eventSequenceNum;
709 UInt16 pktSequenceNum;
710
711 712 713 714
715 Char hdr[];
716
717 718 719 720
721 Char packetArray[];
722 Int numPackets;
723 UInt32 packetSize;
724 };
725 }