module ti.uia.events.UIABenchmark

UIA Benchmark Events

The UIABenchmark module defines events that allow tooling to analyze the performance of the software (processing time, latency, etc.) [ more ... ]
C synopsis target-domain sourced in ti/uia/events/UIABenchmark.xdc
DETAILS
The UIABenchmark module defines events that allow tooling to analyze the performance of the software (processing time, latency, etc.)
The generation of UIABenchmark events is controlled by a module's diagnostics mask, which is described in detail in xdc.runtime.Diags. UIABenchmark 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 UIABenchmark = xdc.useModule('ti.uia.events.UIABenchmark');
  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 UIABenchmark = xdc.useModule('ti.uia.events.UIABenchmark');
  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 UIABenchmark_start  // module-wide

Benchmark event used to log the start of an operation

C synopsis target-domain
extern const Log_Event UIABenchmark_start;
 
VALUES
fmt — a constant string that provides format specifiers for up to 7 additional parameters
EXAMPLE
The following C code shows how to log a simple benchmark 'start' event along with a user-specified format string describing the event.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIABenchmark.h>
  ...
  Log_write1(UIABenchmark_start, (IArg)"My benchmark event");
The following text will be displayed for the event:
  Start: My benchmark event
 
config UIABenchmark_startInstance  // module-wide

Benchmark event used to log the start of an operation instance

C synopsis target-domain
extern const Log_Event UIABenchmark_startInstance;
 
VALUES
fmt — a constant string that provides format specifiers for up to 6 additional parameters
instanceId — a unique instance ID that can be used to match benchmark start and stop events
DETAILS
Event parameter provides instance data to differentiate between multiple instances that can run in parallel.
EXAMPLE
The following C code shows how to log a benchmark 'startInstance' event along with a user-specified instance identifier and a format string describing the event.
  #include <xdc/runtime/Gate.h>
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIABenchmark.h>
  static volatile int gMyGlobalInstanceId = 0;
  ...
  IArg key;
  int localInstanceId;

 // protect pre-increment operation from race conditions
  key = Gate_enterSystem();
  localInstanceId = ++gMyGlobalInstanceId;
  Gate_leaveSystem(key);

  Log_write2(UIABenchmark_startInstance, (IArg)"My benchmark event: instanceId=%d",localInstanceId);
  ...
  Log_write2(UIABenchmark_stopInstance, (IArg)"My benchmark event: instanceId=%d",localInstanceId);
The following text will be displayed for the event:
  StartInstance: My benchmark event: instanceId=1
  StopInstance: My benchmark event: instanceId=1
 
config UIABenchmark_startInstanceWithAdrs  // module-wide

Benchmark event used to log the start of an operation instance

C synopsis target-domain
extern const Log_Event UIABenchmark_startInstanceWithAdrs;
 
