1    /*
     2     * Copyright (c) 2012-2013, 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     * ======== UIAProfile.xdc ========
    35     */
    36    
    37    import xdc.runtime.Diags;
    38    import xdc.runtime.Types;
    39    import ti.uia.events.DvtTypes;
    40    
    41    /*!
    42     * UIA Profile Events
    43     *
    44     * The UIAProfile module defines events that allow
    45     * tooling to analyze the performance of the software
    46     * (processing time, latency, etc.).  These events are
    47     * designed to be logged from function-entry and function-exit
    48     * hook functions that are called by compiler-generated code
    49     *
    50     * TI compilers can be configured to either pass in a parameter
    51     * to the hook functions containing either the address
    52     * of the function or the name of the function.
    53     *
    54     * If the compiler is configured to pass in the address of the function,
    55     * the `UIAProfile_enterFunctionAdrs` event should be logged by the
    56     * entry hook function and the `UIAProfile_exitFunctionAdrs` event
    57     * should be logged by the exit hook function.
    58     *
    59     * If the compiler is configured to pass in the name of the function,
    60     * the `UIAProfile_enterFunctionName` event should be logged by the
    61     * entry hook function and the `UIAProfile_exitFunctionName` event
    62     * should be logged by the exit hook function.
    63     *
    64     * When logging events using the xdc.runtime.Log module, the generation
    65     * of UIAProfile events is controlled by the `Diags.ENTRY` and `Diags.EXIT`
    66     * flags in a module's diagnostics  mask.  (For more information on
    67     * diagnostics masks, please see the xdc.runtime.Diags documentation.)
    68     *
    69     * By default, the UIAProfile module will automatically set both the
    70     * `Main.common$.Diags_ENTRY` and `Main.common$.Diags_EXIT` flags to
    71     * `Diags.ALWAYS_ON` if these flags have not been previously configured.
    72     * To turn off these flags at configuration time, set
    73     * `UIAProfile.enable = false;`  To allow these flags to be configured
    74     * at run time, set `UIAProfile.runtimeControl = true;`
    75     *
    76     * @a(Examples)
    77     * Example 1: This is part of the XDC configuration file for the application:
    78     *
    79     *  @p(code)
    80     *  var UIAProfile = xdc.useModule('ti.uia.events.UIAProfile');
    81     *  var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
    82     *  @p
    83     *
    84     *  @p(html)
    85     *  <hr />
    86     *  @p
    87     *
    88     *  Example 2: The following example configures a module to support logging
    89     *  of ENTRY and EXIT events, but defers the actual activation and deactivation of the
    90     *  logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
    91     *  function for details on specifying the control string.
    92     *
    93     *  This is a part of the XDC configuration file for the application:
    94     *
    95     *  @p(code)
    96     *  var UIAProfile = xdc.useModule('ti.uia.events.UIAProfile');
    97     *  UIAProfile.runtimeControl = true;
    98     *  UIAProfile.enable = false;
    99     *  @p
   100     *
   101     *  This is a part of the C code for the application.
   102     *  The diags_ENTRY mask is set by "E", and the diags_EXIT mask is set by "X".
   103     *
   104     *  @p(code)
   105     *  #include <xdc/runtime/Diags.h>
   106     *  #include <xdc/runtime/Main.h>
   107     *
   108     *  // turn on logging of ENTRY and EXIT events in the module
   109     *  Diags_setMask("xdc.runtime.Main+EX");
   110     *
   111     *  // turn off logging of ENTRY and EXIT events in the module
   112     *  Diags_setMask("xdc.runtime.Main-EX");
   113     *  @p
   114     *
   115     *
   116     */
   117    module UIAProfile inherits IUIAEvent {
   118    
   119        /*!
   120         *  ======== enterFunctionAdrs ========
   121         *  Profiling event used to log the entry point of a function
   122         *
   123         * @a(Example)
   124         * To add entry and exit hook functions to every function
   125         * 1. Use the following compiler options when compiling the source
   126         *  @p(code)
   127         *  --entry_hook=functionEntryHook
   128         *  --entry_param=address
   129         *  --exit_hook=functionExitHook
   130         *  --exit_param=address
   131         *  @p
   132         * 2. Add the following c code to implement the hook functions:
   133         *   The first parameter (the taskHandle) is set to  0 in this example.
   134         *   @see exitFunction for an example of how to log the current task ID
   135         *   for task-aware function profiling.
   136         *   In order to further reduce the CPU overhead of logging the
   137             *   UIAProfile events, you can use the LogUC.h APIs. For more info, please
   138             *   see @link http://processors.wiki.ti.com/index.php/SystemAnalyzerTutorial1F
   139         *  @p(code)
   140         *  #include <xdc/runtime/Log.h>
   141         *  #include <ti/uia/events/UIAProfile.h>
   142         *  ...
   143         * void functionEntryHook( void (*adrs)() ){
   144         *    Log_write2(UIAProfile_enterFunctionAdrs, 0,(IArg)adrs);
   145         *   ...
   146         * void functionExitHook( void (*adrs)() ){
   147         *    Log_write2(UIAProfile_exitFunctionAdrs, 0,(IArg)adrs);
   148         * }
   149         *  @p
   150         *  The following text will be displayed for the event:
   151         *  @p(code)
   152         *  enterFunctionAdrs: taskHandle=0x0, adrs=0x820060
   153         *  exitFunctionAdrs: taskHandle0x0, adrs=0x820060
   154         *  @p
   155         *  @param(taskHandle)   task handle that identifies the currently active task (use 0 if not required)
   156         *  @param(functionAdrs) the address of a function that can differentiate this pair of start and stop events from others
   157         */
   158        config xdc.runtime.Log.Event enterFunctionAdrs = {
   159            mask: Diags.ENTRY,
   160            msg: "enterFunctionAdrs: taskHandle=0x%x, adrs=0x%x"
   161        };
   162    
   163        /*!
   164         *  ======== metaEventEnterFunctionAdrs ========
   165         *  Metadata description of the enterFunctionAdrs event
   166         *
   167         *  @_nodoc
   168         */
   169        metaonly config DvtTypes.MetaEventDescriptor metaEventEnterFunctionAdrs = {
   170            versionId: "2.0",
   171            analysisType: DvtTypes.DvtAnalysisType_START,
   172            displayText: "enterFunctionAdrs",
   173            tooltipText: "function entry",
   174            numParameters: 2,
   175            paramInfo: [
   176            {   name: 'Qualifier',
   177                dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
   178                dataTypeName: 'Int',
   179                units: 'none',
   180                isHidden: false
   181            },
   182            {   name: 'FunctionAdrs',
   183                dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
   184                dataTypeName: 'Int',
   185                units: 'none',
   186                isHidden: false
   187            }
   188            ]
   189        };
   190    
   191    
   192        /*!
   193         *  ======== exitFunctionAdrs ========
   194         *  Profiling event used to log the exit point of a function
   195         *
   196         * @a(Example)
   197         * To add entry and exit hook functions to every function
   198         * 1. Use the following compiler options when compiling the source
   199         *  @p(code)
   200         *  --entry_hook=functionEntryHook
   201         *  --entry_param=address
   202         *  --exit_hook=functionExitHook
   203         *  --exit_param=address
   204         *  @p
   205         * 2. Add the following c code to implement the hook functions:
   206         *   Task_selfMacro() is used to get the current task handle in this example.
   207         *   @see enterFunction for an example of how to save CPU by logging 0
   208         *   instead of the task handle if task-aware profiling is not required.
   209         *   In order to further reduce the CPU overhead of logging the
   210             *   UIAProfile events, you can use the LogUC.h APIs. For more info, please
   211             *   see @link http://processors.wiki.ti.com/index.php/SystemAnalyzerTutorial1F
   212         *  @p(code)
   213         *  #include <xdc/runtime/Log.h>
   214         *  #include <ti/uia/events/UIAProfile.h>
   215         *  #include <ti/sysbios/knl/Task.h>
   216         *  ...
   217         * void functionEntryHook( void (*adrs)() ){
   218         *    Log_write2(UIAProfile_enterFunctionAdrs, (IArg)Task_selfMacro(),(IArg)addr);
   219         *   ...
   220         * void functionExitHook( void (*adrs)() ){
   221         *    Log_write2(UIAProfile_exitFunctionAdrs, (IArg)Task_selfMacro(),(IArg)addr);
   222         * }
   223         *  @p
   224         *  The following text will be displayed for the event:
   225         *  @p(code)
   226         *  enterFunctionAdrs: taskHandle=0x0, adrs=0x820060
   227         *  exitFunctionAdrs: taskHandle=0x0, adrs=0x820060
   228         *  @p
   229         *  @param(taskHandle)   task handle that identifies the currently active task (use 0 if not required)
   230         *  @param(functionAdrs) the address of a function that can differentiate this pair of start and stop events from others
   231         */
   232        config xdc.runtime.Log.Event exitFunctionAdrs = {
   233            mask: Diags.EXIT,
   234            msg: "exitFunctionAdrs: taskHandle=0x%x, adrs=0x%x"
   235        };
   236    
   237        /*!
   238         *  ======== metaEventExitFunction ========
   239         *  Metadata description of the exitFunctionAdrs event
   240         *
   241         *  @_nodoc
   242         */
   243        metaonly config DvtTypes.MetaEventDescriptor metaEventExitFunctionAdrs = {
   244            versionId: "2.0",
   245            analysisType: DvtTypes.DvtAnalysisType_STOP,
   246            displayText: "exitFunctionAdrs",
   247            tooltipText: "Marks the end of analysis for a module instance",
   248            numParameters: 2,
   249            paramInfo: [
   250            {   name: 'Qualifier',
   251                dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
   252                dataTypeName: 'Int',
   253                units: 'none',
   254                isHidden: false
   255            },
   256            {   name: 'FunctionAdrs',
   257                dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
   258                dataTypeName: 'Int',
   259                units: 'none',
   260                isHidden: false
   261            }
   262            ]
   263        };
   264    
   265        /*!
   266         *  ======== enterFunctionName ========
   267         *  Profiling event used to log the entry point of a function
   268         *
   269         * @a(Example)
   270         * To add entry and exit hook functions to every function
   271         * 1. Use the following compiler options when compiling the source
   272         *  @p(code)
   273         *  --entry_hook=functionEntryHook
   274         *  --entry_param=name
   275         *  --exit_hook=functionExitHook
   276         *  --exit_param=name
   277         *  @p
   278         * 2. Add the following c code to implement the hook functions:
   279         *   The first parameter (the taskHandle) is set to  0 in this example.
   280         *   @see exitFunction for an example of how to log the current task ID
   281         *   for task-aware function profiling.
   282         *   In order to further reduce the CPU overhead of logging the
   283         *   UIAProfile events, you can use the LogUC.h APIs. For more info, please
   284         *   see @link http://processors.wiki.ti.com/index.php/SystemAnalyzerTutorial1F
   285         *  @p(code)
   286         *  #include <xdc/runtime/Log.h>
   287         *  #include <ti/uia/events/UIAProfile.h>
   288         *  ...
   289         * void functionEntryHook(const char* name ){
   290         *    Log_write2(UIAProfile_enterFunctionName, 0,(IArg)name);
   291         *   ...
   292         * void functionExitHook(const char* name){
   293         *    Log_write2(UIAProfile_exitFunctionName, 0,(IArg)name);
   294         * }
   295         *  @p
   296         *  The following text will be displayed for the event:
   297         *  @p(code)
   298         *  enterFunctionName: taskHandle=0x0, name=myFunctionName
   299         *  exitFunctionName: taskHandle0x0, name=myFunctionName
   300         *  @p
   301         *  @param(taskHandle)   task handle that identifies the currently active task (use 0 if not required)
   302         *  @param(functionName) the (const char*) name of the function that is passed to the hook fn by the compiler
   303         */
   304        config xdc.runtime.Log.Event enterFunctionName = {
   305            mask: Diags.ENTRY,
   306            msg: "enterFunctionName: taskHandle=0x%x, name=%s"
   307        };
   308    
   309        /*!
   310         *  ======== metaEventEnterFunctionName ========
   311         *  Metadata description of the enterFunctionName event
   312         *
   313         *  @_nodoc
   314         */
   315        metaonly config DvtTypes.MetaEventDescriptor metaEventEnterFunctionName = {
   316            versionId: "2.0",
   317            analysisType: DvtTypes.DvtAnalysisType_START,
   318            displayText: "enterFunctionName",
   319            tooltipText: "function entry",
   320            numParameters: 2,
   321            paramInfo: [
   322            {   name: 'Qualifier',
   323                dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
   324                dataTypeName: 'Int',
   325                units: 'none',
   326                isHidden: false
   327            },
   328            {   name: 'FunctionAdrs',
   329                dataDesc: DvtTypes.DvtDataDesc_STRINGADRS,
   330                dataTypeName: 'Int',
   331                units: 'none',
   332                isHidden: false
   333            }
   334            ]
   335        };
   336    
   337    
   338        /*!
   339         *  ======== exitFunctionName ========
   340         *  Profiling event used to log the exit point of a function
   341         *
   342         * @a(Example)
   343         * To add entry and exit hook functions to every function
   344         * 1. Use the following compiler options when compiling the source
   345         *  @p(code)
   346         *  --entry_hook=functionEntryHook
   347         *  --entry_param=name
   348         *  --exit_hook=functionExitHook
   349         *  --exit_param=name
   350         *  @p
   351         * 2. Add the following c code to implement the hook functions:
   352         *   Task_selfMacro() is used to get the current task handle in this example.
   353         *   @see enterFunction for an example of how to save CPU by logging 0
   354         *   instead of the task handle if task-aware profiling is not required.
   355         *   In order to further reduce the CPU overhead of logging the
   356         *   UIAProfile events, you can use the LogUC.h APIs. For more info, please
   357         *   see @link http://processors.wiki.ti.com/index.php/SystemAnalyzerTutorial1F
   358         *  @p(code)
   359         *  #include <xdc/runtime/Log.h>
   360         *  #include <ti/uia/events/UIAProfile.h>
   361         *  #include <ti/sysbios/knl/Task.h>
   362         *  ...
   363         * void functionEntryHook(const char* name){
   364         *    Log_write2(UIAProfile_enterFunctionName, (IArg)Task_selfMacro(),(IArg)name);
   365         *   ...
   366         * void functionExitHook(const char* name){
   367         *    Log_write2(UIAProfile_exitFunctionName, (IArg)Task_selfMacro(),(IArg)name);
   368         * }
   369         *  @p
   370         *  The following text will be displayed for the event:
   371         *  @p(code)
   372         *  enterFunctionName: taskHandle=0x0, adrs=myFunctionName
   373         *  exitFunctionName: taskHandle=0x0, name=myFunctionName
   374         *  @p
   375         *  @param(taskHandle)   task handle that identifies the currently active task (use 0 if not required)
   376         *  @param(functionName) the (const char*) name of the function that is passed to the hook fn by the compiler
   377         */
   378        config xdc.runtime.Log.Event exitFunctionName = {
   379            mask: Diags.EXIT,
   380            msg: "exitFunctionName: taskHandle=0x%x, name=%s"
   381        };
   382    
   383        /*!
   384         *  ======== metaEventExitFunctionName ========
   385         *  Metadata description of the exitFunctionName event
   386         *
   387         *  @_nodoc
   388         */
   389        metaonly config DvtTypes.MetaEventDescriptor metaEventExitFunctionName = {
   390            versionId: "2.0",
   391            analysisType: DvtTypes.DvtAnalysisType_STOP,
   392            displayText: "exitFunctionName",
   393            tooltipText: "Marks the end of analysis for a module instance",
   394            numParameters: 2,
   395            paramInfo: [
   396            {   name: 'Qualifier',
   397                dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
   398                dataTypeName: 'Int',
   399                units: 'none',
   400                isHidden: false
   401            },
   402            {   name: 'FunctionAdrs',
   403                dataDesc: DvtTypes.DvtDataDesc_STRINGADRS,
   404                dataTypeName: 'Int',
   405                units: 'none',
   406                isHidden: false
   407            }
   408            ]
   409        };
   410    
   411        /*!
   412         *  ======== runtimeControl ========
   413         *  Specify whether profile events can be enabled / disabled at runtime.
   414         *  (set to false by default)
   415         *
   416         *  This determines what diags settings are applied to the module's diags
   417         *  mask.
   418         *  if the UIAProfile enable config property is true (default):
   419         *    If runtimeControl = 'false' the diags bits will be configured as
   420         *    ALWAYS_ON, meaning they can't be changed at runtime.
   421         *    If runtimeControl = 'true', the bits will be configured as 'RUNTIME_ON'.
   422         *
   423         * if the UIAProfile enable config property is false:
   424         *    If runtimeControl = 'false' the diags bits will be configured as
   425         *    ALWAYS_OFF, meaning they can't be changed at runtime.
   426         *    If runtimeControl = 'true', the bits will be configured as 'RUNTIME_OFF'.
   427         */
   428        metaonly config Bool runtimeControl = false;
   429    
   430        /*!
   431         *  ======== enable ========
   432         *  Specify whether profile events are enabled or disabled
   433         *  (set to true by default)
   434         *
   435         *  if the UIAProfile enable config property is true (default):
   436         *    If runtimeControl = 'false' the diags bits will be configured as
   437         *    ALWAYS_ON, meaning they can't be changed at runtime.
   438         *    If runtimeControl = 'true', the bits will be configured as 'RUNTIME_ON'.
   439         *
   440         * if the UIAProfile enable config property is false:
   441         *    If runtimeControl = 'false' the diags bits will be configured as
   442         *    ALWAYS_OFF, meaning they can't be changed at runtime.
   443         *    If runtimeControl = 'true', the bits will be configured as 'RUNTIME_OFF'.
   444         */
   445        metaonly config Bool enable = true;
   446    }