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     *  ======== ClockFreqs.xdc ========
    34     *
    35     *
    36     */
    37    
    38    package ti.sysbios.family.msp430;
    39    
    40    /*!
    41     *  ======== ClockFreqs ========
    42     *  ClockFreqs Module.
    43     *
    44     *  This module is used to define the ACLK and SMCLK frequencies in effect when
    45     *  BIOS_start() is called at the end of main().  It also provides a function 
    46     *  that can be called by the application at runtime to query individual 
    47     *  clock frequencies.
    48     *
    49     *  If the application configuration defines values for these two clocks, it 
    50     *  (the application) is responsible for setting up the clocks to the
    51     *  corresponding frequencies.  This module will simply hold the values 
    52     *  specified, for reference by other SYS/BIOS modules, or for query by the 
    53     *  application.
    54     * 
    55     *  If the application configuration specifies a value for one of these 
    56     *  two clock frequencies, it must specify values for both clock frequencies;
    57     *  if it does not, a build error will be thrown.
    58     *
    59     *  If the application does not define values for one of these clocks, the
    60     *  values will default either to the device reset values, or the boost values
    61     *  setup by the Boot module (ti.catalog.msp430.init.Boot).  For example, if 
    62     *  the application does not configure values for ClockFreq, and does not turn 
    63     *  off the Boot module's default frequency boost, then the Boot module boost 
    64     *  frequencies are used.  
    65     *
    66     *  If the application does not configure values for ClockFreq, and *does* turn
    67     *  off the Boot module's frequency boost (see snippet below), then the default
    68     *  reset frequency values will be used. 
    69     *
    70     *  @p(code)
    71     *      var Boot = xdc.module('ti.catalog.msp430.init.Boot');
    72     *      Boot.configureDCO = false;
    73     *  @p
    74     *
    75     *  Currently the reset and Boot module boost values are fixed, as shown below.
    76     *  In future releases these values may made changeable.
    77     *
    78     *  The default reset values for UCS-based 5xx/6xx devices are:
    79     *
    80     *  @p(code)
    81     *      ACLK  = 32768 Hz
    82     *      SMCLK = 1000000 Hz
    83     *  @p
    84     *
    85     *  The default reset values for CS-based FR58xx/FR59xx devices are:
    86     *
    87     *  @p(code)
    88     *      ACLK  = 39063 Hz
    89     *      SMCLK = 1000000 Hz
    90     *  @p
    91     *
    92     *  The default Boot module boost values for UCS-based 5xx/6xx devices are:
    93     *
    94     *  @p(code)
    95     *      ACLK  = 32768 Hz
    96     *      SMCLK = 8192000 Hz
    97     *  @p
    98     *
    99     *  The default Boot module boost values for CS-based FR58x/FR59x devices are:
   100     *
   101     *  @p(code)
   102     *      ACLK  = 39063 Hz
   103     *      SMCLK = 8000000 Hz
   104     *  @p
   105     *
   106     *
   107     *  Note: This module allows query of the CPU clock (MCLK) frequency via the 
   108     *  ClockFreqs_getFrequency() API.  But MCLK cannot be configured with this 
   109     *  module.  Since MCLK is the CPU frequency, it is configured in the BIOS 
   110     *  module.  For example:
   111     *
   112     *  @p(code)
   113     *      var BIOS = xdc.useModule('ti.sysbios.BIOS');
   114     *      BIOS.cpuFreq.lo = 25000000;
   115     *      BIOS.cpuFreq.hi = 0;
   116     *  @p
   117     *
   118     *  @p(html)
   119     *  <h3> Calling Context </h3>
   120     *  <table border="1" cellpadding="3">
   121     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
   122     *
   123     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
   124     *    <!-- -->
   125     *    <tr><td> {@link #getFrequency} </td><td>   Y    </td><td>   Y    </td><td>   Y </td><td>   Y    </td><td>   Y    </td></tr>
   126     *    <tr><td colspan="6"> Definitions: <br />
   127     *       <ul>
   128     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   129     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   130     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   131     *         <li> <b>Main</b>: API is callable from main(). </li>
   132     *         <li> <b>Startup</b>: API is callable during any module startup. </li>
   133     *       </ul>
   134     *    </td></tr>
   135     *
   136     *  </table>
   137     *  @p
   138     */
   139    
   140    @DirectCall
   141    module ClockFreqs 
   142    {
   143        /*! Clocks */
   144        enum Clock {
   145            Clock_ACLK,             /* ACLK */
   146            Clock_SMCLK,            /* SMCLK */
   147            Clock_MCLK              /* MCLK */
   148        };
   149    
   150        /*! ACLK frequency (Hz) */
   151        config UInt32 ACLK;
   152    
   153        /*! SMCLK frequency (Hz) */
   154        config UInt32 SMCLK;
   155    
   156        /*! 
   157         *  ======== getFrequency ========
   158         *  Get the frequency for a clock.
   159         *
   160         */
   161        UInt32 getFrequency(Clock clock);
   162    
   163    }