1    /*
     2     * Copyright (c) 2014, 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.arm.a8;
    39    
    40    /*!
    41     *  ======== TimestampProvider ========
    42     *  A8 TimestampProvider.
    43     *
    44     *  The source of the timestamps for the A8 TimestampProvider is
    45     *  the A8's internal PMC counter which counts CPU cycles.
    46     *
    47     *  As this counter is only 32 bits in length, provision is made
    48     *  in the get64() API to test if an overflow has occurred since
    49     *  the last invocation of get64() and compensate the return value
    50     *  accordingly.
    51     *
    52     *  As it is possible for the 32 bit counter to roll over more
    53     *  than once between successive get64() calls, this module offers
    54     *  an auto refresh feature. If auto refresh is enabled
    55     *  (see {@link #autoRefreshEnable}), this module will register a
    56     *  clock function with a period less than the amount of time it
    57     *  takes for the 32 bit counter to roll over. The clock function
    58     *  checks for an overflow and updates the upper 32 bits of the
    59     *  counter to guarantee coherency in successive timestamps.
    60     *
    61     *  @a(Note)
    62     *  Auto refresh feature requires that the SYS/BIOS clock is enabled.
    63     *  If the SYS/BIOS clock is disabled
    64     *  (see {@link ti.sysbios.BIOS#clockEnabled BIOS.clockEnabled})
    65     *  then this feature cannot be enabled.
    66     *
    67     *  @p(html)
    68     *  <h3> Calling Context </h3>
    69     *  <table border="1" cellpadding="3">
    70     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    71     *    </colgroup>
    72     *
    73     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    74     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    75     *    <!--                                                              -->
    76     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td>
    77     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    78     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td>
    79     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    80     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td>
    81     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    82     *    <tr><td colspan="6"> Definitions: <br />
    83     *       <ul>
    84     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    85     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    86     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    87     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    88     *           <ul>
    89     *             <li> In your module startup after this module is started
    90     *    (e.g. TimestampProvider_Module_startupDone() returns TRUE). </li>
    91     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    92     *             <li> During main().</li>
    93     *             <li> During BIOS.startupFxns.</li>
    94     *           </ul>
    95     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    96     *           <ul>
    97     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    98     *             <li> In your module startup before this module is started
    99     *    (e.g. TimestampProvider_Module_startupDone() returns FALSE).</li>
   100     *           </ul>
   101     *       </ul>
   102     *    </td></tr>
   103     *
   104     *  </table>
   105     *  @p
   106     */
   107    
   108    @ModuleStartup          /* To get Clock Timer Handle */
   109    
   110    module TimestampProvider inherits ti.sysbios.interfaces.ITimestamp
   111    {
   112        /*! @_nodoc */
   113        @XmlDtd
   114        metaonly struct Module_View {
   115        };
   116    
   117        /*!
   118         *  ======== autoRefreshEnable ========
   119         *  If this config param is set to true, this module will create a
   120         *  clock instance with a timeout that is less than the amount of
   121         *  time it takes for the PMU cycle counter to overflow. The clock
   122         *  handler function will check if the PMU cycle counter has overflowed
   123         *  and update the upper 32 bits of the timestamp so coherency of
   124         *  successive 64bit timestamps is guaranteed.
   125         */
   126        metaonly config Bool autoRefreshEnable = true;
   127    
   128    internal:   /* not for client use */
   129    
   130        /*
   131         * initialize and start the CCNT performance monitor
   132         */
   133        Void initCCNT();
   134    
   135        /*
   136         * Refresh upper32 bits of timestamp
   137         */
   138        Void autoRefreshFxn(UArg arg);
   139    
   140        struct Module_State {
   141            UInt32          upper32Bits;    /* upper 32 bits of counter */
   142            UInt32          prevLoBits;     /* previous lower 32 bits */
   143        }
   144    }