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     *  ======== UIAAppCtx.xdc ========
    35     */
    36    import xdc.runtime.Types;
    37    import xdc.runtime.Diags;
    38    import ti.uia.events.IUIACtx;
    39    
    40    /*!
    41     * UIA Application Context Instrumentation
    42     *
    43     * The UIAAppCtx module defines context change events
    44     * and methods that allow tooling to identify application context
    45     * switches and to enable application-aware filtering, trace and
    46     * analysis.
    47     *
    48     * It inherits IUIACtx, which defines a function pointer to
    49     * an isLoggingEnabled function which, if configured to point to
    50     * a function, will evaluate the function prior to logging the context
    51     * change event and will determine whether to log the event based on the
    52     * return value of the function.  If the function is not configured,
    53     * logging will be conditional upon ti_uia_runtime_CtxFilter_gIsLoggingEnabled.
    54     *
    55     *  The generation of UIAAppCtx events is also controlled by a module's diagnostics
    56     *  mask, which is described in details in `{@link xdc.runtime.Diags}`.
    57     * `UIAAppCtx` events are generated only when the Diags.ANALYSIS bit is set
    58     *  in the module's diagnostics mask.
    59     *
    60     *  The following configuration script demonstrates how the application might
    61     *  control the logging of ANALYSIS events embedded in the `Mod` module at configuration
    62     *  time. In this case, the configuration script arranges for the `Log`
    63     *  statements within modules to always generate ANALYSIS events.
    64     *  Without these configuration statements, no ANALYSIS events would be generated
    65     *  by any modules.
    66     *
    67     * @a(Examples)
    68     * Example 1: This is part of the XDC configuration file for the application:
    69     *
    70     *  @p(code)
    71     *  var LogCtxChg = xdc.useModule('ti.uia.runtime.LogCtxChg');
    72     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    73     *  var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
    74     *  var Defaults = xdc.useModule('xdc.runtime.Defaults');
    75     *  var logger = LoggerSys.create();
    76     *
    77     *  Defaults.common$.diags_ANALYSIS = Diags.ALWAYS_ON;
    78     *  Defaults.common$.logger = logger;
    79     *  @p
    80     *
    81     *  @p(html)
    82     *  <hr />
    83     *  @p
    84     *
    85     *  Example 2: The following example configures a module to support logging
    86     *  of ANALYSIS events, but defers the actual activation and deactivation of the
    87     *  logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
    88     *  function for details on specifying the control string.
    89     *
    90     *  This is a part of the XDC configuration file for the application:
    91     *
    92     *  @p(code)
    93     *  var LogCtxChg = xdc.useModule('ti.uia.runtime.LogCtxChg');
    94     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    95     *  var Mod = xdc.useModule('my.pkg.Mod');
    96     *
    97     *  Mod.common$.diags_ANALYSIS = Diags.RUNTIME_OFF;
    98     *  @p
    99     *
   100     *  This is a part of the C code for the application:
   101     *
   102     *  @p(code)
   103     *  // turn on logging of ANALYSIS events in the module
   104     *  Diags_setMask("my.pkg.Mod+Z");
   105     *
   106     *  // turn off logging of ANALYSIS events in the module
   107     *  Diags_setMask("my.pkg.Mod-Z");
   108     *  @p
   109     */
   110    @CustomHeader
   111    module UIAAppCtx inherits IUIACtx {
   112    
   113        /*!
   114         *  ======== ctxChg ========
   115         *  Application ID Context Change event
   116         *
   117         *  Used to log switching to a new application.
   118         *  Note that this event should not be referenced directly by user code - it is used
   119         *  internally by the LogCtxChg_app function, which logs the previous app Id automatically.
   120         *
   121         *  @a(Example)
   122         *   The following C code shows how to log a Context Change
   123         *   event that identifies a newly loaded application ID
   124         *
   125         *  @p(code)
   126         *  #include <ti/uia/runtime/LogCtxChg.h>
   127         *  ...
   128         *  Void loadApplication(Int newAppId){
   129         *    ...
   130         *    LogCtxChg_app("New AppID=0x%x",newAppId);
   131         *    ...
   132         *  }
   133         *  @p
   134         *  This event prints the Log call site (%$F) and a format string (%$S)
   135         *  which is recursively formatted with any addition arguments.
   136         *  The following text is an example of what will be displayed for the event:
   137         *  @p(code)
   138         *  "AppID Ctx Change at Line 123 in appLoader.c [Prev. AppID = 0x1234] New AppID=0x1235"
   139         *
   140         *  @param(fmt)   a constant string that describes the context change and provides a format specifier for newAppId
   141         *  @param(newAppId)   an integer which uniquely identifies the new application context
   142         */
   143        config xdc.runtime.Log.Event ctxChg = {
   144            mask: Diags.ANALYSIS,
   145            msg: "AppID Ctx Change at %$F [Prev. AppID=0x%x] %$S"};
   146    
   147        /*!
   148         *  ======== metaEventAppCtxChg ========
   149         *  Metadata description of the Application Context Change event
   150         *
   151         *  @_nodoc
   152         */
   153        metaonly config DvtTypes.MetaEventDescriptor metaEventAppCtxChg = {
   154            versionId: "2.0",
   155            analysisType: DvtTypes.DvtAnalysisType_CONTEXTCHANGE,
   156            displayText: "AppID Ctx Change",
   157            tooltipText: "Application ID Context Change",
   158            numParameters: 5,
   159            paramInfo: [
   160            {   name: '__FILE__',
   161                dataDesc: DvtTypes.DvtDataDesc_FILENAMESTR,
   162                dataTypeName: 'String',
   163                units: 'none',
   164                isHidden: false
   165            },
   166            {   name: '__LINE__',
   167                dataDesc: DvtTypes.DvtDataDesc_LINENUM,
   168                dataTypeName: 'Int',
   169                units: 'none',
   170                isHidden: false
   171            },
   172            {   name: 'Prev. App ID',
   173                dataDesc: DvtTypes.DvtDataDesc_APPID,
   174                dataTypeName: 'Int',
   175                units: 'none',
   176                isHidden: false
   177            },
   178            {   name: 'fmt',
   179                dataDesc: DvtTypes.DvtDataDesc_FMTSTR,
   180                dataTypeName: 'String',
   181                units: 'none',
   182                isHidden: false
   183            },
   184            {   name: 'New App ID',
   185                dataDesc: DvtTypes.DvtDataDesc_APPID,
   186                dataTypeName: 'Int',
   187                units: 'none',
   188                isHidden: false
   189            }]
   190    
   191        };
   192    
   193        /*!
   194         * ======== getCtxId ========
   195         * Get the ID for the current channel
   196         *
   197         *  @a(returns)
   198         *  returns the thread ID logged by the last call to UIAAppCtx_logCtxChg.
   199         */
   200        @Macro Int getCtxId();
   201    
   202        /*!
   203         * ======== isLoggingEnabled ========
   204         * returns true if the new context matches the value to enable logging with.
   205         *
   206         *  Default implementation of the IUIACtx_IsLoggingEnabledFxn for user context.
   207         *  To enable context-aware filtering, assign UIAAppCtx_isLoggingEnabledFxn = &UIAAppCtx_isLoggingEnabled
   208         *  in the config script or programmatically, or assign your own implementation of this
   209         *  function.
   210         *  @param(newChanId) the new channel ID
   211         *  @a(returns) true if logging is enabled
   212         */
   213         @DirectCall
   214         Bool isLoggingEnabled(UInt newAppId);
   215    
   216        /*!
   217         * ======== setOldValue =========
   218         * sets the ti_uia_events_UIAAppCtx_gLastValue to the new value and returns the old value before it was updated.
   219         *
   220         * @param(newValue) the new value to save in the global variable
   221         * @a(return0       the original value of the global variable before it was updated.
   222         */
   223         @DirectCall
   224         UInt setOldValue(UInt newValue);
   225    }