1    /*
     2     * Copyright (c) 2013, 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     *  ======== ITimestamp.xdc ========
    34     */
    35    package ti.sysbios.interfaces;
    36    
    37    import xdc.runtime.Types;
    38    
    39    /*!
    40     *  ======== ITimestamp ========
    41     *  Timestamp  Interface
    42     *
    43     *  This interface defines the methods used by client applications to
    44     *  get timestamp values.  It is implemented by the 
    45     *  `{@link xdc.runtime.Timestamp Timestamp}` module.
    46     */
    47    interface ITimestamp inherits xdc.runtime.ITimestampProvider
    48    {
    49        /*!
    50         *  ======== getFreqMeta ========
    51         *  Get timestamp frequency in Hz.
    52         *
    53         *  @_nodoc
    54         *  This function is currently used by UIA and is called in the
    55         *  UIAMetaData validate() function.
    56         */
    57        metaonly Types.FreqHz getFreqMeta();
    58    
    59         /*!
    60         *  ======== get32 ========
    61         *  Return a 32-bit timestamp
    62         *
    63         *  @a(returns)
    64         *  Returns a 32-bit timestamp value.  
    65         *  Use `{@link #getFreq}` to convert this value into units of real time.
    66         *
    67         *  @see #get64
    68         */
    69        override Bits32 get32();
    70    
    71        /*!
    72         *  ======== get64 ========
    73         *  Return a 64-bit timestamp
    74         *
    75         *  @param(result)  pointer to 64-bit result
    76         *
    77         *      This parameter is a pointer to a structure representing a 64-bit
    78         *      wide timestamp value where the current timestamp is written.
    79         *
    80         *      If the underlying hardware does not support 64-bit resolution, the
    81         *      `hi` field of `result` is always set to 0; see
    82         *      `{@link xdc.runtime.Types#Timestamp64}`.  So, it is possible for 
    83         *      the `lo` field to wrap around without any change to the `hi` field.
    84         *      Use `{@link #getFreq}` to convert this value into units of real 
    85         *      time.
    86         *
    87         *  @see #get32
    88         */
    89        override Void get64(xdc.runtime.Types.Timestamp64 *result);
    90        
    91        /*!
    92         *  ======== getFreq ========
    93         *  Get the timestamp timer's frequency (in Hz)
    94         *
    95         *  @param(freq)  pointer to a 64-bit result
    96         *
    97         *      This parameter is a pointer to a structure representing a 64-bit
    98         *      wide frequency value where the timer's frequency (in Hz)
    99         *      is written; see `{@link xdc.runtime.Types#FreqHz}`.
   100         *      This function provides a way of converting timestamp 
   101         *      values into units of real time.
   102         *
   103         *  @see #get32
   104         *  @see #get64
   105         */
   106        override Void getFreq(xdc.runtime.Types.FreqHz *freq);
   107    }