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     * ======== TimestampC64XLocal.xdc ========
    35     */
    36    package ti.uia.family.c64p;
    37    
    38    import xdc.runtime.Types;
    39    
    40    /*!
    41     *  ======== TimestampC64XLocal.xdc ========
    42     *  Implementation of `{@link ITimestampProvider}` for the C64X ISA's internal timestamp.
    43     *
    44     *  Assigning an instance of this module to the ti.uia.runtime.LogSync
    45     *  module's CpuTimestampProxy provides a way for applications to notify
    46     *  System Analyzer about CPU frequency changes, so that multicore event
    47     *  correlation properly accounts for the change in CPU frequency.
    48     *  @p
    49     *  Whenever a SyncPoint event is logged, the LogSync module will use the information
    50     *  stored in this module's Module_state as the CPU clock frequency information.
    51     */
    52    @ModuleStartup
    53    module TimestampC64XLocal inherits ti.uia.runtime.IUIATimestampProvider {
    54    
    55    
    56        /*!
    57         * ======== maxTimerClockFreq =========
    58         * The highest timer clock frequency.
    59         *
    60         * The default ticks per second rate of the timer is calculated by dividing
    61         * the timer's bus clock frequency by the cyclesPerTick config parameter.
    62         * By default, this will be set to the CPU speed defined in the Platform.xdc
    63         * file that is part of the platform specified in the build settings.
    64         *
    65         * @a(Examples)
    66         * Example: The following is an example of the configuration script used
    67         * to configure the frequency for a value of 700 MHz:
    68         * @p(code)
    69         * var TimestampC64XLocal = xdc.useModule('ti.uia.family.c64p.TimestampC64XLocal');
    70         * TimestampC64XLocal.maxTimerClockFreq = {lo:700000000,hi:0};
    71         * @p
    72         *
    73         */
    74        override config Types.FreqHz maxTimerClockFreq;
    75    
    76    
    77        /*!
    78         * ======== maxBusClockFreq =========
    79         * The highest bus clock frequency used to drive the timer.
    80         *
    81         * The default ticks per second rate of the timer is calculated by dividing
    82         * the timer's bus clock frequency by the cyclesPerTick config parameter.
    83         * By default, this will be set to the CPU speed defined in the Platform.xdc
    84         * file that is part of the platform specified in the build settings.
    85         *
    86         * @a(Examples)
    87         * Example: The following is an example of the configuration script used
    88         * to configure the frequency for a value of 700 MHz:
    89         * @p(code)
    90         * var TimestampC64XLocal = xdc.useModule('ti.uia.family.c64p.TimestampC64XLocal');
    91         * TimestampC64XLocal.maxBusClockFreq = {lo:700000000,hi:0};
    92         * @p
    93         */
    94        override config Types.FreqHz maxBusClockFreq;
    95    
    96        /*!
    97         * ======== canFrequencyBeChanged =========
    98         * Indicates whether the timer frequency can be changed or not
    99         *
   100         * @a(returns) true if the timer's clock frequency can be changed
   101         */
   102        override metaonly config Bool canFrequencyBeChanged = false;
   103    
   104        /*!
   105         * ======== cpuCyclesPerTick =========
   106         * The number of CPU cycles each tick of the timestamp corresponds to
   107         *
   108         * A value of 0 indicates that no conversion between the timer's tick count
   109         * and CPU cycles is possible.
   110         */
   111        override metaonly config UInt32 cpuCyclesPerTick = 1;
   112    
   113    
   114        /*!
   115         * ======== canCpuCyclesPerTickBeChanged =========
   116         * Indicates whether the timer's cycles per tick divide down ratio can be
   117         *    changed or not
   118         *
   119         * @a(returns) true if the timer's CPU cycles per tick can be changed
   120         */
   121        override metaonly config Bool canCpuCyclesPerTickBeChanged = false;
   122        /*!
   123         *  ======== get32 ========
   124         *  Return a 32-bit timestamp
   125         *
   126         *  @a(returns)
   127         *  Returns a 32-bit timestamp value.
   128         *  Use `{@link #getFreq}` to convert this value into units of real time.
   129         *
   130         *  @see #get64
   131         */
   132        @DirectCall
   133        override Bits32 get32();
   134    
   135        /*!
   136         *  ======== get64 ========
   137         *  Return a 64-bit timestamp
   138         *
   139         *  @param(result)  pointer to 64-bit result
   140         *
   141         *      This parameter is a pointer to a structure representing a 64-bit
   142         *      wide timestamp value where the current timestamp is written.
   143         *
   144         *      If the underlying hardware does not support 64-bit resolution, the
   145         *      `hi` field of `result` is always set to 0; see
   146         *      `{@link xdc.runtime.Types#Timestamp64}`.  So, it is possible for
   147         *      the `lo` field to wrap around without any change to the `hi` field.
   148         *      Use `{@link #getFreq}` to convert this value into units of real
   149         *      time.
   150         *
   151         *  @see #get32
   152         */
   153        @DirectCall
   154        override Void get64(Types.Timestamp64 *result);
   155    
   156        /*!
   157         *  ======== getFreq ========
   158         *  Get the timestamp timer's frequency (in Hz)
   159         *
   160         *  @param(freq)  pointer to a 64-bit result
   161         *
   162         *      This parameter is a pointer to a structure representing a 64-bit
   163         *      wide frequency value where the timer's frequency (in Hz)
   164         *      is written; see `{@link xdc.runtime.Types#FreqHz}`.
   165         *      This function provides a way of converting timestamp
   166         *      values into units of real time.
   167         *
   168         *  @see #get32
   169         *  @see #get64
   170         */
   171        @DirectCall
   172        override Void getFreq(Types.FreqHz *freq);
   173    
   174        /*!
   175         *  ======== setFreq ========
   176         *  Set the timestamp timer's frequency (in Hz)
   177         *
   178         *  @param(freq)  pointer to a 64-bit input value
   179         *
   180         *      This parameter is a pointer to a structure representing a 64-bit
   181         *      wide frequency value where the timer's frequency (in Hz)
   182         *      is written; see `{@link xdc.runtime.Types#FreqHz}`.
   183         *      This function provides a way of updating the timestamp
   184         *      data that is logged with a sync point event.
   185         *
   186         *  @see #getFreq
   187         */
   188        @DirectCall
   189        Void setFreq(Types.FreqHz *freq);
   190    
   191    instance:
   192    
   193    
   194    internal:
   195        struct Module_State {
   196            Types.FreqHz freq;
   197        };
   198    }