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    import ti.uia.runtime.IUIATraceSyncProvider;
    34    
    35    /*
    36     * ======== IUIATraceSyncClient.xdc ========
    37     *  Interface for client modules that can inject info into a
    38     *  device trace stream whenever a sync point event, snapshot event and / or
    39     *  context change event occurs.  Using a module that implements IUIATraceSyncProvider
    40     *  will cause that module to automatically register its callback function
    41     *  with any modules that implement the IUIATraceSyncClient interface.
    42     *  @p
    43     *  Examples of modules that implement this interface include
    44     *  {@link ti.uia.family.c64p.GemTraceSync ti.uia.family.c64p.GemTraceSync} and
    45     *  {@link ti.uia.family.c66.GemTraceSync ti.uia.family.c66.GemTraceSync}
    46     */
    47    interface IUIATraceSyncClient inherits ti.uia.events.IUIAMetaProvider {
    48    
    49        /*!
    50         * ======== injectIntoTraceFxn ========
    51         * Callback function that handles injection of info such as serial numbers
    52         * of sync point events, context change events or snapshot events into a
    53         * hardware trace stream. (e.g. GEM CPU Trace, System Trace, etc.)
    54         *
    55         * Users can provide their own custom injectIntoTraceFxn to log whatever
    56         * additional information they wish to record when the hook function is called.
    57         * For example, event serial numbers can be injected into the CPU
    58         * trace stream and / or STM trace stream in order to enable correlation
    59         * of information logged in these streams with UIA software events.
    60         * @a(Examples)
    61         * @p(html)
    62         * <B>Example 1: Correlating events with C64X+ and C66 CPU Trace</B>
    63         * @p
    64         * The following is an example of the configuration script used
    65         * to inject serial numbers of sync point events or context change events or
    66         * snapshot Ids associated with snapshot events.
    67         * @p
    68         * Note that the GemTraceSync module's .xs script takes care of finding
    69         * all modules that implement the IUIATraceSyncClient and assigning the
    70         * GemTraceSync_injectIntoTrace function pointer to those modules'
    71         * injectIntoTraceFxn config option.
    72         * @p(code)
    73         * //The following 3 modules all implement the IUIATraceSyncClient interface
    74         * var LogSnapshot   = xdc.useModule('ti.uia.runtime.LogSnapshot');
    75         * var LogCtxChg   = xdc.useModule('ti.uia.runtime.LogCtxChg');
    76         * var LogSync   = xdc.useModule('ti.uia.runtime.LogSync');
    77         * //For C66 devices, replace the following line with
    78         * // var GemTraceSync = xdc.useModule('ti.uia.family.c66.GemTraceSync');
    79         * var GemTraceSync = xdc.useModule('ti.uia.family.c64p.GemTraceSync');
    80         * @p
    81         * @p(html)
    82         * <hr>
    83         * <B>Example 2: How to create a custom hook function
    84         * and assign it to the LogSnapshot module</B>
    85         * @p
    86         * The following is an example of a 'C' code program that implements
    87         * a hook function that prints out the snapshot ID that is passed in
    88         * as the serialNumber
    89         * @p(code)
    90         * #include <xdc/std.h>
    91         * #include <xdc/runtime/Gate.h>
    92         * #include <ti/uia/runtime/IUIATraceSyncProvider.h>
    93         * #include <ti/uia/runtime/LogSnapshot.h>
    94         * #include <stdio.h>
    95         * #include <string.h>
    96         * extern Void myHookFxn(UInt32 serialNumber, IUIATraceSyncProvider_ContextType ctxType);
    97         * Void Test();
    98         * char name[32]={"Bob"};
    99         * UInt32 newAppId = 0;
   100         * Void myHookFxn(UInt32 serialNumber, IUIATraceSyncProvider_ContextType ctxType){
   101         *      volatile UInt32 syncWord;
   102         *      IArg key = Gate_enterSystem();
   103         *      printf("newAppId written with serialNumber %d and ctxType = %d\n",serialNumber,ctxType);
   104         *      Gate_leaveSystem(key);
   105         * }
   106         * Void Test(){
   107         *     // note that the hook function is triggered by calling LogSnapshot_getSnapshotId()
   108         *     // since that is where the unique snapshot ID that is passed to the
   109         *     // hook function is generated.
   110         *     Int snapshotId = LogSnapshot_getSnapshotId();
   111         *     LogSnapshot_writeString(snapshotId,"User-defined name=%s.",name, strlen(name));
   112         * }
   113         *
   114         * Void main(){
   115         *     while(TRUE){  Test();  }
   116         *  }
   117         * @p
   118         * In order to have the above user-defined function called by the LogSnapshot
   119         * module whenever it writes an event, the following configuration script
   120         * is needed:
   121         * @p(code)
   122         * var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
   123         * var LogSnapshot   = xdc.useModule('ti.uia.runtime.LogSnapshot');
   124         * var IUIATraceSyncClient = xdc.useModule('ti.uia.runtime.IUIATraceSyncClient');
   125         * LogSnapshot.injectIntoTraceFxn = $externFxn('myHookFxn');
   126         *
   127         * @p
   128         * @see LoggerTypes#InjectIntoTraceFxn
   129         * @see LogSnapshot
   130         */
   131        config LoggerTypes.InjectIntoTraceFxn injectIntoTraceFxn = null;
   132        /*!
   133         * ======== isInjectIntoTraceEnabled ========
   134         * set false to turn off injection of sync point info into trace even
   135         *  if a module that implements IUIATraceSyncProvider is configured.
   136         *
   137         * The XDCScript associated with a module that implements IUIATraceSyncProvider
   138         * is responsible for checking this config option for all IUIATraceSyncClient
   139         * modules before automatically configuring the client callback function.
   140         * This allows users to control which features have sync points injected
   141         * into the trace stream.  For example, a user may wish to configure
   142         * LogSync.isInjectIntoTraceEnabled = true and
   143         * LogCtxChg.isInjectIntoTraceEnabled = false in order to reduce the number
   144         * of sync point events injected into the trace stream.
   145         */
   146        metaonly config Bool isInjectIntoTraceEnabled = true;
   147    
   148    }