1    /*
     2     * Copyright (c) 2013, 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     * ======== CtxFilter.xdc ========
    35     */
    36    
    37    import xdc.runtime.Diags;
    38    import xdc.rov.ViewInfo;
    39    
    40    /*!
    41     * Context-aware Instrumentation Event Filtering infrastructure
    42     */
    43    @CustomHeader
    44    module CtxFilter {
    45    
    46        /*!
    47         *  @_nodoc
    48         *  ======== ModuleView ========
    49         */
    50        metaonly struct ModuleView {
    51            Bits16 mFlags;
    52            Bits16 mEnableMask;
    53            Bool mIsLoggingEnabled;
    54        }
    55    
    56        /*!
    57         *  @_nodoc
    58         *  ======== rovViewInfo ========
    59         */
    60        @Facet
    61        metaonly config ViewInfo.Instance rovViewInfo =
    62            ViewInfo.create({
    63                viewMap: [
    64                    ['Module',   {type: ViewInfo.MODULE, viewInitFxn: 'viewInitModule', structName: 'ModuleView'}]
    65                ]
    66            });
    67    
    68        /*! Type used to specify bits in the context mask. */
    69        typedef Bits16 Mask;
    70    
    71        const Mask ALWAYS_ENABLED = 0x0000; /*! Event logging is not qualified by context */
    72    
    73        const Mask CONTEXT_ENABLED = true; /*! Enable logging at the call site (subject to Diags.Mask) */
    74        const Mask CONTEXT_DISABLED = false; /*! Disable logging at the call site */
    75    
    76        /*
    77         * ======== isCtxEnabled ========
    78         * Read the mIsLoggingEnabled flag
    79         *
    80         * Returns true if the context filter has been configured
    81         * to enable logging in the current execution context.
    82         *
    83         * @see(xdc.runtime.Diags#Mask)
    84         */
    85        @DirectCall
    86        Bool isCtxEnabled();
    87    
    88        /*
    89         * ======== setCtxEnabled ========
    90         * Set the Context Filter's isLoggingEnabled flag.
    91         * Returns the new value to simplify use in macros.
    92         */
    93        @DirectCall
    94        Bool setCtxEnabled(Bool value);
    95    
    96        /*!
    97         *  ======== setContextFilterFlags ========
    98         *  sets the context filter flags
    99         *
   100         * @param(flags) bitfield of flags, one per context filter type
   101         */
   102        @DirectCall
   103        Void setContextFilterFlags(Bits16 flags);
   104    
   105        /*!
   106         * ======== isLoggingEnabledForAppCtx ========
   107         * optional function to enable context-aware filtering based on application context
   108         *
   109         * Configure the ti.uia.events.UIAAppCtx.IsLoggingEnabledFxn with the
   110         * address of this function in order to enable context-aware filtering based on
   111         * application context.  Alternatively, you can write your own isLoggingEnabled function
   112         * that provides additional filtering and logging capabilities (e.g. it can log
   113         * sync points whenever the context changes).
   114         *
   115         * @param(newAppCtx)  the new application context id that has just been switched to
   116         * @a(return)         true if logging is enabled for this user context.
   117         */
   118        @DirectCall
   119        Bool isLoggingEnabledForAppCtx(Int newAppCtx);
   120    
   121        /*!
   122         * ======== isLoggingEnabledForChanCtx ========
   123         * optional function to enable context-aware filtering based on channel context
   124         *
   125         * Configure the ti.uia.events.UIAChanCtx.IsLoggingEnabledFxn with the
   126         * address of this function in order to enable context-aware filtering based on
   127         * channel context.  Alternatively, you can write your own isLoggingEnabled function
   128         * that provides additional filtering and logging capabilities (e.g. it can log
   129         * sync points whenever the context changes).
   130         *
   131         * @param(newChanId)  the new channel ID that has just been switched to
   132         * @a(return)          true if logging is enabled for this user context.
   133         */
   134        @DirectCall
   135        Bool isLoggingEnabledForChanCtx(Int newChanId);
   136    
   137    
   138        /*!
   139         * ======== isLoggingEnabledForFrameCtx ========
   140         * optional function to enable context-aware filtering based on frame context
   141         *
   142         * Configure the ti.uia.events.UIAFrameCtx.IsLoggingEnabledFxn with the
   143         * address of this function in order to enable context-aware filtering based on
   144         * frame context.  Alternatively, you can write your own isLoggingEnabled function
   145         * that provides additional filtering and logging capabilities (e.g. it can log
   146         * sync points whenever the context changes).
   147         *
   148         * @param(newFrameId)  the new Frame ID that has just been switched to
   149         * @a(return)          true if logging is enabled for this user context.
   150         */
   151        @DirectCall
   152        Bool isLoggingEnabledForFrameCtx(Int newFrameId);
   153    
   154    
   155        /*!
   156         * ======== isLoggingEnabledForThreadCtx ========
   157         * optional function to enable context-aware filtering based on user context
   158         *
   159         * Configure the ti.uia.events.UIAThreadCtx.IsLoggingEnabledFxn with the
   160         * address of this function in order to enable context-aware filtering based on
   161         * thread context.  Alternatively, you can write your own isLoggingEnabled function
   162         * that provides additional filtering and logging capabilities (e.g. it can log
   163         * sync points whenever the context changes).
   164         *
   165         * @param(newThreadId)  the new thread ID that has just been switched to
   166         * @a(return)          true if logging is enabled for this user context.
   167         */
   168         @DirectCall
   169         Bool isLoggingEnabledForThreadCtx(Int newThreadId);
   170    
   171        /*!
   172         * ======== isLoggingEnabledForUserCtx ========
   173         * optional function to enable context-aware filtering based on user context
   174         *
   175         * Configure the ti.uia.events.UIAUserCtx.IsLoggingEnabledFxn with the
   176         * address of this function in order to enable context-aware filtering based on
   177         * user context.  Alternatively, you can write your own isLoggingEnabled function
   178         * that provides additional filtering and logging capabilities (e.g. it can log
   179         * sync points whenever the context changes).
   180         *
   181         * @param(newUserCtx)  the new user context that has just been switched to
   182         * @a(return)          true if logging is enabled for this user context.
   183         */
   184         @DirectCall
   185         Bool isLoggingEnabledForUserCtx(Int newUserCtx);
   186    
   187    internal:
   188    
   189        struct Module_State {
   190            Bits16 mFlags;
   191            Bits16 mEnableMask;
   192            Bool mIsLoggingEnabled;
   193        };
   194    }