1    /*
     2     * Copyright (c) 2012-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     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37    
    38    package ti.sysbios.family.c28;
    39    
    40    /*!
    41     *  ======== TimestampProvider ========
    42     *
    43     *  @p(html)
    44     *  <h3> Calling Context </h3>
    45     *  <table border="1" cellpadding="3">
    46     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    47     *
    48     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    49     *    <!--                                                                                                                 -->
    50     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    51     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    52     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    53     *    <tr><td colspan="6"> Definitions: <br />
    54     *       <ul>
    55     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    56     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    57     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    58     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    59     *           <ul>
    60     *             <li> In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE). </li>
    61     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    62     *             <li> During main().</li>
    63     *             <li> During BIOS.startupFxns.</li>
    64     *           </ul>
    65     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    66     *           <ul>
    67     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    68     *             <li> In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).</li>
    69     *           </ul>
    70     *       </ul>
    71     *    </td></tr>
    72     *  </table>
    73     *  @p
    74     *
    75     */
    76    
    77    @ModuleStartup          /* To get Clock Timer Handle */
    78    
    79    module TimestampProvider inherits ti.sysbios.interfaces.ITimestamp
    80    {
    81        /*! 
    82         * TimestampProvider timer id: 0, 1, or 2
    83         *
    84         * This parameter is ignored if useClockTimer is true.     
    85         */
    86        config UInt timerId = Timer.ANY;
    87    
    88        /*!
    89         *  Whether the TimestampProvider should share the Clock's timer.
    90         *
    91         *  This parameter overrides the timeId setting.
    92         *
    93         *  Sharing the Clock timer leaves more timers available for other uses,
    94         *  but makes the Timestamp APIs less efficient. If the Clock timer is 
    95         *  used, the timestamp is calculated as: 
    96         *    (Clock ticks) x (tick period) + (current timer count)
    97         *  This also limits the maximum value of the timestamp:
    98         *    max timestamp = 2^32 x (Clock tick period)
    99         *
   100         *  Using a dedicated timer allows for a full 64-bit timestamp and does not
   101         *  require any multiplication to retrieve the value.
   102         */
   103        config Bool useClockTimer = false;
   104    
   105        /*!@_nodoc 
   106         *  Internal use. If Timestamp is using a dedicated timer, this function is
   107         *  added to Startup.lastFxns to start the timer before reaching main.
   108         *  
   109         *  There are no C symbol references to this function, so it must be kept
   110         *  above the internal section so that it does not fall away when building
   111         *  a ROM image. If the function falls out of the ROM, when the ROM
   112         *  application finally references the symbol, it will not exist, and the 
   113         *  library will be brought in a second time resulting in multiple symbol
   114         *  definitions.
   115         */
   116        Void startTimer();
   117    
   118        /*!@_nodoc 
   119         *  Internal use. If Timestamp is using a dedicated timer, this function is
   120         *  the timer interrupt handler which maintains a count which is the upper
   121         *  32-bits of the timestamp.
   122         *
   123         *  This function must be kept 'public' for ROM concerns. See startTimer
   124         *  for explanation.
   125         */
   126        Void rolloverFunc(UArg unused);
   127        
   128    internal:   /* not for client use */
   129        
   130        struct Module_State {
   131            Timer.Handle     timer;    /* timer instance used */
   132            volatile UInt32  hi;       /* upper 32 bits */
   133        }
   134    }