VALUES
fmt — a constant string that provides format specifiers for up to 5 additional parameters
instanceId — a unique instance ID that can be used to match benchmark start and stop events
functionAdrs — the address of a function that can differentiate this pair of start and stop events from others
DETAILS
Event parameter provides instance data to differentiate between multiple instances that can run in parallel
EXAMPLE
The following C code shows how to log a benchmark 'startInstanceWithAdrs' event along with a task handle as the instance identifier, the function address and a format string describing the event.
  #include <ti/sysbios/knl/Task.h>
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIABenchmark.h>
  ...
 Void myFunction(){
   Task_Handle hTsk = Task_selfMacro();

   Log_write3(UIABenchmark_startInstanceWithAdrs, (IArg)"My benchmark event: task=0x%x, fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
   ...
   Log_write3(UIABenchmark_stopInstanceWithAdrs, (IArg)"My benchmark event: task=0x%x", fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
 }
The following text will be displayed for the event:
  StartInstanceWithAdrs: My benchmark event: task=0x893230, fnAdrs=0x820060
  StopInstanceWithAdrs: My benchmark event: task=0x893230, fnAdrs=0x820060
 
config UIABenchmark_startInstanceWithStr  // module-wide

Benchmark event used to log the start of an operation instance

C synopsis target-domain
extern const Log_Event UIABenchmark_startInstanceWithStr;
 
VALUES
fmt — a constant string that provides format specifiers for up to 5 additional parameters
instanceId — a unique instance ID that can be used to match benchmark start and stop events
str — a constant string reference
DETAILS
Event parameter provides instance data to differentiate between multiple instances that can run in parallel
EXAMPLE
The following C code shows how to log a benchmark 'startInstanceWithStr' event along with a unique instance identifier and a string reference used only by the pair of start / stop events.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIABenchmark.h>
  ...
 Void packetHdlr(Int packetId){

   Log_write3(UIABenchmark_startInstanceWithStr, (IArg)"My benchmark event: packetId=0x%x",packetId,(IArg)"(routing)");
   ...
   Log_write3(UIABenchmark_stopInstanceWithStr, (IArg)"My benchmark event: packetId=0x%x",packetId,(IArg)"(routing)");
 }
The following text will be displayed for the event:
  StartInstanceWithStr: My benchmark event: packetId=0x3bc3 (routing)
  StopInstanceWithStr: My benchmark event: packetId=0x3bc3 (routing)
Event parameter provides instance data to differentiate between multiple instances that can run in parallel
 
config UIABenchmark_stop  // module-wide

Benchmark event used to log the end of an operation

C synopsis target-domain
extern const Log_Event UIABenchmark_stop;
 
VALUES
fmt — a constant string that provides format specifiers for up to 7 additional parameters
EXAMPLE
The following C code shows how to log a simple benchmark 'stop' event along with a user-specified format string describing the event.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIABenchmark.h>
  ...
  Log_write1(UIABenchmark_stop, (IArg)"My benchmark event");
The following text will be displayed for the event:
  Stop: My benchmark event
 
config UIABenchmark_stopInstance  // module-wide

Benchmark event used to log the end of an operation instance

C synopsis target-domain
extern const Log_Event UIABenchmark_stopInstance;
 
VALUES
fmt — a constant string that provides format specifiers for up to 6 additional parameters
instanceId — a unique instance ID that can be used to match benchmark start and stop events
DETAILS
Event parameter provides instance data to differentiate between multiple instances that can run in parallel.
EXAMPLE
The following C code shows how to log a benchmark 'stopInstance' event along with a user-specified instance identifier and a format string describing the event.
  #include <xdc/runtime/Gate.h>
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIABenchmark.h>
  static volatile int gMyGlobalInstanceId = 0;
  ...
  IArg key;
  int localInstanceId;

 // protect pre-increment operation from race conditions
  key = Gate_enterSystem();
  localInstanceId = ++gMyGlobalInstanceId;
  Gate_leaveSystem(key);

  Log_write2(UIABenchmark_startInstance, (IArg)"My benchmark event: instanceId=%d",localInstanceId);
  ...
  Log_write2(UIABenchmark_stopInstance, (IArg)"My benchmark event: instanceId=%d",localInstanceId);
The following text will be displayed for the event:
  StartInstance: My benchmark event: instanceId=1
  StopInstance: My benchmark event: instanceId=1
 
config UIABenchmark_stopInstanceWithAdrs  // module-wide

Benchmark event used to log the end of an operation instance

C synopsis target-domain
extern const Log_Event UIABenchmark_stopInstanceWithAdrs;
 
VALUES
fmt — a constant string that provides format specifiers for up to 5 additional parameters
instanceId — a unique instance ID that can be used to match benchmark start and stop events
functionAdrs — the address of a function that can differentiate this pair of start and stop events from others
EXAMPLE
The following C code shows how to log a benchmark 'stopInstanceWithAdrs' event along with a task handle as the instance identifier, the function address and a format string describing the event.
  #include <ti/sysbios/knl/Task.h>
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIABenchmark.h>
  ...
 Void myFunction(){
   Task_Handle hTsk = Task_selfMacro();

   Log_write3(UIABenchmark_startInstanceWithAdrs, (IArg)"My benchmark event: task=0x%x, fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
   ...
   Log_write3(UIABenchmark_stopInstanceWithAdrs, (IArg)"My benchmark event: task=0x%x", fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
 }
The following text will be displayed for the event:
  StartInstanceWithAdrs: My benchmark event: task=0x893230, fnAdrs=0x820060
  StopInstanceWithAdrs: My benchmark event: task=0x893230, fnAdrs=0x820060
 
config UIABenchmark_stopInstanceWithStr  // module-wide

Benchmark event used to log the end of an operation instance

C synopsis target-domain
extern const Log_Event UIABenchmark_stopInstanceWithStr;
 
VALUES
fmt — a constant string that provides format specifiers for up to 5 additional parameters
instanceId — a unique instance ID that can be used to match benchmark start and stop events
str — a constant string reference
DETAILS
Event parameter provides instance data to differentiate between multiple instances that can run in parallel
EXAMPLE
The following C code shows how to log a benchmark 'stopInstanceWithStr' event along with a unique instance identifier and a string reference used only by the pair of start / stop events.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIABenchmark.h>
  ...
 Void packetHdlr(Int packetId){

   Log_write3(UIABenchmark_startInstanceWithStr, (IArg)"My benchmark event: packetId=0x%x",packetId,(IArg)"(routing)");
   ...
   Log_write3(UIABenchmark_stopInstanceWithStr, (IArg)"My benchmark event: packetId=0x%x",packetId,(IArg)"(routing)");
 }
The following text will be displayed for the event:
  StartInstanceWithStr: My benchmark event: packetId=0x3bc3 (routing)
  StopInstanceWithStr: My benchmark event: packetId=0x3bc3 (routing)
Event parameter provides instance data to differentiate between multiple instances that can run in parallel
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId UIABenchmark_Module_id();
// Get this module's unique id
 
Bool UIABenchmark_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle UIABenchmark_Module_heap();
// The heap from which this module allocates memory
 
Bool UIABenchmark_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 UIABenchmark_Module_getMask();
// Returns the diagnostics mask for this module
 
Void UIABenchmark_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
XDCscript usage meta-domain sourced in ti/uia/events/UIABenchmark.xdc
var UIABenchmark = xdc.useModule('ti.uia.events.UIABenchmark');
module-wide config parameters
        mask: Diags.ANALYSIS,
        msg: "Start: %$S "
    };
        mask: Diags.ANALYSIS,
        msg: "StartInstance: %$S "
    };
        mask: Diags.ANALYSIS,
        msg: "StartInstanceWithAdrs: %$S"
    };
        mask: Diags.ANALYSIS,
        msg: "StartInstanceWithStr: %$S"
    };
        mask: Diags.ANALYSIS,
        msg: "Stop: %$S "
    };
        mask: Diags.ANALYSIS,
        msg: "StopInstance: %$S "
    };
        mask: Diags.ANALYSIS,
        msg: "StopInstanceWithAdrs: %$S"
    };
        mask: Diags.ANALYSIS,
        msg: "StopInstanceWithStr: %$S"
    };
 
 
 
