module ti.uia.events.UIASnapshot

index URL

UIA Snapshot Events

*       C synopsis

*  Individual elements

*       DETAILS

*       EXAMPLES

The UIASnapshot module defines events that allow collection of dynamic information from the heap such as memory ranges, strings, dynamically assigned names, etc. Snapshot events can be aggregated together using a common snapshot ID as an event parameter in order to build up a multi-event description of the target state. They are intended for use solely with the methods provided by the ti.uia.runtime.LogSnapshot module. [ more ... ]

C synopsis

target-domain

sourced in ti/uia/events/UIASnapshot.h

#include <ti/uia/events/UIASnapshot.h>

Constants

extern const Log_Event 

extern const Log_Event 

extern const Log_Event 

 

DETAILS

The UIASnapshot module defines events that allow collection of dynamic information from the heap such as memory ranges, strings, dynamically assigned names, etc. Snapshot events can be aggregated together using a common snapshot ID as an event parameter in order to build up a multi-event description of the target state. They are intended for use solely with the methods provided by the ti.uia.runtime.LogSnapshot module.

The generation of UIASnapshot events is controlled by a module's diagnostics mask, which is described in details in xdc.runtime.Diags. UIASnapshot events are generated only when the Diags.ANALYSIS bit is set in the module's diagnostics mask.

The following special formatting specifiers are used in the definitions of the msg fields of the UIASnapshot events: %$S - a string parameter that can provide additional formatting specifiers Note that $S use in strings passed in as a paramter is not supported.

%$F - a specifier for a string parameter containing the file name (__FILE__) and an integer parameter containing the line number (__LINE__).

 

EXAMPLES

Example 1: The following example shows how to turn on and off logging of ANALYSIS events from the application source code. See the Diags_setMask() function for details on specifying the control string.

  // turn on logging of ANALYSIS events in the module
  Diags_setMask("my.pkg.Mod+Z");
 
  // turn off logging of ANALYSIS events in the module
  Diags_setMask("my.pkg.Mod-Z");

 

config UIASnapshot_memoryRange  // module-wide

index URL

Analysis event posted when a memoryRange snapshot is logged

C synopsis

target-domain

extern const Log_Event UIASnapshot_memoryRange;

 

VALUES

__FILE__ — The file that the LogSnapshot call site was in (used by %$F)

__LINE__ — The line of code of the LogSnapshot call site (used by %$F)

snapshotID — ID used to identify snapshot events taken at the same time. Set to 0 for first in series, set rest to return value of LogSnapshot API.

startAdrs — the start address of the range of memory

numMAUsDataInEvent — the number of MAUs of data payload for this event

numMAUsDataInRecord — the total number of MAUs of data payload for the multi-event data record

fmt — a constant string that provides a user-readable description of what information the event is capturing

DETAILS

This event is used internally by the LogSnapshot.writeMemoryBlock API.

EXAMPLES

Example: The following C code shows how to log a snapshot event to capture a block of memory.

  #include <ti/uia/runtime/LogSnapshot.h> 
  ...
  UInt32* pIntArray = (UInt32 *)malloc(sizeof(UInt32) * 200);   
  ...  
  LogSnapshot_writeMemoryBlock(0,"pIntArray ptr=0x%x, numBytes=%d",(UInt32)pIntArray,200);
  ...

This event prints the Log call site (%$F) and a format string (%$S) which describes what information the event is logging. The following text will be displayed for the event, if it was logged from file demo.c at line 1234 and all 200 bytes were logged in the same event.

  Memory Snapshot at [demo.c:1234] [snapshotID=0,adrs=0x80002000,
    numMAUsDataInEvent=200,numMAUsDataInRecord=200] ptr=0x80002000, numBytes=200

If the 200 bytes were spread across multiple events, the numMAUsDataInRecord would indicate how many bytes were in the memory block, and numMAUsDataInEvent would indicate how many bytes were stored in that particular event.

 

config UIASnapshot_nameOfReference  // module-wide

index URL

Used to log the contents of a dynamic string on the heap so that host-side tooling can display this string as the name of handle / reference ID

C synopsis

target-domain

extern const Log_Event UIASnapshot_nameOfReference;

 

VALUES

__FILE__ — The file that the LogSnapshot call site was in (used by %$F)

__LINE__ — The line of code of the LogSnapshot call site (used by %$F)

refID — reference ID (e.g. task handle) that the name is associated with

adrs — the start address of the string in memory

numMAUsDataInEvent — the number of MAUs of data payload for this event

numMAUsDataInRecord — the total number of MAUs of data payload for the multi-event data record

fmt — a constant string that provides a user-readable description of what information the event is capturing

DETAILS

This event is used internally by the LogSnapshot.nameOfReference API.

EXAMPLE

The following C code shows how to log a task name for use by task execution graphs etc.

  #include <ti/uia/runtime/LogSnapshot.h> 
  #include <ti/sysbios/BIOS.h>
  #include <ti/sysbios/knl/Task.h>
  ...
  // Task create hook function that logs the task name.
  // Notes: Task name is not trequired when creating a BIOS task. Please \
  // make sure a name is provided in order for the host side analysis tool
  // to work properly.
  Void  tskCreateHook(Task_Handle hTask, Error_Block *eb) {
          String name;
          name = Task_Handle_name(hTask);
          LogSnapshot_writeNameOfReference(hTask,"Task_create name=%s",
            name,strlen(name)+1);
  }

This event prints the Log call site (%$F) and a format string (%$S) which describes what information the event is logging. The following text will be displayed for the event:

  nameOfReference at [demo.c:line 1234] [refID=0x80002000,adrs=0x80001234,40,40] Task_create: name=10msThread.     

 

config UIASnapshot_stringOnHeap  // module-wide

index URL

Analysis event posted when a string snapshot is logged

C synopsis

target-domain

extern const Log_Event UIASnapshot_stringOnHeap;

 

VALUES

__FILE__ — The file that the LogSnapshot call site was in (used by %$F)

__LINE__ — The line of code of the LogSnapshot call site (used by %$F)

snapshotID — ID used to identify snapshot events taken at the same time. Set to 0 for first in series, set rest to return value of LogSnapshot API.

adrs — the start address of the string in memory

numMAUsDataInEvent — the number of MAUs of data payload for this event

numMAUsDataInRecord — the total number of MAUs of data payload for the multi-event data record

fmt — a constant string that provides a user-readable description of what information the event is capturing

DETAILS

This event is used internally by the LogSnapshot.writeString API.

EXAMPLE

The following C code shows how to log a snapshot event to capture a block of memory.

  #include <ti/uia/runtime/LogSnapshot.h> 
  #include <string.h> // for strlen
  ...
  Void myFunc(String name){
     ...
     //Upload the memory contents of the dynamically allocated string 'name'
     LogSnapshot_stringOnHeap(0,"name",name, strlen(name));
     //Now that the string memory contents have been uploaded,
     //subsequent events that reference the string will be properly
     //rendered.  
     Log_info1("User-defined name=%s.",name);
  }

The following text will be displayed for the event, if LogSnapshot was called from file demo.c at line 1234 and the value of "name" was "aUserDefinedName".

  String Snapshot at [../demo.c:1234] [snapshotID=0,adrs=0x80001234,40,40] name.   
  "demo.c", line 1235: User-defined name=aUserDefinedName.

generated on Wed, 14 Mar 2012 16:46:04 GMT