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     * ======== 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.)
    47     *
    48     *  The generation of UIAProfile events is controlled by a module's diagnostics
    49     *  mask, which is described in detail in `{@link xdc.runtime.Diags}`.
    50     * `UIAProfile_enterFunction` events are generated only when the Diags.ENTRY bit
    51     *  in the module's diagnostics mask is set, and 'UIAProfile_exitFunction' events
    52     *  are generated only when the Diags.EXIT bit is set.
    53     *
    54     *  The following configuration script demonstrates how the application might
    55     *  control the logging of events embedded in the `Mod` module at configuration
    56     *  time. In this case, the configuration script arranges for the `Log`
    57     *  statements within modules to always generate ENTRY and EXIT events.
    58     *  Without these configuration statements, no events would be generated
    59     *  by any modules.
    60     *
    61     * @a(Examples)
    62     * Example 1: This is part of the XDC configuration file for the application:
    63     *
    64     *  @p(code)
    65     *  var UIAProfile = xdc.useModule('ti.uia.events.UIAProfile');
    66     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    67     *  var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
    68     *  var Defaults = xdc.useModule('xdc.runtime.Defaults');
    69     *  var logger = LoggerSys.create();
    70     *
    71     *  Defaults.common$.diags_ENTRY = Diags.ALWAYS_ON;
    72     *  Defaults.common$.diags_EXIT = Diags.ALWAYS_ON;
    73     *  Defaults.common$.logger = logger;
    74     *  @p
    75     *
    76     *  @p(html)
    77     *  <hr />
    78     *  @p
    79     *
    80     *  Example 2: The following example configures a module to support logging
    81     *  of ENTRY and EXIT events, but defers the actual activation and deactivation of the
    82     *  logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
    83     *  function for details on specifying the control string.
    84     *
    85     *  This is a part of the XDC configuration file for the application:
    86     *
    87     *  @p(code)
    88     *  var UIAProfile = xdc.useModule('ti.uia.events.UIAProfile');
    89     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    90     *  var Mod = xdc.useModule('my.pkg.Mod');
    91     *
    92     *  Mod.common$.diags_ENTRY = Diags.RUNTIME_OFF;
    93     *  Mod.common$.diags_EXIT = Diags.RUNTIME_OFF;
    94     *  @p
    95     *
    96     *  This is a part of the C code for the application.
    97     *  The diags_ENTRY mask is set by "E", and the diags_EXIT mask is set by "X".
    98     *
    99     *  @p(code)
   100     *  // turn on logging of ENTRY and EXIT events in the module
   101     *  Diags_setMask("my.pkg.Mod+EX");
   102     *
   103     *  // turn off logging of ENTRY and EXIT events in the module
   104     *  Diags_setMask("my.pkg.Mod-EX");
   105     *  @p
   106     *
   107     *
   108     */
   109    module UIAProfile inherits IUIAEvent {
   110    
   111        /*!
   112         *  ======== enterFunction ========
   113         *  Profiling event used to log the entry point of a function
   114         *
   115         * @a(Example)
   116         * To add entry and exit hook functions to every function
   117         * 1. Use the following compiler options when compiling the source
   118         *  @p(code)
   119         *  --entry_hook=functionEntryHook
   120         *  --entry_param=address
   121         *  --exit_hook=functionExitHook
   122         *  --exit_param=address
   123         *  @p
   124         * 2. Add the following c code to implement the hook functions:
   125         *   The first parameter (the taskHandle) is set to  0 in this example.
   126         *   @see exitFunction for an example of how to log the current task ID
   127         *   for task-aware function profiling.
   128         *
   129         *  @p(code)
   130         *  #include <xdc/runtime/Log.h>
   131         *  #include <ti/uia/events/UIAProfile.h>
   132         *  ...
   133         * void functionEntryHook( void (*addr)() ){
   134         *    Log_write2(UIAProfile_enterFunction, 0,(IArg)addr);
   135         *   ...
   136         * void functionExitHook( void (*addr)() ){
   137         *    Log_write2(UIAProfile_exitFunction, 0,(IArg)addr);
   138         * }
   139         *  @p
   140         *  The following text will be displayed for the event:
   141         *  @p(code)
   142         *  enterFunction: taskHandle=0x0, adrs=0x820060
   143         *  exitFunction: taskHandle0x0, adrs=0x820060
   144         *  @p
   145         *  @param(taskHandle)          task handle that identifies the currently active task (use 0 if not required)
   146         *  @param(functionAdrs)        the address of a function that can differentiate this pair of start and stop events from others
   147         */
   148        config xdc.runtime.Log.Event enterFunction = {
   149            mask: Diags.ENTRY,
   150            msg: "enterFunction: taskHandle=0x%x, adrs=0x%x"
   151        };
   152    
   153        /*!
   154         *  ======== metaEventEnterFunction ========
   155         *  Metadata description of the enterFunction event
   156         *
   157         *  @_nodoc
   158         */
   159        metaonly config DvtTypes.MetaEventDescriptor metaEventEnterFunction = {
   160            versionId: "2.0",
   161            analysisType: DvtTypes.DvtAnalysisType_START,
   162            displayText: "enterFunction",
   163            tooltipText: "function entry",
   164            numParameters: 2,
   165            paramInfo: [
   166            {   name: 'Qualifier',
   167                dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
   168                dataTypeName: 'Int',
   169                units: 'none',
   170                isHidden: false
   171            },
   172            {   name: 'FunctionAdrs',
   173                dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
   174                dataTypeName: 'Int',
   175                units: 'none',
   176                isHidden: false
   177            }
   178            ]
   179        };
   180    
   181    
   182        /*!
   183         *  ======== exitFunction ========
   184         *  Profiling event used to log the exit point of a function
   185         *
   186         * @a(Example)
   187         * To add entry and exit hook functions to every function
   188         * 1. Use the following compiler options when compiling the source
   189         *  @p(code)
   190         *  --entry_hook=functionEntryHook
   191         *  --entry_param=address
   192         *  --exit_hook=functionExitHook
   193         *  --exit_param=address
   194         *  @p
   195         * 2. Add the following c code to implement the hook functions:
   196         *   Task_selfMacro() is used to get the current task handle in this example.
   197         *   @see enterFunction for an example of how to save CPU by logging 0
   198         *   instead of the task handle if task-aware profiling is not required.
   199         *
   200         *  @p(code)
   201         *  #include <xdc/runtime/Log.h>
   202         *  #include <ti/uia/events/UIAProfile.h>
   203         *  #include <ti/sysbios/knl/Task.h>
   204         *  ...
   205         * void functionEntryHook( void (*addr)() ){
   206         *    Log_write2(UIAProfile_enterFunction, (IArg)Task_selfMacro(),(IArg)addr);
   207         *   ...
   208         * void functionExitHook( void (*addr)() ){
   209         *    Log_write2(UIAProfile_exitFunction, (IArg)Task_selfMacro(),(IArg)addr);
   210         * }
   211         *  @p
   212         *  The following text will be displayed for the event:
   213         *  @p(code)
   214         *  enterFunction: taskHandle=0x0, adrs=0x820060
   215         *  exitFunction: taskHandle=0x0, adrs=0x820060
   216         *  @p
   217         *  @param(taskHandle)          task handle that identifies the currently active task (use 0 if not required)
   218         *  @param(functionAdrs)        the address of a function that can differentiate this pair of start and stop events from others
   219         */
   220        config xdc.runtime.Log.Event exitFunction = {
   221            mask: Diags.EXIT,
   222            msg: "exitFunction: taskHandle=0x%x, adrs=0x%x"
   223        };
   224    
   225        /*!
   226         *  ======== metaEventExitFunction ========
   227         *  Metadata description of the exitFunction event
   228         *
   229         *  @_nodoc
   230         */
   231        metaonly config DvtTypes.MetaEventDescriptor metaEventExitFunction = {
   232            versionId: "2.0",
   233            analysisType: DvtTypes.DvtAnalysisType_STOP,
   234            displayText: "exitFunction",
   235            tooltipText: "Marks the end of analysis for a module instance",
   236            numParameters: 2,
   237            paramInfo: [
   238            {   name: 'Qualifier',
   239                dataDesc: DvtTypes.DvtDataDesc_INSTANCE,
   240                dataTypeName: 'Int',
   241                units: 'none',
   242                isHidden: false
   243            },
   244            {   name: 'FunctionAdrs',
   245                dataDesc: DvtTypes.DvtDataDesc_FUNCTIONADRS,
   246                dataTypeName: 'Int',
   247                units: 'none',
   248                isHidden: false
   249            }
   250            ]
   251        };
   252    
   253    
   254    }