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 * #include <string.h> // for strlen
254 * ...
255 * Void myFunc(String name){
256 * ...
257 * //Upload the memory contents of the dynamically allocated string 'name'
258 * LogSnapshot_stringOnHeap(0,"name",name, strlen(name));
259 * //Now that the string memory contents have been uploaded,
260 * //subsequent events that reference the string will be properly
261 * //rendered.
262 * Log_info1("User-defined name=%s.",name);
263 * }
264 * @p
265 * The following text will be displayed for the event, if LogSnapshot was called
266 * from file demo.c at line 1234 and the value of "name" was "aUserDefinedName".
267 * @p(code)
268 * String Snapshot at [../demo.c:1234] [snapshotID=0,adrs=0x80001234,40,40] name.
269 * "demo.c", line 1235: User-defined name=aUserDefinedName.
270 * @p
271 *
272 * @param(__FILE__) The file that the LogSnapshot call site was in (used by %$F)
273 * @param(__LINE__) The line of code of the LogSnapshot call site (used by %$F)
274 * @param(snapshotID) ID used to identify snapshot events taken at the same
275 * time. Set to 0 for first in series, set rest to return
276 * value of LogSnapshot API.
277 * @param(adrs) the start address of the string in memory
278 * @param(numMAUsDataInEvent) the number of MAUs of data payload for this event
279 * @param(numMAUsDataInRecord) the total number of MAUs of data payload for the
280 * multi-event data record
281 * @param(fmt) a constant string that provides a user-readable description
282 * of what information the event is capturing
283 */
284 config xdc.runtime.Log.Event stringOnHeap = {
285 mask: Diags.ANALYSIS,
286 msg: "String Snapshot at %$F [snapshotID=%d,adrs=0x%x,numMAUsDataInEvent=%hd,numMAUsDataInRecord=%hd] %$S"
287 };
288
289 /*!
290 * ======== metaEventStringOnHeap ========
291 * Metadata description of the stringOnHeap event
292 *
293 * @_nodoc
294 */
295 metaonly config DvtTypes.MetaEventDescriptor metaEventStringOnHeap = {
296 versionId: "2.0",
297 analysisType: DvtTypes.DvtAnalysisType_STRINGSNAPSHOT,
298 displayText: "String Snapshot",
299 tooltipText: "String Snapshot",
300 numParameters: 8,
301 paramInfo: [
302 { name: 'filename',
303 dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
304 dataTypeName: 'String',
305 units: 'none',
306 isHidden: false
307 },
308 { name: 'linenum',
309 dataDesc: DvtTypes.DvtDataDesc_LINENUM,
310 dataTypeName: 'Int',
311 units: 'none',
312 isHidden: false
313 },
314 { name: 'snapshotID',
315 dataDesc: DvtTypes.DvtDataDesc_SNAPSHOTID,
316 dataTypeName: 'UInt32',
317 units: 'none',
318 isHidden: false
319 },
320 { name: 'startAdrs',
321 dataDesc: DvtTypes.DvtDataDesc_DATAADRS,
322 dataTypeName: 'Ptr',
323 units: 'none',
324 isHidden: false
325 },
326 { name: 'numMAUsDataInEvent',
327 dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
328 dataTypeName: 'Int16',
329 units: 'none',
330 isHidden: false,
331 lsb: 16
332 },
333 { name: 'numMAUsDataInRecord',
334 dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
335 dataTypeName: 'Int16',
336 units: 'none',
337 isHidden: false,
338 lsb: 0
339 },
340 { name: 'fmt',
341 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
342 dataTypeName: 'String',
343 units: 'none',
344 isHidden: false
345 },
346 { name: 'data',
347 dataDesc: DvtTypes.DvtDataDesc_DATAARRAY,
348 dataTypeName: 'Int32',
349 units: 'none',
350 isHidden: false
351 }
352 ]
353 };
354 /*!
355 * ======== nameOfReference ========
356 * Used to log the contents of a dynamic string on the heap so that host-side
357 * tooling can display this string as the name of handle / reference ID
358 *
359 * This event is used internally by the
360 * {@link ti.uia.runtime.LogSnapshot#nameOfReference LogSnapshot.nameOfReference}
361 * API.
362 *
363 * @a(Example)
364 * The following C code shows how to log a task name for use by task
365 * execution graphs etc.
366 *
367 * @p(code)
368 * #include <ti/uia/runtime/LogSnapshot.h>
369 * #include <ti/sysbios/BIOS.h>
370 * #include <ti/sysbios/knl/Task.h>
371 * ...
372 * // Task create hook function that logs the task name.
373 * // Notes: Task name is not trequired when creating a BIOS task. Please \
374 * // make sure a name is provided in order for the host side analysis tool
375 * // to work properly.
376 * Void tskCreateHook(Task_Handle hTask, Error_Block *eb) {
377 * String name;
378 * name = Task_Handle_name(hTask);
379 * LogSnapshot_writeNameOfReference(hTask,"Task_create name=%s",
380 * name,strlen(name)+1);
381 * }
382 * @p
383 * This event prints the Log call site (%$F) and a format string (%$S)
384 * which describes what information the event is logging.
385 * The following text will be displayed for the event:
386 * @p(code)
387 * nameOfReference at [demo.c:line 1234] [refID=0x80002000,adrs=0x80001234,40,40] Task_create: name=10msThread.
388 * @param(__FILE__) The file that the LogSnapshot call site was in (used by %$F)
389 * @param(__LINE__) The line of code of the LogSnapshot call site (used by %$F)
390 * @param(refID) reference ID (e.g. task handle) that the name is
391 * associated with
392 * @param(adrs) the start address of the string in memory
393 * @param(numMAUsDataInEvent) the number of MAUs of data payload for this event
394 * @param(numMAUsDataInRecord) the total number of MAUs of data payload for the
395 * multi-event data record
396 * @param(fmt) a constant string that provides a user-readable description
397 * of what information the event is capturing
398 */
399 config xdc.runtime.Log.Event nameOfReference = {
400 mask: Diags.ANALYSIS,
401 msg: "nameOfReference at %$F [refID=0x%x,adrs=0x%x,numMAUsDataInEvent=%hd numMAUsDataInRecord=%hd] %$S"
402 };
403
404 /*!
405 * ======== metaEventNameOfReference ========
406 * Metadata description of the NameOfReference event
407 *
408 * @_nodoc
409 */
410 metaonly config DvtTypes.MetaEventDescriptor metaEventNameOfReference = {
411 versionId: "2.0",
412 analysisType: DvtTypes.DvtAnalysisType_NAMESNAPSHOT,
413 displayText: "Name Of Reference ID",
414 tooltipText: "Name Of Reference ID",
415 numParameters: 8,
416 paramInfo: [
417 { name: 'filename',
418 dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
419 dataTypeName: 'String',
420 units: 'none',
421 isHidden: false
422 },
423 { name: 'linenum',
424 dataDesc: DvtTypes.DvtDataDesc_LINENUM,
425 dataTypeName: 'Int',
426 units: 'none',
427 isHidden: false
428 },
429 { name: 'referenceID',
430 dataDesc: DvtTypes.DvtDataDesc_REFERENCEID,
431 dataTypeName: 'UInt32',
432 units: 'none',
433 isHidden: false
434 },
435 { name: 'startAdrs',
436 dataDesc: DvtTypes.DvtDataDesc_DATAADRS,
437 dataTypeName: 'Ptr',
438 units: 'none',
439 isHidden: false
440 },
441 { name: 'numMAUsDataInEvent',
442 dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
443 dataTypeName: 'Int16',
444 units: 'none',
445 isHidden: false,
446 lsb: 16
447 },
448 { name: 'numMAUsDataInRecord',
449 dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
450 dataTypeName: 'Int16',
451 units: 'none',
452 isHidden: false,
453 lsb: 0
454 },
455 { name: 'fmt',
456 dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
457 dataTypeName: 'String',
458 units: 'none',
459 isHidden: false
460 },
461 { name: 'data',
462 dataDesc: DvtTypes.DvtDataDesc_DATAARRAY,
463 dataTypeName: 'Int32',
464 units: 'none',
465 isHidden: false
466 }
467 ]
468 };
469 }