config UIABenchmark.start  // module-wide

Benchmark event used to log the start of an operation

XDCscript usage meta-domain
UIABenchmark.start = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "Start: %$S "
};
 
VALUES
fmt — a constant string that provides format specifiers for up to 7 additional parameters
EXAMPLE
The following C code shows how to log a simple benchmark 'start' event along with a user-specified format string describing the event.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIABenchmark.h>
  ...
  Log_write1(UIABenchmark_start, (IArg)"My benchmark event");
The following text will be displayed for the event:
  Start: My benchmark event
C SYNOPSIS
 
config UIABenchmark.startInstance  // module-wide

Benchmark event used to log the start of an operation instance

XDCscript usage meta-domain
UIABenchmark.startInstance = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "StartInstance: %$S "
};
 
VALUES
fmt — a constant string that provides format specifiers for up to 6 additional parameters
instanceId — a unique instance ID that can be used to match benchmark start and stop events
DETAILS
Event parameter provides instance data to differentiate between multiple instances that can run in parallel.
EXAMPLE
The following C code shows how to log a benchmark 'startInstance' event along with a user-specified instance identifier and a format string describing the event.
  #include <xdc/runtime/Gate.h>
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIABenchmark.h>
  static volatile int gMyGlobalInstanceId = 0;
  ...
  IArg key;
  int localInstanceId;

 // protect pre-increment operation from race conditions
  key = Gate_enterSystem();
  localInstanceId = ++gMyGlobalInstanceId;
  Gate_leaveSystem(key);

  Log_write2(UIABenchmark_startInstance, (IArg)"My benchmark event: instanceId=%d",localInstanceId);
  ...
  Log_write2(UIABenchmark_stopInstance, (IArg)"My benchmark event: instanceId=%d",localInstanceId);
