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 Snapshot Events
43 *
44 * The UIASnapshot module defines events that allow
45 * collection of dynamic information from the heap
46 * such as memory ranges, strings, dynamically assigned names, etc.
47 * Snapshot events can be aggregated together using a common snapshot ID
48 * as an event parameter in order to build up a multi-event description of the
49 * target state. They are intended for use solely with the methods provided by
50 * the {@link ti.uia.runtime.LogSnapshot ti.uia.runtime.LogSnapshot} module.
51 *
52 * The generation of UIASnapshot events is controlled by a module's diagnostics
53 * mask, which is described in details in `{@link xdc.runtime.Diags}`.
54 * `UIASnapshot` events are generated only when the Diags.ANALYSIS bit is set
55 * in the module's diagnostics mask.
56 *
57 * The following special formatting specifiers are used in the definitions of the
58 * msg fields of the UIASnapshot events:
59 * %$S - a string parameter that can provide additional formatting specifiers
60 * Note that $S use in strings passed in as a paramter is not supported.
61 *@p
62 * %$F - a specifier for a string parameter containing the file name (__FILE__) and
63 * an integer parameter containing the line number (__LINE__).
64 *
65 * The following configuration script demonstrates how the application might
66 * control the logging of ANALYSIS events embedded in the `Mod` module at configuration
67 * time. In this case, the configuration script arranges for the `Log`
68 * statements within modules to always generate ANALYSIS events.
69 * Without these configuration statements, no ANALYSIS events would be generated
70 * by any modules.
71 *
72 * @a(Examples)
73 * Example 1: This is part of the XDC configuration file for the application:
74 * (Note that the UIASnapshot module is automatically included by the
75 * LogSnapshot.xs script, and so does not need to be referenced in the
76 * application's .cfg file)
77 * @p(code)
78 * var LogSnapshot = xdc.useModule('ti.uia.runtime.LogSnapshot');
79 * var LoggerCircBuf = xdc.useModule('ti.uia.runtime.LoggerCircBuf');
80 * var LoggerCircBufParams = new LoggerCircBuf.Params;
81 * // set the logger buffer size in bytes
82 * LoggerCircBufParams.transferBufSize = 32768;
83 * var logger = LoggerCircBuf.create(LoggerCircBufParams);
84 *
85 * // Configure all modules to always log Analysis events, including
86 * // UIASnapshot events
87 * var Diags = xdc.useModule('xdc.runtime.Diags');
88 * var Defaults = xdc.useModule('xdc.runtime.Defaults');
89 * Defaults.common$.diags_ANALYSIS = Diags.ALWAYS_ON;
90 * Defaults.common$.logger = logger;
91 *
92 * @p
93 *
94 * @p(html)
95 * <hr />
96 * @p
97 *
98 * Example 2: The following example configures a module to support logging
99 * of ANALYSIS events, but defers the actual activation and deactivation of the
100 * logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
101 * function for details on specifying the control string.
102 *
103 * This is part of the XDC configuration file for the application:
104 * @p(code)
105 * var LogSnapshot = xdc.useModule('ti.uia.runtime.LogSnapshot');
106 * var Diags = xdc.useModule('xdc.runtime.Diags');
107 * var Mod = xdc.useModule('my.pkg.Mod');
108 *
109 * Mod.common$.diags_ANALYSIS = Diags.RUNTIME_OFF;
110 * @p
111 *
112 * This is a part of the C code for the application:
113 *
114 * @p(code)
115 * // turn on logging of ANALYSIS events in the module
116 * Diags_setMask("my.pkg.Mod+Z");
117 *
118 * // turn off logging of ANALYSIS events in the module
119 * Diags_setMask("my.pkg.Mod-Z");
120 * @p
121 */
122 module UIASnapshot inherits IUIAEvent {
123
124 /*!
125 * ======== memoryRange ========
126 * Analysis event posted when a memoryRange snapshot is logged.
127 *
128 * This event is used internally by the
129 * {@link ti.uia.runtime.LogSnapshot#writeMemoryBlock LogSnapshot.writeMemoryBlock}
130 * API.
131 *
132 * @a(Examples)
133 * Example: The following C code shows how to log a snapshot event to
134 * capture a block of memory.
135 *
136 * @p(code)
137 * #include <ti/uia/runtime/LogSnapshot.h>
138 * ...
139 * UInt32* pIntArray = (UInt32 *)malloc(sizeof(UInt32) * 200);
140 * ...
141 * LogSnapshot_writeMemoryBlock(0,"pIntArray ptr=0x%x, numBytes=%d",(UInt32)pIntArray,200);
142 * ...
143 * @p
144 * This event prints the Log call site (%$F) and a format string (%$S)
145 * which describes what information the event is logging.
146 * The following text will be displayed for the event, if it was logged
147 * from file demo.c at line 1234 and all 200 bytes were logged in the
148 * same event.
149 * @p(code)
150 * Memory Snapshot at [demo.c:1234] [snapshotID=0,adrs=0x80002000,
151 * numMAUsDataInEvent=200,numMAUsDataInRecord=200] ptr=0x80002000, numBytes=200
152 * @p
153 * If the 200 bytes were spread across multiple events,
154 * the numMAUsDataInRecord would indicate how many bytes were in the
155 * memory block, and numMAUsDataInEvent would indicate how many bytes
156 * were stored in that particular event.
157 * @p
158 * @param(__FILE__) The file that the LogSnapshot call site was in (used by %$F)
159 * @param(__LINE__) The line of code of the LogSnapshot call site (used by %$F)
160 * @param(snapshotID) ID used to identify snapshot events taken at the same
161 * time. Set to 0 for first in series, set rest to return
162 * value of LogSnapshot API.
163 * @param(startAdrs) the start address of the range of memory
164 * @param(numMAUsDataInEvent) the number of MAUs of data payload for this event
165 * @param(numMAUsDataInRecord) the total number of MAUs of data payload for the
166 * multi-event data record
167 * @param(fmt) a constant string that provides a user-readable description
168 * of what information the event is capturing
169 */
170 config xdc.runtime.Log.Event memoryRange = {
171 mask: Diags.ANALYSIS,
172 msg: "Memory Snapshot at %$F% [snapshotID=%d,adrs=0x%x,numMAUsDataInEvent=%hd,numMAUsDataInRecord=%hd] %$S"
173 };
174
175 /*!
176 * ======== metaEventMemoryRange ========
177 * Metadata description of the memoryRange event
178 *
179 * @_nodoc
180 */
181 metaonly config DvtTypes.MetaEventDescriptor metaEventMemoryRange = {
182 versionId: "2.0",
183 analysisType: DvtTypes.DvtAnalysisType_MEMORYSNAPSHOT,
184 displayText: "Memory Snapshot",
185 tooltipText: "Memory Snapshot",
186 numParameters: 8,
187 paramInfo: [
188 { name: 'filename',
189 dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
190 dataTypeName: 'String',
191 units: 'none',
192 isHidden: false
193 },
194 { name: 'linenum',
195 dataDesc: DvtTypes.DvtDataDesc_LINENUM,
196 dataTypeName: 'Int',
197 units: 'none',
198 isHidden: false
199 },
200 { name: 'snapshotID',
201 dataDesc: DvtTypes.DvtDataDesc_SNAPSHOTID,
202 dataTypeName: 'UInt32',
203 units: 'none',
204 isHidden: false
205 },
206 { name: 'startAdrs',
207 dataDesc: DvtTypes.DvtDataDesc_DATAADRS,
208 dataTypeName: 'Ptr',
209 units: 'none',
210 isHidden: false
211 },
212 { name: 'numMAUsDataInEvent',
213 dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
214 dataTypeName: 'Int16',
215 units: 'none',
216 isHidden: false,
217 lsb: 16
218 },
219 { name: 'numMAUsDataInRecord',
220 dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
221 dataTypeName: 'Int16',
222 units: 'none',
223 isHidden: false,
224 lsb: 0
225 },
226 { name: 'fmt',
227 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
228 dataTypeName: 'String',
229 units: 'none',
230 isHidden: false
231 },
232 { name: 'data',
233 dataDesc: DvtTypes.DvtDataDesc_DATAARRAY,
234 dataTypeName: 'Int32',
235 units: 'none',
236 isHidden: false
237 }
238 ]
239 };
240 /*!
241 * ======== stringOnHeap ========
242 * Analysis event posted when a string snapshot is logged
243 *
244 * This event is used internally by the
245 * {@link ti.uia.runtime.LogSnapshot#writeString LogSnapshot.writeString}
246 * API.
247 * @a(Example)
248 * The following C code shows how to log a snapshot event to capture a
249 * block of memory.
250 *
251 * @p(code)
252 * #include <ti/uia/runtime/LogSnapshot.h>
253 * ...
254 * Void myFunc(String name){
255 * ...
256 * LogSnapshot_stringOnHeap(0,"User-defined name=%s.",name, strlen(name));
257 * }
258 * @p
259 * The following text will be displayed for the event, if it was logged
260 * from file demo.c at line 1234 and all bytes in the 40 character string
261 * was logged in the same event.
262 * @p(code)
263 * String Snapshot at [../demo.c:1234] [snapshotID=0,adrs=0x80001234,40,40] User-defined name=ValueOfParm.
264 * @p
265 * and a format string (%$S)
266 * which describes what information the event is logging. *
267 * @param(__FILE__) The file that the LogSnapshot call site was in (used by %$F)
268 * @param(__LINE__) The line of code of the LogSnapshot call site (used by %$F)
269 * @param(snapshotID) ID used to identify snapshot events taken at the same
270 * time. Set to 0 for first in series, set rest to return
271 * value of LogSnapshot API.
272 * @param(adrs) the start address of the string in memory
273 * @param(numMAUsDataInEvent) the number of MAUs of data payload for this event
274 * @param(numMAUsDataInRecord) the total number of MAUs of data payload for the
275 * multi-event data record
276 * @param(fmt) a constant string that provides a user-readable description
277 * of what information the event is capturing
278 */
279 config xdc.runtime.Log.Event stringOnHeap = {
280 mask: Diags.ANALYSIS,
281 msg: "String Snapshot at %$F [snapshotID=%d,adrs=0x%x,numMAUsDataInEvent=%hd,numMAUsDataInRecord=%hd] %$S"
282 };
283
284 /*!
285 * ======== metaEventStringOnHeap ========
286 * Metadata description of the stringOnHeap event
287 *
288 * @_nodoc
289 */
290 metaonly config DvtTypes.MetaEventDescriptor metaEventStringOnHeap = {
291 versionId: "2.0",
292 analysisType: DvtTypes.DvtAnalysisType_STRINGSNAPSHOT,
293 displayText: "String Snapshot",
294 tooltipText: "String Snapshot",
295 numParameters: 8,
296 paramInfo: [
297 { name: 'filename',
298 dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
299 dataTypeName: 'String',
300 units: 'none',
301 isHidden: false
302 },
303 { name: 'linenum',
304 dataDesc: DvtTypes.DvtDataDesc_LINENUM,
305 dataTypeName: 'Int',
306 units: 'none',
307 isHidden: false
308 },
309 { name: 'snapshotID',
310 dataDesc: DvtTypes.DvtDataDesc_SNAPSHOTID,
311 dataTypeName: 'UInt32',
312 units: 'none',
313 isHidden: false
314 },
315 { name: 'startAdrs',
316 dataDesc: DvtTypes.DvtDataDesc_DATAADRS,
317 dataTypeName: 'Ptr',
318 units: 'none',
319 isHidden: false
320 },
321 { name: 'numMAUsDataInEvent',
322 dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
323 dataTypeName: 'Int16',
324 units: 'none',
325 isHidden: false,
326 lsb: 16
327 },
328 { name: 'numMAUsDataInRecord',
329 dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
330 dataTypeName: 'Int16',
331 units: 'none',
332 isHidden: false,
333 lsb: 0
334 },
335 { name: 'fmt',
336 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
337 dataTypeName: 'String',
338 units: 'none',
339 isHidden: false
340 },
341 { name: 'data',
342 dataDesc: DvtTypes.DvtDataDesc_DATAARRAY,
343 dataTypeName: 'Int32',
344 units: 'none',
345 isHidden: false
346 }
347 ]
348 };
349 /*!
350 * ======== nameOfReference ========
351 * Used to log the contents of a dynamic string on the heap so that host-side
352 * tooling can display this string as the name of handle / reference ID
353 *
354 * This event is used internally by the
355 * {@link ti.uia.runtime.LogSnapshot#nameOfReference LogSnapshot.nameOfReference}
356 * API.
357 *
358 * @a(Example)
359 * The following C code shows how to log a task name for use by task
360 * execution graphs etc.
361 *
362 * @p(code)
363 * #include <ti/uia/runtime/LogSnapshot.h>
364 * #include <ti/sysbios/BIOS.h>
365 * #include <ti/sysbios/knl/Task.h>
366 * ...
367 * // Task create hook function that logs the task name.
368 * // Notes: Task name is not trequired when creating a BIOS task. Please \
369 * // make sure a name is provided in order for the host side analysis tool
370 * // to work properly.
371 * Void tskCreateHook(Task_Handle hTask, Error_Block *eb) {
372 * String name;
373 * name = Task_Handle_name(hTask);
374 * LogSnapshot_writeNameOfReference(hTask,"Task_create name=%s",
375 * name,strlen(name)+1);
376 * }
377 * @p
378 * This event prints the Log call site (%$F) and a format string (%$S)
379 * which describes what information the event is logging.
380 * The following text will be displayed for the event:
381 * @p(code)
382 * nameOfReference at [demo.c:line 1234] [refID=0x80002000,adrs=0x80001234,40,40] Task_create: name=10msThread.
383 * @param(__FILE__) The file that the LogSnapshot call site was in (used by %$F)
384 * @param(__LINE__) The line of code of the LogSnapshot call site (used by %$F)
385 * @param(refID) reference ID (e.g. task handle) that the name is
386 * associated with
387 * @param(adrs) the start address of the string in memory
388 * @param(numMAUsDataInEvent) the number of MAUs of data payload for this event
389 * @param(numMAUsDataInRecord) the total number of MAUs of data payload for the
390 * multi-event data record
391 * @param(fmt) a constant string that provides a user-readable description
392 * of what information the event is capturing
393 */
394 config xdc.runtime.Log.Event nameOfReference = {
395 mask: Diags.ANALYSIS,
396 msg: "nameOfReference at %$F [refID=0x%x,adrs=0x%x,numMAUsDataInEvent=%hd numMAUsDataInRecord=%hd] %$S"
397 };
398
399 /*!
400 * ======== metaEventNameOfReference ========
401 * Metadata description of the NameOfReference event
402 *
403 * @_nodoc
404 */
405 metaonly config DvtTypes.MetaEventDescriptor metaEventNameOfReference = {
406 versionId: "2.0",
407 analysisType: DvtTypes.DvtAnalysisType_NAMESNAPSHOT,
408 displayText: "Name Of Reference ID",
409 tooltipText: "Name Of Reference ID",
410 numParameters: 8,
411 paramInfo: [
412 { name: 'filename',
413 dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
414 dataTypeName: 'String',
415 units: 'none',
416 isHidden: false
417 },
418 { name: 'linenum',
419 dataDesc: DvtTypes.DvtDataDesc_LINENUM,
420 dataTypeName: 'Int',
421 units: 'none',
422 isHidden: false
423 },
424 { name: 'referenceID',
425 dataDesc: DvtTypes.DvtDataDesc_REFERENCEID,
426 dataTypeName: 'UInt32',
427 units: 'none',
428 isHidden: false
429 },
430 { name: 'startAdrs',
431 dataDesc: DvtTypes.DvtDataDesc_DATAADRS,
432 dataTypeName: 'Ptr',
433 units: 'none',
434 isHidden: false
435 },
436 { name: 'numMAUsDataInEvent',
437 dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
438 dataTypeName: 'Int16',
439 units: 'none',
440 isHidden: false,
441 lsb: 16
442 },
443 { name: 'numMAUsDataInRecord',
444 dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
445 dataTypeName: 'Int16',
446 units: 'none',
447 isHidden: false,
448 lsb: 0
449 },
450 { name: 'fmt',
451 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
452 dataTypeName: 'String',
453 units: 'none',
454 isHidden: false
455 },
456 { name: 'data',
457 dataDesc: DvtTypes.DvtDataDesc_DATAARRAY,
458 dataTypeName: 'Int32',
459 units: 'none',
460 isHidden: false
461 }
462 ]
463 };
464 }
465
466 467 468 469 470