1    /*
     2     * Copyright (c) 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     *  ======== Boot.xdc ========
    34     */
    35    
    36    package ti.sysbios.family.arm.v7r.tms570;
    37    
    38    import xdc.rov.ViewInfo;
    39    
    40    /*!
    41     *  ======== Boot ========
    42     *  TMS570DCxx/RM57Dxx Boot Support.
    43     *
    44     *  //TODO Document this module
    45     *
    46     *  This Boot module supports boot initialization for the Cortex-R5F cores.
    47     *  A special boot init function is created based on the configuration
    48     *  settings for this module.  This function is hooked into the
    49     *  xdc.runtime.Reset.fxns[] array and called very early at boot time (prior
    50     *  to cinit processing).
    51     *
    52     *  The code to support the boot module is placed in a separate section
    53     *  named `".text:.bootCodeSection"` to allow placement of this section in
    54     *  the linker .cmd file if necessary. This section is a subsection of the
    55     *  `".text"` section so this code will be placed into the .text section unless
    56     *  explicitly placed, either through
    57     *  `{@link xdc.cfg.Program#sectMap Program.sectMap}` or through a linker
    58     *  command file.
    59     *
    60     *  @a(Clock configuration)
    61     *  Using this Boot module will automatically enable clock configuration. As
    62     *  part of the clock configuration, this module will setup the PLL based
    63     *  on the multiplier and divider values configured. Once the PLL is setup,
    64     *  the CPU clock source (GCLK) is changed from OSCIN to PLL1. In addition,
    65     *  this module also sets up the VCLK to equal GCLK/2 and selects the VCLK
    66     *  as the source for the RTI timer.
    67     *
    68     *  The formula for PLL output frequency is shown below. The multiplier
    69     *  and the various dividers can be configured to achieve different CPU
    70     *  frequencies. By default, this module will configure the PLL to run the
    71     *  CPU at 100MHz and the RTI Timer is clocked at 50MHz.
    72     *
    73     *  @p(code)
    74     *  Formula for PLL output frequency:
    75     *
    76     *          Foscin       NF
    77     *  Fpll = -------- X --------
    78     *            NR       OD x R
    79     *
    80     *  where, Foscin is frequency of PLL input clock from oscillator
    81     *         NR     is prescale divider for the input clock
    82     *         NF     is multiplier
    83     *         OD,R   is postscale divider
    84     *
    85     *  NF = PLLMUL + 1
    86     *  NR = REFCLKDIV + 1 (max 62)
    87     *  R  = PLLDIV + 1
    88     *  OD = ODPLL + 1
    89     *  @p
    90     *
    91     *  @a(Flash configuration)
    92     *  If flash configuration is enabled, this module will compute the number
    93     *  of flash wait states required at the current CPU frequency and will
    94     *  program the respective flash registers. This module also allows the
    95     *  user to enable/disable flash prefetching on flash ports A and B.
    96     */
    97    @Template("./Boot.xdt")
    98    @DirectCall
    99    module Boot
   100    {
   101        metaonly struct ModuleView {
   102            Bool configureClocks;
   103            Bool frequencyModulationEnable;
   104            UInt OSCIN;
   105            UInt PLLMUL;
   106            UInt PLLDIV;
   107            UInt REFCLKDIV;
   108            UInt ODPLL;
   109            UInt SPREADINGRATE;
   110            UInt MULMOD;
   111            UInt SPR_AMOUNT;
   112        }
   113    
   114        @Facet
   115        metaonly config ViewInfo.Instance rovViewInfo =
   116            ViewInfo.create({
   117                viewMap: [
   118                [
   119                    'Module',
   120                    {
   121                        type: ViewInfo.MODULE,
   122                        viewInitFxn: 'viewInitModule',
   123                        structName: 'ModuleView'
   124                    }
   125                ],
   126                ]
   127            });
   128    
   129        /*!
   130         *  ======== configureClocks ========
   131         *  Clock configuration flag, default is true.
   132         *
   133         *  Set to false to disable clock configuration.
   134         *
   135         *  Clock configuration will setup the CPU (and RTI) clock source,
   136         *  configure the PLL and system clock dividers.
   137         */
   138        config Bool configureClocks = true;
   139    
   140        /*!
   141         *  ======== OSCIN ========
   142         *  Input frequency to PLL, in MHz. Default is 16 MHz.
   143         *
   144         *  This is the frequency of the oscillator clock (OSCIN) input to the
   145         *  PLL.
   146         */
   147        metaonly config UInt OSCIN = 16;
   148    
   149        /*!
   150         *  ======== PLLMUL ========
   151         *  PLL Multiplication factor value (valid range from 0 to 255)
   152         *
   153         *  PLL Multiplier, NF = PLLMUL + 1
   154         */
   155        metaonly config UInt PLLMUL = 0x4A;
   156    
   157        /*!
   158         *  ======== REFCLKDIV ========
   159         *  PLL Reference clock divider value (valid range from 0 to 62)
   160         *
   161         *  PLL Prescale divider, NR = REFCLKDIV + 1 (max 62)
   162         */
   163        metaonly config UInt REFCLKDIV = 0x5;
   164    
   165        /*!
   166         *  ======== PLLDIV ========
   167         *  PLL Output clock divider (valid range from 0 to 31)
   168         *
   169         *  PLL postscale divider, R = PLLDIV + 1
   170         */
   171        metaonly config UInt PLLDIV = 0;
   172    
   173        /*!
   174         *  ======== ODPLL ========
   175         *  Internal PLL Output divider (valid range from 0 to 7)
   176         *
   177         *  PLL postscale divider, OD = ODPLL + 1
   178         */
   179        metaonly config UInt ODPLL = 1;
   180    
   181        /*!
   182         *  ======== SPREADINGRATE ========
   183         *  Spreading rate (valid range from 0 to 511)
   184         */
   185        metaonly config UInt SPREADINGRATE = 0x1FF;
   186    
   187        /*!
   188         *  ======== MULMOD ========
   189         *  Multiplier correction when modulation enabled (valid range
   190         *  from 0 to 511)
   191         */
   192        metaonly config UInt MULMOD = 0;
   193    
   194        /*!
   195         *  ======== SPR_AMOUNT ========
   196         *  Spreading amount (valid range from 0 to 511)
   197         */
   198        metaonly config UInt SPR_AMOUNT = 0;
   199    
   200        /*!
   201         *  ======== frequencyModulationEnable ========
   202         *  Enable frequency modulation. Default is false.
   203         */
   204        metaonly config Bool frequencyModulationEnable = false;
   205    
   206        /*!
   207         *  ======== configureFlashController ========
   208         *  Flash controller configuration flag, default is true.
   209         *
   210         *  Set to true to enable the configuration of the Flash controller
   211         *  wait states and prefetch mode.
   212         */
   213        metaonly config Bool configureFlashController = true;
   214    
   215        /*!
   216         *  ======== configureFlashWaitStates ========
   217         *  Flash controller wait states configuration flag, default is true.
   218         *
   219         *  Set to true to configure the Flash controller wait states.  The number
   220         *  of wait states is computed based upon the CPU frequency.
   221         */
   222        metaonly config Bool configureFlashWaitStates = true;
   223    
   224        /*!
   225         *  ======== flashPortAPrefetchEnable ========
   226         *  Flash controller port A prefetch enable flag, default is true.
   227         */
   228        metaonly config Bool flashPortAPrefetchEnable = true;
   229    
   230        /*!
   231         *  ======== flashPortBPrefetchEnable ========
   232         *  Flash controller port B prefetch enable flag, default is true.
   233         */
   234        metaonly config Bool flashPortBPrefetchEnable = true;
   235    
   236        /*!
   237         *  @_nodoc
   238         *  ======== getFrequency ========
   239         *  Gets the resulting CPU frequency (in Hz) given the Clock
   240         *  configuration parameters.
   241         *
   242         */
   243        UInt32 getFrequency();
   244    
   245        /*!
   246         *  @_nodoc
   247         *  ======== registerFreqListener ========
   248         *  Register a module to be notified whenever the frequency changes.
   249         *
   250         *  The registered module must have a function named 'fireFrequencyUpdate'
   251         *  which takes the new frequency as an argument.
   252         */
   253        function registerFreqListener();
   254    
   255    internal:
   256    
   257        /* Used to display the computed CPU frequency value in the Grace page. */
   258        metaonly config String displayFrequency;
   259    
   260        /* The computed Flash wait states */
   261        metaonly config UInt flashWaitStates = 3;
   262    
   263    };