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     * ======== UIARoundtrip.xdc ========
    35     */
    36    
    37    import xdc.runtime.Diags;
    38    import xdc.runtime.Types;
    39    import ti.uia.events.DvtTypes;
    40    
    41    /*!
    42     * UIA Roundtrip Events
    43     *
    44     *  The UIARoundtrip module defines events that allow
    45     *  tooling to analyze the absolute time elapsed between
    46     *  a start point event and a stop point event.  It differs
    47     *  from UIABenchmark in that UIABenchmark supports context-awareness
    48     *  (i.e. exclusive time elapsed) whereas UIARoundtrip is always
    49     *  inclusive (i.e. the time elapsed that DVT displays includes
    50     *  time spent in all other threads / tasks).
    51     *
    52     *  The generation of UIARoundtrip events is controlled by a module's diagnostics
    53     *  mask, which is described in details in `{@link xdc.runtime.Diags}`.
    54     * `UIARoundtrip` events are generated only when the Diags.ANALYSIS bit is set
    55     *  in the module's diagnostics mask.
    56     *
    57     *  The following configuration script demonstrates how the application might
    58     *  control the logging of ANALYSIS events embedded in the `Mod` module at configuration
    59     *  time. In this case, the configuration script arranges for the `Log`
    60     *  statements within modules to always generate ANALYSIS events.
    61     *  Without these configuration statements, no ANALYSIS events would be generated
    62     *  by any modules.
    63     *
    64     * @a(Examples)
    65     * Example 1: This is part of the XDC configuration file for the application:
    66     *
    67     *  @p(code)
    68     *  var UIARoundtrip = xdc.useModule('ti.uia.events.UIARoundtrip');
    69     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    70     *  var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
    71     *  var Defaults = xdc.useModule('xdc.runtime.Defaults');
    72     *  var logger = LoggerSys.create();
    73     *
    74     *  Defaults.common$.diags_ANALYSIS = Diags.ALWAYS_ON;
    75     *  Defaults.common$.logger = logger;
    76     *  @p
    77     *
    78     *  @p(html)
    79     *  <hr />
    80     *  @p
    81     *
    82     *  Example 2: The following example configures a module to support logging
    83     *  of ANALYSIS events, but defers the actual activation and deactivation of the
    84     *  logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
    85     *  function for details on specifying the control string.
    86     *
    87     *  This is a part of the XDC configuration file for the application:
    88     *
    89     *  @p(code)
    90     *  var UIARoundtrip = xdc.useModule('ti.uia.events.UIARoundtrip');
    91     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    92     *  var Mod = xdc.useModule('my.pkg.Mod');
    93     *
    94     *  Mod.common$.diags_ANALYSIS = Diags.RUNTIME_OFF;
    95     *  @p
    96     *
    97     *  This is a part of the C code for the application:
    98     *
    99     *  @p(code)
   100     *  // turn on logging of ANALYSIS events in the module
   101     *  Diags_setMask("my.pkg.Mod+Z");
   102     *
   103     *  // turn off logging of ANALYSIS events in the module
   104     *  Diags_setMask("my.pkg.Mod-Z");
   105     *  @p
   106     */
   107    
   108    module UIARoundtrip inherits IUIAEvent {
   109    
   110        /*!
   111         *  ======== start ========
   112         *  Roundtrip event used to log the start of an operation
   113         *
   114         * @a(Example)
   115         *   The following C code shows how to log a simple
   116         *   roundtrip 'start' event along with a user-specified
   117         *   format string describing the event.
   118         *
   119         *  @p(code)
   120         *  #include <xdc/runtime/Log.h>
   121         *  #include <ti/uia/events/UIARoundtrip.h>
   122         *  ...
   123         *  Log_write1(UIARoundtrip_start, "My roundtrip event");
   124         *  @p
   125         *  The following text will be displayed for the event:
   126         *  @p(code)
   127         *  Roundtrip_Start: My roundtrip event
   128         *  @p
   129         *
   130         *  @param(fmt)  a constant string that provides format specifiers for up to 6 additional parameters
   131         */
   132        config xdc.runtime.Log.Event start = {
   133            mask: Diags.ANALYSIS,
   134            msg: "Roundtrip_Start: %$S"};
   135    
   136        /*!
   137         *  ======== metaEventStart ========
   138         *  Metadata description of the start event
   139         *
   140         *  @_nodoc
   141         */
   142        metaonly config DvtTypes.MetaEventDescriptor metaEventStart = {
   143            versionId: "2.0",
   144            analysisType: DvtTypes.DvtAnalysisType_START,
   145            displayText: "Roundtrip_Start",
   146            tooltipText: "Marks the start of analysis",
   147            numParameters: 1,
   148            paramInfo: [
   149            {   name: 'fmt',
   150                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   151                dataTypeName: 'String',
   152                units: 'none',
   153                isHidden: false
   154            }]
   155        };
   156    
   157        /*!
   158         *  ======== stop ========
   159         *  Roundtrip event used to log the end of an operation
   160         *
   161         * @a(Example)
   162         *   The following C code shows how to log a simple
   163         *   roundtrip 'stop' event along with a user-specified
   164         *   format string describing the event.
   165         *
   166         *  @p(code)
   167         *  #include <xdc/runtime/Log.h>
   168         *  #include <ti/uia/events/UIARoundtrip.h>
   169         *  ...
   170         *  Log_write1(UIARoundtrip_stop, "My roundtrip event");
   171         *  @p
   172         *  The following text will be displayed for the event:
   173         *  @p(code)
   174         *  Roundtrip_Stop: My roundtrip event
   175         *  @p
   176         *  @param(fmt)        a constant string that provides format specifiers for up to 6 additional parameters
   177         */
   178        config xdc.runtime.Log.Event stop = {
   179            mask: Diags.ANALYSIS,
   180            msg: "Roundtrip_Stop: %$S"};
   181    
   182        /*!
   183         *  ======== metaEventStop ========
   184         *  Metadata description of the stop event
   185         *
   186         *  @_nodoc
   187         */
   188        metaonly config DvtTypes.MetaEventDescriptor metaEventStop = {
   189            versionId: "2.0",
   190            analysisType: DvtTypes.DvtAnalysisType_STOP,
   191            displayText: "Roundtrip_Stop",
   192            tooltipText: "Marks the end of analysis",
   193            numParameters: 1,
   194            paramInfo: [
   195            {   name: 'fmt',
   196                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   197                dataTypeName: 'String',
   198                units: 'none',
   199                isHidden: false
   200            }]
   201        };
   202        /*!
   203         *  ======== startInstance ========
   204         *  Roundtrip event used to log the start of an operation instance
   205         *
   206         *  Event parameter provides instance data to differentiate
   207         *  between multiple instances that can run in parallel.
   208         *
   209         *  @a(Example)
   210         *   The following C code shows how to log a roundtrip
   211         *   'startInstance' event along with a user-specified
   212         *   instance identifier and a format string describing the event.
   213         *
   214         *  @p(code)
   215         *  #include <xdc/runtime/Gate.h>
   216         *  #include <xdc/runtime/Log.h>
   217         *  #include <ti/uia/events/UIARoundtrip.h>
   218         *  static volatile int gMyGlobalInstanceId = 0;
   219         *  ...
   220         *  IArg key;
   221         *  int localInstanceId;
   222         *
   223         * // protect pre-increment operation from race conditions
   224         *  key = Gate_enterSystem();
   225         *  localInstanceId = ++gMyGlobalInstanceId;
   226         *  Gate_leaveSystem(key);
   227         *
   228         *  Log_write2(UIARoundtrip_startInstance, "My roundtrip event: instanceId=%d",localInstanceId);
   229         *  ...
   230         *  Log_write2(UIARoundtrip_stopInstance, "My roundtrip event: instanceId=%d",localInstanceId);
   231         *  @p
   232         *  The following text will be displayed for the event:
   233         *  @p(code)
   234         *  Roundtrip_StartInstance: My roundtrip event: instanceId=1
   235         *  Roundtrip_StopInstance: My roundtrip event: instanceId=1
   236         *  @p
   237         *  @param(fmt)                 a constant string that provides format specifiers for up to 5 additional parameters
   238         *  @param(instanceId)          a unique instance ID that can be used to match Roundtrip start and stop events
   239         */
   240        config xdc.runtime.Log.Event startInstance = {
   241            mask: Diags.ANALYSIS,
   242            msg: "Roundtrip_StartInstance: %$S"
   243        };
   244    
   245        /*!
   246         *  ======== metaEventStartInstance ========
   247         *  Metadata description of the startInstance event
   248         *
   249         *  @_nodoc
   250         */
   251        metaonly config DvtTypes.MetaEventDescriptor metaEventStartInstance = {
   252            versionId: "2.0",
   253            analysisType: DvtTypes.DvtAnalysisType_START,
   254            displayText: "Roundtrip_StartInstance",
   255            tooltipText: "Marks the start of analysis for a module instance",
   256            numParameters: 2,
   257            paramInfo: [
   258            {   name: 'fmt',
   259                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   260                dataTypeName: 'String',
   261                units: 'none',
   262                isHidden: false
   263            },
   264            {   name: 'InstanceID',
   265                dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
   266                dataTypeName: 'Int',
   267                units: 'none',
   268                isHidden: false
   269            }
   270            ]
   271        };
   272    
   273        /*!
   274         *  ======== stopInstance ========
   275         *  Roundtrip event used to log the end of an operation instance
   276         *
   277         *  Event parameter provides instance data to differentiate
   278         *  between multiple instances that can run in parallel
   279         *  @a(Example)
   280         *   The following C code shows how to log a roundtrip
   281         *   'stopInstance' event along with a user-specified
   282         *   instance identifier and a format string describing the event.
   283         *
   284         *  @p(code)
   285         *  #include <xdc/runtime/Gate.h>
   286         *  #include <xdc/runtime/Log.h>
   287         *  #include <ti/uia/events/UIARoundtrip.h>
   288         *  static volatile int gMyGlobalInstanceId = 0;
   289         *  ...
   290         *  IArg key;
   291         *  int localInstanceId;
   292         *
   293         * // protect pre-increment operation from race conditions
   294         *  key = Gate_enterSystem();
   295         *  localInstanceId = ++gMyGlobalInstanceId;
   296         *  Gate_leaveSystem(key);
   297         *
   298         *  Log_write2(UIARoundtrip_startInstance, "My roundtrip event: instanceId=%d",localInstanceId);
   299         *  ...
   300         *  Log_write2(UIARoundtrip_stopInstance, "My roundtrip event: instanceId=%d",localInstanceId);
   301         *  @p
   302         *  The following text will be displayed for the event:
   303         *  @p(code)
   304         *  Roundtrip_StartInstance: My roundtrip event: instanceId=1
   305         *  Roundtrip_StopInstance: My roundtrip event: instanceId=1
   306         *  @p
   307         *  @param(fmt)                 a constant string that provides format specifiers for up to 4 additional parameters
   308         *  @param(instanceId)          a unique instance ID that can be used to match Roundtrip start and stop events
   309         */
   310        config xdc.runtime.Log.Event stopInstance = {
   311            mask: Diags.ANALYSIS,
   312            msg: "Roundtrip_StopInstance: %$S"
   313        };
   314    
   315        /*!
   316         *  ======== metaEventStopInstance ========
   317         *  Metadata description of the stopInstance event
   318         *
   319         *  @_nodoc
   320         */
   321        metaonly config DvtTypes.MetaEventDescriptor metaEventStopInstance = {
   322            versionId: "2.0",
   323            analysisType: DvtTypes.DvtAnalysisType_STOP,
   324            displayText: "Roundtrip_StopInstance",
   325            tooltipText: "Marks the end of analysis for a module instance",
   326            numParameters: 2,
   327            paramInfo: [
   328            {   name: 'fmt',
   329                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   330                dataTypeName: 'String',
   331                units: 'none',
   332                isHidden: false
   333            },
   334            {   name: 'InstanceID',
   335                dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
   336                dataTypeName: 'Int',
   337                units: 'none',
   338                isHidden: false
   339            }
   340            ]
   341        };
   342    
   343    
   344        /*!
   345         *  ======== startInstanceWithAdrs ========
   346         *  Roundtrip event used to log the start of an operation instance
   347         *
   348         *  Event parameter provides instance data to differentiate
   349         *  between multiple instances that can run in parallel
   350         *
   351         * @a(Example)
   352         *   The following C code shows how to log a roundtrip
   353         *   'startInstanceWithAdrs' event along with a task handle as the
   354         *   instance identifier, the function address and a format string
   355         *   describing the event.
   356         *
   357         *  @p(code)
   358         *  #include <ti/sysbios/knl/Task.h>
   359         *  #include <xdc/runtime/Log.h>
   360         *  #include <ti/uia/events/UIARoundtrip.h>
   361         *  ...
   362         * Void myFunction(){
   363         *   Task_Handle hTsk = Task_selfMacro( );
   364         *
   365         *   Log_write3(UIARoundtrip_startInstanceWithAdrs, "My roundtrip event: task=0x%x, fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
   366         *   ...
   367         *   Log_write3(UIARoundtrip_stopInstanceWithAdrs, "My roundtrip event: task=0x%x", fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
   368         * }
   369         *  @p
   370         *  The following text will be displayed for the event:
   371         *  @p(code)
   372         *  Roundtrip_StartInstanceWithAdrs: My roundtrip event: task=0x893230, fnAdrs=0x820060
   373         *  Roundtrip_StopInstanceWithAdrs: My roundtrip event: task=0x893230, fnAdrs=0x820060
   374         *  @p
   375         *  @param(fmt)                 a constant string that provides format specifiers for up to 5 additional parameters
   376         *  @param(instanceId)          a unique instance ID that can be used to match benchmark start and stop events
   377         *  @param(functionAdrs)        the address of a function that can differentiate this pair of start and stop events from others
   378    
   379         */
   380        config xdc.runtime.Log.Event startInstanceWithAdrs = {
   381            mask: Diags.ANALYSIS,
   382            msg: "Roundtrip_StartInstanceWithAdrs: %$S"
   383        };
   384    
   385        /*!
   386         *  ======== metaEventStartInstanceWithAdrs ========
   387         *  Metadata description of the startInstanceWithAdrs event
   388         *
   389         *  @_nodoc
   390         */
   391        metaonly config DvtTypes.MetaEventDescriptor metaEventStartInstanceWithAdrs = {
   392            versionId: "2.0",
   393            analysisType: DvtTypes.DvtAnalysisType_START,
   394            displayText: "Roundtrip_StartInstanceWithAdrs",
   395            tooltipText: "Marks the start of analysis for a module instance",
   396            numParameters: 3,
   397            paramInfo: [
   398            {   name: 'fmt',
   399                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   400                dataTypeName: 'String',
   401                units: 'none',
   402                isHidden: false
   403            },
   404            {   name: 'InstanceID',
   405                dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
   406                dataTypeName: 'Int',
   407                units: 'none',
   408                isHidden: false
   409            },
   410            {   name: 'FunctionAdrs',
   411                dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
   412                dataTypeName: 'Int',
   413                units: 'none',
   414                isHidden: false
   415            }
   416            ]
   417        };
   418    
   419    
   420    
   421    
   422    
   423        /*!
   424         *  ======== stopInstanceWithAdrs ========
   425         *  Roundtrip event used to log the end of an operation instance
   426         *
   427         * @a(Example)
   428         *   The following C code shows how to log a roundtrip
   429         *   'stopInstanceWithAdrs' event along with a task handle as the
   430         *   instance identifier, the function address and a format string
   431         *   describing the event.
   432         *
   433         *  @p(code)
   434         *  #include <ti/sysbios/knl/Task.h>
   435         *  #include <xdc/runtime/Log.h>
   436         *  #include <ti/uia/events/UIARoundtrip.h>
   437         *  ...
   438         * Void myFunction(){
   439         *   Task_Handle hTsk = Task_selfMacro( );
   440         *
   441         *   Log_write3(UIARoundtrip_startInstanceWithAdrs, "My roundtrip event: task=0x%x, fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
   442         *   ...
   443         *   Log_write3(UIARoundtrip_stopInstanceWithAdrs, "My roundtrip event: task=0x%x", fnAdrs=0x%x",(IArg)hTsk,(IArg)&myFunc);
   444         * }
   445         *  @p
   446         *  The following text will be displayed for the event:
   447         *  @p(code)
   448         *  Roundtrip_StartInstanceWithAdrs: My roundtrip event: task=0x893230, fnAdrs=0x820060
   449         *  Roundtrip_StopInstanceWithAdrs: My roundtrip event: task=0x893230, fnAdrs=0x820060
   450         *  @p
   451         *  @param(fmt)                 a constant string that provides format specifiers for up to 4 additional parameters
   452         *  @param(instanceId)          a unique instance ID that can be used to match Roundtrip start and stop events
   453         *  @param(functionAdrs)        the address of the function
   454         */
   455        config xdc.runtime.Log.Event stopInstanceWithAdrs = {
   456            mask: Diags.ANALYSIS,
   457            msg: "Roundtrip_StopInstanceWithAdrs: %$S"
   458        };
   459    
   460        /*!
   461         *  ======== metaEventStopInstanceWithAdrs ========
   462         *  Metadata description of the stopInstanceWithAdrs event
   463         *
   464         *  @_nodoc
   465         */
   466        metaonly config DvtTypes.MetaEventDescriptor metaEventStopInstanceWithAdrs = {
   467            versionId: "2.0",
   468            analysisType: DvtTypes.DvtAnalysisType_STOP,
   469            displayText: "Roundtrip_StopInstanceWithAdrs",
   470            tooltipText: "Marks the end of analysis for a module instance",
   471            numParameters: 3,
   472            paramInfo: [
   473            {   name: 'fmt',
   474                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   475                dataTypeName: 'String',
   476                units: 'none',
   477                isHidden: false
   478            },
   479            {   name: 'Handle',
   480                dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
   481                dataTypeName: 'Int',
   482                units: 'none',
   483                isHidden: false
   484            },
   485            {   name: 'FunctionAdrs',
   486                dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
   487                dataTypeName: 'Int',
   488                units: 'none',
   489                isHidden: false
   490            }
   491            ]
   492        };
   493    
   494    
   495        /*!
   496         *  ======== startInstanceWithStr ========
   497         *  Roundtrip event used to log the start of an operation instance
   498         *
   499         *  Event parameter provides instance data to differentiate
   500         *  between multiple instances that can run in parallel
   501         * @a(Example)
   502         *   The following C code shows how to log a roundtrip
   503         *   'startInstanceWithStr' event along with a unique instance identifier
   504         *   and a string reference used only by the pair of start / stop events.
   505         *
   506         *  @p(code)
   507         *  #include <xdc/runtime/Log.h>
   508         *  #include <ti/uia/events/UIARoundtrip.h>
   509         *  ...
   510         * Void packetHdlr(Int packetId){
   511         *
   512         *   Log_write3(UIARoundtrip_startInstanceWithStr, "My roundtrip event: packetId=0x%x",packetId,(IArg)"(routing)");
   513         *   ...
   514         *   Log_write3(UIARoundtrip_stopInstanceWithStr, "My roundtrip event: packetId=0x%x",packetId,(IArg)"(routing)");
   515         * }
   516         *  @p
   517         *  The following text will be displayed for the event:
   518         *  @p(code)
   519         *  Roundtrip_StartInstanceWithStr: My roundtrip event: packetId=0x3bc3 (routing)
   520         *  Roundtrip_StopInstanceWithStr: My roundtrip event: packetId=0x3bc3 (routing)
   521         *  @p
   522         *  Event parameter provides instance data to differentiate
   523         *  between multiple instances that can run in parallel
   524         *  @param(fmt)                 a constant string that provides format specifiers for up to 4 additional parameters
   525         *  @param(instanceId)          a unique instance ID that can be used to match Roundtrip start and stop events
   526         *  @param(str)                 a constant string reference
   527         */
   528        config xdc.runtime.Log.Event startInstanceWithStr = {
   529            mask: Diags.ANALYSIS,
   530            msg: "Roundtrip_StartInstanceWithStr: %$S"
   531        };
   532    
   533        /*!
   534         *  ======== metaEventStartInstanceWithStr ========
   535         *  Metadata description of the startInstance event
   536         *
   537         *  @_nodoc
   538         */
   539        metaonly config DvtTypes.MetaEventDescriptor metaEventStartInstanceWithStr = {
   540            versionId: "2.0",
   541            analysisType: DvtTypes.DvtAnalysisType_START,
   542            displayText: "Roundtrip_StartInstanceWithStr",
   543            tooltipText: "Marks the start of analysis for a module instance",
   544            numParameters: 3,
   545            paramInfo: [
   546            {   name: 'fmt',
   547                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   548                dataTypeName: 'String',
   549                units: 'none',
   550                isHidden: false
   551            },
   552            {   name: 'InstanceID',
   553                dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
   554                dataTypeName: 'Int',
   555                units: 'none',
   556                isHidden: false
   557            },
   558            {   name: 'FunctionAdrs',
   559                dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
   560                dataTypeName: 'Int',
   561                units: 'none',
   562                isHidden: false
   563            }
   564            ]
   565        };
   566    
   567    
   568        /*!
   569         *  ======== stopInstanceWithStr ========
   570         *  Roundtrip event used to log the end of an operation instance
   571         *
   572         *  Event parameter provides instance data to differentiate
   573         *  between multiple instances that can run in parallel
   574         * @a(Example)
   575         *   The following C code shows how to log a roundtrip
   576         *   'stopInstanceWithStr' event along with a unique instance identifier
   577         *   and a string reference used only by the pair of start / stop events.
   578         *
   579         *  @p(code)
   580         *  #include <xdc/runtime/Log.h>
   581         *  #include <ti/uia/events/UIARoundtrip.h>
   582         *  ...
   583         * Void packetHdlr(Int packetId){
   584         *
   585         *   Log_write3(UIARoundtrip_startInstanceWithStr, "My roundtrip event: packetId=0x%x",packetId,(IArg)"(routing)");
   586         *   ...
   587         *   Log_write3(UIARoundtrip_stopInstanceWithStr, "My roundtrip event: packetId=0x%x",packetId,(IArg)"(routing)");
   588         * }
   589         *  @p
   590         *  The following text will be displayed for the event:
   591         *  @p(code)
   592         *  Roundtrip_StartInstanceWithStr: My roundtrip event: packetId=0x3bc3 (routing)
   593         *  Roundtrip_StopInstanceWithStr: My roundtrip event: packetId=0x3bc3 (routing)
   594         *  @p
   595         *  Event parameter provides instance data to differentiate
   596         *  between multiple instances that can run in parallel
   597         *  @param(fmt)                 a constant string that provides format specifiers for up to 4 additional parameters
   598         *  @param(instanceId)          a unique instance ID that can be used to match Roundtrip start and stop events
   599         *  @param(str)                 a constant string reference
   600         */
   601        config xdc.runtime.Log.Event stopInstanceWithStr = {
   602            mask: Diags.ANALYSIS,
   603            msg: "Roundtrip_StopInstanceWithStr: %$S"
   604        };
   605    
   606        /*!
   607         *  ======== metaEventStopInstance ========
   608         *  Metadata description of the stopInstance event
   609         *
   610         *  @_nodoc
   611         */
   612        metaonly config DvtTypes.MetaEventDescriptor metaEventStopInstanceWithStr = {
   613            versionId: "2.0",
   614            analysisType: DvtTypes.DvtAnalysisType_STOP,
   615            displayText: "Roundtrip_StopInstanceWithStr",
   616            tooltipText: "Marks the end of analysis for a module instance",
   617            numParameters: 3,
   618            paramInfo: [
   619            {   name: 'fmt',
   620                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   621                dataTypeName: 'String',
   622                units: 'none',
   623                isHidden: false
   624            },
   625            {   name: 'InstanceID',
   626                dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
   627                dataTypeName: 'Int',
   628                units: 'none',
   629                isHidden: false
   630            },
   631            {   name: 'String',
   632                dataDesc: DvtTypes.DvtDataDesc_STRINGADRS,
   633                dataTypeName: 'String',
   634                units: 'none',
   635                isHidden: false
   636            }
   637            ]
   638        };
   639    
   640    }