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 import xdc.runtime.Diags;
37
38 /*!
39 * UIA Statistics Events
40 *
41 * The UIAStatistic module defines events that allow
42 * tooling to analyze the performance of the software
43 * (CPU Utilization, throughput, etc.)
44 *
45 * The generation of UIAStatistic events is controlled by a module's diagnostics
46 * mask, which is described in details in `{@link xdc.runtime.Diags}`.
47 * `UIAStatistic` events are generated only when the Diags.ANALYSIS bit is set
48 * in the module's diagnostics mask.
49 *
50 * The following configuration script demonstrates how the application might
51 * control the logging of ANALYSIS events embedded in the `Mod` module at configuration
52 * time. In this case, the configuration script arranges for the `Log`
53 * statements within modules to always generate ANALYSIS events.
54 * Without these configuration statements, no ANALYSIS events would be generated
55 * by any modules.
56 *
57 * @a(Examples)
58 * Example 1: This is part of the XDC configuration file for the application:
59 *
60 * @p(code)
61 * var UIAStatistic = xdc.useModule('ti.uia.events.UIAStatistic');
62 * var Diags = xdc.useModule('xdc.runtime.Diags');
63 * var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
64 * var Defaults = xdc.useModule('xdc.runtime.Defaults');
65 * var logger = LoggerSys.create();
66 *
67 * Defaults.common$.diags_ANALYSIS = Diags.ALWAYS_ON;
68 * Defaults.common$.logger = logger;
69 * @p
70 *
71 * @p(html)
72 * <hr />
73 * @p
74 *
75 * Example 2: The following example configures a module to support logging
76 * of ANALYSIS events, but defers the actual activation and deactivation of the
77 * logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
78 * function for details on specifying the control string.
79 *
80 * This is a part of the XDC configuration file for the application:
81 *
82 * @p(code)
83 * var UIAStatistic = xdc.useModule('ti.uia.events.UIAStatistic');
84 * var Diags = xdc.useModule('xdc.runtime.Diags');
85 * var Mod = xdc.useModule('my.pkg.Mod');
86 *
87 * Mod.common$.diags_ANALYSIS = Diags.RUNTIME_OFF;
88 * @p
89 *
90 * This is a part of the C code for the application:
91 *
92 * @p(code)
93 * // turn on logging of ANALYSIS events in the module
94 * Diags_setMask("my.pkg.Mod+Z");
95 *
96 * // turn off logging of ANALYSIS events in the module
97 * Diags_setMask("my.pkg.Mod-Z");
98 * @p
99 */
100
101 module UIAStatistic inherits IUIAEvent {
102
103 /*! ====== cpuLoad ======
104 * Number of cycles used by an XDC module
105 *
106 * @a(Example)
107 * The following C code shows how to log a cpuLoad
108 * event that tracks the number of cycles used by an XDC module.
109 * The module ID is logged along with the event. For non-XDC
110 * code, or for code with multiple instances @see #cpuLoadByInstance.
111 * @p(code)
112 * #include <xdc/runtime/Log.h>
113 * #include <ti/uia/events/UIAStatistic.h>
114 * ...
115 * Void myFunction(){
116 * int numCycles = 0;
117 * // update numCycles with the number of cycles processed
118 * Log_write1(UIAStatistic_cpuLoad, numCycles);
119 * }
120 * @p
121 * The following text will be displayed for the event:
122 * @p(code)
123 * CPU Load: NumCycles=1234
124 * @p
125 *
126 * @param(numCycles) the CPU load in cycles
127 */
128 config xdc.runtime.Log.Event cpuLoad = {
129 mask: Diags.ANALYSIS,
130 msg: "CPU Load: NumCycles=%d"
131 };
132
133 /*! ====== cpuLoadByInstance ======
134 * Number of cycles used by a non XDC module or thread
135 *
136 * @a(Example)
137 * The following C code shows how to log a cpuLoad
138 * event that tracks the number of cycles used by
139 * code that is not in an XDC module or by a thread
140 * @p(code)
141 * #include <xdc/runtime/Log.h>
142 * #include <ti/uia/events/UIAStatistic.h>
143 * static volatile int gMyGlobalInstanceId = 0;
144 * ...
145 * Void myFunction(){
146 * IArg key;
147 * int localInstanceId;
148 * int numCycles = 0;
149 * // protect pre-increment operation from race conditions
150 * key = Gate_enterSystem();
151 * localInstanceId = ++gMyGlobalInstanceId;
152 * Gate_leaveSystem(key);
153 * // update numCycles with the number of cycles processed
154 * Log_write3(UIAStatistic_cpuLoadByInstance, "myFunction",localInstanceId,numCycles);
155 * }
156 * @p
157 * The following text will be displayed for the event:
158 * @p(code)
159 * CPU Load for myFunction (instanceId = 0x1234): NumCycles=1234
160 * @param(name) a constant string that provides the name of the entity that is processing the data
161 * @param(instanceId) the instance ID (e.g. thread handle) of the entity that is processing the data
162 * @param(numCycles) the CPU load in cycles
163 */
164 config xdc.runtime.Log.Event cpuLoadByInstance = {
165 mask: Diags.ANALYSIS,
166 msg: "CPU Load for %s (instanceId = 0x%x): NumCycles=%d"
167 };
168
169 /*! ====== bytesProcessed ======
170 * bytesProcessed statistic event
171 *
172 * Number of bytes that were processed.
173 * @param(name) a constant string that provides the name
174 * of the entity that is processing the data
175 * @param(numBytes) the number of bytes processed
176 */
177 config xdc.runtime.Log.Event bytesProcessed = {
178 mask: Diags.ANALYSIS,
179 msg: "Bytes Processed by %s: NumBytes=0x%x"
180 };
181
182 /*! ====== bytesProcessedByInstance ======
183 * bytesProcessedByInstance statistic event
184 *
185 * Number of bytes that were processed along with filename,
186 * line number and instance ID.
187 * @a(Example)
188 * The following C code shows how to log an
189 * event that tracks the number of bytes processed
190 * @p(code)
191 * #include <xdc/runtime/Log.h>
192 * #include <ti/uia/events/UIAStatistic.h>
193 * ...
194 * Void myFunction(){
195 * int instanceId = 0x1234; // change to e.g. a TaskId or some other unique ID
196 * int numBytes= 567; // change to number of bytes actually processed
197 *
198 * Log_write4(UIAStatistic_bytesProcessedByInstance, (IArg)__FILE__,(IArg)__LINE__,instanceId,numBytes);
199 * }
200 * @p
201 * The following text will be displayed for the event:
202 * @p(code)
203 * Bytes Processed at Line 123 in demo.c (InstanceId 0x1234): Num Bytes=567
204 * @p
205 * @param(__FILE__) constant string identifying the file the event was logged from
206 * @param(__LINE__) the line number the event was logged from
207 * @param(instanceId) the instance ID (e.g. thread handle) of the
208 * entity that is processing the data
209 * @param(numBytes) the number of bytes processed
210 */
211 config xdc.runtime.Log.Event bytesProcessedByInstance = {
212 mask: Diags.ANALYSIS,
213 msg: "Bytes Processed at %$F (InstanceId 0x%x): Num Bytes=%d"
214 };
215
216 /*!
217 * ======== metaEventBytesProcessedByInstance ========
218 * Metadata description of the bytesProcessedByInstance event
219 *
220 * @_nodoc
221 */
222 metaonly config DvtTypes.MetaEventDescriptor metaEventBytesProcessedByInstance = {
223 versionId: "2.0",
224 analysisType: DvtTypes.DvtAnalysisType_STATISTIC,
225 displayText: "Bytes Processed",
226 tooltipText: "Bytes Processed",
227 numParameters: 4,
228 paramInfo: [
229 { name: '__FILE__',
230 dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
231 dataTypeName: 'String',
232 units: 'none',
233 isHidden: false
234 },
235 { name: '__LINE__',
236 dataDesc: DvtTypes.DvtDataDesc_LINENUM,
237 dataTypeName: 'Int',
238 units: 'none',
239 isHidden: false
240 },
241 { name: 'Instance ID',
242 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
243 dataTypeName: 'Int',
244 units: 'none',
245 isHidden: false
246 },
247 { name: 'Words Processed',
248 dataDesc: DvtTypes.DvtDataDesc_VALUE,
249 dataTypeName: 'Int',
250 units: 'bytes',
251 isHidden: false
252 }]
253
254 };
255
256
257 /*! ====== wordsProcessed ======
258 * wordsProcessed statistic event
259 *
260 * number of words that were processed.
261 * @param(name) a constant string that provides the name
262 * of the entity that is processing the data
263 * @param(numWords) the number of words processed
264 */
265 config xdc.runtime.Log.Event wordsProcessed = {
266 mask: Diags.ANALYSIS,
267 msg: "Words Processed by %s: NumWords=0x%x"
268 };
269
270
271 /*! ====== wordsProcessedByInstance ======
272 * wordsProcessedByInstance statistic event
273 *
274 * Number of words that were processed along with filename,
275 * line number and instance ID.
276 * @a(Example)
277 * The following C code shows how to log an
278 * event that tracks the number of words processed
279 * @p(code)
280 * #include <xdc/runtime/Log.h>
281 * #include <ti/uia/events/UIAStatistic.h>
282 * ...
283 * Void myFunction(){
284 * int instanceId = 0x1234; // change to e.g. a TaskId or some other unique ID
285 * int numWords= 567; // change to number of words actually processed
286 *
287 * Log_write4(UIAStatistic_wordsProcessedByInstance, (IArg)__FILE__,(IArg)__LINE__,instanceId,numWords);
288 * }
289 * @p
290 * The following text will be displayed for the event:
291 * @p(code)
292 * Words Processed at Line 123 in demo.c (InstanceId 0x1234): Num Words=567
293 * @p
294 * @param(__FILE__) constant string identifying the file the event was logged from
295 * @param(__LINE__) the line number the event was logged from
296 * @param(instanceId) the instance ID (e.g. thread handle) of the
297 * entity that is processing the data
298 * @param(numWords) the number of words processed
299 */
300 config xdc.runtime.Log.Event wordsProcessedByInstance = {
301 mask: Diags.ANALYSIS,
302 msg: "Words Processed at %$F (InstanceId 0x%x): Num Words=%d"
303 };
304
305 /*!
306 * ======== metaEventWordsProcessedByInstance ========
307 * Metadata description of the wordsProcessedByInstance event
308 *
309 * @_nodoc
310 */
311 metaonly config DvtTypes.MetaEventDescriptor metaEventWordsProcessedByInstance = {
312 versionId: "2.0",
313 analysisType: DvtTypes.DvtAnalysisType_STATISTIC,
314 displayText: "Words Processed",
315 tooltipText: "Words Processed",
316 numParameters: 4,
317 paramInfo: [
318 { name: '__FILE__',
319 dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
320 dataTypeName: 'String',
321 units: 'none',
322 isHidden: false
323 },
324 { name: '__LINE__',
325 dataDesc: DvtTypes.DvtDataDesc_LINENUM,
326 dataTypeName: 'Int',
327 units: 'none',
328 isHidden: false
329 },
330 { name: 'Instance ID',
331 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
332 dataTypeName: 'Int',
333 units: 'none',
334 isHidden: false
335 },
336 { name: 'Words Processed',
337 dataDesc: DvtTypes.DvtDataDesc_VALUE,
338 dataTypeName: 'Int',
339 units: 'words',
340 isHidden: false
341 }]
342
343 };
344
345 /*! ====== freeBytes ======
346 * Number of free bytes in heap.
347 *
348 * @a(Example)
349 * The following C code shows how to log a freeBytes
350 * event that tracks the number of bytes free in the heap
351 * @p(code)
352 * #include <xdc/runtime/Log.h>
353 * #include <ti/uia/events/UIAStatistic.h>
354 * ...
355 * Void myFunction(){
356 * int heapId = 0x1234; // change to heap ID
357 * int numBytesFree = 567; // change to number of bytes free on the heap
358 *
359 * Log_write4(UIAStatistic_freeBytes, (IArg)__FILE__,(IArg)__LINE__,heapId,numFreeBytes);
360 * }
361 * @p
362 * The following text will be displayed for the event:
363 * @p(code)
364 * Heap at Line 123 in demo.c (HeapId 0x1234): Free Bytes=567
365 * @p
366 * @param(__FILE__) constant string identifying the file the event was logged from
367 * @param(__LINE__) the line number the event was logged from
368 * @param(heapId) heap identifier (e.g IHeap_Handle)
369 * @param(freeBytes) the number of bytes free on the heap
370 */
371 config xdc.runtime.Log.Event freeBytes = {
372 mask: Diags.ANALYSIS,
373 msg: "Heap at %$F (HeapId 0x%x): Free Bytes=%d"
374 };
375
376 /*!
377 * ======== metaEventFreeBytes ========
378 * Metadata description of the FreeBytes event
379 *
380 * @_nodoc
381 */
382 metaonly config DvtTypes.MetaEventDescriptor metaEventFreeBytes = {
383 versionId: "2.0",
384 analysisType: DvtTypes.DvtAnalysisType_STATISTIC,
385 displayText: "Free Bytes",
386 tooltipText: "Free Bytes in Heap",
387 numParameters: 4,
388 paramInfo: [
389 { name: '__FILE__',
390 dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
391 dataTypeName: 'String',
392 units: 'none',
393 isHidden: false
394 },
395 { name: '__LINE__',
396 dataDesc: DvtTypes.DvtDataDesc_LINENUM,
397 dataTypeName: 'Int',
398 units: 'none',
399 isHidden: false
400 },
401 { name: 'Heap ID',
402 dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
403 dataTypeName: 'Int',
404 units: 'none',
405 isHidden: false
406 },
407 { name: 'Free Bytes',
408 dataDesc: DvtTypes.DvtDataDesc_VALUE,
409 dataTypeName: 'Int',
410 units: 'bytes',
411 isHidden: false
412 }]
413
414 };
415 }