module ti.uia.events.UIAEvt
index URL

UIA Standard Events

The UIAEvt module defines events that allow tooling to display event information and filter events based on their priority. [ more ... ]
C synopsis target-domain sourced in ti/uia/events/UIAEvt.xdc
#include <ti/uia/events/UIAEvt.h>
Functions common to all target modules
UIAEvt_Module_getMask// Returns the diagnostics mask for this module, UIAEvt_Module_hasMask// Test whether this module has a diagnostics mask, UIAEvt_Module_heap// The heap from which this module allocates memory, UIAEvt_Module_id// Get this module's unique id, UIAEvt_Module_setMask// Set the diagnostics mask for this module, UIAEvt_Module_startupDone// Test if this module has completed startup
Constants
extern const Log_Event 
UIAEvt_detail// Event to use to log a Detail-level Event Code;
extern const Log_Event 
UIAEvt_detailWithStr// Event to use to log a Detail-level Event Code and fmt string;
extern const Log_Event 
UIAEvt_info// Event to use to log an Informational Event Code;
extern const Log_Event 
UIAEvt_infoWithStr// Event to use to log a Informational Event Code and format string;
extern const Log_Event 
UIAEvt_intWithKey// Event to use to log values to be analyzed as Statistics and / or Graphs;
extern const Log_Event 
UIAEvt_warning// Event to use to log a Warning Event Code;
extern const Log_Event 
UIAEvt_warningWithStr// Event to use to log a Warning Event Code and fmt string;
 
DETAILS
The UIAEvt module defines events that allow tooling to display event information and filter events based on their priority.
The events in this module have one of the following event priority levels: WARNING: used to indicate an unexpected or problematic situation such as when a resource becomes dangerously low INFO: used to indicate something of interest or of use in understanding the current state of the system or behaviour of the software DETAIL: used to indicate additional information that may be of interest in troubleshooting problems or improving the software
For each priority level, two predefined event codes are provided: one for logging a single event code, and one for logging an event code along with a reference to a constant formatting string that can be used to format the text displayed for the event. The formatting string allows additional arguments to be displayed along with the event code when the event is rendered as text (e.g. by DVT).
The following special formatting specifiers may be used in the msg field of an event's config specification:
%$S - a string parameter that can provide additional formatting specifiers Note that $S use in strings passed in as a paramter is not supported.
%$F - a specifier for a string parameter containing the file name (__FILE__) and an integer parameter containing the line number (__LINE__).
The generation of UIAEvt events is controlled by a module's diagnostics mask, which is described in details in xdc.runtime.Diags. UIAEvt warning events are generated only when the Diags.STATUS bit is set in the module's diagnostics mask. The Diags.STATUS bit is set to ALWAYS_ON by default. 'UIAEvt' info and detail events are generated only when the Diags.INFO bit is set in the module's diagnostics mask.
The following configuration script demonstrates how to enable use of UIAEvt events within an application. Since the Diags.STATUS bits are set to ALWAYS_ON by default, no explicit code is required to enable the Diags Masks for these events. The Diags.INFO bitmust be explicitly set in order to enable info and detail level events.
This is part of the XDC configuration file for the application:
  var UIAEvt = xdc.useModule('ti.uia.events.UIAEvt');
  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$.logger = logger;
  Defaults.common$.diags_INFO = Diags.ALWAYS_ON;
Example 2: The following example configures a module to support logging of STATUS events and INFO 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 UIAEvt = xdc.useModule('ti.uia.events.UIAEvt');
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Mod = xdc.useModule('my.pkg.Mod');

  Mod.common$.diags_STATUS = Diags.RUNTIME_OFF;
  Mod.common$.diags_INFO = Diags.RUNTIME_OFF;
This is a part of the C code for the application:
  // turn on logging of STATUS events (S) and INFO events (F)
  // in the module
  Diags_setMask("my.pkg.Mod+SF");

  // turn off logging of STATUS events and INFO events in the module
  Diags_setMask("my.pkg.Mod-SF");
 
config UIAEvt_detail  // module-wide
index URL

Event to use to log a Detail-level Event Code

C synopsis target-domain
extern const Log_Event UIAEvt_detail;
 
VALUES
eventCode — integer that identifies the specific detail event being logged
EXAMPLE
The following C code shows how to log a detail-level event code as a UIA event.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAEvt.h>
  ...
  Int myEventCode = 0xE1;
  ...
  Log_write1(UIAEvt_detail, myEventCode);
  ...
