1    /*
     2     * Copyright (c) 2014-2015, 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     *  ======== Seconds.xdc ========
    34     */
    35    
    36    package ti.sysbios.hal;
    37    
    38    import xdc.rov.ViewInfo;
    39    
    40    /*!
    41     *  ======== Seconds ========
    42     *  Seconds Manager.
    43     *
    44     *  This module is a proxy to the device-specific Seconds module functions
    45     *  as defined in ISeconds.xdc.
    46     *
    47     *  This module generates a custom time() function in the
    48     *  configuration-generated .c file.  This time() function calls Seconds_get()
    49     *  to get the number of seconds since 1970 from a device-specific delegate
    50     *  function.
    51     *
    52     *  Note: For TI codegen tools, time() returns the number of seconds since
    53     *  1900. The generated time() function takes this into account, and adds the
    54     *  number of seconds from 1900 to 1970 to the value returned by Seconds_get().
    55     *  This allows functions such as localtime() to work correctly with TI tools.
    56     *
    57     *  The actual implementations of the Seconds module functions are
    58     *  provided by the Seconds module delegates.
    59     *
    60     *  Additional, family-specific Seconds module APIs may also be provided
    61     *  by the Seconds module delegates.
    62     *
    63     *  Follow the link below to determine which Seconds delegate is used
    64     *  for your Target/Device:
    65     *
    66     *      {@link ./../family/doc-files/delegates.html Delegate Mappings}
    67     *
    68     *  @p(html)
    69     *  <h3> Calling Context </h3>
    70     *  <table border="1" cellpadding="3">
    71     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    72     *    </colgroup>
    73     *
    74     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    75     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    76     *    <!--                                            -->
    77     *    <tr><td> {@link #get} </td><td>   Y    </td><td>   Y    </td>
    78     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    79     *    <tr><td> {@link #set} </td><td>   N    </td><td>   N    </td>
    80     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    81     *    <tr><td colspan="6"> Definitions: <br />
    82     *       <ul>
    83     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    84     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    85     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    86     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    87     *           <ul>
    88     *             <li> In your module startup after this module is started
    89     *    (e.g. Seconds_Module_startupDone() returns TRUE). </li>
    90     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    91     *             <li> During main().</li>
    92     *             <li> During BIOS.startupFxns.</li>
    93     *           </ul>
    94     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    95     *           <ul>
    96     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    97     *             <li> In your module startup before this module is started
    98     *    (e.g. Seconds_Module_startupDone() returns FALSE).</li>
    99     *           </ul>
   100     *       </ul>
   101     *    </td></tr>
   102     *
   103     *  </table>
   104     *  @p
   105     *
   106     *  Usage example with run-time support library:
   107     *
   108     *  @p(code)
   109     *  #include <ti/sysbios/hal/Seconds.h>
   110     *  #include <time.h>
   111     *
   112     *  time_t t;
   113     *  struct tm *ltm;
   114     *  char *curTime;
   115     *
   116     *  Seconds_set(STARTTIME);
   117     *
   118     *  t = time(NULL);
   119     *  ltm = localtime(&t);
   120     *  curTime = asctime(ltm);
   121     *  System_printf("Time(GMT): %s\n", curTime);
   122     *  @p
   123     */
   124    
   125    @Template("./Seconds.xdt")
   126    module Seconds inherits ti.sysbios.interfaces.ISeconds
   127    {
   128       /*!
   129        *  ======== generateTimeFuncton ========
   130        *  Generate time() function that will call Seconds_get() internally.
   131        *
   132        *  This generated function will override the compiler's RTS library's
   133        *  time() function.
   134        */
   135        metaonly config Bool generateTimeFunction = true;
   136    
   137        /*!
   138         *  ======== SecondsProxy ========
   139         *  Target/device-specific Seconds implementation
   140         */
   141        proxy SecondsProxy inherits ti.sysbios.interfaces.ISeconds;
   142    }