module ti.uia.events.UIAStatistic

UIA Statistics Events

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

bytesProcessed statistic event

C synopsis target-domain
extern const Log_Event UIAStatistic_bytesProcessed;
 
VALUES
name — a constant string that provides the name of the entity that is processing the data
numBytes — the number of bytes processed
DETAILS
Number of bytes that were processed.
 
config UIAStatistic_bytesProcessedByInstance  // module-wide

bytesProcessedByInstance statistic event

C synopsis target-domain
extern const Log_Event UIAStatistic_bytesProcessedByInstance;
 
VALUES
__FILE__ — constant string identifying the file the event was logged from
__LINE__ — the line number the event was logged from
instanceId — the instance ID (e.g. thread handle) of the entity that is processing the data
numBytes — the number of bytes processed
DETAILS
Number of bytes that were processed along with filename, line number and instance ID.
EXAMPLE
The following C code shows how to log an event that tracks the number of bytes processed
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAStatistic.h>
  ...
 Void myFunction(){
   int instanceId = 0x1234; // change to e.g. a TaskId or some other unique ID
   int numBytes= 567;       // change to number of bytes actually processed

   Log_write4(UIAStatistic_bytesProcessedByInstance, (IArg)__FILE__,(IArg)__LINE__,instanceId,numBytes);
 }
The following text will be displayed for the event:
  Bytes Processed at Line 123 in demo.c (InstanceId 0x1234): Num Bytes=567
 
config UIAStatistic_cpuLoad  // module-wide

Number of cycles used by an XDC module

C synopsis target-domain
extern const Log_Event UIAStatistic_cpuLoad;
 
VALUES
numCycles — the CPU load in cycles
EXAMPLE
The following C code shows how to log a cpuLoad event that tracks the number of cycles used by an XDC module. The module ID is logged along with the event. For non-XDC code, or for code with multiple instances @see #cpuLoadByInstance.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAStatistic.h>
  ...
 Void myFunction(){
   int numCycles = 0;
   // update numCycles with the number of cycles processed
   Log_write1(UIAStatistic_cpuLoad, numCycles);
 }
The following text will be displayed for the event:
  CPU Load: NumCycles=1234
 
config UIAStatistic_cpuLoadByInstance  // module-wide

Number of cycles used by a non XDC module or thread

C synopsis target-domain
extern const Log_Event UIAStatistic_cpuLoadByInstance;
 
VALUES
name — a constant string that provides the name of the entity that is processing the data
instanceId — the instance ID (e.g. thread handle) of the entity that is processing the data
numCycles — the CPU load in cycles
EXAMPLE
The following C code shows how to log a cpuLoad event that tracks the number of cycles used by code that is not in an XDC module or by a thread
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAStatistic.h>
  static volatile int gMyGlobalInstanceId = 0;
  ...
 Void myFunction(){
  IArg key;
  int localInstanceId;
  int numCycles = 0;
 // protect pre-increment operation from race conditions
  key = Gate_enterSystem();
  localInstanceId = ++gMyGlobalInstanceId;
  Gate_leaveSystem(key);
   // update numCycles with the number of cycles processed
   Log_write3(UIAStatistic_cpuLoadByInstance, "myFunction",localInstanceId,numCycles);
 }
The following text will be displayed for the event:
  CPU Load for myFunction (instanceId = 0x1234): NumCycles=1234
 
config UIAStatistic_freeBytes  // module-wide

Number of free bytes in heap

C synopsis target-domain
extern const Log_Event UIAStatistic_freeBytes;
 
VALUES
__FILE__ — constant string identifying the file the event was logged from
__LINE__ — the line number the event was logged from
heapId — heap identifier (e.g IHeap_Handle)
freeBytes — the number of bytes free on the heap
EXAMPLE
The following C code shows how to log a freeBytes event that tracks the number of bytes free in the heap
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAStatistic.h>
  ...
 Void myFunction(){
   int heapId = 0x1234;    // change to heap ID
   int numBytesFree = 567; // change to number of bytes free on the heap

   Log_write4(UIAStatistic_freeBytes, (IArg)__FILE__,(IArg)__LINE__,heapId,numFreeBytes);
 }
The following text will be displayed for the event:
  Heap at Line 123 in demo.c (HeapId 0x1234): Free Bytes=567
 
config UIAStatistic_wordsProcessed  // module-wide

wordsProcessed statistic event

C synopsis target-domain
extern const Log_Event UIAStatistic_wordsProcessed;
 