The following text is an example of what will be displayed for the event:
  "DETAIL: EventCode:0xE1."
SEE
detailWithStr
 
config UIAEvt_detailWithStr  // module-wide
index URL

Event to use to log a Detail-level Event Code and fmt string

C synopsis target-domain
extern const Log_Event UIAEvt_detailWithStr;
 
VALUES
eventCode — integer that identifies the specific detail event being logged
fmt — a constant string that provides format specifiers for up to 6 additional parameters
EXAMPLE
The following C code shows how to log a detail-level event code and format string as a UIA event. It also shows how additional parameters can be logged along with the event and format string.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAEvt.h>
  ...
  Int myEventCode = 0xE1;
  Int anAdditionalParam = 0x6543;
  ...
  Log_write3(UIAEvt_detailWithStr, myEventCode,(IArg)"Descriptive text. anAdditionalParam=0x%x.",anAdditionalParam);
  ...
The following text is an example of what will be displayed for the event:
  "DETAIL: EventCode:0xE1. Some descriptive text.  anAdditionalParam=0x6543."
SEE
detail
 
config UIAEvt_info  // module-wide
index URL

Event to use to log an Informational Event Code

C synopsis target-domain
extern const Log_Event UIAEvt_info;
 
VALUES
eventCode — integer that identifies the type of info event
EXAMPLE
The following C code shows how to log an informational event code as a UIA event.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAEvt.h>
  ...
  Int myInfoCode = 0xC0DE;
  ...
  Log_write1(UIAEvt_info, myInfoCode);
  ...
The following text is an example of what will be displayed for the event:
  "INFO: EventCode:0xC0DE."
SEE
infoWithStr
 
config UIAEvt_infoWithStr  // module-wide
index URL

Event to use to log a Informational Event Code and format string

C synopsis target-domain
extern const Log_Event UIAEvt_infoWithStr;
 
VALUES
eventCode — integer that identifies the specific info event being logged
fmt — a constant string that provides format specifiers for up to 6 additional parameters
EXAMPLE
The following C code shows how to log an informational event code and format string as a UIA event. It also shows how additional parameters can be logged along with the event and format string.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAEvt.h>
  ...
  Int myInfoCode = 0xC0DE;
  Int anAdditionalParam = 0x6543;
  ...
  Log_write3(UIAEvt_infoWithStr, myInfoCode,(IArg)"Descriptive text. anAdditionalParam=0x%x.",anAdditionalParam);
  ...
The following text is an example of what will be displayed for the event:
  "INFO: EventCode:0xC0DE. Some descriptive text.  anAdditionalParam=0x6543."
SEE
info
 
config UIAEvt_intWithKey  // module-wide
index URL

Event to use to log values to be analyzed as Statistics and / or Graphs

C synopsis target-domain
extern const Log_Event UIAEvt_intWithKey;
 
VALUES
value — integer value that is to be analyzed
auxData1 — auxiliary data that is to be displayed along with the event (use 0 if none)
auxData2 — auxiliary data that is to be displayed along with the event (use 0 if none)
key — a constant string that provides format specifiers for up to 4 key entries
EXAMPLE
Example 1: The following C code shows how to log an intWithKey event code that logs a value, a format string that defines the key, and parameters for use within the key format string.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAEvt.h>
  ...
  Int myValue = 1001;
  Int myInstanceId = 0x6543;
  ...
  Log_write5(UIAEvt_intWithKey, myValue,0,0,(IArg)"InstanceId=0x%x.",myInstanceId);
  ...
The following text is an example of what will be displayed for the event:
  "VALUE=1001 (AuxData=0,0) Key: InstanceId=0x6543."
Example 2: The following C code shows how to log an intWithKey event code that logs a value, a format string that defines the key, and parameters for use within the key format string, including the file name and line of code that the event was logged at. This example uses a special format specifier, %$F, which is used to format two parameters (__FILE__ and __LINE__) in a way that tools will be able to display the line of code that the event was logged from in a source code editor when the user clicks on the event.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAEvt.h>
  ...
  Int myValue = 1001;
  Int myInstanceId = 9876;
  ...
  Log_write7(UIAEvt_intWithKey, myValue,0,0,(IArg)"InstanceId=%d, at %$F.",
                    myInstanceId,(IArg)__FILE__,(IArg)__LINE__);
  ...
  // If you wish to log only the line number as a key, use the following:
  Log_write6(UIAEvt_intWithKey, myValue+1,0,0,(IArg)"InstanceId=%d, at line %d.",
                    myInstanceId,(IArg)__LINE__);
  ...
  // If you wish to log only the file name as a key and the line number
  // as auxiliary data which is logged along with the event, use the following:
  Log_write6(UIAEvt_intWithKey, myValue+2,(IArg)__LINE__,0,(IArg)"InstanceId=%d, in file [%s].",
                    myInstanceId,(IArg)__FILE__);
