module ti.uia.runtime.LogSnapshot

index URL

Snapshot Event logging manager for logging blocks of memory, strings in memory and names of dynamically created objects

*       C synopsis

*  Individual elements

Snapshot events are used to log dynamic target state information in order to capture the execution context of the application at a particular moment in time. Types of information that can be logged include: [ more ... ]

C synopsis

target-domain

sourced in ti/uia/runtime/LogSnapshot.h

#include <ti/uia/runtime/LogSnapshot.h>

Functions

UInt32 

Void 

macro Void 

LogSnapshot_putMemoryRange// Unconditionally put the specified Types event. Supports both writeMemoryRange and writeString(Types_Event evt, Types_ModuleId mid, IArg fileName, IArg lineNum, UInt32 snapshotID, IArg fmt, IArg startAdrs, IArg lengthInMAUs);

macro Void 

LogSnapshot_writeMemoryBlock// Generate a LogSnapshot event for a block of memory(UInt32 snapshotID, IArg fmt, Ptr pMemoryRange, UInt16 lengthInMAUs);

macro Void 

macro Void 

LogSnapshot_writeString// Generate a LogSnapshot event for a string in memory(UInt32 snapshotID, IArg fmt, Ptr pString, UInt16 lengthInMAUs);

Functions common to all target modules

 

Typedefs

typedef struct

Constants

extern const Bool 

extern const Int 

 

DETAILS

Snapshot events are used to log dynamic target state information in order to capture the execution context of the application at a particular moment in time. Types of information that can be logged include:

*  Blocks of memory (using the LogSnapshot_writeMemoryBlock API)

*  Strings that reside in memory (using the LogSnapshot_writeString API)

*  Names of dynamically created objects (using the LogSnapshot_writeNameOfReference API)

The host-side tooling can be instructed to treat a series of LogSnapshot events as representing the state of the target at the same moment in time by using the same non-zero value in the snapshot ID parameter of each of the LogSnapshot events in the series.

Snapshot events are logged by a logger that implements the LoggerFlexSupport_writeMemoryRange API (e.g. LoggerStreamer).  Rather than invoking the logger's APIs directly, the APIs are called indirectly via the LogSnapshot module's macro APIs so that different types of loggers can be used without having to recompile the source code that is logging the snapshot events

 

LogSnapshot_getSnapshotId()  // module-wide

index URL

returns a unique ID to use to group a set of snapshot event logs together

C synopsis

target-domain

UInt32 LogSnapshot_getSnapshotId();

 

DETAILS

Allows tooling to treat a set of consecutive event logs as a unit and display all of the relevent data together as a set

EXAMPLE

The following C code shows how to log two snapshot events that capture the target state of two different data structures, using a common unique non-zero snapshot ID provided by the getSnapshotId to inform the host-side tooling that the events represent the target state at the same point in time

  #include <ti/uia/runtime/LogSnapshot.h> 
  ...
  MyStruct1 myStruct1;
  MyStruct2 myStruct2;   
  UInt32 snapshotId;
  ...  
  snapshotId = LogSnapshot_getSnapshotId();
  LogSnapshot_writeMemoryBlock(snapshotId,"myStruct1 ptr=0x%x, numBytes=%d",(UInt32)&myStruct1,sizeof(MyStruct1));
  LogSnapshot_writeMemoryBlock(snapshotId,"myStruct2 ptr=0x%x, numBytes=%d",(UInt32)&myStruct2,sizeof(MyStruct2));
  ...

RETURN

a unique non-zero snapshot ID to pass in as a parameter to the LogSnapshot APIs

 

LogSnapshot_putMemoryRange()  // module-wide

index URL

Unconditionally put the specified Types event. Supports both writeMemoryRange and writeString

C synopsis

target-domain

macro Void LogSnapshot_putMemoryRange(Types_Event evt, Types_ModuleId mid, IArg fileName, IArg lineNum, UInt32 snapshotID, IArg fmt, IArg startAdrs, IArg lengthInMAUs);

 

ARGUMENTS

evt — the Types event to put into the log

mid — the module ID of the caller

snapshotId — unique ID that binds together a series of events used to log a large memory range

fileName — the name of the file that the event was logged from

lineNum — the line number that the event was logged from

fmt — a user-specified print format string

startAdrs — the start address of the memory range to log

lengthInMAUs — the number of minimum addressable units (e.g. bytes) to log

DETAILS

This method unconditionally puts the specified memoryRangeTypes.Event evt into the log. This type of event is created either implicitly (and passed to an ISnapshotLogger implementation) or explicitly via Types.makeEvent().

RETURN

value to use as snapshotId parameter for subsequent events

 

LogSnapshot_writeMemoryBlock()  // module-wide

index URL

Generate a LogSnapshot event for a block of memory

C synopsis

target-domain

macro Void LogSnapshot_writeMemoryBlock(UInt32 snapshotID, IArg fmt, Ptr pMemoryRange, UInt16 lengthInMAUs);

 

ARGUMENTS

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. see getSnapshotId()

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

pMemoryRange — the start address of the range of memory

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

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);
  ...

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.

 

LogSnapshot_writeNameOfReference()  // 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

macro Void LogSnapshot_writeNameOfReference(UInt32 refID, IArg fmt, Ptr pString, UInt16 lengthInMAUs);

 

ARGUMENTS

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

pString — the start address of the string on the heap

lengthInMAUs — the number of MAUs to log (e.g. strlen(pString))

fmt — a constant string that provides format specifiers describing the string

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. 

 

LogSnapshot_writeString()  // module-wide

index URL

Generate a LogSnapshot event for a string in memory

C synopsis

target-domain

macro Void LogSnapshot_writeString(UInt32 snapshotID, IArg fmt, Ptr pString, UInt16 lengthInMAUs);

 

ARGUMENTS

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. see getSnapshotId()

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

pString — the start address of the string in memory

lengthInMAUs — the number of MAUs to log (e.g. strlen(pString))

EXAMPLE

The following C code shows how to log a snapshot event to log the contents of a string in memory.

  #include <ti/uia/runtime/LogSnapshot.h> 
  ...
  Void myFunc(String name){
     ...
     LogSnapshot_writeString(0,"User-defined name=%s.",name, strlen(name));
  }

The following text will be displayed for the event, if it was logged from file demo.c at line 1234 and all bytes in the 40 character string was logged in the same event.

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

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