module ti.uia.events.UIAProfile

UIA Profile Events

The UIAProfile module defines events that allow tooling to analyze the performance of the software (processing time, latency, etc.). These events are designed to be logged from function-entry and function-exit hook functions that are called by compiler-generated code [ more ... ]
C synopsis target-domain sourced in ti/uia/events/UIAProfile.xdc
DETAILS
The UIAProfile module defines events that allow tooling to analyze the performance of the software (processing time, latency, etc.). These events are designed to be logged from function-entry and function-exit hook functions that are called by compiler-generated code
TI compilers can be configured to either pass in a parameter to the hook functions containing either the address of the function or the name of the function.
If the compiler is configured to pass in the address of the function, the UIAProfile_enterFunctionAdrs event should be logged by the entry hook function and the UIAProfile_exitFunctionAdrs event should be logged by the exit hook function.
If the compiler is configured to pass in the name of the function, the UIAProfile_enterFunctionName event should be logged by the entry hook function and the UIAProfile_exitFunctionName event should be logged by the exit hook function.
When logging events using the xdc.runtime.Log module, the generation of UIAProfile events is controlled by the Diags.ENTRY and Diags.EXIT flags in a module's diagnostics mask. (For more information on diagnostics masks, please see the xdc.runtime.Diags documentation.)
By default, the UIAProfile module will automatically set both the Main.common$.Diags_ENTRY and Main.common$.Diags_EXIT flags to Diags.ALWAYS_ON if these flags have not been previously configured. To turn off these flags at configuration time, set UIAProfile.enable = false; To allow these flags to be configured at run time, set UIAProfile.runtimeControl = true;
EXAMPLES
Example 1: This is part of the XDC configuration file for the application:
  var UIAProfile = xdc.useModule('ti.uia.events.UIAProfile');
  var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');

Example 2: The following example configures a module to support logging of ENTRY and EXIT 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 UIAProfile = xdc.useModule('ti.uia.events.UIAProfile');
  UIAProfile.runtimeControl = true;
  UIAProfile.enable = false;
This is a part of the C code for the application. The diags_ENTRY mask is set by "E", and the diags_EXIT mask is set by "X".
  #include <xdc/runtime/Diags.h>
  #include <xdc/runtime/Main.h>

  // turn on logging of ENTRY and EXIT events in the module
  Diags_setMask("xdc.runtime.Main+EX");

  // turn off logging of ENTRY and EXIT events in the module
  Diags_setMask("xdc.runtime.Main-EX");
 
config UIAProfile_enterFunctionAdrs  // module-wide

Profiling event used to log the entry point of a function

C synopsis target-domain
extern const Log_Event UIAProfile_enterFunctionAdrs;
 
VALUES
taskHandle — task handle that identifies the currently active task (use 0 if not required)
functionAdrs — the address of a function that can differentiate this pair of start and stop events from others
EXAMPLE
To add entry and exit hook functions to every function 1. Use the following compiler options when compiling the source
  --entry_hook=functionEntryHook
  --entry_param=address
  --exit_hook=functionExitHook
  --exit_param=address