The following text is an example of what will be displayed for the event, assuming it was logged from a file named demo.c at line 1234:
  "VALUE=1001 (AuxData=0,0) Key: InstanceId=9876, at [../demo.c:1234] ."
  "VALUE=1002 (AuxData=0,0) Key: InstanceId=9876, at line 1234."
  "VALUE=1003 (AuxData=1234,0) Key: InstanceId=9876, in file [../demo.c]."
 
config UIAEvt_warning  // module-wide
index URL

Event to use to log a Warning Event Code

C synopsis target-domain
extern const Log_Event UIAEvt_warning;
 
VALUES
eventCode — integer that identifies the type of warning
fmt — a constant string that provides format specifiers for up to 6 additional parameters
EXAMPLE
The following C code shows how to log a legacy warning code as a UIA event.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAEvt.h>
  ...
  Int myWarningCode = 0xBAD;
  ...
  Log_write1(UIAEvt_warning, myWarningCode);
  ...
The following text is an example of what will be displayed for the event:
  "WARNING: EventCode:0xBAD."
SEE
warningWithStr
 
config UIAEvt_warningWithStr  // module-wide
index URL

Event to use to log a Warning Event Code and fmt string

C synopsis target-domain
extern const Log_Event UIAEvt_warningWithStr;
 
VALUES
eventCode — integer that identifies the type of warning event
fmt — a constant string that provides format specifiers for up to 6 additional parameters
EXAMPLE
The following C code shows how to log a legacy warning code and string as a UIA event.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAEvt.h>
  ...
  Int myWarningCode = 0xBAD;
  String myWarningStr = "Legacy Warning String for warning 0xBAD";
  ...
  Log_write2(UIAEvt_warning,myWarningCode,(IArg)myWarningStr);
  ...
The following text is an example of what will be displayed for the event:
  "WARNING: EventCode:0xBAD. Legacy Warning String for warning 0xBAD"
SEE
warning
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId UIAEvt_Module_id();
// Get this module's unique id
 
Bool UIAEvt_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle UIAEvt_Module_heap();
// The heap from which this module allocates memory
 
Bool UIAEvt_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 UIAEvt_Module_getMask();
// Returns the diagnostics mask for this module
 
Void UIAEvt_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
XDCscript usage meta-domain sourced in ti/uia/events/UIAEvt.xdc
var UIAEvt = xdc.useModule('ti.uia.events.UIAEvt');
module-wide config parameters
    UIAEvt.detail// Event to use to log a Detail-level Event Code = Log.EventDesc {
        mask: Diags.INFO,
        level: Diags.LEVEL4,
        msg: "DETAIL: EventCode:0x%x"
    };
    UIAEvt.detailWithStr// Event to use to log a Detail-level Event Code and fmt string = Log.EventDesc {
        mask: Diags.INFO,
        level: Diags.LEVEL4,
        msg: "DETAIL: EventCode:0x%x. %$S"
    };
    UIAEvt.info// Event to use to log an Informational Event Code = Log.EventDesc {
        mask: Diags.INFO,
        msg: "INFO: EventCode: 0x%x"
    };
    UIAEvt.infoWithStr// Event to use to log a Informational Event Code and format string = Log.EventDesc {
        mask: Diags.INFO,
        msg: "INFO: EventCode:0x%x. %$S"
    };
    UIAEvt.intWithKey// Event to use to log values to be analyzed as Statistics and / or Graphs = Log.EventDesc {
        mask: Diags.ANALYSIS,
        msg: "VALUE=%d (AuxData=%d, %d) Key:%$S"
    };
    UIAEvt.warning// Event to use to log a Warning Event Code = Log.EventDesc {
        mask: Diags.STATUS,
        level: Diags.WARNING,
        msg: "WARNING: EventCode:0x%x"
    };
    UIAEvt.warningWithStr// Event to use to log a Warning Event Code and fmt string = Log.EventDesc {
        mask: Diags.STATUS,
        level: Diags.WARNING,
        msg: "WARNING: EventCode:0x%x. %$S"
    };
 
    UIAEvt.common$// Common module configuration parameters = Types.Common$ undefined;
 
 
