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     * ======== UIAStatistic.xdc ========
    35     */
    36    import xdc.runtime.Diags;
    37    
    38    /*!
    39     * UIA Statistics Events
    40     *
    41     * The UIAStatistic module defines events that allow
    42     * tooling to analyze the performance of the software
    43     * (CPU Utilization, throughput, etc.)
    44     *
    45     *  The generation of UIAStatistic events is controlled by a module's diagnostics
    46     *  mask, which is described in details in `{@link xdc.runtime.Diags}`.
    47     * `UIAStatistic` events are generated only when the Diags.ANALYSIS bit is set
    48     *  in the module's diagnostics mask.
    49     *
    50     *  The following configuration script demonstrates how the application might
    51     *  control the logging of ANALYSIS events embedded in the `Mod` module at configuration
    52     *  time. In this case, the configuration script arranges for the `Log`
    53     *  statements within modules to always generate ANALYSIS events.
    54     *  Without these configuration statements, no ANALYSIS events would be generated
    55     *  by any modules.
    56     *
    57     * @a(Examples)
    58     * Example 1: This is part of the XDC configuration file for the application:
    59     *
    60     *  @p(code)
    61     *  var UIAStatistic = xdc.useModule('ti.uia.events.UIAStatistic');
    62     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    63     *  var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
    64     *  var Defaults = xdc.useModule('xdc.runtime.Defaults');
    65     *  var logger = LoggerSys.create();
    66     *
    67     *  Defaults.common$.diags_ANALYSIS = Diags.ALWAYS_ON;
    68     *  Defaults.common$.logger = logger;
    69     *  @p
    70     *
    71     *  @p(html)
    72     *  <hr />
    73     *  @p
    74     *
    75     *  Example 2: The following example configures a module to support logging
    76     *  of ANALYSIS events, but defers the actual activation and deactivation of the
    77     *  logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
    78     *  function for details on specifying the control string.
    79     *
    80     *  This is a part of the XDC configuration file for the application:
    81     *
    82     *  @p(code)
    83     *  var UIAStatistic = xdc.useModule('ti.uia.events.UIAStatistic');
    84     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    85     *  var Mod = xdc.useModule('my.pkg.Mod');
    86     *
    87     *  Mod.common$.diags_ANALYSIS = Diags.RUNTIME_OFF;
    88     *  @p
    89     *
    90     *  This is a part of the C code for the application:
    91     *
    92     *  @p(code)
    93     *  // turn on logging of ANALYSIS events in the module
    94     *  Diags_setMask("my.pkg.Mod+Z");
    95     *
    96     *  // turn off logging of ANALYSIS events in the module
    97     *  Diags_setMask("my.pkg.Mod-Z");
    98     *  @p
    99     */
   100    
   101    module UIAStatistic inherits IUIAEvent {
   102    
   103        /*! ====== cpuLoad ======
   104         * Number of cycles used by an XDC module
   105         *
   106         * @a(Example)
   107         *   The following C code shows how to log a cpuLoad
   108         *   event that tracks the number of cycles used by an XDC module.
   109         *   The module ID is logged along with the event.  For non-XDC
   110         *   code, or for code with multiple instances @see #cpuLoadByInstance.
   111         *  @p(code)
   112         *  #include <xdc/runtime/Log.h>
   113         *  #include <ti/uia/events/UIAStatistic.h>
   114         *  ...
   115         * Void myFunction(){
   116         *   int numCycles = 0;
   117         *   // update numCycles with the number of cycles processed
   118         *   Log_write1(UIAStatistic_cpuLoad, numCycles);
   119         * }
   120         *  @p
   121         *  The following text will be displayed for the event:
   122         *  @p(code)
   123         *  CPU Load: NumCycles=1234
   124         *  @p
   125         *
   126         *  @param(numCycles)           the CPU load in cycles
   127         */
   128        config xdc.runtime.Log.Event cpuLoad = {
   129            mask: Diags.ANALYSIS,
   130            msg: "CPU Load: NumCycles=%d"
   131        };
   132    
   133        /*! ====== cpuLoadByInstance ======
   134         * Number of cycles used by a non XDC module or thread
   135         *
   136         * @a(Example)
   137         *   The following C code shows how to log a cpuLoad
   138         *   event that tracks the number of cycles used by
   139         *   code that is not in an XDC module or by a thread
   140         *  @p(code)
   141         *  #include <xdc/runtime/Log.h>
   142         *  #include <ti/uia/events/UIAStatistic.h>
   143         *  static volatile int gMyGlobalInstanceId = 0;
   144         *  ...
   145         * Void myFunction(){
   146         *  IArg key;
   147         *  int localInstanceId;
   148         *  int numCycles = 0;
   149         * // protect pre-increment operation from race conditions
   150         *  key = Gate_enterSystem();
   151         *  localInstanceId = ++gMyGlobalInstanceId;
   152         *  Gate_leaveSystem(key);
   153         *   // update numCycles with the number of cycles processed
   154         *   Log_write3(UIAStatistic_cpuLoadByInstance, "myFunction",localInstanceId,numCycles);
   155         * }
   156         *  @p
   157         *  The following text will be displayed for the event:
   158         *  @p(code)
   159         *  CPU Load for myFunction (instanceId = 0x1234): NumCycles=1234
   160         *  @param(name)                a constant string that provides the name of the entity that is processing the data
   161         *  @param(instanceId)          the instance ID (e.g. thread handle) of the entity that is processing the data
   162         *  @param(numCycles)           the CPU load in cycles
   163         */
   164        config xdc.runtime.Log.Event cpuLoadByInstance = {
   165            mask: Diags.ANALYSIS,
   166            msg: "CPU Load for %s (instanceId = 0x%x): NumCycles=%d"
   167        };
   168    
   169        /*! ====== bytesProcessed ======
   170         *  bytesProcessed statistic event
   171         *
   172         *  Number of bytes that were processed.
   173         *  @param(name)                a constant string that provides the name
   174         *                              of the entity that is processing the data
   175         *  @param(numBytes)            the number of bytes processed
   176         */
   177        config xdc.runtime.Log.Event bytesProcessed = {
   178            mask: Diags.ANALYSIS,
   179            msg: "Bytes Processed by %s: NumBytes=0x%x"
   180        };
   181    
   182        /*! ====== bytesProcessedByInstance ======
   183         * bytesProcessedByInstance statistic event
   184         *
   185         *  Number of bytes that were processed along with filename,
   186         *  line number and instance ID.
   187         * @a(Example)
   188         *   The following C code shows how to log an
   189         *   event that tracks the number of bytes processed
   190         *  @p(code)
   191         *  #include <xdc/runtime/Log.h>
   192         *  #include <ti/uia/events/UIAStatistic.h>
   193         *  ...
   194         * Void myFunction(){
   195         *   int instanceId = 0x1234; // change to e.g. a TaskId or some other unique ID
   196         *   int numBytes= 567;       // change to number of bytes actually processed
   197         *
   198         *   Log_write4(UIAStatistic_bytesProcessedByInstance, (IArg)__FILE__,(IArg)__LINE__,instanceId,numBytes);
   199         * }
   200         *  @p
   201         *  The following text will be displayed for the event:
   202         *  @p(code)
   203         *  Bytes Processed at Line 123 in demo.c (InstanceId 0x1234): Num Bytes=567
   204         *  @p
   205         *  @param(__FILE__)           constant string identifying the file the event was logged from
   206         *  @param(__LINE__)           the line number the event was logged from
   207         *  @param(instanceId)         the instance ID (e.g. thread handle) of the
   208         *                             entity that is processing the data
   209         *  @param(numBytes)           the number of bytes processed
   210         */
   211        config xdc.runtime.Log.Event bytesProcessedByInstance = {
   212            mask: Diags.ANALYSIS,
   213            msg: "Bytes Processed at %$F (InstanceId 0x%x): Num Bytes=%d"
   214        };
   215    
   216         /*!
   217         *  ======== metaEventBytesProcessedByInstance ========
   218         *  Metadata description of the bytesProcessedByInstance event
   219         *
   220         *  @_nodoc
   221         */
   222        metaonly config DvtTypes.MetaEventDescriptor metaEventBytesProcessedByInstance = {
   223            versionId: "2.0",
   224            analysisType: DvtTypes.DvtAnalysisType_STATISTIC,
   225            displayText: "Bytes Processed",
   226            tooltipText: "Bytes Processed",
   227            numParameters: 4,
   228            paramInfo: [
   229            {   name: '__FILE__',
   230                dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
   231                dataTypeName: 'String',
   232                units: 'none',
   233                isHidden: false
   234            },
   235            {   name: '__LINE__',
   236                dataDesc: DvtTypes.DvtDataDesc_LINENUM,
   237                dataTypeName: 'Int',
   238                units: 'none',
   239                isHidden: false
   240            },
   241            {   name: 'Instance ID',
   242                dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
   243                dataTypeName: 'Int',
   244                units: 'none',
   245                isHidden: false
   246            },
   247            {   name: 'Words Processed',
   248                dataDesc: DvtTypes.DvtDataDesc_VALUE,
   249                dataTypeName: 'Int',
   250                units: 'bytes',
   251                isHidden: false
   252            }]
   253    
   254        };
   255    
   256    
   257        /*! ====== wordsProcessed ======
   258         *  wordsProcessed statistic event
   259         *
   260         *  number of words that were processed.
   261         *  @param(name)                a constant string that provides the name
   262         *                              of the entity that is processing the data
   263         *  @param(numWords)            the number of words processed
   264         */
   265        config xdc.runtime.Log.Event wordsProcessed = {
   266            mask: Diags.ANALYSIS,
   267            msg: "Words Processed by %s: NumWords=0x%x"
   268        };
   269    
   270    
   271        /*! ====== wordsProcessedByInstance ======
   272         * wordsProcessedByInstance statistic event
   273         *
   274         *  Number of words that were processed along with filename,
   275         *  line number and instance ID.
   276         * @a(Example)
   277         *   The following C code shows how to log an
   278         *   event that tracks the number of words processed
   279         *  @p(code)
   280         *  #include <xdc/runtime/Log.h>
   281         *  #include <ti/uia/events/UIAStatistic.h>
   282         *  ...
   283         * Void myFunction(){
   284         *   int instanceId = 0x1234;  // change to e.g. a TaskId or some other unique ID
   285         *   int numWords= 567;        // change to number of words actually processed
   286         *
   287         *   Log_write4(UIAStatistic_wordsProcessedByInstance, (IArg)__FILE__,(IArg)__LINE__,instanceId,numWords);
   288         * }
   289         *  @p
   290         *  The following text will be displayed for the event:
   291         *  @p(code)
   292         *  Words Processed at Line 123 in demo.c (InstanceId 0x1234): Num Words=567
   293         *  @p
   294         *  @param(__FILE__)           constant string identifying the file the event was logged from
   295         *  @param(__LINE__)           the line number the event was logged from
   296         *  @param(instanceId)         the instance ID (e.g. thread handle) of the
   297         *                             entity that is processing the data
   298         *  @param(numWords)           the number of words processed
   299         */
   300        config xdc.runtime.Log.Event wordsProcessedByInstance = {
   301            mask: Diags.ANALYSIS,
   302            msg: "Words Processed at %$F (InstanceId 0x%x): Num Words=%d"
   303        };
   304    
   305         /*!
   306         *  ======== metaEventWordsProcessedByInstance ========
   307         *  Metadata description of the wordsProcessedByInstance event
   308         *
   309         *  @_nodoc
   310         */
   311        metaonly config DvtTypes.MetaEventDescriptor metaEventWordsProcessedByInstance = {
   312            versionId: "2.0",
   313            analysisType: DvtTypes.DvtAnalysisType_STATISTIC,
   314            displayText: "Words Processed",
   315            tooltipText: "Words Processed",
   316            numParameters: 4,
   317            paramInfo: [
   318            {   name: '__FILE__',
   319                dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
   320                dataTypeName: 'String',
   321                units: 'none',
   322                isHidden: false
   323            },
   324            {   name: '__LINE__',
   325                dataDesc: DvtTypes.DvtDataDesc_LINENUM,
   326                dataTypeName: 'Int',
   327                units: 'none',
   328                isHidden: false
   329            },
   330            {   name: 'Instance ID',
   331                dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
   332                dataTypeName: 'Int',
   333                units: 'none',
   334                isHidden: false
   335            },
   336            {   name: 'Words Processed',
   337                dataDesc: DvtTypes.DvtDataDesc_VALUE,
   338                dataTypeName: 'Int',
   339                units: 'words',
   340                isHidden: false
   341            }]
   342    
   343        };
   344    
   345        /*! ====== freeBytes ======
   346         *  Number of free bytes in heap.
   347         *
   348         * @a(Example)
   349         *   The following C code shows how to log a freeBytes
   350         *   event that tracks the number of bytes free in the heap
   351         *  @p(code)
   352         *  #include <xdc/runtime/Log.h>
   353         *  #include <ti/uia/events/UIAStatistic.h>
   354         *  ...
   355         * Void myFunction(){
   356         *   int heapId = 0x1234;    // change to heap ID
   357         *   int numBytesFree = 567; // change to number of bytes free on the heap
   358         *
   359         *   Log_write4(UIAStatistic_freeBytes, (IArg)__FILE__,(IArg)__LINE__,heapId,numFreeBytes);
   360         * }
   361         *  @p
   362         *  The following text will be displayed for the event:
   363         *  @p(code)
   364         *  Heap at Line 123 in demo.c (HeapId 0x1234): Free Bytes=567
   365         *  @p
   366         *  @param(__FILE__)           constant string identifying the file the event was logged from
   367         *  @param(__LINE__)           the line number the event was logged from
   368         *  @param(heapId)             heap identifier (e.g IHeap_Handle)
   369         *  @param(freeBytes)          the number of bytes free on the heap
   370         */
   371        config xdc.runtime.Log.Event freeBytes = {
   372            mask: Diags.ANALYSIS,
   373            msg: "Heap at %$F (HeapId 0x%x): Free Bytes=%d"
   374        };
   375    
   376        /*!
   377         *  ======== metaEventFreeBytes ========
   378         *  Metadata description of the FreeBytes event
   379         *
   380         *  @_nodoc
   381         */
   382        metaonly config DvtTypes.MetaEventDescriptor metaEventFreeBytes = {
   383            versionId: "2.0",
   384            analysisType: DvtTypes.DvtAnalysisType_STATISTIC,
   385            displayText: "Free Bytes",
   386            tooltipText: "Free Bytes in Heap",
   387            numParameters: 4,
   388            paramInfo: [
   389            {   name: '__FILE__',
   390                dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
   391                dataTypeName: 'String',
   392                units: 'none',
   393                isHidden: false
   394            },
   395            {   name: '__LINE__',
   396                dataDesc: DvtTypes.DvtDataDesc_LINENUM,
   397                dataTypeName: 'Int',
   398                units: 'none',
   399                isHidden: false
   400            },
   401            {   name: 'Heap ID',
   402                dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
   403                dataTypeName: 'Int',
   404                units: 'none',
   405                isHidden: false
   406            },
   407            {   name: 'Free Bytes',
   408                dataDesc: DvtTypes.DvtDataDesc_VALUE,
   409                dataTypeName: 'Int',
   410                units: 'bytes',
   411                isHidden: false
   412            }]
   413    
   414        };
   415    }