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     *  ======== LogCtxChg.xdc ========
    35     */
    36    package ti.uia.runtime;
    37    import xdc.runtime.Types;
    38    import ti.uia.runtime.LoggerTypes;
    39    import xdc.runtime.ILogger;
    40    import ti.uia.runtime.CtxFilter;
    41    import xdc.runtime.ILogger;
    42    import xdc.runtime.Diags;
    43    import xdc.runtime.Text;
    44    
    45    /*!
    46     *  ======== LogCtxChg ========
    47     *  Context Change Event logging manager for logging context change events
    48     *
    49     *  Allows context change events to be logged to a logger that is different from the one used by
    50     *  xdc.runtime.Log.
    51     *
    52     *  Users can provide a special function to inject context change information into trace or log
    53     *  sync points whenever a context change is logged.  See ctxFilterEnabled config parameter for more info.
    54     */
    55    @CustomHeader
    56    module LogCtxChg {
    57    
    58        /*!
    59         *  ======== isTimestampEnabled ========
    60         *  used to enable or disable logging the 64b local CPU timestamp
    61         *  at the start of each event
    62         */
    63        config Bool isTimestampEnabled = true;
    64    
    65        /*!
    66         *  ======== loggerDefined ========
    67         *  set to true in the configuration script when a logger that implements ILoggerSnapshot is attached
    68         */
    69        config Bool loggerDefined = false;
    70    
    71        /*!
    72         *  ======== ctxFilterEnabled ========
    73         *  set to true in the configuration script in order to enable context filtering.
    74         *
    75         *  User can implement a custom function that is called instead of ti_uia_runtime_CtxFilter_isCtxEnabled()
    76         *  to control context-aware filtering.  This function can also e.g. inject context information into
    77         *  the GEM trace or log sync point information if desired.
    78         *  @see ti.uia.runtime.CtxFilter
    79         */
    80         config Bool ctxFilterEnabled = false;
    81    
    82        /*!
    83         *  ======== loggerObj ========
    84         *  handle of the logger that is to be used to log snapshot events
    85         */
    86        config Ptr loggerObj = null;
    87    
    88        config xdc.runtime.Types.LoggerFxn2 loggerFxn2 = null;
    89        config xdc.runtime.Types.LoggerFxn8 loggerFxn8 = null;
    90    
    91        /*!
    92         *  ======== putCtxChg1 ========
    93         *  Unconditionally put the specified `Types` event along with file name, line number, fmt string and 1 arg.
    94         *
    95         *  This method unconditionally puts the specified context change`{@link Types#Event}`
    96         *  `evt` into the log along with the fmt string, line and file name that the event was logged from,
    97         *   and one parameter
    98         *
    99         *  @param(evt)   the `Types` event to put into the log
   100         *  @param(mask)  the diags mask of the event
   101         *  @param(syncPtSeqNum) the sync point sequence number to log with the event for correlation with trace
   102         *  @param(fmt)   a constant string that provides format specifiers for up to 6 additional parameters
   103         *  @param(arg1)  the context change argument to log
   104         */
   105        @Macro UInt32 putCtxChg1(Types.Event evt, Types.ModuleId mid, UInt32 syncPtSeqNum, IArg fmt, IArg arg1);
   106    
   107        /*!
   108         *  ======== putCtxChg2 ========
   109         *  Unconditionally put the specified `Types` event along with file name, line number, fmt string and 2 args.
   110         *
   111         *  This method unconditionally puts the specified context change`{@link Types#Event}`
   112         *  `evt` into the log along with the fmt string, line and file name that the event was logged from,
   113         *   and two parameters
   114         *
   115         *  @param(evt)   the `Types` event to put into the log
   116         *  @param(mask)  the diags mask of the event
   117         *  @param(a1)  the first context change argument to log
   118         *  @param(a2)  the second context change argument to log
   119         */
   120        @Macro UInt32 putCtxChg2(Types.Event evt, Types.ModuleId mid, IArg a1, IArg a2);
   121    
   122        /*!
   123         *  ======== putCtxChg8 ========
   124         *  Unconditionally put the specified `Types` event along with file name, line number, fmt string and 4 args.
   125         *
   126         *  This method unconditionally puts the specified context change`{@link Types#Event}`
   127         *  `evt` into the log along with the fmt string, line and file name that the event was logged from,
   128         *   and 4 parameters
   129         *
   130         *  @param(evt)   the `Types` event to put into the log
   131         *  @param(mask)  the diags mask of the event
   132         *  @param(syncPtSeqNum) the sync point sequence number to log with the event for correlation with trace
   133         *  @param(fmt)   a constant string that provides format specifiers for up to 6 additional parameters
   134         *  @param(a1)  the first context change argument to log
   135         *  @param(a2)  the second context change argument to log
   136         *  @param(a3)  the third context change argument to log
   137         *  @param(a4)  the fourth context change argument to log
   138         *  @param(a5)  the fifth context change argument to log
   139         *  @param(a6)  the sixth context change argument to log
   140         *  @param(a7)  the seventh context change argument to log
   141         *  @param(a8)  the eighth context change argument to log
   142         */
   143        @Macro UInt32 putCtxChg8(Types.Event evt, Types.ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4,IArg a5, IArg a6, IArg a7, IArg a8);
   144    
   145        /*!
   146         *  ======== ti_uia_runtime_LogCtxChg_app ========
   147         *  Log a context change event that can be used to enable context-aware event
   148         *  filtering, context-aware profiling, etc.
   149         *
   150         *  @see ti.uia.events.UIAAppCtx#ctxChg
   151         */
   152        @Macro Void app(String fmt, IArg newAppId);
   153    
   154        /*!
   155         *  ======== ti_uia_runtime_LogCtxChg_channel ========
   156         *  Log a context change event that can be used to enable context-aware event
   157         *  filtering, context-aware profiling, etc.
   158         *
   159         *  @see ti.uia.events.UIAChanCtx#ctxChg
   160         */
   161        @Macro Void channel(String fmt, IArg newChanId);
   162    
   163        /*!
   164         *  ======== ti_uia_runtime_LogCtxChg_thread ========
   165         *  Log a context change event that can be used to enable context-aware event
   166         *  filtering, context-aware profiling, etc.
   167         *
   168         *  @see ti.uia.events.UIAThreadCtx#ctxChg
   169         */
   170        @Macro Void thread(String fmt, IArg newThreadId);
   171    
   172        /*!
   173         *  ======== ti_uia_runtime_LogCtxChg_threadAndFunc ========
   174         *  Log a context change event that can be used to enable context-aware event
   175         *  filtering, context-aware profiling, etc.
   176         *
   177         *  @see ti.uia.events.UIAThreadCtx#ctxChgWithFunc
   178         */
   179        @Macro Void threadAndFunc(String fmt, IArg newThreadId, IArg oldFunc, IArg newFunc);
   180    
   181        /*!
   182         *  ======== ti_uia_runtime_LogCtxChg_frame ========
   183         *  Log a context change event that can be used to enable context-aware event
   184         *  filtering, context-aware profiling, etc.
   185         *
   186         *  @see ti.uia.events.UIAFrameCtx#ctxChg
   187         */
   188        @Macro Void frame(String fmt, IArg newFrameId);
   189    
   190    
   191        /*!
   192         *  ======== ti_uia_runtime_LogCtxChg_hwiStart ========
   193         *  Log a context change event that can be used to enable context-aware event
   194         *  filtering, context-aware profiling, etc.
   195         *
   196         *  @see ti.uia.events.UIAHWICtx#start
   197         */
   198        @Macro Void hwiStart(String fmt, IArg hwiId);
   199    
   200        /*!
   201         *  ======== ti_uia_runtime_LogCtxChg_hwiStop ========
   202         *  Log a context change event that can be used to enable context-aware event
   203         *  filtering, context-aware profiling, etc.
   204         *
   205         *  @see ti.uia.events.UIAHWICtx#stop
   206         */
   207         @Macro Void hwiStop(String fmt, IArg hwiId);
   208    
   209        /*!
   210         *  ======== ti_uia_runtime_LogCtxChg_swiStart ========
   211         *  Log a context change event that can be used to enable context-aware event
   212         *  filtering, context-aware profiling, etc.
   213         *
   214         *  @see ti.uia.events.UIASWICtx#start
   215         */
   216        @Macro Void swiStart(String fmt, IArg swiId);
   217        /*!
   218         *  ======== ti_uia_runtime_LogCtxChg_swiStop ========
   219         *  Log a context change event that can be used to enable context-aware event
   220         *  filtering, context-aware profiling, etc.
   221         *
   222         *  @see ti.uia.events.UIASWICtx#stop
   223         */
   224        @Macro Void swiStop(String fmt, IArg swiId);
   225    
   226        /*!
   227         *  ======== ti_uia_runtime_LogCtxChg_user ========
   228         *  Log a context change event that can be used to enable context-aware event
   229         *  filtering, context-aware profiling, etc.
   230         *
   231         *  @see ti.uia.events.UIAUserCtx#ctxChg
   232         */
   233        @Macro Void user(String fmt, IArg newCtxId);
   234    
   235    
   236        internal:
   237    
   238        /*
   239         *  ======== idToInfo ========
   240         *  Map event ID strings into a string of the form <eventName>::<eventMsg>
   241         */
   242        metaonly config String idToInfo[string] = [];
   243    }