1    /* --COPYRIGHT--,BSD
     2     * Copyright (c) $(CPYYEAR), 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     * --/COPYRIGHT--*/
    32    
    33    /*
    34     * ======== UIASnapshot.xdc ========
    35     */
    36    
    37    import xdc.runtime.Diags;
    38    import xdc.runtime.Types;
    39    import ti.uia.events.DvtTypes;
    40    
    41    /*!
    42     * UIA Snapshot Events
    43     *
    44     * The UIASnapshot module defines events that allow
    45     * collection of dynamic information from the heap
    46     * such as memory ranges, strings, dynamically assigned names, etc.
    47     * Snapshot events can be aggregated together using a common snapshot ID
    48     * as an event parameter in order to build up a multi-event description of the
    49     * target state.  They are intended for use solely with the methods provided by
    50     * the {@link ti.uia.runtime.LogSnapshot ti.uia.runtime.LogSnapshot} module.
    51     * 
    52     *  The generation of UIASnapshot events is controlled by a module's diagnostics
    53     *  mask, which is described in details in `{@link xdc.runtime.Diags}`.
    54     * `UIASnapshot` events are generated only when the Diags.ANALYSIS bit is set 
    55     *  in the module's diagnostics mask. 
    56     *
    57     * The following special formatting specifiers are used in the definitions of the
    58     * msg fields of the UIASnapshot events:
    59     * %$S - a string parameter that can provide additional formatting specifiers
    60     *       Note that $S use in strings passed in as a paramter is not supported.
    61     *@p
    62     * %$F - a specifier for a string parameter containing the file name (__FILE__) and
    63     *       an integer parameter containing the line number (__LINE__).
    64     *
    65     *  The following configuration script demonstrates how the application might
    66     *  control the logging of ANALYSIS events embedded in the `Mod` module at configuration
    67     *  time. In this case, the configuration script arranges for the `Log`
    68     *  statements within modules to always generate ANALYSIS events.
    69     *  Without these configuration statements, no ANALYSIS events would be generated
    70     *  by any modules.
    71     *
    72     * @a(Examples)
    73     * Example 1: This is part of the XDC configuration file for the application:
    74     * (Note that the UIASnapshot module is automatically included by the 
    75     * LogSnapshot.xs script, and so does not need to be referenced in the
    76     * application's .cfg file)
    77     *  @p(code)
    78     *  var LogSnapshot = xdc.useModule('ti.uia.runtime.LogSnapshot');
    79     *  var LoggerCircBuf = xdc.useModule('ti.uia.runtime.LoggerCircBuf');
    80     *  var LoggerCircBufParams = new LoggerCircBuf.Params;
    81     *  // set the logger buffer size in bytes 
    82     *  LoggerCircBufParams.transferBufSize = 32768;  
    83     *  var logger = LoggerCircBuf.create(LoggerCircBufParams);
    84     *  
    85     *  // Configure all modules to always log Analysis events, including
    86     *  // UIASnapshot events
    87     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    88     *  var Defaults = xdc.useModule('xdc.runtime.Defaults');
    89     *  Defaults.common$.diags_ANALYSIS = Diags.ALWAYS_ON; 
    90     *  Defaults.common$.logger = logger;
    91     *  
    92     *  @p
    93     *
    94     *  @p(html)
    95     *  <hr />
    96     *  @p
    97     *
    98     *  Example 2: The following example configures a module to support logging
    99     *  of ANALYSIS events, but defers the actual activation and deactivation of the
   100     *  logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
   101     *  function for details on specifying the control string.
   102     *
   103     *  This is part of the XDC configuration file for the application:
   104     *  @p(code)
   105     *  var LogSnapshot = xdc.useModule('ti.uia.runtime.LogSnapshot');
   106     *  var Diags = xdc.useModule('xdc.runtime.Diags');
   107     *  var Mod = xdc.useModule('my.pkg.Mod');
   108     *
   109     *  Mod.common$.diags_ANALYSIS = Diags.RUNTIME_OFF;
   110     *  @p
   111     *
   112     *  This is a part of the C code for the application:
   113     *
   114     *  @p(code)
   115     *  // turn on logging of ANALYSIS events in the module
   116     *  Diags_setMask("my.pkg.Mod+Z");
   117     *
   118     *  // turn off logging of ANALYSIS events in the module
   119     *  Diags_setMask("my.pkg.Mod-Z");
   120     *  @p
   121     */
   122    module UIASnapshot inherits IUIAEvent {
   123    
   124        /*!
   125         *  ======== memoryRange ========
   126         *  Analysis event posted when a memoryRange snapshot is logged.
   127         *  
   128         *  This event is used internally by the 
   129         *  {@link ti.uia.runtime.LogSnapshot#writeMemoryBlock LogSnapshot.writeMemoryBlock}
   130         *  API.
   131         *
   132         * @a(Examples)
   133         * Example: The following C code shows how to log a snapshot event to 
   134         *   capture a block of memory.
   135         *  
   136         *  @p(code)
   137         *  #include <ti/uia/runtime/LogSnapshot.h> 
   138         *  ...
   139         *  UInt32* pIntArray = (UInt32 *)malloc(sizeof(UInt32) * 200);   
   140         *  ...  
   141         *  LogSnapshot_writeMemoryBlock(0,"pIntArray ptr=0x%x, numBytes=%d",(UInt32)pIntArray,200);
   142         *  ...
   143         *  @p
   144         *  This event prints the Log call site (%$F) and a format string (%$S)
   145         *  which describes what information the event is logging.     
   146         *  The following text will be displayed for the event, if it was logged
   147         *  from file demo.c at line 1234 and all 200 bytes were logged in the
   148         *  same event.  
   149         *  @p(code)
   150         *  Memory Snapshot at [demo.c:1234] [snapshotID=0,adrs=0x80002000,
   151         *    numMAUsDataInEvent=200,numMAUsDataInRecord=200] ptr=0x80002000, numBytes=200
   152         *  @p
   153         *  If the 200 bytes were spread across multiple events,
   154         *  the numMAUsDataInRecord would indicate how many bytes were in the
   155         *  memory block, and numMAUsDataInEvent would indicate how many bytes
   156         *  were stored in that particular event. 
   157         *  @p
   158         *  @param(__FILE__)   The file that the LogSnapshot call site was in (used by %$F)
   159         *  @param(__LINE__)   The line of code of the LogSnapshot call site (used by %$F)
   160         *  @param(snapshotID) ID used to identify snapshot events taken at the same 
   161         *                     time. Set to 0 for first in series, set rest to return 
   162         *                     value of LogSnapshot API.
   163         *  @param(startAdrs)  the start address of the range of memory
   164         *  @param(numMAUsDataInEvent) the number of MAUs of data payload for this event
   165         *  @param(numMAUsDataInRecord) the total number of MAUs of data payload for the                     
   166         *                     multi-event data record 
   167         *  @param(fmt)        a constant string that provides a user-readable description
   168         *                     of what information the event is capturing 
   169         */
   170        config xdc.runtime.Log.Event memoryRange = {
   171            mask: Diags.ANALYSIS,
   172            msg: "Memory Snapshot at %$F% [snapshotID=%d,adrs=0x%x,numMAUsDataInEvent=%hd,numMAUsDataInRecord=%hd] %$S"
   173        };
   174    
   175        /*!
   176         *  ======== metaEventMemoryRange ========
   177         *  Metadata description of the memoryRange event
   178         *
   179         *  @_nodoc
   180         */
   181        metaonly config DvtTypes.MetaEventDescriptor metaEventMemoryRange = {
   182            versionId: "2.0",
   183            analysisType: DvtTypes.DvtAnalysisType_MEMORYSNAPSHOT,
   184            displayText: "Memory Snapshot",
   185            tooltipText: "Memory Snapshot",
   186            numParameters: 8,
   187            paramInfo: [
   188            {   name: 'filename',
   189                dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
   190                dataTypeName: 'String',
   191                units: 'none',
   192                isHidden: false
   193            },
   194            {   name: 'linenum',
   195                dataDesc: DvtTypes.DvtDataDesc_LINENUM,
   196                dataTypeName: 'Int',
   197                units: 'none',
   198                isHidden: false
   199            },
   200            {   name: 'snapshotID',
   201                dataDesc: DvtTypes.DvtDataDesc_SNAPSHOTID,
   202                dataTypeName: 'UInt32',
   203                units: 'none',
   204                isHidden: false
   205            },
   206            {   name: 'startAdrs',
   207                dataDesc: DvtTypes.DvtDataDesc_DATAADRS,
   208                dataTypeName: 'Ptr',
   209                units: 'none',
   210                isHidden: false
   211            },
   212            {   name: 'numMAUsDataInEvent',
   213                dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
   214                dataTypeName: 'Int16',
   215                units: 'none',
   216                isHidden: false,
   217                lsb: 16
   218            },
   219            {   name: 'numMAUsDataInRecord',
   220                dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
   221                dataTypeName: 'Int16',
   222                units: 'none',
   223                isHidden: false,
   224                lsb: 0
   225            },
   226            {   name: 'fmt',
   227                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   228                dataTypeName: 'String',
   229                units: 'none',
   230                isHidden: false
   231            },
   232            {   name: 'data',
   233                dataDesc: DvtTypes.DvtDataDesc_DATAARRAY,
   234                dataTypeName: 'Int32',
   235                units: 'none',
   236                isHidden: false
   237            }
   238            ]
   239        };
   240        /*!
   241         *  ======== stringOnHeap ========
   242         *  Analysis event posted when a string snapshot is logged
   243         *
   244         *  This event is used internally by the 
   245         *  {@link ti.uia.runtime.LogSnapshot#writeString LogSnapshot.writeString}
   246         *  API.
   247         *  @a(Example)
   248         *   The following C code shows how to log a snapshot event to capture a 
   249         *   block of memory.
   250         *  
   251         *  @p(code)
   252         *  #include <ti/uia/runtime/LogSnapshot.h> 
   253         *  ...
   254         *  Void myFunc(String name){
   255         *     ...
   256         *     LogSnapshot_stringOnHeap(0,"User-defined name=%s.",name, strlen(name));
   257         *  }
   258         *  @p
   259         *  The following text will be displayed for the event, if it was logged
   260         *  from file demo.c at line 1234 and all bytes in the 40 character string 
   261         *  was logged in the same event.  
   262         *  @p(code)
   263         *  String Snapshot at [../demo.c:1234] [snapshotID=0,adrs=0x80001234,40,40] User-defined name=ValueOfParm.   
   264         *  @p  
   265         *   and a format string (%$S)
   266         *  which describes what information the event is logging.      *  
   267         *  @param(__FILE__)   The file that the LogSnapshot call site was in (used by %$F)
   268         *  @param(__LINE__)   The line of code of the LogSnapshot call site (used by %$F)
   269         *  @param(snapshotID) ID used to identify snapshot events taken at the same 
   270         *                     time. Set to 0 for first in series, set rest to return 
   271         *                     value of LogSnapshot API.
   272         *  @param(adrs)       the start address of the string in memory
   273         *  @param(numMAUsDataInEvent) the number of MAUs of data payload for this event
   274         *  @param(numMAUsDataInRecord) the total number of MAUs of data payload for the                     
   275         *                     multi-event data record 
   276         *  @param(fmt)        a constant string that provides a user-readable description
   277         *                     of what information the event is capturing                           
   278         */
   279        config xdc.runtime.Log.Event stringOnHeap = {
   280            mask: Diags.ANALYSIS,
   281            msg: "String Snapshot at %$F [snapshotID=%d,adrs=0x%x,numMAUsDataInEvent=%hd,numMAUsDataInRecord=%hd] %$S"
   282        };
   283    
   284        /*!
   285         *  ======== metaEventStringOnHeap ========
   286         *  Metadata description of the stringOnHeap event
   287         *
   288         *  @_nodoc
   289         */
   290        metaonly config DvtTypes.MetaEventDescriptor metaEventStringOnHeap = {
   291            versionId: "2.0",
   292            analysisType: DvtTypes.DvtAnalysisType_STRINGSNAPSHOT,
   293            displayText: "String Snapshot",
   294            tooltipText: "String Snapshot",
   295            numParameters: 8,
   296            paramInfo: [
   297            {   name: 'filename',
   298                dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
   299                dataTypeName: 'String',
   300                units: 'none',
   301                isHidden: false
   302            },
   303            {   name: 'linenum',
   304                dataDesc: DvtTypes.DvtDataDesc_LINENUM,
   305                dataTypeName: 'Int',
   306                units: 'none',
   307                isHidden: false
   308            },
   309            {   name: 'snapshotID',
   310                dataDesc: DvtTypes.DvtDataDesc_SNAPSHOTID,
   311                dataTypeName: 'UInt32',
   312                units: 'none',
   313                isHidden: false
   314            },
   315            {   name: 'startAdrs',
   316                dataDesc: DvtTypes.DvtDataDesc_DATAADRS,
   317                dataTypeName: 'Ptr',
   318                units: 'none',
   319                isHidden: false
   320            },
   321            {   name: 'numMAUsDataInEvent',
   322                dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
   323                dataTypeName: 'Int16',
   324                units: 'none',
   325                isHidden: false,
   326                lsb: 16
   327            },
   328            {   name: 'numMAUsDataInRecord',
   329                dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
   330                dataTypeName: 'Int16',
   331                units: 'none',
   332                isHidden: false,
   333                lsb: 0
   334            },
   335            {   name: 'fmt',
   336                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   337                dataTypeName: 'String',
   338                units: 'none',
   339                isHidden: false
   340            },
   341            {   name: 'data',
   342                dataDesc: DvtTypes.DvtDataDesc_DATAARRAY,
   343                dataTypeName: 'Int32',
   344                units: 'none',
   345                isHidden: false
   346            }
   347            ]
   348        };
   349        /*!
   350         *  ======== nameOfReference ========
   351         *  Used to log the contents of a dynamic string on the heap so that host-side
   352         *  tooling can display this string as the name of handle / reference ID 
   353         *
   354         *  This event is used internally by the 
   355         *  {@link ti.uia.runtime.LogSnapshot#nameOfReference LogSnapshot.nameOfReference}
   356         *  API.
   357         *
   358         *  @a(Example)
   359         *   The following C code shows how to log a task name for use by task 
   360         *   execution graphs etc.
   361         *  
   362         *  @p(code)
   363         *  #include <ti/uia/runtime/LogSnapshot.h> 
   364         *  #include <ti/sysbios/BIOS.h>
   365         *  #include <ti/sysbios/knl/Task.h>
   366         *  ...
   367         *  // Task create hook function that logs the task name.
   368         *  // Notes: Task name is not trequired when creating a BIOS task. Please \
   369         *  // make sure a name is provided in order for the host side analysis tool
   370         *  // to work properly.
   371         *  Void  tskCreateHook(Task_Handle hTask, Error_Block *eb) {
   372         *          String name;
   373         *          name = Task_Handle_name(hTask);
   374         *          LogSnapshot_writeNameOfReference(hTask,"Task_create name=%s",
   375         *            name,strlen(name)+1);
   376         *  }
   377         *  @p
   378         *  This event prints the Log call site (%$F) and a format string (%$S)
   379         *  which describes what information the event is logging. 
   380         *  The following text will be displayed for the event:
   381         *  @p(code)
   382         *  nameOfReference at [demo.c:line 1234] [refID=0x80002000,adrs=0x80001234,40,40] Task_create: name=10msThread.     
   383         *  @param(__FILE__)   The file that the LogSnapshot call site was in (used by %$F)
   384         *  @param(__LINE__)   The line of code of the LogSnapshot call site (used by %$F)
   385         *  @param(refID)      reference ID (e.g. task handle) that the name is 
   386         *                       associated with
   387         *  @param(adrs)       the start address of the string in memory
   388         *  @param(numMAUsDataInEvent) the number of MAUs of data payload for this event
   389         *  @param(numMAUsDataInRecord) the total number of MAUs of data payload for the                     
   390         *                     multi-event data record 
   391         *  @param(fmt)        a constant string that provides a user-readable description
   392         *                     of what information the event is capturing  
   393         */
   394        config xdc.runtime.Log.Event nameOfReference = {
   395            mask: Diags.ANALYSIS,
   396            msg: "nameOfReference at %$F [refID=0x%x,adrs=0x%x,numMAUsDataInEvent=%hd numMAUsDataInRecord=%hd] %$S"
   397        };
   398    
   399        /*!
   400         *  ======== metaEventNameOfReference ========
   401         *  Metadata description of the NameOfReference event
   402         *
   403         *  @_nodoc
   404         */
   405        metaonly config DvtTypes.MetaEventDescriptor metaEventNameOfReference = {
   406            versionId: "2.0",
   407            analysisType: DvtTypes.DvtAnalysisType_NAMESNAPSHOT,
   408            displayText: "Name Of Reference ID",
   409            tooltipText: "Name Of Reference ID",
   410            numParameters: 8,
   411            paramInfo: [
   412            {   name: 'filename',
   413                dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
   414                dataTypeName: 'String',
   415                units: 'none',
   416                isHidden: false
   417            },
   418            {   name: 'linenum',
   419                dataDesc: DvtTypes.DvtDataDesc_LINENUM,
   420                dataTypeName: 'Int',
   421                units: 'none',
   422                isHidden: false
   423            },
   424            {   name: 'referenceID',
   425                dataDesc: DvtTypes.DvtDataDesc_REFERENCEID,
   426                dataTypeName: 'UInt32',
   427                units: 'none',
   428                isHidden: false
   429            },
   430            {   name: 'startAdrs',
   431                dataDesc: DvtTypes.DvtDataDesc_DATAADRS,
   432                dataTypeName: 'Ptr',
   433                units: 'none',
   434                isHidden: false
   435            },
   436            {   name: 'numMAUsDataInEvent',
   437                dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
   438                dataTypeName: 'Int16',
   439                units: 'none',
   440                isHidden: false,
   441                lsb: 16
   442            },
   443            {   name: 'numMAUsDataInRecord',
   444                dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
   445                dataTypeName: 'Int16',
   446                units: 'none',
   447                isHidden: false,
   448                lsb: 0
   449            },
   450            {   name: 'fmt',
   451                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   452                dataTypeName: 'String',
   453                units: 'none',
   454                isHidden: false
   455            },
   456            {   name: 'data',
   457                dataDesc: DvtTypes.DvtDataDesc_DATAARRAY,
   458                dataTypeName: 'Int32',
   459                units: 'none',
   460                isHidden: false
   461            }
   462            ]
   463        };
   464    }
   465    
   466    /*
   467     *! Revision History
   468     *! ================
   469     *! 23-Jun-2010 toddm Started revision history
   470     */