config UIAEvt.detail  // module-wide
index URL

Event to use to log a Detail-level Event Code

XDCscript usage meta-domain
UIAEvt.detail = Log.EventDesc {
    mask: Diags.INFO,
    level: Diags.LEVEL4,
    msg: "DETAIL: EventCode:0x%x"
};
 
VALUES
eventCode — integer that identifies the specific detail event being logged
EXAMPLE
The following C code shows how to log a detail-level event code as a UIA event.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAEvt.h>
  ...
  Int myEventCode = 0xE1;
  ...
  Log_write1(UIAEvt_detail, myEventCode);
  ...
The following text is an example of what will be displayed for the event:
  "DETAIL: EventCode:0xE1."
SEE
detailWithStr
C SYNOPSIS
UIAEvt_detail
 
config UIAEvt.detailWithStr  // module-wide
index URL

Event to use to log a Detail-level Event Code and fmt string

XDCscript usage meta-domain
UIAEvt.detailWithStr = Log.EventDesc {
    mask: Diags.INFO,
    level: Diags.LEVEL4,
    msg: "DETAIL: EventCode:0x%x. %$S"
};
 
VALUES
eventCode — integer that identifies the specific detail event being logged
fmt — a constant string that provides format specifiers for up to 6 additional parameters
EXAMPLE
The following C code shows how to log a detail-level event code and format string as a UIA event. It also shows how additional parameters can be logged along with the event and format string.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAEvt.h>
  ...
  Int myEventCode = 0xE1;
  Int anAdditionalParam = 0x6543;
  ...
  Log_write3(UIAEvt_detailWithStr, myEventCode,(IArg)"Descriptive text. anAdditionalParam=0x%x.",anAdditionalParam);
  ...
The following text is an example of what will be displayed for the event:
  "DETAIL: EventCode:0xE1. Some descriptive text.  anAdditionalParam=0x6543."
SEE
detail
C SYNOPSIS
UIAEvt_detailWithStr
 
config UIAEvt.info  // module-wide
index URL

Event to use to log an Informational Event Code

XDCscript usage meta-domain
UIAEvt.info = Log.EventDesc {
    mask: Diags.INFO,
    msg: "INFO: EventCode: 0x%x"
};
 
VALUES
eventCode — integer that identifies the type of info event
EXAMPLE
The following C code shows how to log an informational event code as a UIA event.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAEvt.h>
  ...
  Int myInfoCode = 0xC0DE;
  ...
  Log_write1(UIAEvt_info, myInfoCode);
  ...
The following text is an example of what will be displayed for the event:
  "INFO: EventCode:0xC0DE."
SEE
infoWithStr
C SYNOPSIS
UIAEvt_info
 
config UIAEvt.infoWithStr  // module-wide
index URL

Event to use to log a Informational Event Code and format string

XDCscript usage meta-domain
UIAEvt.infoWithStr = Log.EventDesc {
    mask: Diags.INFO,
    msg: "INFO: EventCode:0x%x. %$S"
};
 
VALUES
eventCode — integer that identifies the specific info event being logged
fmt — a constant string that provides format specifiers for up to 6 additional parameters
EXAMPLE
The following C code shows how to log an informational event code and format string as a UIA event. It also shows how additional parameters can be logged along with the event and format string.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAEvt.h>
  ...
  Int myInfoCode = 0xC0DE;
  Int anAdditionalParam = 0x6543;
  ...
  Log_write3(UIAEvt_infoWithStr, myInfoCode,(IArg)"Descriptive text. anAdditionalParam=0x%x.",anAdditionalParam);
  ...
The following text is an example of what will be displayed for the event:
  "INFO: EventCode:0xC0DE. Some descriptive text.  anAdditionalParam=0x6543."
SEE
info
C SYNOPSIS
UIAEvt_infoWithStr
 
config UIAEvt.intWithKey  // module-wide
index URL

Event to use to log values to be analyzed as Statistics and / or Graphs

XDCscript usage meta-domain
UIAEvt.intWithKey = Log.EventDesc {
    mask: Diags.ANALYSIS,
    msg: "VALUE=%d (AuxData=%d, %d) Key:%$S"
};
 