VALUES
name — a constant string that provides the name of the entity that is processing the data
numWords — the number of words processed
DETAILS
number of words that were processed.
 
config UIAStatistic_wordsProcessedByInstance  // module-wide

wordsProcessedByInstance statistic event

C synopsis target-domain
extern const Log_Event UIAStatistic_wordsProcessedByInstance;
 
VALUES
__FILE__ — constant string identifying the file the event was logged from
__LINE__ — the line number the event was logged from
instanceId — the instance ID (e.g. thread handle) of the entity that is processing the data
numWords — the number of words processed
DETAILS
Number of words that were processed along with filename, line number and instance ID.
EXAMPLE
The following C code shows how to log an event that tracks the number of words processed
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAStatistic.h>
  ...
 Void myFunction(){
   int instanceId = 0x1234;  // change to e.g. a TaskId or some other unique ID
   int numWords= 567;        // change to number of words actually processed

   Log_write4(UIAStatistic_wordsProcessedByInstance, (IArg)__FILE__,(IArg)__LINE__,instanceId,numWords);
 }
The following text will be displayed for the event:
  Words Processed at Line 123 in demo.c (InstanceId 0x1234): Num Words=567
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId UIAStatistic_Module_id();
// Get this module's unique id
 
Bool UIAStatistic_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle UIAStatistic_Module_heap();
// The heap from which this module allocates memory
 
Bool UIAStatistic_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 UIAStatistic_Module_getMask();
// Returns the diagnostics mask for this module
 
Void UIAStatistic_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
XDCscript usage meta-domain sourced in ti/uia/events/UIAStatistic.xdc
var UIAStatistic = xdc.useModule('ti.uia.events.UIAStatistic');
module-wide config parameters
        mask: Diags.ANALYSIS,
        msg: "Bytes Processed by %s: NumBytes=0x%x"
    };
        mask: Diags.ANALYSIS,
        msg: "Bytes Processed at %$F (InstanceId 0x%x): Num Bytes=%d"
    };
        mask: Diags.ANALYSIS,
        msg: "CPU Load: NumCycles=%d"
    };
        mask: Diags.ANALYSIS,
        msg: "CPU Load for %s (instanceId = 0x%x): NumCycles=%d"
    };
        mask: Diags.ANALYSIS,
        msg: "Heap at %$F (HeapId 0x%x): Free Bytes=%d"
    };
        mask: Diags.ANALYSIS,
        msg: "Words Processed by %s: NumWords=0x%x"
    };
        mask: Diags.ANALYSIS,
        msg: "Words Processed at %$F (InstanceId 0x%x): Num Words=%d"
    };
 
 
 
config UIAStatistic.bytesProcessed  // module-wide

bytesProcessed statistic event

XDCscript usage meta-domain
UIAStatistic.bytesProcessed = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "Bytes Processed by %s: NumBytes=0x%x"
};
 
VALUES
name — a constant string that provides the name of the entity that is processing the data
numBytes — the number of bytes processed
DETAILS
Number of bytes that were processed.
C SYNOPSIS
 
config UIAStatistic.bytesProcessedByInstance  // module-wide

bytesProcessedByInstance statistic event

XDCscript usage meta-domain
UIAStatistic.bytesProcessedByInstance = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "Bytes Processed at %$F (InstanceId 0x%x): Num Bytes=%d"
};
 
VALUES
__FILE__ — constant string identifying the file the event was logged from
__LINE__ — the line number the event was logged from
instanceId — the instance ID (e.g. thread handle) of the entity that is processing the data
numBytes — the number of bytes processed
DETAILS
Number of bytes that were processed along with filename, line number and instance ID.
EXAMPLE
The following C code shows how to log an event that tracks the number of bytes processed
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAStatistic.h>
  ...
 Void myFunction(){
   int instanceId = 0x1234; // change to e.g. a TaskId or some other unique ID
   int numBytes= 567;       // change to number of bytes actually processed

   Log_write4(UIAStatistic_bytesProcessedByInstance, (IArg)__FILE__,(IArg)__LINE__,instanceId,numBytes);
 }
The following text will be displayed for the event:
  Bytes Processed at Line 123 in demo.c (InstanceId 0x1234): Num Bytes=567
C SYNOPSIS
 
config UIAStatistic.cpuLoad  // module-wide

Number of cycles used by an XDC module

XDCscript usage meta-domain
UIAStatistic.cpuLoad = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "CPU Load: NumCycles=%d"
};
 