The following text will be displayed for the event:
  StartInstance: My benchmark event: instanceId=1
  StopInstance: My benchmark event: instanceId=1
C SYNOPSIS
 
config UIABenchmark.startInstanceWithAdrs  // module-wide

Benchmark event used to log the start of an operation instance

XDCscript usage meta-domain
UIABenchmark.startInstanceWithAdrs = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "StartInstanceWithAdrs: %$S"
};
 
VALUES
fmt — a constant string that provides format specifiers for up to 5 additional parameters
instanceId — a unique instance ID that can be used to match benchmark start and stop events
functionAdrs — the address of a function that can differentiate this pair of start and stop events from others
DETAILS
Event parameter provides instance data to differentiate between multiple instances that can run in parallel
EXAMPLE
The following C code shows how to log a benchmark 'startInstanceWithAdrs' event along with a task handle as the instance identifier, the function address and a format string describing the event.
  #include <ti/sysbios/knl/Task.h>
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIABenchmark.h>
  ...
 Void myFunction(){
   Task_Handle hTsk = Task_selfMacro();

   Log_write3(UIABenchmark_startInstanceWithAdrs, (IArg)"My benchmark event: task=0x%x, fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
   ...
   Log_write3(UIABenchmark_stopInstanceWithAdrs, (IArg)"My benchmark event: task=0x%x", fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
 }
The following text will be displayed for the event:
  StartInstanceWithAdrs: My benchmark event: task=0x893230, fnAdrs=0x820060
  StopInstanceWithAdrs: My benchmark event: task=0x893230, fnAdrs=0x820060
C SYNOPSIS
 
config UIABenchmark.startInstanceWithStr  // module-wide

Benchmark event used to log the start of an operation instance

XDCscript usage meta-domain
UIABenchmark.startInstanceWithStr = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "StartInstanceWithStr: %$S"
};
 
VALUES
fmt — a constant string that provides format specifiers for up to 5 additional parameters
instanceId — a unique instance ID that can be used to match benchmark start and stop events
str — a constant string reference
DETAILS
Event parameter provides instance data to differentiate between multiple instances that can run in parallel
EXAMPLE
The following C code shows how to log a benchmark 'startInstanceWithStr' event along with a unique instance identifier and a string reference used only by the pair of start / stop events.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIABenchmark.h>
  ...
 Void packetHdlr(Int packetId){

   Log_write3(UIABenchmark_startInstanceWithStr, (IArg)"My benchmark event: packetId=0x%x",packetId,(IArg)"(routing)");
   ...
   Log_write3(UIABenchmark_stopInstanceWithStr, (IArg)"My benchmark event: packetId=0x%x",packetId,(IArg)"(routing)");
 }
The following text will be displayed for the event:
  StartInstanceWithStr: My benchmark event: packetId=0x3bc3 (routing)
  StopInstanceWithStr: My benchmark event: packetId=0x3bc3 (routing)
Event parameter provides instance data to differentiate between multiple instances that can run in parallel
C SYNOPSIS
 
config UIABenchmark.stop  // module-wide

Benchmark event used to log the end of an operation

XDCscript usage meta-domain
UIABenchmark.stop = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "Stop: %$S "
};
 
VALUES
fmt — a constant string that provides format specifiers for up to 7 additional parameters
EXAMPLE
The following C code shows how to log a simple benchmark 'stop' event along with a user-specified format string describing the event.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIABenchmark.h>
  ...
  Log_write1(UIABenchmark_stop, (IArg)"My benchmark event");
The following text will be displayed for the event:
  Stop: My benchmark event
C SYNOPSIS
 
config UIABenchmark.stopInstance  // module-wide

Benchmark event used to log the end of an operation instance

