1    /*
     2     * Copyright (c) 2014-2016, 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    package ti.sysbios.family.arm.msp432;
    37    
    38    import xdc.rov.ViewInfo;
    39    
    40    /*!
    41     *  ======== ClockFreqs ========
    42     *  ClockFreqs Module.
    43     *
    44     *  This module is used to define the ACLK, SMCLK, and HSMCLK frequencies in
    45     *  effect when BIOS_start() is called at the end of main().  It also provides
    46     *  runtime functions that can be used to query or set individual clock
    47     *  frequencies.
    48     *
    49     *  If the application defines values for these three clocks, the application
    50     *  is responsible for setting up the clocks to the corresponding frequencies.
    51     *  This module will simply hold the values specified, for reference by other
    52     *  SYS/BIOS modules, or for query by the application at runtime.
    53     *
    54     *  If the application configuration specifies (in its .cfg file) a value for
    55     *  one of these three clock frequencies, it must specify values for all three
    56     *  clocks; if it does not, a build error will be thrown.
    57     *
    58     *  If the application does not define values for these clocks, the values will
    59     *  default either to the device reset values, or the boost values setup by
    60     *  the Boot module (ti.sysbios.family.arm.msp432.init.Boot).  For example, if
    61     *  the application does not configure values for ClockFreq, and does not turn
    62     *  off the Boot module's default frequency boost, then the Boot module boost
    63     *  frequencies are used.
    64     *
    65     *  If the application does not configure values for ClockFreq, and *does* turn
    66     *  off the Boot module's frequency boost (see snippet below), then the default
    67     *  reset frequency values will be used.
    68     *
    69     *  @p(code)
    70     *      var Boot = xdc.module('ti.sysbios.family.arm.msp432.init.Boot');
    71     *      Boot.configureClocks = false;
    72     *  @p
    73     *
    74     *  Currently the reset and Boot module boost values are fixed, as shown below.
    75     *
    76     *  The default reset values are:
    77     *
    78     *  @p(code)
    79     *      ACLK  = 32768 Hz
    80     *      SMCLK = 3 MHz
    81     *      HSMCLK = 3 MHz
    82     *  @p
    83     *
    84     *  The default Boot module boost values are:
    85     *
    86     *  @p(code)
    87     *      ACLK  = 32768 Hz
    88     *      SMCLK = 12 MHz
    89     *      HSMCLK = 24 MHz
    90     *  @p
    91     *
    92     *  Note: This module only tracks the ACLK, SMCLK, and HSMCLK values. It does
    93     *  not track the CPU clock (MCLK) frequency.  MCLK can be configured and
    94     *  queried with the BIOS module.  For example, to configure the CPU
    95     *  frequency:
    96     *
    97     *      var BIOS = xdc.useModule('ti.sysbios.BIOS');
    98     *      BIOS.cpuFreq.lo = 48000000;
    99     *      BIOS.cpuFreq.hi = 0;
   100     *  @p
   101     *
   102     *  @p(html)
   103     *  <h3> Calling Context </h3>
   104     *  <table border="1" cellpadding="3">
   105     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
   106     *
   107     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
   108     *    <!-- -->
   109     *    <tr><td> {@link #getFrequency} </td><td>   Y    </td><td>   Y    </td><td>   Y </td><td>   Y    </td><td>   Y    </td></tr>
   110     *    <tr><td> {@link #setFrequency} </td><td>   Y    </td><td>   Y    </td><td>   Y </td><td>   Y    </td><td>   Y    </td></tr>
   111     *    <tr><td colspan="6"> Definitions: <br />
   112     *       <ul>
   113     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   114     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   115     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   116     *         <li> <b>Main</b>: API is callable from main(). </li>
   117     *         <li> <b>Startup</b>: API is callable during any module startup. </li>
   118     *       </ul>
   119     *    </td></tr>
   120     *
   121     *  </table>
   122     *  @p
   123     */
   124    
   125    
   126    @Template("./ClockFreqs.xdt")
   127    
   128    
   129    @DirectCall
   130    module ClockFreqs
   131    {
   132        metaonly struct ModuleView {
   133            UInt    ACLK;
   134            UInt    MCLK;
   135            UInt    SMCLK;
   136            UInt    HSMCLK;
   137        }
   138    
   139        @Facet
   140        metaonly config ViewInfo.Instance rovViewInfo =
   141            ViewInfo.create({
   142                viewMap: [
   143                [
   144                    'Module',
   145                    {
   146                        type: ViewInfo.MODULE,
   147                        viewInitFxn: 'viewInitModule',
   148                        structName: 'ModuleView'
   149                    }
   150                ],
   151                ]
   152            });
   153    
   154        /*! Clocks */
   155        enum Clock {
   156            Clock_ACLK,             /* ACLK */
   157            Clock_SMCLK,            /* SMCLK */
   158            Clock_HSMCLK            /* HSMCLK */
   159        };
   160    
   161        /*! ACLK frequency (Hz) */
   162        config UInt32 ACLK;
   163    
   164        /*! SMCLK frequency (Hz) */
   165        config UInt32 SMCLK;
   166    
   167        /*! HSMCLK frequency (Hz) */
   168        config UInt32 HSMCLK;
   169    
   170        /*!
   171         *  ======== getFrequency ========
   172         *  Get the frequency for a clock.
   173         *
   174         */
   175        UInt32 getFrequency(Clock clock);
   176    
   177        /*!
   178         *  ======== setFrequency ========
   179         *  Set the frequency for a clock.
   180         *
   181         */
   182        Void setFrequency(Clock clock, UInt32 frequency);
   183    
   184    internal:   /* not for client use */
   185    
   186        struct Module_State {
   187            UInt32          ACLK;           /* ACLK frequency */
   188            UInt32          SMCLK;          /* SMCLK frequency */
   189            UInt32          HSMCLK;         /* HSCLK frequency */
   190        }
   191    }