1    /*
     2     * Copyright (c) 2012-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.msp430;
    39    
    40    /*!
    41     *  ======== TimestampProvider ========
    42     *  MSP430 Timestamp Provider
    43     *
    44     *  @p(html)
    45     *  <h3> Calling Context </h3>
    46     *  <table border="1" cellpadding="3">
    47     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    48     *
    49     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main**  </th><th>  Startup***  </th></tr>
    50     *    <!--                                                                                                                 -->
    51     *    <tr><td> {@link #get16}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    52     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    53     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    54     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    55     *
    56     *  </table>
    57     *  @p
    58     */
    59    
    60    @ModuleStartup          /* To get Clock Timer Handle */
    61    
    62    module TimestampProvider inherits ti.sysbios.interfaces.ITimestamp
    63    {
    64        // -------- Module Types --------
    65    
    66        /*! Input clock sources for dedicated Timestamp timer */
    67        enum Source {
    68            Source_ACLK,                    /*! ACLK */
    69            Source_SMCLK                    /*! SMCLK */
    70        };
    71    
    72        /*!
    73         *  ======== timerId ========
    74         *  Id of the timer to use for creating timestamps
    75         *
    76         *  A value of {@link Timer#ANY Timer.ANY} (-1) indicates any timer
    77         *  supported by {@link Timer} is ok.
    78         */
    79        config UInt timerId = Timer.ANY;
    80    
    81        /*!
    82         *  
    83         *  ======== useClockTimer ========
    84         *  Use the same timer as Clock
    85         *
    86         *  Set this parameter when you want TimestampProvider to use the same
    87         *  timer as the BIOS {@link ti.sysbios.knl.Clock Clock} module.
    88         *
    89         *  This parameter overrides the {@link #timerId timeId} setting.
    90         */
    91        config Bool useClockTimer;
    92    
    93        /*!
    94         *  
    95         *  ======== clockSource ========
    96         *  Input clock source for dedicated timer
    97         *
    98         *  If the TimestampProvider is to use a different timer than the one
    99         *  used by the {@link ti.sysbios.knl.Clock Clock} module, this
   100         *  parameter specifies the input clock source for that dedicated timer.
   101         *
   102         *  For example, to use a dedicated timer for Timestamps, and to have it
   103         *  run off of SMCLK, add the following to the application config script:
   104         *  
   105         *  @p(code)
   106         *  var Timestamp = xdc.useModule('ti.sysbios.family.msp430.TimestampProvider');
   107         *  Timestamp.useClockTimer = false;
   108         *  Timestamp.clockSource = Timestamp.Source_SMCLK;
   109         *  @p
   110         */
   111        config Source clockSource = Source_ACLK;
   112    
   113        /*!
   114         *
   115         *  ======== synchronize ========
   116         *  Selected clock source is synchronous to CPU clock
   117         *
   118         *  If the TimestampProvider is to use a different timer than the one
   119         *  used by the {@link ti.sysbios.knl.Clock Clock} module, this
   120         *  parameter specifies if the clock source is synchronous to CPU clock.
   121         */
   122        config Bool synchronize = false;
   123    
   124        /*!
   125         *  ======== get16 ========
   126         *  Return a 16-bit timestamp
   127         *
   128         *  @a(returns)
   129         *  Returns a 16-bit timestamp value.
   130         *  Use `{@link #getFreq}` to convert this value into units of real time.
   131         */
   132        Bits16 get16();
   133    
   134        /*!
   135         *  ======== startTimer ========
   136         *  Function that starts timer before main
   137         *
   138         *  @_nodoc Internal use. 
   139         */
   140        Void startTimer();
   141    
   142        /*!
   143         *  ======== rolloverFunc ========
   144         *  Timer rollover interrupt handler
   145         *
   146         *  @_nodoc Internal use. 
   147         */
   148        Void rolloverFunc(UArg unused);
   149    
   150    internal:   /* not for client use */
   151    
   152        /*
   153         *  ======== Module_State ========
   154         */
   155        struct Module_State {
   156            Timer.Handle    timer;          /* timer instance used */
   157            volatile UInt32 rollovers;      /* timer rollover counts */
   158        }
   159    }