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     * ======== 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         *  #include <string.h> // for strlen
   254         *  ...
   255         *  Void myFunc(String name){
   256         *     ...
   257         *     //Upload the memory contents of the dynamically allocated string 'name'
   258         *     LogSnapshot_stringOnHeap(0,"name",name, strlen(name));
   259         *     //Now that the string memory contents have been uploaded,
   260         *     //subsequent events that reference the string will be properly
   261         *     //rendered.
   262         *     Log_info1("User-defined name=%s.",name);
   263         *  }
   264         *  @p
   265         *  The following text will be displayed for the event, if LogSnapshot was called
   266         *  from file demo.c at line 1234 and the value of "name" was "aUserDefinedName".
   267         *  @p(code)
   268         *  String Snapshot at [../demo.c:1234] [snapshotID=0,adrs=0x80001234,40,40] name.
   269         *  "demo.c", line 1235: User-defined name=aUserDefinedName.
   270         *  @p
   271         *
   272         *  @param(__FILE__)   The file that the LogSnapshot call site was in (used by %$F)
   273         *  @param(__LINE__)   The line of code of the LogSnapshot call site (used by %$F)
   274         *  @param(snapshotID) ID used to identify snapshot events taken at the same
   275         *                     time. Set to 0 for first in series, set rest to return
   276         *                     value of LogSnapshot API.
   277         *  @param(adrs)       the start address of the string in memory
   278         *  @param(numMAUsDataInEvent) the number of MAUs of data payload for this event
   279         *  @param(numMAUsDataInRecord) the total number of MAUs of data payload for the
   280         *                     multi-event data record
   281         *  @param(fmt)        a constant string that provides a user-readable description
   282         *                     of what information the event is capturing
   283         */
   284        config xdc.runtime.Log.Event stringOnHeap = {
   285            mask: Diags.ANALYSIS,
   286            msg: "String Snapshot at %$F [snapshotID=%d,adrs=0x%x,numMAUsDataInEvent=%hd,numMAUsDataInRecord=%hd] %$S"
   287        };
   288    
   289        /*!
   290         *  ======== metaEventStringOnHeap ========
   291         *  Metadata description of the stringOnHeap event
   292         *
   293         *  @_nodoc
   294         */
   295        metaonly config DvtTypes.MetaEventDescriptor metaEventStringOnHeap = {
   296            versionId: "2.0",
   297            analysisType: DvtTypes.DvtAnalysisType_STRINGSNAPSHOT,
   298            displayText: "String Snapshot",
   299            tooltipText: "String Snapshot",
   300            numParameters: 8,
   301            paramInfo: [
   302            {   name: 'filename',
   303                dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
   304                dataTypeName: 'String',
   305                units: 'none',
   306                isHidden: false
   307            },
   308            {   name: 'linenum',
   309                dataDesc: DvtTypes.DvtDataDesc_LINENUM,
   310                dataTypeName: 'Int',
   311                units: 'none',
   312                isHidden: false
   313            },
   314            {   name: 'snapshotID',
   315                dataDesc: DvtTypes.DvtDataDesc_SNAPSHOTID,
   316                dataTypeName: 'UInt32',
   317                units: 'none',
   318                isHidden: false
   319            },
   320            {   name: 'startAdrs',
   321                dataDesc: DvtTypes.DvtDataDesc_DATAADRS,
   322                dataTypeName: 'Ptr',
   323                units: 'none',
   324                isHidden: false
   325            },
   326            {   name: 'numMAUsDataInEvent',
   327                dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
   328                dataTypeName: 'Int16',
   329                units: 'none',
   330                isHidden: false,
   331                lsb: 16
   332            },
   333            {   name: 'numMAUsDataInRecord',
   334                dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
   335                dataTypeName: 'Int16',
   336                units: 'none',
   337                isHidden: false,
   338                lsb: 0
   339            },
   340            {   name: 'fmt',
   341                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   342                dataTypeName: 'String',
   343                units: 'none',
   344                isHidden: false
   345            },
   346            {   name: 'data',
   347                dataDesc: DvtTypes.DvtDataDesc_DATAARRAY,
   348                dataTypeName: 'Int32',
   349                units: 'none',
   350                isHidden: false
   351            }
   352            ]
   353        };
   354        /*!
   355         *  ======== nameOfReference ========
   356         *  Used to log the contents of a dynamic string on the heap so that host-side
   357         *  tooling can display this string as the name of handle / reference ID
   358         *
   359         *  This event is used internally by the
   360         *  {@link ti.uia.runtime.LogSnapshot#nameOfReference LogSnapshot.nameOfReference}
   361         *  API.
   362         *
   363         *  @a(Example)
   364         *   The following C code shows how to log a task name for use by task
   365         *   execution graphs etc.
   366         *
   367         *  @p(code)
   368         *  #include <ti/uia/runtime/LogSnapshot.h>
   369         *  #include <ti/sysbios/BIOS.h>
   370         *  #include <ti/sysbios/knl/Task.h>
   371         *  ...
   372         *  // Task create hook function that logs the task name.
   373         *  // Notes: Task name is not trequired when creating a BIOS task. Please \
   374         *  // make sure a name is provided in order for the host side analysis tool
   375         *  // to work properly.
   376         *  Void  tskCreateHook(Task_Handle hTask, Error_Block *eb) {
   377         *          String name;
   378         *          name = Task_Handle_name(hTask);
   379         *          LogSnapshot_writeNameOfReference(hTask,"Task_create name=%s",
   380         *            name,strlen(name)+1);
   381         *  }
   382         *  @p
   383         *  This event prints the Log call site (%$F) and a format string (%$S)
   384         *  which describes what information the event is logging.
   385         *  The following text will be displayed for the event:
   386         *  @p(code)
   387         *  nameOfReference at [demo.c:line 1234] [refID=0x80002000,adrs=0x80001234,40,40] Task_create: name=10msThread.
   388         *  @param(__FILE__)   The file that the LogSnapshot call site was in (used by %$F)
   389         *  @param(__LINE__)   The line of code of the LogSnapshot call site (used by %$F)
   390         *  @param(refID)      reference ID (e.g. task handle) that the name is
   391         *                       associated with
   392         *  @param(adrs)       the start address of the string in memory
   393         *  @param(numMAUsDataInEvent) the number of MAUs of data payload for this event
   394         *  @param(numMAUsDataInRecord) the total number of MAUs of data payload for the
   395         *                     multi-event data record
   396         *  @param(fmt)        a constant string that provides a user-readable description
   397         *                     of what information the event is capturing
   398         */
   399        config xdc.runtime.Log.Event nameOfReference = {
   400            mask: Diags.ANALYSIS,
   401            msg: "nameOfReference at %$F [refID=0x%x,adrs=0x%x,numMAUsDataInEvent=%hd numMAUsDataInRecord=%hd] %$S"
   402        };
   403    
   404        /*!
   405         *  ======== metaEventNameOfReference ========
   406         *  Metadata description of the NameOfReference event
   407         *
   408         *  @_nodoc
   409         */
   410        metaonly config DvtTypes.MetaEventDescriptor metaEventNameOfReference = {
   411            versionId: "2.0",
   412            analysisType: DvtTypes.DvtAnalysisType_NAMESNAPSHOT,
   413            displayText: "Name Of Reference ID",
   414            tooltipText: "Name Of Reference ID",
   415            numParameters: 8,
   416            paramInfo: [
   417            {   name: 'filename',
   418                dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
   419                dataTypeName: 'String',
   420                units: 'none',
   421                isHidden: false
   422            },
   423            {   name: 'linenum',
   424                dataDesc: DvtTypes.DvtDataDesc_LINENUM,
   425                dataTypeName: 'Int',
   426                units: 'none',
   427                isHidden: false
   428            },
   429            {   name: 'referenceID',
   430                dataDesc: DvtTypes.DvtDataDesc_REFERENCEID,
   431                dataTypeName: 'UInt32',
   432                units: 'none',
   433                isHidden: false
   434            },
   435            {   name: 'startAdrs',
   436                dataDesc: DvtTypes.DvtDataDesc_DATAADRS,
   437                dataTypeName: 'Ptr',
   438                units: 'none',
   439                isHidden: false
   440            },
   441            {   name: 'numMAUsDataInEvent',
   442                dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
   443                dataTypeName: 'Int16',
   444                units: 'none',
   445                isHidden: false,
   446                lsb: 16
   447            },
   448            {   name: 'numMAUsDataInRecord',
   449                dataDesc: DvtTypes.DvtDataDesc_LENGTHINMAUS,
   450                dataTypeName: 'Int16',
   451                units: 'none',
   452                isHidden: false,
   453                lsb: 0
   454            },
   455            {   name: 'fmt',
   456                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   457                dataTypeName: 'String',
   458                units: 'none',
   459                isHidden: false
   460            },
   461            {   name: 'data',
   462                dataDesc: DvtTypes.DvtDataDesc_DATAARRAY,
   463                dataTypeName: 'Int32',
   464                units: 'none',
   465                isHidden: false
   466            }
   467            ]
   468        };
   469    }