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     * ======== UIAHWICtx.xdc
    35     */
    36    import xdc.runtime.Types;
    37    import xdc.runtime.Diags;
    38    import ti.uia.events.IUIACtx;
    39    
    40    /*!
    41     * UIA Hardware Interrupt Context Instrumentation
    42     *
    43     * The UIAHWICtx module defines context change events
    44     * and methods that allow tooling to identify hardware interrupt context
    45     * switches and to enable HWI-aware filtering, trace and
    46     * analysis.
    47     *
    48     * Note: in order to reduce overhead, UIAHWICtx does not support context-aware filtering
    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 LogCtxChg = xdc.useModule('ti.uia.runtime.LogCtxChg');
    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     *
    70     *  // BIOS specific configuration:
    71     *  var Hwi = xdc.useModule('ti.sysbios.hal.Hwi');
    72     *  Hwi.addHookSet({
    73     *    beginFxn: '&hwiBeginHook',
    74     *    endFxn: '&hwiEndHook'
    75     *   });
    76     *  @p
    77     *
    78     *  @p(html)
    79     *  <hr />
    80     *  @p
    81     *
    82     * Example 2: The following example configures a module to support logging
    83     * of ANALYSIS events, but defers the actual activation and deactivation of the
    84     * logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
    85     * function for details on specifying the control string.
    86     *
    87     * This is a part of the XDC configuration file for the application:
    88     *
    89     *  @p(code)
    90     *  var LogCtxChg = xdc.useModule('ti.uia.runtime.LogCtxChg');
    91     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    92     *  var Mod = xdc.useModule('my.pkg.Mod');
    93     *
    94     *  Mod.common$.diags_ANALYSIS = Diags.RUNTIME_OFF;
    95     *  @p
    96     *
    97     *  This is a part of the C code for the application:
    98     *
    99     *  @p(code)
   100     *  // turn on logging of ANALYSIS events in the module
   101     *  Diags_setMask("my.pkg.Mod+Z");
   102     *
   103     *  // turn off logging of ANALYSIS events in the module
   104     *  Diags_setMask("my.pkg.Mod-Z");
   105     *  @p
   106     */
   107    module UIAHWICtx inherits IUIACtx {
   108    
   109        /*!
   110         *  ======== start ========
   111         *  Hardware Interrupt start event
   112         *
   113         *  Used to log the start of a hardware interrupt service routine
   114         *
   115         *  @a(Example)
   116         *   The following C code shows how to log a Context Change
   117         *   event that identifies the start of a HWI.  It implements
   118         *   a BIOS hook function.  Alternatively, the LogCtxChg_hwiStart
   119         *   API can be called directly from the HWI service routine.
   120         *
   121         *  @p(code)
   122         *  #include <ti/uia/runtime/LogCtxChg.h>
   123         *   ...
   124         *  Void hwiBeginHook(Hwi_Handle handle) {
   125         *    LogCtxChg_hwiStart("Hwi_Handle:0x%x",handle);
   126         *  }
   127         *  @p
   128         *  This event has an associated format string (%$S)
   129         *  which is recursively formatted with any addition arguments.
   130         *  The following text is an example of what will be displayed for the event:
   131         *  @p(code)
   132         *  "HWI start: Hwi_Handle:0x80001200"
   133         *
   134         *  @param(fmt)   a constant string that describes the HWI and provides a format specifier for the HWI handle
   135         *  @param(handle)   an integer which uniquely identifies the HWI
   136         */
   137        config xdc.runtime.Log.Event start = {
   138            mask: Diags.ANALYSIS,
   139            msg: "HWI start: %$S"
   140        };
   141        /*!
   142         *  ======== metaEventHwiStart ========
   143         *  Metadata description of the HWI Start event
   144         *
   145         *  @_nodoc
   146         */
   147        metaonly config DvtTypes.MetaEventDescriptor metaEventHwiStart = {
   148            versionId: "2.0",
   149            analysisType: DvtTypes.DvtAnalysisType_START,
   150            displayText: "HWI Start",
   151            tooltipText: "HWI Start",
   152            numParameters: 2,
   153            paramInfo: [
   154            {   name: 'fmt',
   155                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   156                dataTypeName: 'String',
   157                units: 'none',
   158                isHidden: false
   159            },
   160            {   name: 'HWI ID',
   161                dataDesc: DvtTypes.DvtDataDesc_HWIID,
   162                dataTypeName: 'Int',
   163                units: 'none',
   164                isHidden: false
   165            }]
   166    
   167        };
   168        /*!
   169         *  ======== stop ========
   170         *  Hardware Interrupt exit event
   171         *
   172         *  Used to log the end of a hardware interrupt service routine
   173         *  @a(Example)
   174         *   The following C code shows how to log a Context Change
   175         *   event that identifies the end of a HWI.  It implements
   176         *   a BIOS hook function.  Alternatively, the LogCtxChg_hwiStop
   177         *   API can be called directly from the HWI service routine.
   178         *
   179         *  @p(code)
   180         *  #include <ti/uia/runtime/LogCtxChg.h>
   181         *   ...
   182         *  Void hwiEndHook(Hwi_Handle handle) {
   183         *    LogCtxChg_hwiStop("Hwi_Handle:0x%x",handle);
   184         *  }
   185         *  @p
   186         *  This event has an associated format string (%$S)
   187         *  which is recursively formatted with any addition arguments.
   188         *  The following text is an example of what will be displayed for the event:
   189         *  @p(code)
   190         *  "HWI stop: Hwi_Handle:0x80001200"
   191         *
   192         *  @param(fmt)   a constant string that describes the HWI and provides a format specifier for the HWI handle
   193         *  @param(handle)   an integer which uniquely identifies the HWI
   194         */
   195        config xdc.runtime.Log.Event stop = {
   196            mask: Diags.ANALYSIS,
   197            msg: "HWI stop: %$S"
   198        };
   199    
   200        /*!
   201         *  ======== metaEventHwiStop ========
   202         *  Metadata description of the HWI Stop event
   203         *
   204         *  @_nodoc
   205         */
   206        metaonly config DvtTypes.MetaEventDescriptor metaEventHwiStop = {
   207            versionId: "2.0",
   208            analysisType: DvtTypes.DvtAnalysisType_STOP,
   209            displayText: "HWI Exit",
   210            tooltipText: "HWI Exit",
   211            numParameters: 2,
   212            paramInfo: [
   213            {   name: 'fmt',
   214                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   215                dataTypeName: 'String',
   216                units: 'none',
   217                isHidden: false
   218            },
   219            {   name: 'HWI ID',
   220                dataDesc: DvtTypes.DvtDataDesc_HWIID,
   221                dataTypeName: 'Int',
   222                units: 'none',
   223                isHidden: false
   224            }]
   225    
   226        };
   227    
   228    }