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     * ======== UIASWICtx.xdc ========
    35     */
    36    
    37    import xdc.runtime.Types;
    38    import xdc.runtime.Diags;
    39    import ti.uia.events.IUIACtx;
    40    
    41    /*!
    42     * UIA Software Interrupt Context Instrumentation
    43     *
    44     * The UIASWICtx module defines context change events
    45     * and methods that allow tooling to identify software interrupt context
    46     * switches and to enable SWI-aware filtering, trace and
    47     * analysis.
    48     *
    49     * Note: in order to reduce overhead, UIASWICtx does not support context-aware filtering
    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 Swi = xdc.useModule('ti.sysbios.hal.Swi');
    72     *  Swi.addHookSet({
    73     *    beginFxn: '&swiBeginHook',
    74     *    endFxn: '&swiEndHook'
    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    
   108    module UIASWICtx inherits IUIACtx {
   109    
   110        /*!
   111         *  ======== start ========
   112         *  Software Interrupt start event
   113         *
   114         *  Used to log the start of a Software Interrupt service routine
   115         *
   116         *  @a(Example)
   117         *   The following C code shows how to log a Context Change
   118         *   event that identifies the start of a SWI.  It implements
   119         *   a BIOS hook function.  Alternatively, the LogCtxChg_swiStart
   120         *   API can be called directly from the SWI service routine.
   121         *
   122         *  @p(code)
   123         *  #include <ti/uia/runtime/LogCtxChg.h>
   124         *   ...
   125         *  Void swiBeginHook(Swi_Handle handle) {
   126             *    LogCtxChg_swiStart("Swi_Handle:0x%x",handle);
   127         *  }
   128         *  @p
   129         *  This event has an associated format string (%$S)
   130         *  which is recursively formatted with any addition arguments.
   131         *  The following text is an example of what will be displayed for the event:
   132         *  @p(code)
   133         *  "SWI start: Swi_Handle:0x80001200"
   134         *
   135         *  @param(fmt)   a constant string that describes the SWI and provides a format specifier for the SWI handle
   136         *  @param(handle)   an integer which uniquely identifies the SWI
   137         */
   138        config xdc.runtime.Log.Event start = {
   139            mask: Diags.ANALYSIS,
   140            msg: "SWI start: %$S"
   141        };
   142        /*!
   143         *  ======== metaEventHwiStart ========
   144         *  Metadata description of the HWI Start event
   145         *
   146         *  @_nodoc
   147         */
   148        metaonly config DvtTypes.MetaEventDescriptor metaEventSwiStart = {
   149            versionId: "2.0",
   150            analysisType: DvtTypes.DvtAnalysisType_START,
   151            displayText: "SWI Start",
   152            tooltipText: "SWI Start",
   153            numParameters: 2,
   154            paramInfo: [
   155            {   name: 'fmt',
   156                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   157                dataTypeName: 'String',
   158                units: 'none',
   159                isHidden: false
   160            },
   161            {   name: 'SWI ID',
   162                dataDesc: DvtTypes.DvtDataDesc_SWIID,
   163                dataTypeName: 'Int',
   164                units: 'none',
   165                isHidden: false
   166            }]
   167    
   168        };
   169        /*!
   170         *  ======== stop ========
   171         *  Software Interrupt Stop event
   172         *
   173         *  Used to log the end of a Software Interrupt service routine
   174         *  @a(Example)
   175         *   The following C code shows how to log a Context Change
   176         *   event that identifies the end of a SWI.  It implements
   177         *   a BIOS hook function.  Alternatively, the LogCtxChg_swiStop
   178         *   API can be called directly from the SWI service routine.
   179         *
   180         *  @p(code)
   181         *  #include <ti/uia/runtime/LogCtxChg.h>
   182         *   ...
   183         *  Void swiEndHook(Swi_Handle handle) {
   184             *    LogCtxChg_swiStop("Swi_Handle:0x%x",handle);
   185         *  }
   186         *  @p
   187         *  This event has an associated format string (%$S)
   188         *  which is recursively formatted with any addition arguments.
   189         *  The following text is an example of what will be displayed for the event:
   190         *  @p(code)
   191         *  "SWI stop: Swi_Handle:0x80001200"
   192         *
   193         *  @param(fmt)   a constant string that describes the HWI and provides a format specifier for the HWI handle
   194         *  @param(handle)   an integer which uniquely identifies the HWI
   195         */
   196        config xdc.runtime.Log.Event stop = {
   197            mask: Diags.ANALYSIS,
   198            msg: "SWI stop: %$S"
   199        };
   200    
   201        /*!
   202         *  ======== metaEventSwiStop ========
   203         *  Metadata description of the SWI Stop event
   204         *
   205         *  @_nodoc
   206         */
   207        metaonly config DvtTypes.MetaEventDescriptor metaEventSwiStop = {
   208            versionId: "2.0",
   209            analysisType: DvtTypes.DvtAnalysisType_STOP,
   210            displayText: "SWI Exit",
   211            tooltipText: "SWI Exit",
   212            numParameters: 2,
   213            paramInfo: [
   214            {   name: 'fmt',
   215                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   216                dataTypeName: 'String',
   217                units: 'none',
   218                isHidden: false
   219            },
   220            {   name: 'SWI ID',
   221                dataDesc: DvtTypes.DvtDataDesc_SWIID,
   222                dataTypeName: 'Int',
   223                units: 'none',
   224                isHidden: false
   225            }]
   226    
   227        };
   228    
   229    }