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