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     * ======== GemTraceSync.xdc ========
    35     */
    36    package ti.uia.family.c64p;
    37    import ti.uia.runtime.IUIATraceSyncProvider;
    38    import ti.uia.events.UIASync;
    39    
    40    /*!
    41     *  ======== GemTraceSync.xdc ========
    42     *  C64X+ specific code for injecting sync point info into the GEM Trace stream
    43     *
    44     * The OVERLAY register (a.k.a. TSDR register) is an undocumented register
    45     * availble on C64X+ Full GEM targets.  Writes into this register are injected
    46     * into the trace stream.  The data that is written is used by the host to
    47     * determine what target-side context was active at the time the trace data
    48     * was recorded.
    49     *
    50     * The register only has 30 writable bits, so in order to inject a 32b value
    51     * into the trace stream  (e.g. the thread handle of the currently executing
    52     * thread), the 32b address needs to be split into two pieces and written into
    53     * the OVERLAY register in two successive write operations.  To make it possible
    54     * to use the OVERLAY register to inject different types of context info into
    55     * the trace stream, the following bit assignments need to be used when
    56     * writing data into the OVERLAY register:
    57     *
    58     * OVERLAY register bit assignments:
    59     * 2 LSBs fixed (011b)
    60     * 6 MSBs used to determine what type of data the OVERLAY register contains
    61     *
    62     * b31-b26  : a 6 bit ?type ID? that describes what context info the sync point
    63     *             contains
    64     * 000000b  : reserved
    65     * 000001b  : b25-b2 of OVERLAY register contains the 24 LSBs
    66     *             of the sequence number of the Sync Point event
    67     *             that contains correlation info.  Only 1 OVERLAY
    68     *             register write is required for this info.
    69     * 000010b  : b25-b2 of OVERLAY register contains the 24 LSBs
    70     *             of the sequence number of the Context Change event
    71     *             that contains context change info.  Only 1 OVERLAY
    72     *             register write is required for this info.
    73     *   . . .  : reserved
    74     * 000011b  : b25-b2 of OVERLAY register contains the 24 LSBs
    75     *             of the snapshot ID of the snapshot event
    76     *             that contains snapshot info.  Only 1 OVERLAY register
    77     *             write is required for this info.
    78     * 10XXXXb  : contains first word of a 2 word OVERLAY register sequence.
    79     * b25-b2   : the 24 MSBs of 32b context data.
    80     *
    81     * 11XXXXb:    contains second word of a 2 word OVERLAY register sequence.
    82     * b29-b10 contain the 20LSBs of the sequence number of an event that contains
    83     *             context info.
    84     * b9-b2 contain 8 LSBs of 32b context data.
    85     *
    86     * If the 2 word OVERLAY register protocol is being used and there is a sync
    87     * loss, then only the OVERLAY register data with b31-b30 = 11b will be
    88     * available since it was the last data written into the register.  Since this
    89     * contains a sequence number, it may be possible for the host to recover the
    90     * lost sync data by finding the context change event that has the same sequence
    91     * number.
    92     */
    93    
    94    @Gated
    95    module GemTraceSync inherits ti.uia.runtime.IUIATraceSyncProvider {
    96    
    97       /*!
    98         * ====== injectIntoTrace ======
    99         * Inject syncPoint info into GEM Trace
   100         *
   101         * This method logs a sync point event and injects
   102         * correlation info into the trace stream (if available)
   103         * to enable correlation between software events and hardware trace.
   104         *
   105         * @param(serialNumber) a sync point serial number to inject into the trace
   106         *    stream
   107         * @param(ctxType) the CtxChg_ContextType constant that describes what
   108         *    context info the 2 words contain
   109         */
   110        @DirectCall
   111        override Void injectIntoTrace(UInt32 serialNum,
   112                   IUIATraceSyncProvider.ContextType ctxType);
   113    
   114    }