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     *  ======== Timer.xdc ========
    34     *
    35     */
    36    package ti.sysbios.hal;
    37    
    38    import xdc.runtime.Error;
    39    
    40    /*!
    41     *  ======== Timer ========
    42     *  Timer Manager Proxy.
    43     *
    44     *  The ti.sysbios.hal.Timer module presents a standard interface for using 
    45     *  the timer peripherals. This module is part of the Hardware Abstraction  
    46     *  Layer (HAL) package, which hides target/device-specific characteristics  
    47     *  of the hardware. 
    48     *   
    49     *  You can use this module to create a timer (that is, to mark a timer for  
    50     *  use) and configure it to call a tickFxn when the timer expires. Use this 
    51     *  module only if you do not need to do any custom configuration of the  
    52     *  timer peripheral. 
    53     *   
    54     *  The timer can be configured as a one-shot or a continuous mode timer. 
    55     *  The period can be specified in timer counts or microseconds. 
    56     *   
    57     *  The timer interrupt always uses the Hwi dispatcher. The Timer tickFxn 
    58     *  runs in the context of a Hwi thread. The Timer module automatically 
    59     *  creates a Hwi instance for the timer interrupt.
    60     *  
    61     *  The actual implementations of the Timer module functions are
    62     *  provided by device/family-specific Timer modules. 
    63     *  Additional, family-specific Timer module APIs may also be provided by
    64     *  your Timer module implementation.
    65     *  Follow the link below to determine which Timer implementation is used
    66     *  for your target:
    67     *
    68     *      {@link ./../family/doc-files/delegates.html Delegate Mappings}
    69     *
    70     *  @a(constraints)
    71     *  Since the hal Timer module has no knowledge of the delegate Timer
    72     *  module's instance definition, Timer_construct() can NOT be properly
    73     *  supported.
    74     *
    75     *  If {@link ti.sysbios.BIOS#runtimeCreatesEnabled BIOS.runtimeCreatesEnabled}
    76     *  is set to true, both Timer_create() and Timer_construct() 
    77     *  will attempt to dynamically create (ie NOT construct) a delegate Timer
    78     *  object.
    79     *
    80     *  If {@link ti.sysbios.BIOS#runtimeCreatesEnabled BIOS.runtimeCreatesEnabled}
    81     *  is set to false, both Timer_create() and Timer_construct() will fail.
    82     *
    83     *  @p(html)
    84     *  <h3> Calling Context </h3>
    85     *  <table border="1" cellpadding="3">
    86     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    87     *    </colgroup>
    88     *
    89     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    90     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    91     *    <!--                                                                  -->
    92     *    <tr><td> {@link #getNumTimers}            </td><td>   Y    </td>
    93     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    94     *    <tr><td> {@link #getStatus}               </td><td>   Y    </td>
    95     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    96     *    <tr><td> {@link #Params_init}             </td><td>   Y    </td>
    97     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    98     *    <tr><td> {@link #construct}               </td><td>   Y    </td>
    99     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   100     *    <tr><td> {@link #create}                  </td><td>   N    </td>
   101     *    <td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   102     *    <tr><td> {@link #delete}                  </td><td>   N    </td>
   103     *    <td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   104     *    <tr><td> {@link #destruct}                </td><td>   Y    </td>
   105     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   106     *    <tr><td> {@link #getFreq}                 </td><td>   Y    </td>
   107     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   108     *    <tr><td> {@link #getPeriod}               </td><td>   Y    </td>
   109     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   110     *    <tr><td> {@link #setPeriod}               </td><td>   Y    </td>
   111     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   112     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   Y    </td>
   113     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   114     *    <tr><td> {@link #start}                   </td><td>   Y    </td>
   115     *    <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   116     *    <tr><td> {@link #stop}                    </td><td>   Y    </td>
   117     *    <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   118     *    <tr><td colspan="6"> Definitions: <br />
   119     *       <ul>
   120     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   121     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   122     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   123     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   124     *           <ul>
   125     *             <li> In your module startup after this module is started 
   126     *    (e.g. Timer_Module_startupDone() returns TRUE). </li>
   127     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   128     *             <li> During main().</li>
   129     *             <li> During BIOS.startupFxns.</li>
   130     *           </ul>
   131     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   132     *           <ul>
   133     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   134     *             <li> In your module startup before this module is started 
   135     *    (e.g. Timer_Module_startupDone() returns FALSE).</li>
   136     *           </ul>
   137     *       </ul>
   138     *    </td></tr>
   139     *
   140     *  </table>
   141     *  @p
   142     */
   143    
   144    @ModuleStartup
   145    
   146    module Timer inherits ti.sysbios.interfaces.ITimer 
   147    {
   148        /*!
   149         *  ======== viewGetHandle ========
   150         *  @_nodoc
   151         *  Returns the corresponding hal Timer handle for a delegate Timer handle
   152         *
   153         *  @b(returns)     hal Timer handle
   154         */
   155        metaonly Handle viewGetHandle(Ptr pi);
   156    
   157    instance:
   158    
   159        /*! 
   160         *  ======== create ========
   161         *  Create a timer.
   162         *
   163         *  Create could fail if timer peripheral is unavailable. To
   164         *  request any available timer use {@link #ANY} as the id.
   165         *  TimerId's are logical ids. The family-specific implementations 
   166         *  map the ids to physical peripherals.
   167         *
   168         *  @param(id)      Timer id ranging from 0 to a platform specific value
   169         *  @param(tickFxn) function that runs upon timer expiry.
   170         */
   171        override create(Int id, FuncPtr tickFxn);
   172    
   173    internal:   /* not for client use */
   174    
   175        /*! target/device-specific Timer implementation. */
   176        proxy TimerProxy inherits ti.sysbios.interfaces.ITimer;
   177    
   178        struct Instance_State {
   179            TimerProxy.Handle pi;
   180        };
   181    }