VALUES
value — integer value that is to be analyzed
auxData1 — auxiliary data that is to be displayed along with the event (use 0 if none)
auxData2 — auxiliary data that is to be displayed along with the event (use 0 if none)
key — a constant string that provides format specifiers for up to 4 key entries
EXAMPLE
Example 1: The following C code shows how to log an intWithKey event code that logs a value, a format string that defines the key, and parameters for use within the key format string.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAEvt.h>
  ...
  Int myValue = 1001;
  Int myInstanceId = 0x6543;
  ...
  Log_write5(UIAEvt_intWithKey, myValue,0,0,(IArg)"InstanceId=0x%x.",myInstanceId);
  ...
The following text is an example of what will be displayed for the event:
  "VALUE=1001 (AuxData=0,0) Key: InstanceId=0x6543."
Example 2: The following C code shows how to log an intWithKey event code that logs a value, a format string that defines the key, and parameters for use within the key format string, including the file name and line of code that the event was logged at. This example uses a special format specifier, %$F, which is used to format two parameters (__FILE__ and __LINE__) in a way that tools will be able to display the line of code that the event was logged from in a source code editor when the user clicks on the event.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAEvt.h>
  ...
  Int myValue = 1001;
  Int myInstanceId = 9876;
  ...
  Log_write7(UIAEvt_intWithKey, myValue,0,0,(IArg)"InstanceId=%d, at %$F.",
                    myInstanceId,(IArg)__FILE__,(IArg)__LINE__);
  ...
  // If you wish to log only the line number as a key, use the following:
  Log_write6(UIAEvt_intWithKey, myValue+1,0,0,(IArg)"InstanceId=%d, at line %d.",
                    myInstanceId,(IArg)__LINE__);
  ...
  // If you wish to log only the file name as a key and the line number
  // as auxiliary data which is logged along with the event, use the following:
  Log_write6(UIAEvt_intWithKey, myValue+2,(IArg)__LINE__,0,(IArg)"InstanceId=%d, in file [%s].",
                    myInstanceId,(IArg)__FILE__);
The following text is an example of what will be displayed for the event, assuming it was logged from a file named demo.c at line 1234:
  "VALUE=1001 (AuxData=0,0) Key: InstanceId=9876, at [../demo.c:1234] ."
  "VALUE=1002 (AuxData=0,0) Key: InstanceId=9876, at line 1234."
  "VALUE=1003 (AuxData=1234,0) Key: InstanceId=9876, in file [../demo.c]."
C SYNOPSIS
UIAEvt_intWithKey
 
config UIAEvt.warning  // module-wide
index URL

Event to use to log a Warning Event Code

XDCscript usage meta-domain
UIAEvt.warning = Log.EventDesc {
    mask: Diags.STATUS,
    level: Diags.WARNING,
    msg: "WARNING: EventCode:0x%x"
};
 
VALUES
eventCode — integer that identifies the type of warning
fmt — a constant string that provides format specifiers for up to 6 additional parameters
EXAMPLE
The following C code shows how to log a legacy warning code as a UIA event.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAEvt.h>
  ...
  Int myWarningCode = 0xBAD;
  ...
  Log_write1(UIAEvt_warning, myWarningCode);
  ...
The following text is an example of what will be displayed for the event:
  "WARNING: EventCode:0xBAD."
SEE
warningWithStr
C SYNOPSIS
UIAEvt_warning
 
config UIAEvt.warningWithStr  // module-wide
index URL

Event to use to log a Warning Event Code and fmt string

XDCscript usage meta-domain
UIAEvt.warningWithStr = Log.EventDesc {
    mask: Diags.STATUS,
    level: Diags.WARNING,
    msg: "WARNING: EventCode:0x%x. %$S"
};
 
VALUES
eventCode — integer that identifies the type of warning event
fmt — a constant string that provides format specifiers for up to 6 additional parameters
EXAMPLE
The following C code shows how to log a legacy warning code and string as a UIA event.
  #include <xdc/runtime/Log.h>
  #include <ti/uia/events/UIAEvt.h>
  ...
  Int myWarningCode = 0xBAD;
  String myWarningStr = "Legacy Warning String for warning 0xBAD";
  ...
  Log_write2(UIAEvt_warning,myWarningCode,(IArg)myWarningStr);
  ...
The following text is an example of what will be displayed for the event:
  "WARNING: EventCode:0xBAD. Legacy Warning String for warning 0xBAD"
SEE
warning
C SYNOPSIS
UIAEvt_warningWithStr
 
metaonly config UIAEvt.common$  // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
UIAEvt.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 Thu, 14 Mar 2013 17:50:47 GMT