VALUES
numCycles — the CPU load in cycles
EXAMPLE
The following C code shows how to log a cpuLoad event that tracks the number of cycles used by an XDC module. The module ID is logged along with the event. For non-XDC code, or for code with multiple instances @see #cpuLoadByInstance.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAStatistic.h>
  ...
 Void myFunction(){
   int numCycles = 0;
   // update numCycles with the number of cycles processed
   Log_write1(UIAStatistic_cpuLoad, numCycles);
 }
The following text will be displayed for the event:
  CPU Load: NumCycles=1234
C SYNOPSIS
 
config UIAStatistic.cpuLoadByInstance  // module-wide

Number of cycles used by a non XDC module or thread

XDCscript usage meta-domain
UIAStatistic.cpuLoadByInstance = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "CPU Load for %s (instanceId = 0x%x): NumCycles=%d"
};
 
VALUES
name — a constant string that provides the name of the entity that is processing the data
instanceId — the instance ID (e.g. thread handle) of the entity that is processing the data
numCycles — the CPU load in cycles
EXAMPLE
The following C code shows how to log a cpuLoad event that tracks the number of cycles used by code that is not in an XDC module or by a thread
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAStatistic.h>
  static volatile int gMyGlobalInstanceId = 0;
  ...
 Void myFunction(){
  IArg key;
  int localInstanceId;
  int numCycles = 0;
 // protect pre-increment operation from race conditions
  key = Gate_enterSystem();
  localInstanceId = ++gMyGlobalInstanceId;
  Gate_leaveSystem(key);
   // update numCycles with the number of cycles processed
   Log_write3(UIAStatistic_cpuLoadByInstance, "myFunction",localInstanceId,numCycles);
 }
The following text will be displayed for the event:
  CPU Load for myFunction (instanceId = 0x1234): NumCycles=1234
C SYNOPSIS
 
config UIAStatistic.freeBytes  // module-wide

Number of free bytes in heap

XDCscript usage meta-domain
UIAStatistic.freeBytes = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "Heap at %$F (HeapId 0x%x): Free Bytes=%d"
};
 
VALUES
__FILE__ — constant string identifying the file the event was logged from
__LINE__ — the line number the event was logged from
heapId — heap identifier (e.g IHeap_Handle)
freeBytes — the number of bytes free on the heap
EXAMPLE
The following C code shows how to log a freeBytes event that tracks the number of bytes free in the heap
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAStatistic.h>
  ...
 Void myFunction(){
   int heapId = 0x1234;    // change to heap ID
   int numBytesFree = 567; // change to number of bytes free on the heap

   Log_write4(UIAStatistic_freeBytes, (IArg)__FILE__,(IArg)__LINE__,heapId,numFreeBytes);
 }
The following text will be displayed for the event:
  Heap at Line 123 in demo.c (HeapId 0x1234): Free Bytes=567
C SYNOPSIS
 
config UIAStatistic.wordsProcessed  // module-wide

wordsProcessed statistic event

XDCscript usage meta-domain
UIAStatistic.wordsProcessed = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "Words Processed by %s: NumWords=0x%x"
};
 
VALUES
name — a constant string that provides the name of the entity that is processing the data
numWords — the number of words processed
DETAILS
number of words that were processed.
C SYNOPSIS
 
config UIAStatistic.wordsProcessedByInstance  // module-wide

wordsProcessedByInstance statistic event

XDCscript usage meta-domain
UIAStatistic.wordsProcessedByInstance = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "Words Processed at %$F (InstanceId 0x%x): Num Words=%d"
};
 
VALUES
__FILE__ — constant string identifying the file the event was logged from
__LINE__ — the line number the event was logged from
instanceId — the instance ID (e.g. thread handle) of the entity that is processing the data
numWords — the number of words processed
DETAILS
Number of words that were processed along with filename, line number and instance ID.
EXAMPLE
The following C code shows how to log an event that tracks the number of words processed
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAStatistic.h>
  ...
 Void myFunction(){
   int instanceId = 0x1234;  // change to e.g. a TaskId or some other unique ID
   int numWords= 567;        // change to number of words actually processed

   Log_write4(UIAStatistic_wordsProcessedByInstance, (IArg)__FILE__,(IArg)__LINE__,instanceId,numWords);
 }
The following text will be displayed for the event:
  Words Processed at Line 123 in demo.c (InstanceId 0x1234): Num Words=567
C SYNOPSIS
 
metaonly config UIAStatistic.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
UIAStatistic.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