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 ... ]
#include <ti/uia/events/UIASnapshot.h>
Functions common to all target modules |
|
|
Constants |
| |
| |
| |
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
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
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
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 |
 |
// Get this module's unique id
Bool UIASnapshot_Module_startupDone();
// Test if this module has completed startup
// 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
var UIASnapshot = xdc.useModule('ti.uia.events.UIASnapshot');
module-wide config parameters
msg: "Memory Snapshot at %$F% [snapshotID=%d,adrs=0x%x,numMAUsDataInEvent=%hd,numMAUsDataInRecord=%hd] %$S"
};
msg: "nameOfReference at %$F [refID=0x%x,adrs=0x%x,numMAUsDataInEvent=%hd numMAUsDataInRecord=%hd] %$S"
};
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
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
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
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
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