2. Add the following c code to implement the hook functions: The first parameter (the taskHandle) is set to 0 in this example.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAProfile.h>
  ...
 void functionEntryHook(void (*adrs)()){
    Log_write2(UIAProfile_enterFunctionAdrs, 0,(IArg)adrs);
   ...
 void functionExitHook( void (*adrs)() ){
    Log_write2(UIAProfile_exitFunctionAdrs, 0,(IArg)adrs);
 }
The following text will be displayed for the event:
  enterFunctionAdrs: taskHandle=0x0, adrs=0x820060
  exitFunctionAdrs: taskHandle0x0, adrs=0x820060
SEE
 
config UIAProfile_enterFunctionName  // module-wide

Profiling event used to log the entry point of a function

C synopsis target-domain
extern const Log_Event UIAProfile_enterFunctionName;
 
VALUES
taskHandle — task handle that identifies the currently active task (use 0 if not required)
functionName — the (const char*) name of the function that is passed to the hook fn by the compiler
EXAMPLE
To add entry and exit hook functions to every function 1. Use the following compiler options when compiling the source
  --entry_hook=functionEntryHook
  --entry_param=name
  --exit_hook=functionExitHook
  --exit_param=name
2. Add the following c code to implement the hook functions: The first parameter (the taskHandle) is set to 0 in this example.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAProfile.h>
  ...
 void functionEntryHook(const char* name){
    Log_write2(UIAProfile_enterFunctionName, 0,(IArg)name);
   ...
 void functionExitHook(const char* name){
    Log_write2(UIAProfile_exitFunctionName, 0,(IArg)name);
 }
The following text will be displayed for the event:
  enterFunctionName: taskHandle=0x0, name=myFunctionName
  exitFunctionName: taskHandle0x0, name=myFunctionName
SEE
 
config UIAProfile_exitFunctionAdrs  // module-wide

Profiling event used to log the exit point of a function

C synopsis target-domain
extern const Log_Event UIAProfile_exitFunctionAdrs;
 
VALUES
taskHandle — task handle that identifies the currently active task (use 0 if not required)
functionAdrs — the address of a function that can differentiate this pair of start and stop events from others
EXAMPLE
To add entry and exit hook functions to every function 1. Use the following compiler options when compiling the source
  --entry_hook=functionEntryHook
  --entry_param=address
  --exit_hook=functionExitHook
  --exit_param=address
2. Add the following c code to implement the hook functions: Task_selfMacro() is used to get the current task handle in this example.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAProfile.h>
  #include <ti/sysbios/knl/Task.h>
  ...
 void functionEntryHook(void (*adrs)()){
    Log_write2(UIAProfile_enterFunctionAdrs, (IArg)Task_selfMacro(),(IArg)addr);
   ...
 void functionExitHook( void (*adrs)() ){
    Log_write2(UIAProfile_exitFunctionAdrs, (IArg)Task_selfMacro(),(IArg)addr);
 }
The following text will be displayed for the event:
  enterFunctionAdrs: taskHandle=0x0, adrs=0x820060
  exitFunctionAdrs: taskHandle=0x0, adrs=0x820060
SEE
 
config UIAProfile_exitFunctionName  // module-wide

Profiling event used to log the exit point of a function

C synopsis target-domain
extern const Log_Event UIAProfile_exitFunctionName;
 
VALUES
taskHandle — task handle that identifies the currently active task (use 0 if not required)
functionName — the (const char*) name of the function that is passed to the hook fn by the compiler
EXAMPLE
To add entry and exit hook functions to every function 1. Use the following compiler options when compiling the source
  --entry_hook=functionEntryHook
  --entry_param=name
  --exit_hook=functionExitHook
  --exit_param=name
2. Add the following c code to implement the hook functions: Task_selfMacro() is used to get the current task handle in this example.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAProfile.h>
  #include <ti/sysbios/knl/Task.h>
  ...
 void functionEntryHook(const char* name){
    Log_write2(UIAProfile_enterFunctionName, (IArg)Task_selfMacro(),(IArg)name);
   ...
 void functionExitHook(const char* name){
    Log_write2(UIAProfile_exitFunctionName, (IArg)Task_selfMacro(),(IArg)name);
 }
The following text will be displayed for the event:
  enterFunctionName: taskHandle=0x0, adrs=myFunctionName
  exitFunctionName: taskHandle=0x0, name=myFunctionName
SEE
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId UIAProfile_Module_id();
// Get this module's unique id
 
Bool UIAProfile_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle UIAProfile_Module_heap();
// The heap from which this module allocates memory
 
Bool UIAProfile_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 UIAProfile_Module_getMask();
// Returns the diagnostics mask for this module
 
Void UIAProfile_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
Configuration settings sourced in ti/uia/events/UIAProfile.xdc
var UIAProfile = xdc.useModule('ti.uia.events.UIAProfile');
module-wide config parameters
        mask: Diags.ENTRY,
        msg: "enterFunctionAdrs: taskHandle=0x%x, adrs=0x%x"
    };
        mask: Diags.ENTRY,
        msg: "enterFunctionName: taskHandle=0x%x, name=%s"
    };
        mask: Diags.EXIT,
        msg: "exitFunctionAdrs: taskHandle=0x%x, adrs=0x%x"
    };
        mask: Diags.EXIT,
        msg: "exitFunctionName: taskHandle=0x%x, name=%s"
    };
 
 
 
