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    package ti.uia.runtime;
    33    
    34    import xdc.runtime.Types;
    35    
    36    /*!
    37     *  ======== IUIATimestampProvider ========
    38     *  UIA timestamp provider interface
    39     *
    40     *  This interface is implemented by platform-specific modules that
    41     *  "provide" underlying timestamp services that allow 64b timestamp values
    42     *  to be read directly into event parameters.
    43     *
    44     *  Note that the implementation is typically not thread safe - it
    45     *  is up to the caller to ensure that the get64() API is protected from
    46     *  preemption by another thread or another CPU core in order to ensure
    47     *  that a coherent 64b result is returned.  For timers that are a shared
    48     *  resource, some form of system-level lock (e.g. Lampart's bakery algorithm,
    49     *  spinlock or Peterson lock) or IPC round-robin mechanism may be required in
    50     *  order to ensure that there are no race conditions.
    51     */
    52    interface IUIATimestampProvider inherits xdc.runtime.ITimestampProvider {
    53    
    54        /*!
    55         * ======== maxTimerClockFreqLSW =========
    56         * The highest timer clock frequency.
    57         *
    58         * The default ticks per second rate of the timer is calculated by dividing
    59         * the timer's bus clock frequency by the cyclesPerTick config parameter.
    60         *
    61         * @a(returns) the 32 LSBs of the highest timer clock frequency
    62         *   (i.e. ticksPerSecond).
    63         */
    64        config Types.FreqHz maxTimerClockFreq;
    65    
    66        /*!
    67         * ======== maxBusClockFreqMSW =========
    68         * The highest bus clock frequency used to drive the timer.
    69         *
    70         * The default ticks per second rate of the timer is calculated by dividing
    71         * the timer's bus clock frequency by the cyclesPerTick config parameter.
    72         *
    73         * @a(returns) the 32 MSBs of the highest bus clock frequency used to drive
    74         *    the timer.
    75         */
    76        config Types.FreqHz maxBusClockFreq;
    77    
    78        /*!
    79         * ======== canFrequencyBeChanged =========
    80         * Indicates whether the timer frequency can be changed or not
    81         *
    82         * @a(returns) true if the timer's clock frequency can be changed
    83         */
    84        metaonly config Bool canFrequencyBeChanged = false;
    85    
    86        /*!
    87         * ======== cpuCyclesPerTick =========
    88         * The number of CPU cycles each tick of the timestamp corresponds to
    89         *
    90         * A value of 0 indicates that no conversion between the timer's tick count
    91         * and CPU cycles is possible.
    92         */
    93        metaonly config UInt32 cpuCyclesPerTick = 0;
    94    
    95        /*!
    96         * ======== canCpuCyclesPerTickBeChanged =========
    97         * Indicates whether the timer's cycles per tick divide down ratio can be
    98         * changed or not
    99         *
   100         * @a(returns) true if the timer's CPU cycles per tick can be changed
   101         */
   102        metaonly config Bool canCpuCyclesPerTickBeChanged = false;
   103    }