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