module ti.uia.runtime.LogSnapshot |
Snapshot Event logging manager for logging blocks of
memory, strings in memory and names of dynamically created objects
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>
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 |
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 |
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 |
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 |
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 |
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