module ti.uia.events.UIASnapshot

UIA Snapshot Events

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.xdc
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__).
The following configuration script demonstrates how the application might control the logging of ANALYSIS events embedded in the Mod module at configuration time. In this case, the configuration script arranges for the Log statements within modules to always generate ANALYSIS events. Without these configuration statements, no ANALYSIS events would be generated by any modules.
EXAMPLES
Example 1: This is part of the XDC configuration file for the application: (Note that the UIASnapshot module is automatically included by the LogSnapshot.xs script, and so does not need to be referenced in the application's .cfg file)
  var LogSnapshot = xdc.useModule('ti.uia.runtime.LogSnapshot');
  var LoggerCircBuf = xdc.useModule('ti.uia.runtime.LoggerCircBuf');
  var LoggerCircBufParams = new LoggerCircBuf.Params;
  // set the logger buffer size in bytes
  LoggerCircBufParams.transferBufSize = 32768;
  var logger = LoggerCircBuf.create(LoggerCircBufParams);

  // Configure all modules to always log Analysis events, including
  // UIASnapshot events
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Defaults = xdc.useModule('xdc.runtime.Defaults');
  Defaults.common$.diags_ANALYSIS = Diags.ALWAYS_ON;
  Defaults.common$.logger = logger;


Example 2: The following example configures a module to support logging of ANALYSIS events, but defers the actual activation and deactivation of the logging until runtime. See the Diags_setMask() function for details on specifying the control string.
This is part of the XDC configuration file for the application:
  var LogSnapshot = xdc.useModule('ti.uia.runtime.LogSnapshot');
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Mod = xdc.useModule('my.pkg.Mod');

  Mod.common$.diags_ANALYSIS = Diags.RUNTIME_OFF;
This is a part of the C code for the application:
  // 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

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

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

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.
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId UIASnapshot_Module_id();
// Get this module's unique id
 
Bool UIASnapshot_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle UIASnapshot_Module_heap();
// The heap from which this module allocates memory
 
Bool UIASnapshot_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 UIASnapshot_Module_getMask();
// Returns the diagnostics mask for this module
 
Void UIASnapshot_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
Configuration settings sourced in ti/uia/events/UIASnapshot.xdc
var UIASnapshot = xdc.useModule('ti.uia.events.UIASnapshot');
module-wide config parameters
        mask: Diags.ANALYSIS,
        msg: "Memory Snapshot at %$F% [snapshotID=%d,adrs=0x%x,numMAUsDataInEvent=%hd,numMAUsDataInRecord=%hd] %$S"
    };
        mask: Diags.ANALYSIS,
        msg: "nameOfReference at %$F [refID=0x%x,adrs=0x%x,numMAUsDataInEvent=%hd numMAUsDataInRecord=%hd] %$S"
    };
        mask: Diags.ANALYSIS,
        msg: "String Snapshot at %$F [snapshotID=%d,adrs=0x%x,numMAUsDataInEvent=%hd,numMAUsDataInRecord=%hd] %$S"
    };
 
 
 
config UIASnapshot.memoryRange  // module-wide

Analysis event posted when a memoryRange snapshot is logged

Configuration settings
UIASnapshot.memoryRange = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "Memory Snapshot at %$F% [snapshotID=%d,adrs=0x%x,numMAUsDataInEvent=%hd,numMAUsDataInRecord=%hd] %$S"
};
 
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.
C SYNOPSIS
 
config UIASnapshot.nameOfReference  // module-wide

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

Configuration settings
UIASnapshot.nameOfReference = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "nameOfReference at %$F [refID=0x%x,adrs=0x%x,numMAUsDataInEvent=%hd numMAUsDataInRecord=%hd] %$S"
};
 
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.
C SYNOPSIS
 
config UIASnapshot.stringOnHeap  // module-wide

Analysis event posted when a string snapshot is logged

Configuration settings
UIASnapshot.stringOnHeap = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "String Snapshot at %$F [snapshotID=%d,adrs=0x%x,numMAUsDataInEvent=%hd,numMAUsDataInRecord=%hd] %$S"
};
 
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.
C SYNOPSIS
 
metaonly config UIASnapshot.common$  // module-wide

Common module configuration parameters

Configuration settings
UIASnapshot.common$ = Types.Common$ undefined;
 
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Tue, 14 Feb 2017 00:15:10 GMT