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     * ======== CtxFilter.xdc ========
    35     */
    36    
    37    import xdc.runtime.Diags;
    38    
    39    /*!
    40     * Context-aware Instrumentation Event Filtering infrastructure
    41     */
    42    @CustomHeader
    43    module CtxFilter {
    44    
    45        extern Bits16 ti_uia_runtime_CtxFilter_gFlags;
    46        extern Bits16 ti_uia_runtime_CtxFilter_gEnableMask;
    47        extern Bool ti_uia_runtime_CtxFilter_gIsLoggingEnabled;
    48    
    49        /*! Type used to specify bits in the context mask. */
    50        typedef Bits16 Mask;
    51    
    52        const Mask ALWAYS_ENABLED = 0x0000; /*! Event logging is not qualified by context */
    53    
    54        const Mask CONTEXT_ENABLED = true; /*! Enable logging at the call site (subject to Diags.Mask) */
    55        const Mask CONTEXT_DISABLED = false; /*! Disable logging at the call site */
    56    
    57        /*
    58         * ======== isCtxEnabled ========
    59         * Read the ti_uia_events_gIsLoggingEnabled flag
    60         *
    61         * Returns true if the context filter has been configured
    62         * to enable logging in the current execution context.
    63         *
    64         * @see(xdc.runtime.Diags#Mask)
    65         */
    66        @Macro Bool isCtxEnabled();
    67    
    68        /*!
    69         *  ======== setContextFilterFlags ========
    70         *  sets the context filter flags
    71         *
    72         * @param(flags) bitfield of flags, one per context filter type
    73         */
    74        @DirectCall
    75        Void setContextFilterFlags(Bits16 flags);
    76    
    77    
    78        /*!
    79         * ======== isLoggingEnabledForChanCtx ========
    80         * optional function to enable context-aware filtering based on channel context
    81         *
    82         * Configure the ti.uia.events.UIAChanCtx.IsLoggingEnabledFxn with the
    83         * address of this function in order to enable context-aware filtering based on
    84         * channel context.  Alternatively, you can write your own isLoggingEnabled function
    85         * that provides additional filtering and logging capabilities (e.g. it can log
    86         * sync points whenever the context changes).
    87         *
    88         * @param(newChanId)  the new channel ID that has just been switched to
    89         * @a(return)          true if logging is enabled for this user context.
    90         */
    91        @DirectCall
    92        Bool isLoggingEnabledForChanCtx(Int newChanId);
    93    
    94    
    95        /*!
    96         * ======== isLoggingEnabledForFrameCtx ========
    97         * optional function to enable context-aware filtering based on frame context
    98         *
    99         * Configure the ti.uia.events.UIAFrameCtx.IsLoggingEnabledFxn with the
   100         * address of this function in order to enable context-aware filtering based on
   101         * frame context.  Alternatively, you can write your own isLoggingEnabled function
   102         * that provides additional filtering and logging capabilities (e.g. it can log
   103         * sync points whenever the context changes).
   104         *
   105         * @param(newFrameId)  the new Frame ID that has just been switched to
   106         * @a(return)          true if logging is enabled for this user context.
   107         */
   108        @DirectCall
   109        Bool isLoggingEnabledForFrameCtx(Int newFrameId);
   110    
   111    
   112        /*!
   113         * ======== isLoggingEnabledForThreadCtx ========
   114         * optional function to enable context-aware filtering based on user context
   115         *
   116         * Configure the ti.uia.events.UIAThreadCtx.IsLoggingEnabledFxn with the
   117         * address of this function in order to enable context-aware filtering based on
   118         * thread context.  Alternatively, you can write your own isLoggingEnabled function
   119         * that provides additional filtering and logging capabilities (e.g. it can log
   120         * sync points whenever the context changes).
   121         *
   122         * @param(newThreadId)  the new thread ID that has just been switched to
   123         * @a(return)          true if logging is enabled for this user context.
   124         */
   125         @DirectCall
   126         Bool isLoggingEnabledForThreadCtx(Int newThreadId);
   127    
   128        /*!
   129         * ======== isLoggingEnabledForUserCtx ========
   130         * optional function to enable context-aware filtering based on user context
   131         *
   132         * Configure the ti.uia.events.UIAUserCtx.IsLoggingEnabledFxn with the
   133         * address of this function in order to enable context-aware filtering based on
   134         * user context.  Alternatively, you can write your own isLoggingEnabled function
   135         * that provides additional filtering and logging capabilities (e.g. it can log
   136         * sync points whenever the context changes).
   137         *
   138         * @param(newUserCtx)  the new user context that has just been switched to
   139         * @a(return)          true if logging is enabled for this user context.
   140         */
   141         @DirectCall
   142         Bool isLoggingEnabledForUserCtx(Int newUserCtx);
   143    }