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 import xdc.runtime.Diags;
38 import xdc.runtime.Types;
39 import ti.uia.events.DvtTypes;
40
41 /*!
42 * UIA Roundtrip Events
43 *
44 * The UIARoundtrip module defines events that allow
45 * tooling to analyze the absolute time elapsed between
46 * a start point event and a stop point event. It differs
47 * from UIABenchmark in that UIABenchmark supports context-awareness
48 * (i.e. exclusive time elapsed) whereas UIARoundtrip is always
49 * inclusive (i.e. the time elapsed that DVT displays includes
50 * time spent in all other threads / tasks).
51 *
52 * The generation of UIARoundtrip events is controlled by a module's diagnostics
53 * mask, which is described in details in `{@link xdc.runtime.Diags}`.
54 * `UIARoundtrip` events are generated only when the Diags.ANALYSIS bit is set
55 * in the module's diagnostics mask.
56 *
57 * The following configuration script demonstrates how the application might
58 * control the logging of ANALYSIS events embedded in the `Mod` module at configuration
59 * time. In this case, the configuration script arranges for the `Log`
60 * statements within modules to always generate ANALYSIS events.
61 * Without these configuration statements, no ANALYSIS events would be generated
62 * by any modules.
63 *
64 * @a(Examples)
65 * Example 1: This is part of the XDC configuration file for the application:
66 *
67 * @p(code)
68 * var UIARoundtrip = xdc.useModule('ti.uia.events.UIARoundtrip');
69 * var Diags = xdc.useModule('xdc.runtime.Diags');
70 * var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
71 * var Defaults = xdc.useModule('xdc.runtime.Defaults');
72 * var logger = LoggerSys.create();
73 *
74 * Defaults.common$.diags_ANALYSIS = Diags.ALWAYS_ON;
75 * Defaults.common$.logger = logger;
76 * @p
77 *
78 * @p(html)
79 * <hr />
80 * @p
81 *
82 * Example 2: The following example configures a module to support logging
83 * of ANALYSIS events, but defers the actual activation and deactivation of the
84 * logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
85 * function for details on specifying the control string.
86 *
87 * This is a part of the XDC configuration file for the application:
88 *
89 * @p(code)
90 * var UIARoundtrip = xdc.useModule('ti.uia.events.UIARoundtrip');
91 * var Diags = xdc.useModule('xdc.runtime.Diags');
92 * var Mod = xdc.useModule('my.pkg.Mod');
93 *
94 * Mod.common$.diags_ANALYSIS = Diags.RUNTIME_OFF;
95 * @p
96 *
97 * This is a part of the C code for the application:
98 *
99 * @p(code)
100 * // turn on logging of ANALYSIS events in the module
101 * Diags_setMask("my.pkg.Mod+Z");
102 *
103 * // turn off logging of ANALYSIS events in the module
104 * Diags_setMask("my.pkg.Mod-Z");
105 * @p
106 */
107
108 module UIARoundtrip inherits IUIAEvent {
109
110 /*!
111 * ======== start ========
112 * Roundtrip event used to log the start of an operation
113 *
114 * @a(Example)
115 * The following C code shows how to log a simple
116 * roundtrip 'start' event along with a user-specified
117 * format string describing the event.
118 *
119 * @p(code)
120 * #include <xdc/runtime/Log.h>
121 * #include <ti/uia/events/UIARoundtrip.h>
122 * ...
123 * Log_write1(UIARoundtrip_start, "My roundtrip event");
124 * @p
125 * The following text will be displayed for the event:
126 * @p(code)
127 * Roundtrip_Start: My roundtrip event
128 * @p
129 *
130 * @param(fmt) a constant string that provides format specifiers for up to 6 additional parameters
131 */
132 config xdc.runtime.Log.Event start = {
133 mask: Diags.ANALYSIS,
134 msg: "Roundtrip_Start: %$S"};
135
136 /*!
137 * ======== metaEventStart ========
138 * Metadata description of the start event
139 *
140 * @_nodoc
141 */
142 metaonly config DvtTypes.MetaEventDescriptor metaEventStart = {
143 versionId: "2.0",
144 analysisType: DvtTypes.DvtAnalysisType_START,
145 displayText: "Roundtrip_Start",
146 tooltipText: "Marks the start of analysis",
147 numParameters: 1,
148 paramInfo: [
149 { name: 'fmt',
150 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
151 dataTypeName: 'String',
152 units: 'none',
153 isHidden: false
154 }]
155 };
156
157 /*!
158 * ======== stop ========
159 * Roundtrip event used to log the end of an operation
160 *
161 * @a(Example)
162 * The following C code shows how to log a simple
163 * roundtrip 'stop' event along with a user-specified
164 * format string describing the event.
165 *
166 * @p(code)
167 * #include <xdc/runtime/Log.h>
168 * #include <ti/uia/events/UIARoundtrip.h>
169 * ...
170 * Log_write1(UIARoundtrip_stop, "My roundtrip event");
171 * @p
172 * The following text will be displayed for the event:
173 * @p(code)
174 * Roundtrip_Stop: My roundtrip event
175 * @p
176 * @param(fmt) a constant string that provides format specifiers for up to 6 additional parameters
177 */
178 config xdc.runtime.Log.Event stop = {
179 mask: Diags.ANALYSIS,
180 msg: "Roundtrip_Stop: %$S"};
181
182 /*!
183 * ======== metaEventStop ========
184 * Metadata description of the stop event
185 *
186 * @_nodoc
187 */
188 metaonly config DvtTypes.MetaEventDescriptor metaEventStop = {
189 versionId: "2.0",
190 analysisType: DvtTypes.DvtAnalysisType_STOP,
191 displayText: "Roundtrip_Stop",
192 tooltipText: "Marks the end of analysis",
193 numParameters: 1,
194 paramInfo: [
195 { name: 'fmt',
196 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
197 dataTypeName: 'String',
198 units: 'none',
199 isHidden: false
200 }]
201 };
202 /*!
203 * ======== startInstance ========
204 * Roundtrip event used to log the start of an operation instance
205 *
206 * Event parameter provides instance data to differentiate
207 * between multiple instances that can run in parallel.
208 *
209 * @a(Example)
210 * The following C code shows how to log a roundtrip
211 * 'startInstance' event along with a user-specified
212 * instance identifier and a format string describing the event.
213 *
214 * @p(code)
215 * #include <xdc/runtime/Gate.h>
216 * #include <xdc/runtime/Log.h>
217 * #include <ti/uia/events/UIARoundtrip.h>
218 * static volatile int gMyGlobalInstanceId = 0;
219 * ...
220 * IArg key;
221 * int localInstanceId;
222 *
223 * // protect pre-increment operation from race conditions
224 * key = Gate_enterSystem();
225 * localInstanceId = ++gMyGlobalInstanceId;
226 * Gate_leaveSystem(key);
227 *
228 * Log_write2(UIARoundtrip_startInstance, "My roundtrip event: instanceId=%d",localInstanceId);
229 * ...
230 * Log_write2(UIARoundtrip_stopInstance, "My roundtrip event: instanceId=%d",localInstanceId);
231 * @p
232 * The following text will be displayed for the event:
233 * @p(code)
234 * Roundtrip_StartInstance: My roundtrip event: instanceId=1
235 * Roundtrip_StopInstance: My roundtrip event: instanceId=1
236 * @p
237 * @param(fmt) a constant string that provides format specifiers for up to 5 additional parameters
238 * @param(instanceId) a unique instance ID that can be used to match Roundtrip start and stop events
239 */
240 config xdc.runtime.Log.Event startInstance = {
241 mask: Diags.ANALYSIS,
242 msg: "Roundtrip_StartInstance: %$S"
243 };
244
245 /*!
246 * ======== metaEventStartInstance ========
247 * Metadata description of the startInstance event
248 *
249 * @_nodoc
250 */
251 metaonly config DvtTypes.MetaEventDescriptor metaEventStartInstance = {
252 versionId: "2.0",
253 analysisType: DvtTypes.DvtAnalysisType_START,
254 displayText: "Roundtrip_StartInstance",
255 tooltipText: "Marks the start of analysis for a module instance",
256 numParameters: 2,
257 paramInfo: [
258 { name: 'fmt',
259 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
260 dataTypeName: 'String',
261 units: 'none',
262 isHidden: false
263 },
264 { name: 'InstanceID',
265 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
266 dataTypeName: 'Int',
267 units: 'none',
268 isHidden: false
269 }
270 ]
271 };
272
273 /*!
274 * ======== stopInstance ========
275 * Roundtrip event used to log the end of an operation instance
276 *
277 * Event parameter provides instance data to differentiate
278 * between multiple instances that can run in parallel
279 * @a(Example)
280 * The following C code shows how to log a roundtrip
281 * 'stopInstance' event along with a user-specified
282 * instance identifier and a format string describing the event.
283 *
284 * @p(code)
285 * #include <xdc/runtime/Gate.h>
286 * #include <xdc/runtime/Log.h>
287 * #include <ti/uia/events/UIARoundtrip.h>
288 * static volatile int gMyGlobalInstanceId = 0;
289 * ...
290 * IArg key;
291 * int localInstanceId;
292 *
293 * // protect pre-increment operation from race conditions
294 * key = Gate_enterSystem();
295 * localInstanceId = ++gMyGlobalInstanceId;
296 * Gate_leaveSystem(key);
297 *
298 * Log_write2(UIARoundtrip_startInstance, "My roundtrip event: instanceId=%d",localInstanceId);
299 * ...
300 * Log_write2(UIARoundtrip_stopInstance, "My roundtrip event: instanceId=%d",localInstanceId);
301 * @p
302 * The following text will be displayed for the event:
303 * @p(code)
304 * Roundtrip_StartInstance: My roundtrip event: instanceId=1
305 * Roundtrip_StopInstance: My roundtrip event: instanceId=1
306 * @p
307 * @param(fmt) a constant string that provides format specifiers for up to 4 additional parameters
308 * @param(instanceId) a unique instance ID that can be used to match Roundtrip start and stop events
309 */
310 config xdc.runtime.Log.Event stopInstance = {
311 mask: Diags.ANALYSIS,
312 msg: "Roundtrip_StopInstance: %$S"
313 };
314
315 /*!
316 * ======== metaEventStopInstance ========
317 * Metadata description of the stopInstance event
318 *
319 * @_nodoc
320 */
321 metaonly config DvtTypes.MetaEventDescriptor metaEventStopInstance = {
322 versionId: "2.0",
323 analysisType: DvtTypes.DvtAnalysisType_STOP,
324 displayText: "Roundtrip_StopInstance",
325 tooltipText: "Marks the end of analysis for a module instance",
326 numParameters: 2,
327 paramInfo: [
328 { name: 'fmt',
329 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
330 dataTypeName: 'String',
331 units: 'none',
332 isHidden: false
333 },
334 { name: 'InstanceID',
335 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
336 dataTypeName: 'Int',
337 units: 'none',
338 isHidden: false
339 }
340 ]
341 };
342
343
344 /*!
345 * ======== startInstanceWithAdrs ========
346 * Roundtrip event used to log the start of an operation instance
347 *
348 * Event parameter provides instance data to differentiate
349 * between multiple instances that can run in parallel
350 *
351 * @a(Example)
352 * The following C code shows how to log a roundtrip
353 * 'startInstanceWithAdrs' event along with a task handle as the
354 * instance identifier, the function address and a format string
355 * describing the event.
356 *
357 * @p(code)
358 * #include <ti/sysbios/knl/Task.h>
359 * #include <xdc/runtime/Log.h>
360 * #include <ti/uia/events/UIARoundtrip.h>
361 * ...
362 * Void myFunction(){
363 * Task_Handle hTsk = Task_selfMacro( );
364 *
365 * Log_write3(UIARoundtrip_startInstanceWithAdrs, "My roundtrip event: task=0x%x, fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
366 * ...
367 * Log_write3(UIARoundtrip_stopInstanceWithAdrs, "My roundtrip event: task=0x%x", fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
368 * }
369 * @p
370 * The following text will be displayed for the event:
371 * @p(code)
372 * Roundtrip_StartInstanceWithAdrs: My roundtrip event: task=0x893230, fnAdrs=0x820060
373 * Roundtrip_StopInstanceWithAdrs: My roundtrip event: task=0x893230, fnAdrs=0x820060
374 * @p
375 * @param(fmt) a constant string that provides format specifiers for up to 5 additional parameters
376 * @param(instanceId) a unique instance ID that can be used to match benchmark start and stop events
377 * @param(functionAdrs) the address of a function that can differentiate this pair of start and stop events from others
378
379 */
380 config xdc.runtime.Log.Event startInstanceWithAdrs = {
381 mask: Diags.ANALYSIS,
382 msg: "Roundtrip_StartInstanceWithAdrs: %$S"
383 };
384
385 /*!
386 * ======== metaEventStartInstanceWithAdrs ========
387 * Metadata description of the startInstanceWithAdrs event
388 *
389 * @_nodoc
390 */
391 metaonly config DvtTypes.MetaEventDescriptor metaEventStartInstanceWithAdrs = {
392 versionId: "2.0",
393 analysisType: DvtTypes.DvtAnalysisType_START,
394 displayText: "Roundtrip_StartInstanceWithAdrs",
395 tooltipText: "Marks the start of analysis for a module instance",
396 numParameters: 3,
397 paramInfo: [
398 { name: 'fmt',
399 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
400 dataTypeName: 'String',
401 units: 'none',
402 isHidden: false
403 },
404 { name: 'InstanceID',
405 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
406 dataTypeName: 'Int',
407 units: 'none',
408 isHidden: false
409 },
410 { name: 'FunctionAdrs',
411 dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
412 dataTypeName: 'Int',
413 units: 'none',
414 isHidden: false
415 }
416 ]
417 };
418
419
420
421
422
423 /*!
424 * ======== stopInstanceWithAdrs ========
425 * Roundtrip event used to log the end of an operation instance
426 *
427 * @a(Example)
428 * The following C code shows how to log a roundtrip
429 * 'stopInstanceWithAdrs' event along with a task handle as the
430 * instance identifier, the function address and a format string
431 * describing the event.
432 *
433 * @p(code)
434 * #include <ti/sysbios/knl/Task.h>
435 * #include <xdc/runtime/Log.h>
436 * #include <ti/uia/events/UIARoundtrip.h>
437 * ...
438 * Void myFunction(){
439 * Task_Handle hTsk = Task_selfMacro( );
440 *
441 * Log_write3(UIARoundtrip_startInstanceWithAdrs, "My roundtrip event: task=0x%x, fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
442 * ...
443 * Log_write3(UIARoundtrip_stopInstanceWithAdrs, "My roundtrip event: task=0x%x", fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
444 * }
445 * @p
446 * The following text will be displayed for the event:
447 * @p(code)
448 * Roundtrip_StartInstanceWithAdrs: My roundtrip event: task=0x893230, fnAdrs=0x820060
449 * Roundtrip_StopInstanceWithAdrs: My roundtrip event: task=0x893230, fnAdrs=0x820060
450 * @p
451 * @param(fmt) a constant string that provides format specifiers for up to 4 additional parameters
452 * @param(instanceId) a unique instance ID that can be used to match Roundtrip start and stop events
453 * @param(functionAdrs) the address of the function
454 */
455 config xdc.runtime.Log.Event stopInstanceWithAdrs = {
456 mask: Diags.ANALYSIS,
457 msg: "Roundtrip_StopInstanceWithAdrs: %$S"
458 };
459
460 /*!
461 * ======== metaEventStopInstanceWithAdrs ========
462 * Metadata description of the stopInstanceWithAdrs event
463 *
464 * @_nodoc
465 */
466 metaonly config DvtTypes.MetaEventDescriptor metaEventStopInstanceWithAdrs = {
467 versionId: "2.0",
468 analysisType: DvtTypes.DvtAnalysisType_STOP,
469 displayText: "Roundtrip_StopInstanceWithAdrs",
470 tooltipText: "Marks the end of analysis for a module instance",
471 numParameters: 3,
472 paramInfo: [
473 { name: 'fmt',
474 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
475 dataTypeName: 'String',
476 units: 'none',
477 isHidden: false
478 },
479 { name: 'Handle',
480 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
481 dataTypeName: 'Int',
482 units: 'none',
483 isHidden: false
484 },
485 { name: 'FunctionAdrs',
486 dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
487 dataTypeName: 'Int',
488 units: 'none',
489 isHidden: false
490 }
491 ]
492 };
493
494
495 /*!
496 * ======== startInstanceWithStr ========
497 * Roundtrip event used to log the start of an operation instance
498 *
499 * Event parameter provides instance data to differentiate
500 * between multiple instances that can run in parallel
501 * @a(Example)
502 * The following C code shows how to log a roundtrip
503 * 'startInstanceWithStr' event along with a unique instance identifier
504 * and a string reference used only by the pair of start / stop events.
505 *
506 * @p(code)
507 * #include <xdc/runtime/Log.h>
508 * #include <ti/uia/events/UIARoundtrip.h>
509 * ...
510 * Void packetHdlr(Int packetId){
511 *
512 * Log_write3(UIARoundtrip_startInstanceWithStr, "My roundtrip event: packetId=0x%x",packetId,(IArg)"(routing)");
513 * ...
514 * Log_write3(UIARoundtrip_stopInstanceWithStr, "My roundtrip event: packetId=0x%x",packetId,(IArg)"(routing)");
515 * }
516 * @p
517 * The following text will be displayed for the event:
518 * @p(code)
519 * Roundtrip_StartInstanceWithStr: My roundtrip event: packetId=0x3bc3 (routing)
520 * Roundtrip_StopInstanceWithStr: My roundtrip event: packetId=0x3bc3 (routing)
521 * @p
522 * Event parameter provides instance data to differentiate
523 * between multiple instances that can run in parallel
524 * @param(fmt) a constant string that provides format specifiers for up to 4 additional parameters
525 * @param(instanceId) a unique instance ID that can be used to match Roundtrip start and stop events
526 * @param(str) a constant string reference
527 */
528 config xdc.runtime.Log.Event startInstanceWithStr = {
529 mask: Diags.ANALYSIS,
530 msg: "Roundtrip_StartInstanceWithStr: %$S"
531 };
532
533 /*!
534 * ======== metaEventStartInstanceWithStr ========
535 * Metadata description of the startInstance event
536 *
537 * @_nodoc
538 */
539 metaonly config DvtTypes.MetaEventDescriptor metaEventStartInstanceWithStr = {
540 versionId: "2.0",
541 analysisType: DvtTypes.DvtAnalysisType_START,
542 displayText: "Roundtrip_StartInstanceWithStr",
543 tooltipText: "Marks the start of analysis for a module instance",
544 numParameters: 3,
545 paramInfo: [
546 { name: 'fmt',
547 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
548 dataTypeName: 'String',
549 units: 'none',
550 isHidden: false
551 },
552 { name: 'InstanceID',
553 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
554 dataTypeName: 'Int',
555 units: 'none',
556 isHidden: false
557 },
558 { name: 'FunctionAdrs',
559 dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
560 dataTypeName: 'Int',
561 units: 'none',
562 isHidden: false
563 }
564 ]
565 };
566
567
568 /*!
569 * ======== stopInstanceWithStr ========
570 * Roundtrip event used to log the end of an operation instance
571 *
572 * Event parameter provides instance data to differentiate
573 * between multiple instances that can run in parallel
574 * @a(Example)
575 * The following C code shows how to log a roundtrip
576 * 'stopInstanceWithStr' event along with a unique instance identifier
577 * and a string reference used only by the pair of start / stop events.
578 *
579 * @p(code)
580 * #include <xdc/runtime/Log.h>
581 * #include <ti/uia/events/UIARoundtrip.h>
582 * ...
583 * Void packetHdlr(Int packetId){
584 *
585 * Log_write3(UIARoundtrip_startInstanceWithStr, "My roundtrip event: packetId=0x%x",packetId,(IArg)"(routing)");
586 * ...
587 * Log_write3(UIARoundtrip_stopInstanceWithStr, "My roundtrip event: packetId=0x%x",packetId,(IArg)"(routing)");
588 * }
589 * @p
590 * The following text will be displayed for the event:
591 * @p(code)
592 * Roundtrip_StartInstanceWithStr: My roundtrip event: packetId=0x3bc3 (routing)
593 * Roundtrip_StopInstanceWithStr: My roundtrip event: packetId=0x3bc3 (routing)
594 * @p
595 * Event parameter provides instance data to differentiate
596 * between multiple instances that can run in parallel
597 * @param(fmt) a constant string that provides format specifiers for up to 4 additional parameters
598 * @param(instanceId) a unique instance ID that can be used to match Roundtrip start and stop events
599 * @param(str) a constant string reference
600 */
601 config xdc.runtime.Log.Event stopInstanceWithStr = {
602 mask: Diags.ANALYSIS,
603 msg: "Roundtrip_StopInstanceWithStr: %$S"
604 };
605
606 /*!
607 * ======== metaEventStopInstance ========
608 * Metadata description of the stopInstance event
609 *
610 * @_nodoc
611 */
612 metaonly config DvtTypes.MetaEventDescriptor metaEventStopInstanceWithStr = {
613 versionId: "2.0",
614 analysisType: DvtTypes.DvtAnalysisType_STOP,
615 displayText: "Roundtrip_StopInstanceWithStr",
616 tooltipText: "Marks the end of analysis for a module instance",
617 numParameters: 3,
618 paramInfo: [
619 { name: 'fmt',
620 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
621 dataTypeName: 'String',
622 units: 'none',
623 isHidden: false
624 },
625 { name: 'InstanceID',
626 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
627 dataTypeName: 'Int',
628 units: 'none',
629 isHidden: false
630 },
631 { name: 'String',
632 dataDesc: DvtTypes.DvtDataDesc_STRINGADRS,
633 dataTypeName: 'String',
634 units: 'none',
635 isHidden: false
636 }
637 ]
638 };
639
640 }