config UIAProfile.enterFunctionAdrs  // module-wide

Profiling event used to log the entry point of a function

Configuration settings
UIAProfile.enterFunctionAdrs = Log.EventDesc {
    mask: Diags.ENTRY,
    msg: "enterFunctionAdrs: taskHandle=0x%x, adrs=0x%x"
};
 
VALUES
taskHandle — task handle that identifies the currently active task (use 0 if not required)
functionAdrs — the address of a function that can differentiate this pair of start and stop events from others
EXAMPLE
To add entry and exit hook functions to every function 1. Use the following compiler options when compiling the source
  --entry_hook=functionEntryHook
  --entry_param=address
  --exit_hook=functionExitHook
  --exit_param=address
2. Add the following c code to implement the hook functions: The first parameter (the taskHandle) is set to 0 in this example.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAProfile.h>
  ...
 void functionEntryHook(void (*adrs)()){
    Log_write2(UIAProfile_enterFunctionAdrs, 0,(IArg)adrs);
   ...
 void functionExitHook( void (*adrs)() ){
    Log_write2(UIAProfile_exitFunctionAdrs, 0,(IArg)adrs);
 }
The following text will be displayed for the event:
  enterFunctionAdrs: taskHandle=0x0, adrs=0x820060
  exitFunctionAdrs: taskHandle0x0, adrs=0x820060
SEE
C SYNOPSIS
 
config UIAProfile.enterFunctionName  // module-wide

Profiling event used to log the entry point of a function

Configuration settings
UIAProfile.enterFunctionName = Log.EventDesc {
    mask: Diags.ENTRY,
    msg: "enterFunctionName: taskHandle=0x%x, name=%s"
};
 
VALUES
taskHandle — task handle that identifies the currently active task (use 0 if not required)
functionName — the (const char*) name of the function that is passed to the hook fn by the compiler
EXAMPLE
To add entry and exit hook functions to every function 1. Use the following compiler options when compiling the source
  --entry_hook=functionEntryHook
  --entry_param=name
  --exit_hook=functionExitHook
  --exit_param=name
2. Add the following c code to implement the hook functions: The first parameter (the taskHandle) is set to 0 in this example.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAProfile.h>
  ...
 void functionEntryHook(const char* name){
    Log_write2(UIAProfile_enterFunctionName, 0,(IArg)name);
   ...
 void functionExitHook(const char* name){
    Log_write2(UIAProfile_exitFunctionName, 0,(IArg)name);
 }
The following text will be displayed for the event:
  enterFunctionName: taskHandle=0x0, name=myFunctionName
  exitFunctionName: taskHandle0x0, name=myFunctionName
SEE
C SYNOPSIS
 
config UIAProfile.exitFunctionAdrs  // module-wide

Profiling event used to log the exit point of a function

Configuration settings
UIAProfile.exitFunctionAdrs = Log.EventDesc {
    mask: Diags.EXIT,
    msg: "exitFunctionAdrs: taskHandle=0x%x, adrs=0x%x"
};
 
VALUES
taskHandle — task handle that identifies the currently active task (use 0 if not required)
functionAdrs — the address of a function that can differentiate this pair of start and stop events from others
EXAMPLE
To add entry and exit hook functions to every function 1. Use the following compiler options when compiling the source
  --entry_hook=functionEntryHook
  --entry_param=address
  --exit_hook=functionExitHook
  --exit_param=address
2. Add the following c code to implement the hook functions: Task_selfMacro() is used to get the current task handle in this example.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAProfile.h>
  #include <ti/sysbios/knl/Task.h>
  ...
 void functionEntryHook(void (*adrs)()){
    Log_write2(UIAProfile_enterFunctionAdrs, (IArg)Task_selfMacro(),(IArg)addr);
   ...
 void functionExitHook( void (*adrs)() ){
    Log_write2(UIAProfile_exitFunctionAdrs, (IArg)Task_selfMacro(),(IArg)addr);
 }
The following text will be displayed for the event:
  enterFunctionAdrs: taskHandle=0x0, adrs=0x820060
  exitFunctionAdrs: taskHandle=0x0, adrs=0x820060
SEE
C SYNOPSIS
 
config UIAProfile.exitFunctionName  // module-wide

Profiling event used to log the exit point of a function

Configuration settings
UIAProfile.exitFunctionName = Log.EventDesc {
    mask: Diags.EXIT,
    msg: "exitFunctionName: taskHandle=0x%x, name=%s"
};
 
VALUES
taskHandle — task handle that identifies the currently active task (use 0 if not required)
functionName — the (const char*) name of the function that is passed to the hook fn by the compiler
EXAMPLE
To add entry and exit hook functions to every function 1. Use the following compiler options when compiling the source
  --entry_hook=functionEntryHook
  --entry_param=name
  --exit_hook=functionExitHook
  --exit_param=name
2. Add the following c code to implement the hook functions: Task_selfMacro() is used to get the current task handle in this example.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAProfile.h>
  #include <ti/sysbios/knl/Task.h>
  ...
 void functionEntryHook(const char* name){
    Log_write2(UIAProfile_enterFunctionName, (IArg)Task_selfMacro(),(IArg)name);
   ...
 void functionExitHook(const char* name){
    Log_write2(UIAProfile_exitFunctionName, (IArg)Task_selfMacro(),(IArg)name);
 }
The following text will be displayed for the event:
  enterFunctionName: taskHandle=0x0, adrs=myFunctionName
  exitFunctionName: taskHandle=0x0, name=myFunctionName
SEE
C SYNOPSIS
 
metaonly config UIAProfile.common$  // module-wide

Common module configuration parameters

Configuration settings
UIAProfile.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.
 
metaonly config UIAProfile.enable  // module-wide

Specify whether profile events are enabled or disabled (set to true by default)

Configuration settings
UIAProfile.enable = Bool true;
 
DETAILS
if the UIAProfile enable config property is true (default): If runtimeControl = 'false' the diags bits will be configured as ALWAYS_ON, meaning they can't be changed at runtime. If runtimeControl = 'true', the bits will be configured as 'RUNTIME_ON'.
if the UIAProfile enable config property is false: If runtimeControl = 'false' the diags bits will be configured as ALWAYS_OFF, meaning they can't be changed at runtime. If runtimeControl = 'true', the bits will be configured as 'RUNTIME_OFF'.
 
metaonly config UIAProfile.isContextAwareProfilingEnabled  // module-wide

Specify whether the task context that the function is executing within is logged or not Set to false if not using Sys/BIOS or to reduce CPU overhead

Configuration settings
UIAProfile.isContextAwareProfilingEnabled = Bool true;
 
 
metaonly config UIAProfile.runtimeControl  // module-wide

Specify whether profile events can be enabled / disabled at runtime. (set to false by default)

Configuration settings
UIAProfile.runtimeControl = Bool false;
 
DETAILS
This determines what diags settings are applied to the module's diags mask. if the UIAProfile enable config property is true (default): If runtimeControl = 'false' the diags bits will be configured as ALWAYS_ON, meaning they can't be changed at runtime. If runtimeControl = 'true', the bits will be configured as 'RUNTIME_ON'.
if the UIAProfile enable config property is false: If runtimeControl = 'false' the diags bits will be configured as ALWAYS_OFF, meaning they can't be changed at runtime. If runtimeControl = 'true', the bits will be configured as 'RUNTIME_OFF'.
generated on Tue, 14 Feb 2017 00:15:09 GMT