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 ... ]
C synopsis target-domain sourced in ti/uia/events/UIAUserCtx.xdc
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 store the return value of the function in ti_uia_runtime_CtxFilter_gIsLoggingEnabled, which is used to determine whether or not to log events.
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
C synopsis target-domain
typedef Bool (*UIAUserCtx_IsLoggingEnabledFxn)(Int);
 
 
config UIAUserCtx_ENABLEMASK  // module-wide

Ctx Filter Enable Mask

C synopsis target-domain
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

C synopsis target-domain
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

C synopsis target-domain
extern const Log_Event UIAUserCtx_ctxChg;
 
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
C synopsis target-domain
extern const IUIACtx_IsLoggingEnabledFxn UIAUserCtx_isLoggingEnabledFxn;
 
 
UIAUserCtx_getCtxId()  // module-wide

Get the ID for the current user-defined context

C synopsis target-domain
macro Int UIAUserCtx_getCtxId();
 
RETURNS
returns the context ID logged by the last call to UIAUserCtx_logCtxChg.
 
UIAUserCtx_isLoggingEnabled()  // module-wide

returns true if the new context matches the value to enable logging with

C synopsis target-domain
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, assign UIAUserCtx_isLoggingEnabledFxn = &UIAUserCtx_isLoggingEnabled in the config script or programmatically, or assign your own implementation of this function.
RETURNS
true if logging is enabled
 
UIAUserCtx_setOldValue()  // module-wide

sets ti_uia_events_UIAUserCtx_gLastValue to the new value and returns the old value before it was updated

C synopsis target-domain
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

C synopsis target-domain
Types_ModuleId UIAUserCtx_Module_id();
// Get this module's unique id
 
Bool UIAUserCtx_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle UIAUserCtx_Module_heap();
// 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
 
XDCscript usage meta-domain sourced in ti/uia/events/UIAUserCtx.xdc
var UIAUserCtx = xdc.useModule('ti.uia.events.UIAUserCtx');
module-wide config parameters
    UIAUserCtx.SYNCID// Trace Synchronization ID = Bits16 undefined;
        mask: Diags.ANALYSIS,
        msg: "User Ctx Change at %$F [Prev. ctx = 0x%x] %$S"
    };
    UIAUserCtx.isLoggingEnabledFxn//  = Bool(*)(Int) null;
 
 
 
config UIAUserCtx.ENABLEMASK  // module-wide

Ctx Filter Enable Mask

XDCscript usage meta-domain
UIAUserCtx.ENABLEMASK = Bits16 undefined;
 
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.
C SYNOPSIS
 
config UIAUserCtx.SYNCID  // module-wide

Trace Synchronization ID

XDCscript usage meta-domain
UIAUserCtx.SYNCID = Bits16 undefined;
 
DETAILS
configures the value to be written into the 4 bit context change type field used by the UIASync trace synchronization
C SYNOPSIS
 
config UIAUserCtx.ctxChg  // module-wide

User-defined Context Change event

XDCscript usage meta-domain
UIAUserCtx.ctxChg = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "User Ctx Change at %$F [Prev. ctx = 0x%x] %$S"
};
 
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"

C SYNOPSIS
 
config UIAUserCtx.isLoggingEnabledFxn  // module-wide
XDCscript usage meta-domain
UIAUserCtx.isLoggingEnabledFxn = Bool(*)(Int) null;
 
C SYNOPSIS
 
metaonly config UIAUserCtx.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
UIAUserCtx.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 Mon, 28 Jan 2013 17:45:34 GMT