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 * Benchmark event used to log the start of an operation instance
343 *
344 * Event parameter provides instance data to differentiate
345 * between multiple instances that can run in parallel
346 *
347 * @a(Example)
348 * The following C code shows how to log a benchmark
349 * 'startInstanceWithAdrs' event along with a task handle as the
350 * instance identifier, the function address and a format string
351 * describing the event.
352 *
353 * @p(code)
354 * #include <ti/sysbios/knl/Task.h>
355 * #include <xdc/runtime/Log.h>
356 * #include <ti/uia/events/UIABenchmark.h>
357 * ...
358 * Void myFunction(){
359 * Task_Handle hTsk = Task_selfMacro( );
360 *
361 * Log_write3(UIABenchmark_startInstanceWithAdrs, (IArg)"My benchmark event: task=0x%x, fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
362 * ...
363 * Log_write3(UIABenchmark_stopInstanceWithAdrs, (IArg)"My benchmark event: task=0x%x", fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
364 * }
365 * @p
366 * The following text will be displayed for the event:
367 * @p(code)
368 * StartInstanceWithAdrs: My benchmark event: task=0x893230, fnAdrs=0x820060
369 * StopInstanceWithAdrs: My benchmark event: task=0x893230, fnAdrs=0x820060
370 * @p
371 * @param(fmt) a constant string that provides format specifiers for up to 5 additional parameters
372 * @param(instanceId) a unique instance ID that can be used to match benchmark start and stop events
373 * @param(functionAdrs) the address of a function that can differentiate this pair of start and stop events from others
374 */
375 config xdc.runtime.Log.Event startInstanceWithAdrs = {
376 mask: Diags.ANALYSIS,
377 msg: "StartInstanceWithAdrs: %$S"
378 };
379
380 /*!
381 * ======== metaEventStartInstanceWithAdrs ========
382 * Metadata description of the startInstanceWithAdrs event
383 *
384 * @_nodoc
385 */
386 metaonly config DvtTypes.MetaEventDescriptor metaEventStartInstanceWithAdrs = {
387 versionId: "2.0",
388 analysisType: DvtTypes.DvtAnalysisType_START,
389 displayText: "StartInstanceWithAdrs",
390 tooltipText: "Marks the start of analysis for a module instance",
391 numParameters: 3,
392 paramInfo: [
393 { name: 'fmt',
394 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
395 dataTypeName: 'String',
396 units: 'none',
397 isHidden: false
398 },
399 { name: 'InstanceID',
400 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
401 dataTypeName: 'Int',
402 units: 'none',
403 isHidden: false
404 },
405 { name: 'FunctionAdrs',
406 dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
407 dataTypeName: 'Int',
408 units: 'none',
409 isHidden: false
410 }
411 ]
412 };
413
414
415
416
417
418 /*!
419 * ======== stopInstanceWithAdrs ========
420 * Benchmark event used to log the end of an operation instance
421 *
422 * @a(Example)
423 * The following C code shows how to log a benchmark
424 * 'stopInstanceWithAdrs' event along with a task handle as the
425 * instance identifier, the function address and a format string
426 * describing the event.
427 *
428 * @p(code)
429 * #include <ti/sysbios/knl/Task.h>
430 * #include <xdc/runtime/Log.h>
431 * #include <ti/uia/events/UIABenchmark.h>
432 * ...
433 * Void myFunction(){
434 * Task_Handle hTsk = Task_selfMacro( );
435 *
436 * Log_write3(UIABenchmark_startInstanceWithAdrs, (IArg)"My benchmark event: task=0x%x, fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
437 * ...
438 * Log_write3(UIABenchmark_stopInstanceWithAdrs, (IArg)"My benchmark event: task=0x%x", fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
439 * }
440 * @p
441 * The following text will be displayed for the event:
442 * @p(code)
443 * StartInstanceWithAdrs: My benchmark event: task=0x893230, fnAdrs=0x820060
444 * StopInstanceWithAdrs: My benchmark event: task=0x893230, fnAdrs=0x820060
445 * @p
446 * @param(fmt) a constant string that provides format specifiers for up to 5 additional parameters
447 * @param(instanceId) a unique instance ID that can be used to match benchmark start and stop events
448 * @param(functionAdrs) the address of a function that can differentiate this pair of start and stop events from others
449 */
450 config xdc.runtime.Log.Event stopInstanceWithAdrs = {
451 mask: Diags.ANALYSIS,
452 msg: "StopInstanceWithAdrs: %$S"
453 };
454
455 /*!
456 * ======== metaEventStopInstanceWithAdrs ========
457 * Metadata description of the stopInstanceWithAdrs event
458 *
459 * @_nodoc
460 */
461 metaonly config DvtTypes.MetaEventDescriptor metaEventStopInstanceWithAdrs = {
462 versionId: "2.0",
463 analysisType: DvtTypes.DvtAnalysisType_STOP,
464 displayText: "StopInstanceWithAdrs",
465 tooltipText: "Marks the end of analysis for a module instance",
466 numParameters: 3,
467 paramInfo: [
468 { name: 'fmt',
469 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
470 dataTypeName: 'String',
471 units: 'none',
472 isHidden: false
473 },
474 { name: 'Handle',
475 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
476 dataTypeName: 'Int',
477 units: 'none',
478 isHidden: false
479 },
480 { name: 'FunctionAdrs',
481 dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
482 dataTypeName: 'Int',
483 units: 'none',
484 isHidden: false
485 }
486 ]
487 };
488
489
490 /*!
491 * ======== startInstanceWithStr ========
492 * Benchmark event used to log the start of an operation instance
493 *
494 * Event parameter provides instance data to differentiate
495 * between multiple instances that can run in parallel
496 * @a(Example)
497 * The following C code shows how to log a benchmark
498 * 'startInstanceWithStr' event along with a unique instance identifier
499 * and a string reference used only by the pair of start / stop events.
500 *
501 * @p(code)
502 * #include <xdc/runtime/Log.h>
503 * #include <ti/uia/events/UIABenchmark.h>
504 * ...
505 * Void packetHdlr(Int packetId){
506 *
507 * Log_write3(UIABenchmark_startInstanceWithStr, (IArg)"My benchmark event: packetId=0x%x",packetId,(IArg)"(routing)");
508 * ...
509 * Log_write3(UIABenchmark_stopInstanceWithStr, (IArg)"My benchmark event: packetId=0x%x",packetId,(IArg)"(routing)");
510 * }
511 * @p
512 * The following text will be displayed for the event:
513 * @p(code)
514 * StartInstanceWithStr: My benchmark event: packetId=0x3bc3 (routing)
515 * StopInstanceWithStr: My benchmark event: packetId=0x3bc3 (routing)
516 * @p
517 * Event parameter provides instance data to differentiate
518 * between multiple instances that can run in parallel
519 * @param(fmt) a constant string that provides format specifiers for up to 5 additional parameters
520 * @param(instanceId) a unique instance ID that can be used to match benchmark start and stop events
521 * @param(str) a constant string reference
522 */
523 config xdc.runtime.Log.Event startInstanceWithStr = {
524 mask: Diags.ANALYSIS,
525 msg: "StartInstanceWithStr: %$S"
526 };
527
528 /*!
529 * ======== metaEventStartInstanceWithStr ========
530 * Metadata description of the startInstance event
531 *
532 * @_nodoc
533 */
534 metaonly config DvtTypes.MetaEventDescriptor metaEventStartInstanceWithStr = {
535 versionId: "2.0",
536 analysisType: DvtTypes.DvtAnalysisType_START,
537 displayText: "StartInstanceWithStr",
538 tooltipText: "Marks the start of analysis for a module instance",
539 numParameters: 3,
540 paramInfo: [
541 { name: 'fmt',
542 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
543 dataTypeName: 'String',
544 units: 'none',
545 isHidden: false
546 },
547 { name: 'InstanceID',
548 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
549 dataTypeName: 'Int',
550 units: 'none',
551 isHidden: false
552 },
553 { name: 'FunctionAdrs',
554 dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
555 dataTypeName: 'Int',
556 units: 'none',
557 isHidden: false
558 }
559 ]
560 };
561
562
563
564
565
566 /*!
567 * ======== stopInstanceWithStr ========
568 * Benchmark event used to log the end of an operation instance
569 *
570 * Event parameter provides instance data to differentiate
571 * between multiple instances that can run in parallel
572 * @a(Example)
573 * The following C code shows how to log a benchmark
574 * 'stopInstanceWithStr' event along with a unique instance identifier
575 * and a string reference used only by the pair of start / stop events.
576 *
577 * @p(code)
578 * #include <xdc/runtime/Log.h>
579 * #include <ti/uia/events/UIABenchmark.h>
580 * ...
581 * Void packetHdlr(Int packetId){
582 *
583 * Log_write3(UIABenchmark_startInstanceWithStr, (IArg)"My benchmark event: packetId=0x%x",packetId,(IArg)"(routing)");
584 * ...
585 * Log_write3(UIABenchmark_stopInstanceWithStr, (IArg)"My benchmark event: packetId=0x%x",packetId,(IArg)"(routing)");
586 * }
587 * @p
588 * The following text will be displayed for the event:
589 * @p(code)
590 * StartInstanceWithStr: My benchmark event: packetId=0x3bc3 (routing)
591 * StopInstanceWithStr: My benchmark event: packetId=0x3bc3 (routing)
592 * @p
593 * Event parameter provides instance data to differentiate
594 * between multiple instances that can run in parallel
595 * @param(fmt) a constant string that provides format specifiers for up to 5 additional parameters
596 * @param(instanceId) a unique instance ID that can be used to match benchmark start and stop events
597 * @param(str) a constant string reference
598 */
599 config xdc.runtime.Log.Event stopInstanceWithStr = {
600 mask: Diags.ANALYSIS,
601 msg: "StopInstanceWithStr: %$S"
602 };
603
604 /*!
605 * ======== metaEventStopInstance ========
606 * Metadata description of the stopInstance event
607 *
608 * @_nodoc
609 */
610 metaonly config DvtTypes.MetaEventDescriptor metaEventStopInstanceWithStr = {
611 versionId: "2.0",
612 analysisType: DvtTypes.DvtAnalysisType_STOP,
613 displayText: "StopInstanceWithStr",
614 tooltipText: "Marks the end of analysis for a module instance",
615 numParameters: 3,
616 paramInfo: [
617 { name: 'fmt',
618 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
619 dataTypeName: 'String',
620 units: 'none',
621 isHidden: false
622 },
623 { name: 'InstanceID',
624 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
625 dataTypeName: 'Int',
626 units: 'none',
627 isHidden: false
628 },
629 { name: 'String',
630 dataDesc: DvtTypes.DvtDataDesc_STRINGADRS,
631 dataTypeName: 'String',
632 units: 'none',
633 isHidden: false
634 }
635 ]
636 };
637
638 }