XDCscript usage meta-domain
UIABenchmark.stopInstance = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "StopInstance: %$S "
};
 
VALUES
fmt — a constant string that provides format specifiers for up to 6 additional parameters
instanceId — a unique instance ID that can be used to match benchmark start and stop events
DETAILS
Event parameter provides instance data to differentiate between multiple instances that can run in parallel.
EXAMPLE
The following C code shows how to log a benchmark 'stopInstance' event along with a user-specified instance identifier and a format string describing the event.
  #include <xdc/runtime/Gate.h>
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIABenchmark.h>
  static volatile int gMyGlobalInstanceId = 0;
  ...
  IArg key;
  int localInstanceId;

 // protect pre-increment operation from race conditions
  key = Gate_enterSystem();
  localInstanceId = ++gMyGlobalInstanceId;
  Gate_leaveSystem(key);

  Log_write2(UIABenchmark_startInstance, (IArg)"My benchmark event: instanceId=%d",localInstanceId);
  ...
  Log_write2(UIABenchmark_stopInstance, (IArg)"My benchmark event: instanceId=%d",localInstanceId);
The following text will be displayed for the event:
  StartInstance: My benchmark event: instanceId=1
  StopInstance: My benchmark event: instanceId=1
C SYNOPSIS
 
config UIABenchmark.stopInstanceWithAdrs  // module-wide

Benchmark event used to log the end of an operation instance

XDCscript usage meta-domain
UIABenchmark.stopInstanceWithAdrs = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "StopInstanceWithAdrs: %$S"
};
 
VALUES
fmt — a constant string that provides format specifiers for up to 5 additional parameters
instanceId — a unique instance ID that can be used to match benchmark start and stop events
functionAdrs — the address of a function that can differentiate this pair of start and stop events from others
EXAMPLE
The following C code shows how to log a benchmark 'stopInstanceWithAdrs' event along with a task handle as the instance identifier, the function address and a format string describing the event.
  #include <ti/sysbios/knl/Task.h>
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIABenchmark.h>
  ...
 Void myFunction(){
   Task_Handle hTsk = Task_selfMacro();

   Log_write3(UIABenchmark_startInstanceWithAdrs, (IArg)"My benchmark event: task=0x%x, fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
   ...
   Log_write3(UIABenchmark_stopInstanceWithAdrs, (IArg)"My benchmark event: task=0x%x", fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
 }
The following text will be displayed for the event:
  StartInstanceWithAdrs: My benchmark event: task=0x893230, fnAdrs=0x820060
  StopInstanceWithAdrs: My benchmark event: task=0x893230, fnAdrs=0x820060
C SYNOPSIS
 
config UIABenchmark.stopInstanceWithStr  // module-wide

Benchmark event used to log the end of an operation instance

XDCscript usage meta-domain
UIABenchmark.stopInstanceWithStr = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "StopInstanceWithStr: %$S"
};
 
VALUES
fmt — a constant string that provides format specifiers for up to 5 additional parameters
instanceId — a unique instance ID that can be used to match benchmark start and stop events
str — a constant string reference
DETAILS
Event parameter provides instance data to differentiate between multiple instances that can run in parallel
EXAMPLE
The following C code shows how to log a benchmark 'stopInstanceWithStr' event along with a unique instance identifier and a string reference used only by the pair of start / stop events.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIABenchmark.h>
  ...
 Void packetHdlr(Int packetId){

   Log_write3(UIABenchmark_startInstanceWithStr, (IArg)"My benchmark event: packetId=0x%x",packetId,(IArg)"(routing)");
   ...
   Log_write3(UIABenchmark_stopInstanceWithStr, (IArg)"My benchmark event: packetId=0x%x",packetId,(IArg)"(routing)");
 }
The following text will be displayed for the event:
  StartInstanceWithStr: My benchmark event: packetId=0x3bc3 (routing)
  StopInstanceWithStr: My benchmark event: packetId=0x3bc3 (routing)
Event parameter provides instance data to differentiate between multiple instances that can run in parallel
C SYNOPSIS
 
metaonly config UIABenchmark.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
UIABenchmark.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:32 GMT