1    /*
     2     * Copyright (c) 2012, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    
    33    /*
    34     * ======== UIAEvt.xdc ========
    35     */
    36    import xdc.runtime.Diags;
    37    
    38    /*!
    39     * UIA Standard Events
    40     * @p
    41     * The UIAEvt module defines events that allow
    42     * tooling to display event information
    43     * and filter events based on their priority.
    44     * @p
    45     * The events in this module have one of the following event priority levels:
    46     *  WARNING: used to indicate an unexpected or problematic situation such as when a resource
    47     *  becomes dangerously low
    48     *  INFO: used to indicate something of interest or of use in understanding the
    49     *  current state of the system or behaviour of the software
    50     *  DETAIL: used to indicate additional information that may be of interest
    51     *  in troubleshooting problems or improving the software
    52     *@p
    53     * For each priority level, two predefined event codes
    54     * are provided: one for logging a single event code,
    55     * and one for logging an event code along with a
    56     * reference to a constant formatting string that can
    57     * be used to format the text displayed for the event.
    58     * The formatting string allows additional arguments
    59     * to be displayed along with the event code when the
    60     * event is rendered as text (e.g. by DVT).
    61     *@p
    62     * The following special formatting specifiers may be used in the
    63     * msg field of an event's config specification:
    64     * @p
    65     * %$S - a string parameter that can provide additional formatting specifiers
    66     *       Note that $S use in strings passed in as a paramter is not supported.
    67     *@p
    68     * %$F - a specifier for a string parameter containing the file name (__FILE__) and
    69     *       an integer parameter containing the line number (__LINE__).
    70     *@p
    71     *  The generation of UIAEvt events is controlled by a module's diagnostics
    72     *  mask, which is described in details in `{@link xdc.runtime.Diags}`.
    73     * `UIAEvt` warning events are generated only when the Diags.STATUS bit is set
    74     *  in the module's diagnostics mask.  The Diags.STATUS bit is set to ALWAYS_ON
    75     *  by default.  'UIAEvt' info and detail events are generated only when the
    76     *  Diags.INFO bit is set in the module's diagnostics mask.
    77     *
    78     *  The following configuration script demonstrates how to enable use of
    79     *  UIAEvt events within an application.  Since the Diags.STATUS bits are set
    80     *  to ALWAYS_ON by default, no explicit code is required to enable the
    81     *  Diags Masks for these events.  The Diags.INFO bitmust be explicitly set
    82     *  in order to enable info and detail level events.
    83     *
    84     *  This is part of the XDC configuration file for the application:
    85     *
    86     *  @p(code)
    87     *  var UIAEvt = xdc.useModule('ti.uia.events.UIAEvt');
    88     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    89     *  var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
    90     *  var Defaults = xdc.useModule('xdc.runtime.Defaults');
    91     *  var logger = LoggerSys.create();
    92     *
    93     *  Defaults.common$.logger = logger;
    94     *  Defaults.common$.diags_INFO = Diags.ALWAYS_ON;
    95     *  @p
    96     *
    97     *  @p(html)
    98     *  <hr />
    99     *  @p
   100     *
   101     *  Example 2: The following example configures a module to support logging
   102     *  of STATUS events and INFO events, but defers the actual activation and deactivation of the
   103     *  logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
   104     *  function for details on specifying the control string.
   105     *
   106     *  This is a part of the XDC configuration file for the application:
   107     *
   108     *  @p(code)
   109     *  var UIAEvt = xdc.useModule('ti.uia.events.UIAEvt');
   110     *  var Diags = xdc.useModule('xdc.runtime.Diags');
   111     *  var Mod = xdc.useModule('my.pkg.Mod');
   112     *
   113     *  Mod.common$.diags_STATUS = Diags.RUNTIME_OFF;
   114     *  Mod.common$.diags_INFO = Diags.RUNTIME_OFF;
   115     *  @p
   116     *
   117     *  This is a part of the C code for the application:
   118     *
   119     *  @p(code)
   120     *  // turn on logging of STATUS events (S) and INFO events (F)
   121     *  // in the module
   122     *  Diags_setMask("my.pkg.Mod+SF");
   123     *
   124     *  // turn off logging of STATUS events and INFO events in the module
   125     *  Diags_setMask("my.pkg.Mod-SF");
   126     *  @p
   127     */
   128     module UIAEvt inherits IUIAEvent {
   129    
   130        /*!
   131         *  ======== warning ========
   132         *  Event to use to log a Warning Event Code
   133         *
   134         *  @a(Example)
   135         *   The following C code shows how to log a legacy warning code as a UIA event.
   136         *
   137         *  @p(code)
   138         *  #include <xdc/runtime/Log.h>
   139         *  #include <ti/uia/events/UIAEvt.h>
   140         *  ...
   141         *  Int myWarningCode = 0xBAD;
   142         *  ...
   143         *  Log_write1(UIAEvt_warning, myWarningCode);
   144         *  ...
   145         *  @p
   146         *  The following text is an example of what will be displayed for the event:
   147         *  @p(code)
   148         *  "WARNING: EventCode:0xBAD."
   149         *  @p
   150         *  @param(eventCode)  integer that identifies the type of warning
   151         *  @param(fmt)        a constant string that provides format specifiers for up to 6 additional parameters
   152         *
   153         *  @see #warningWithStr
   154         */
   155        config xdc.runtime.Log.Event warning = {
   156                mask: Diags.STATUS,
   157                level: Diags.WARNING,
   158                msg: "WARNING: EventCode:0x%x"
   159        };
   160    
   161        /*!
   162         *  ======== warningWithStr ========
   163         *  Event to use to log a Warning Event Code and fmt string
   164         *
   165         *  @a(Example)
   166         *  The following C code shows how to log a legacy warning code and string as a UIA event.
   167         *  @p(code)
   168         *  #include <xdc/runtime/Log.h>
   169         *  #include <ti/uia/events/UIAEvt.h>
   170         *  ...
   171         *  Int myWarningCode = 0xBAD;
   172         *  String myWarningStr = "Legacy Warning String for warning 0xBAD";
   173         *  ...
   174         *  Log_write2(UIAEvt_warning,myWarningCode,(IArg)myWarningStr);
   175         *  ...
   176         *  @p
   177         *  The following text is an example of what will be displayed for the event:
   178         *  @p(code)
   179         *  "WARNING: EventCode:0xBAD. Legacy Warning String for warning 0xBAD"
   180         *  @p
   181         *  @param(eventCode)  integer that identifies the type of warning event
   182         *  @param(fmt)        a constant string that provides format specifiers for up to 6 additional parameters
   183         *
   184         *  @see #warning
   185         *
   186         */
   187        config xdc.runtime.Log.Event warningWithStr = {
   188                mask: Diags.STATUS,
   189                level: Diags.WARNING,
   190                msg: "WARNING: EventCode:0x%x. %$S"
   191        };
   192    
   193        /*!
   194         *  ======== info ========
   195         *  Event to use to log an Informational Event Code
   196         *
   197         *  @a(Example)
   198         *   The following C code shows how to log an informational event code as a UIA event.
   199         *
   200         *  @p(code)
   201         *  #include <xdc/runtime/Log.h>
   202         *  #include <ti/uia/events/UIAEvt.h>
   203         *  ...
   204         *  Int myInfoCode = 0xC0DE;
   205         *  ...
   206         *  Log_write1(UIAEvt_info, myInfoCode);
   207         *  ...
   208         *  @p
   209         *  The following text is an example of what will be displayed for the event:
   210         *  @p(code)
   211         *  "INFO: EventCode:0xC0DE."
   212         *  @p
   213         *  @param(eventCode)          integer that identifies the type of info event
   214         *
   215         *  @see #infoWithStr
   216         *
   217         */
   218        config xdc.runtime.Log.Event info = {
   219                mask: Diags.INFO,
   220                msg: "INFO: EventCode: 0x%x"
   221        };
   222    
   223        /*!
   224         *  ======== infoWithStr ========
   225         *  Event to use to log a Informational Event Code and format string
   226         *
   227         *  @a(Example)
   228         *   The following C code shows how to log an informational event code
   229         *   and format string as a UIA event.  It also shows how additional parameters
   230         *   can be logged along with the event and format string.
   231         *
   232         *  @p(code)
   233         *  #include <xdc/runtime/Log.h>
   234         *  #include <ti/uia/events/UIAEvt.h>
   235         *  ...
   236         *  Int myInfoCode = 0xC0DE;
   237         *  Int anAdditionalParam = 0x6543;
   238         *  ...
   239         *  Log_write3(UIAEvt_infoWithStr, myInfoCode,(IArg)"Descriptive text. anAdditionalParam=0x%x.",anAdditionalParam);
   240         *  ...
   241         *  @p
   242         *  The following text is an example of what will be displayed for the event:
   243         *  @p(code)
   244         *  "INFO: EventCode:0xC0DE. Some descriptive text.  anAdditionalParam=0x6543."
   245         *  @p
   246         *  @param(eventCode)  integer that identifies the specific info event being logged
   247         *  @param(fmt)        a constant string that provides format specifiers for up to 6 additional parameters
   248         *
   249         *  @see #info
   250         */
   251        config xdc.runtime.Log.Event infoWithStr = {
   252                mask: Diags.INFO,
   253                msg: "INFO: EventCode:0x%x.  %$S"
   254        };
   255    
   256        /*!
   257         *  ======== detail ========
   258         *  Event to use to log a Detail-level Event Code
   259         *
   260         *  @a(Example)
   261         *   The following C code shows how to log a detail-level event code as a UIA event.
   262         *
   263         *  @p(code)
   264         *  #include <xdc/runtime/Log.h>
   265         *  #include <ti/uia/events/UIAEvt.h>
   266         *  ...
   267         *  Int myEventCode = 0xE1;
   268         *  ...
   269         *  Log_write1(UIAEvt_detail, myEventCode);
   270         *  ...
   271         *  @p
   272         *  The following text is an example of what will be displayed for the event:
   273         *  @p(code)
   274         *  "DETAIL: EventCode:0xE1."
   275         *  @p
   276         *  @param(eventCode)  integer that identifies the specific detail event being logged
   277         *
   278         *  @see #detailWithStr
   279         */
   280        config xdc.runtime.Log.Event detail = {
   281                mask: Diags.INFO,
   282                level: Diags.LEVEL4,
   283                msg: "DETAIL: EventCode:0x%x"
   284        };
   285    
   286        /*!
   287         *  ======== detailWithStr ========
   288         *  Event to use to log a Detail-level Event Code and fmt string
   289         *
   290         *  @a(Example)
   291         *   The following C code shows how to log a detail-level event code
   292         *   and format string as a UIA event.  It also shows how additional parameters
   293         *   can be logged along with the event and format string.
   294         *
   295         *  @p(code)
   296         *  #include <xdc/runtime/Log.h>
   297         *  #include <ti/uia/events/UIAEvt.h>
   298         *  ...
   299         *  Int myEventCode = 0xE1;
   300         *  Int anAdditionalParam = 0x6543;
   301         *  ...
   302         *  Log_write3(UIAEvt_detailWithStr, myEventCode,(IArg)"Descriptive text. anAdditionalParam=0x%x.",anAdditionalParam);
   303         *  ...
   304         *  @p
   305         *  The following text is an example of what will be displayed for the event:
   306         *  @p(code)
   307         *  "DETAIL: EventCode:0xE1. Some descriptive text.  anAdditionalParam=0x6543."
   308         *  @p
   309         *  @param(eventCode)  integer that identifies the specific detail event being logged
   310         *  @param(fmt)        a constant string that provides format specifiers for up to 6 additional parameters
   311         *
   312         *  @see #detail
   313         */
   314        config xdc.runtime.Log.Event detailWithStr = {
   315                mask: Diags.INFO ,
   316                level: Diags.LEVEL4,
   317                msg: "DETAIL: EventCode:0x%x.  %$S"
   318        };
   319    
   320        /*!
   321         *  ======== intWithKey ========
   322         *  Event to use to log values to be analyzed as Statistics and / or Graphs
   323         *
   324         *  @a(Example)
   325         *  Example 1:
   326         *   The following C code shows how to log an intWithKey event code
   327         *   that logs a value, a format string that defines the key, and
   328         *   parameters for use within the key format string.
   329         *
   330         *  @p(code)
   331         *  #include <xdc/runtime/Log.h>
   332         *  #include <ti/uia/events/UIAEvt.h>
   333         *  ...
   334         *  Int myValue = 1001;
   335         *  Int myInstanceId = 0x6543;
   336         *  ...
   337         *  Log_write5(UIAEvt_intWithKey, myValue,0,0,(IArg)"InstanceId=0x%x.",myInstanceId);
   338         *  ...
   339         *  @p
   340         *  The following text is an example of what will be displayed for the event:
   341         *  @p(code)
   342         *  "VALUE=1001 (AuxData=0,0) Key: InstanceId=0x6543."
   343             *
   344         *  @a(Example)
   345         *  Example 2:
   346         *   The following C code shows how to log an intWithKey event code
   347         *   that logs a value, a format string that defines the key, and
   348         *   parameters for use within the key format string, including
   349         *   the file name and line of code that the event was logged at.
   350         *   This example uses a special format specifier, %$F, which
   351         *   is used to format two parameters (__FILE__ and __LINE__)
   352         *   in a way that tools will be able to display the line of code
   353         *   that the event was logged from in a source code editor
   354         *   when the user clicks on the event.
   355         *
   356         *  @p(code)
   357         *  #include <xdc/runtime/Log.h>
   358         *  #include <ti/uia/events/UIAEvt.h>
   359         *  ...
   360         *  Int myValue = 1001;
   361         *  Int myInstanceId = 9876;
   362         *  ...
   363         *  Log_write7(UIAEvt_intWithKey, myValue,0,0,(IArg)"InstanceId=%d, at %$F.",
   364         *                    myInstanceId,(IArg)__FILE__,(IArg)__LINE__);
   365         *  ...
   366         *  // If you wish to log only the line number as a key, use the following:
   367         *  Log_write6(UIAEvt_intWithKey, myValue+1,0,0,(IArg)"InstanceId=%d, at line %d.",
   368         *                    myInstanceId,(IArg)__LINE__);
   369         *  ...
   370         *  // If you wish to log only the file name as a key and the line number
   371         *  // as auxiliary data which is logged along with the event, use the following:
   372         *  Log_write6(UIAEvt_intWithKey, myValue+2,(IArg)__LINE__,0,(IArg)"InstanceId=%d, in file [%s].",
   373         *                    myInstanceId,(IArg)__FILE__);
   374         *  @p
   375         *  The following text is an example of what will be displayed for the event,
   376         *  assuming it was logged from a file named demo.c at line 1234:
   377         *  @p(code)
   378         *  "VALUE=1001 (AuxData=0,0) Key: InstanceId=9876, at [../demo.c:1234] ."
   379         *  "VALUE=1002 (AuxData=0,0) Key: InstanceId=9876, at line 1234."
   380         *  "VALUE=1003 (AuxData=1234,0) Key: InstanceId=9876, in file [../demo.c]."
   381         *  @p
   382         *
   383         *  @param(value)      integer value that is to be analyzed
   384         *  @param(auxData1)   auxiliary data that is to be displayed along with the event (use 0 if none)
   385         *  @param(auxData2)   auxiliary data that is to be displayed along with the event (use 0 if none)
   386         *  @param(key)        a constant string that provides format specifiers for up to 4 key entries
   387         */
   388        config xdc.runtime.Log.Event intWithKey = {
   389                    mask: Diags.ANALYSIS,
   390                    msg: "VALUE=%d (AuxData=%d, %d) Key:%$S"
   391        };
   392    
   393        /*!
   394         *  ======== metaEventStart ========
   395         *  Metadata description of the start event
   396         *
   397         *  @_nodoc
   398         */
   399        metaonly config DvtTypes.MetaEventDescriptor metaEventIntWithKey = {
   400            versionId: "2.0",
   401            analysisType: DvtTypes.DvtAnalysisType_STATISTIC,
   402            displayText: "intWithKey",
   403            tooltipText: "Value with a key string",
   404            numParameters: 4,
   405            paramInfo: [
   406            {   name: 'value',
   407                dataDesc: DvtTypes.DvtDataDesc_VALUE,
   408                dataTypeName: 'Int',
   409                units: 'none',
   410                isHidden: false
   411            },
   412            {   name: 'aux1',
   413                dataDesc: DvtTypes.DvtDataDesc_VALUE,
   414                dataTypeName: 'Int',
   415                units: 'none',
   416                isHidden: false
   417            },
   418            {   name: 'aux2',
   419                dataDesc: DvtTypes.DvtDataDesc_VALUE,
   420                dataTypeName: 'Int',
   421                units: 'none',
   422                isHidden: false
   423            },
   424            {   name: 'key',
   425                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   426                dataTypeName: 'String',
   427                units: 'none',
   428                isHidden: false
   429            }
   430            ]
   431        };
   432    
   433    }