module ti.uia.events.UIAUserCtx |
 |
 |
UIA User Context Instrumentation
The UIAUserCtx module provides context change events
and methods that allow tooling to identify user-defined
context switches and to enable context-aware filtering,
trace and analysis.
[
more ... ]
#include <ti/uia/events/UIAUserCtx.h>
Functions |
UInt | |
UInt | |
Bool | |
Void | |
UInt | |
Functions common to all target modules |
|
|
Typedefs |
typedef Bool | |
Constants |
| |
extern const Bits16 | |
| |
extern const Bits16 | |
DETAILS
The UIAUserCtx module provides context change events
and methods that allow tooling to identify user-defined
context switches and to enable context-aware filtering,
trace and analysis.
It inherits IUIACtx, which defines a function pointer to
an isLoggingEnabled function which, if configured to point to
a function, will evaluate the function prior to logging the context
change event and will determine whether to log the event based on the
return value of the function. If the function is not configured,
logging will be conditional upon ti_uia_runtime_CtxFilter_module->mIsLoggingEnabled.
The generation of UIAUserCtx events is also controlled by a module's diagnostics
mask, which is described in details in
xdc.runtime.Diags.
UIAUserCtx events are generated only when the Diags.ANALYSIS bit is set
in the module's diagnostics mask.
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:
var LogCtxChg = xdc.useModule('ti.uia.runtime.LogCtxChg');
var Diags = xdc.useModule('xdc.runtime.Diags');
var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
var Defaults = xdc.useModule('xdc.runtime.Defaults');
var logger = LoggerSys.create();
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 a part of the XDC configuration file for the application:
var LogCtxChg = xdc.useModule('ti.uia.runtime.LogCtxChg');
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");
typedef UIAUserCtx_IsLoggingEnabledFxn |
 |
typedef Bool (*UIAUserCtx_IsLoggingEnabledFxn)(Int);
config UIAUserCtx_ENABLEMASK // module-wide |
 |
Ctx Filter Enable Mask
extern const Bits16 UIAUserCtx_ENABLEMASK;
DETAILS
configures which bit of the ti_uia_runtime_CtxFilter_gFlags
is assigned to control context aware filtering for
frame context changes. Must be configured with a
value that is 2**SYNCID.
config UIAUserCtx_SYNCID // module-wide |
 |
Trace Synchronization ID
extern const Bits16 UIAUserCtx_SYNCID;
DETAILS
configures the value to be written into the
4 bit context change type field used by the
UIASync trace synchronization
config UIAUserCtx_ctxChg // module-wide |
 |
User-defined Context Change event
VALUES
fmt
a constant string that describes the context change and provides a format specifier for newAppId
newUserContextId
an integer which uniquely identifies the new user context
DETAILS
Used to log the start of new state in the user-defined context
Note that this event should not be referenced directly by user code - it is used
internally by the LogCtxChg_user function, which logs the previous user context Id automatically.
EXAMPLE
The following C code shows how to log a Context Change
event that identifies a new user-specified context ID
#include <ti/uia/runtime/LogCtxChg.h>
...
LogCtxChg_user("New user context=0x%x",newUserContextId);
...
This event prints the Log call site (%$F) and a format string (%$S)
which is recursively formatted with any addition arguments.
The following text is an example of what will be displayed for the event:
"User Ctx Change at Line 123 in appLoader.c [Prev. ctx = 0x1234] New user context=0x1235"
config UIAUserCtx_isLoggingEnabledFxn // module-wide |
 |
UIAUserCtx_getCtxId() // module-wide |
 |
Get the ID for the current user-defined context
UInt UIAUserCtx_getCtxId();
RETURNS
returns the context ID logged by the last call to UIAUserCtx_logCtxChg.
UIAUserCtx_getEnableOnValue() // module-wide |
 |
Get the EnableOn value
UInt UIAUserCtx_getEnableOnValue();
RETURNS
returns the context ID value that logging will be enabled for.
UIAUserCtx_isLoggingEnabled() // module-wide |
 |
returns true if the new context matches the value to enable logging with
Bool UIAUserCtx_isLoggingEnabled(UInt newUserCtx);
ARGUMENTS
newUserCtx
the new user context
DETAILS
Default implementation of the IUIACtx_IsLoggingEnabledFxn for user context.
To enable context-aware filtering, in the .cfg script assign
UIAUserCtx_isLoggingEnabledFxn = '&UIAUserCtx_isLoggingEnabled'
or assign your own implementation of this function.
RETURNS
true if logging is enabled
UIAUserCtx_setEnableOnValue() // module-wide |
 |
Set the EnableOn value
Void UIAUserCtx_setEnableOnValue(UInt value);
ARGUMENTS
value
the CtxId value that logging will be enabled for.
UIAUserCtx_setOldValue() // module-wide |
 |
sets ti_uia_events_UIAUserCtx_gLastValue to the new value and returns the old value before it was updated
UInt UIAUserCtx_setOldValue(UInt newValue);
ARGUMENTS
newValue
the new value to save in the global variable
RETURN
the original value of the global variable before it was updated.
Module-Wide Built-Ins |
 |
// Get this module's unique id
Bool UIAUserCtx_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool UIAUserCtx_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 UIAUserCtx_Module_getMask();
// Returns the diagnostics mask for this module
Void UIAUserCtx_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
var UIAUserCtx = xdc.useModule('ti.uia.events.UIAUserCtx');
module-wide config parameters
msg: "User Ctx Change at %$F [Prev. ctx = 0x%x] %$S"
};
generated on Tue, 14 Feb 2017 00:15:10 GMT