1    /*
     2     * Copyright (c) 2015-2020, 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     *  ======== Cache.xdc ========
    34     */
    35    
    36    package ti.sysbios.family.arm.v7r;
    37    
    38    import xdc.rov.ViewInfo;
    39    
    40    import xdc.runtime.Assert;
    41    
    42    /*!
    43     *  ======== Cache ========
    44     *  ARMv7-R Cache Module
    45     *
    46     *  This module manages the data and instruction caches on Cortex-R5
    47     *  processors. It provides a list of functions that perform cache operations.
    48     *  The functions operate on a per cache line except for the 'All' functions
    49     *  which operate on the entire cache specified.  Any Address that is not
    50     *  aligned to a cache line gets rounded down to the address of the nearest
    51     *  cache line.
    52     *
    53     *  The L1 data and program caches are enabled by default early during the
    54     *  startup sequence (prior to any Module_startup()s).
    55     *  Data caching requires the MPU to be enabled and attributes for the
    56     *  memory region to be set as cacheable.
    57     *  Program caching does not require the MPU to be enabled and therefore
    58     *  occurs when the L1 program cache is enabled.
    59     *
    60     *  (See the {@link ti.sysbios.family.arm.Mpu} module for information
    61     *   about the MPU.)
    62     *
    63     *  Unconstrained Functions
    64     *  All functions
    65     *
    66     *  @p(html)
    67     *  <h3> Calling Context </h3>
    68     *  <table border="1" cellpadding="3">
    69     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    70     *    </colgroup>
    71     *
    72     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    73     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    74     *    <!--                               -->
    75     *    <tr><td> {@link #disable}     </td><td>   Y    </td><td>   Y    </td>
    76     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    77     *    <tr><td> {@link #enable}      </td><td>   Y    </td><td>   Y    </td>
    78     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    79     *    <tr><td> {@link #inv}         </td><td>   Y    </td><td>   Y    </td>
    80     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    81     *    <tr><td> {@link #invL1dAll}   </td><td>   Y    </td><td>   Y    </td>
    82     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    83     *    <tr><td> {@link #invL1pAll}   </td><td>   Y    </td><td>   Y    </td>
    84     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    85     *    <tr><td> {@link #wait}        </td><td>   Y    </td><td>   Y    </td>
    86     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    87     *    <tr><td> {@link #wb}          </td><td>   Y    </td><td>   Y    </td>
    88     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    89     *    <tr><td> {@link #wbAll}      </td><td>   Y    </td><td>   Y    </td>
    90     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    91     *    <tr><td> {@link #wbInv}       </td><td>   Y    </td><td>   Y    </td>
    92     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    93     *    <tr><td> {@link #wbInvAll}   </td><td>   Y    </td><td>   Y    </td>
    94     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    95     *    <tr><td colspan="6"> Definitions: <br />
    96     *       <ul>
    97     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    98     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    99     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   100     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   101     *           <ul>
   102     *             <li> In your module startup after this module is started
   103     *   (e.g. Cache_Module_startupDone() returns TRUE). </li>
   104     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   105     *             <li> During main().</li>
   106     *             <li> During BIOS.startupFxns.</li>
   107     *           </ul>
   108     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   109     *           <ul>
   110     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   111     *             <li> In your module startup before this module is started
   112     *   (e.g. Cache_Module_startupDone() returns FALSE).</li>
   113     *           </ul>
   114     *       </ul>
   115     *    </td></tr>
   116     *
   117     *  </table>
   118     *  @p
   119     */
   120    
   121    /* REQ_TAG(SYSBIOS-1244) */
   122    module Cache inherits ti.sysbios.interfaces.ICache
   123    {
   124        /*!
   125         *  ======== ModView ========
   126         *  @_nodoc
   127         */
   128        metaonly struct CacheInfoView {
   129            String      cache;
   130            SizeT       cacheSize;
   131            SizeT       lineSize;
   132            UInt        ways;
   133            SizeT       waySize;
   134        };
   135    
   136        /*!
   137         *  ======== rovViewInfo ========
   138         *  @_nodoc
   139         */
   140        @Facet
   141        metaonly config ViewInfo.Instance rovViewInfo =
   142            ViewInfo.create({
   143                viewMap: [
   144                    ['Cache Info',  { type: ViewInfo.MODULE_DATA,
   145                                      viewInitFxn: 'viewInitCacheInfo',
   146                                      structName: 'CacheInfoView'}]
   147                ]
   148            });
   149    
   150        /*! Asserted in Cache_lock */
   151        config Assert.Id A_badBlockLength = {
   152            msg: "A_badBlockLength: Block length too large. Must be <= L2 way size."
   153        };
   154    
   155        /*! Asserted in Cache_lock */
   156        config Assert.Id A_blockCrossesPage = {
   157            msg: "A_blockCrossesPage: Memory block crosses L2 way page boundary."
   158        };
   159    
   160        /*!
   161         *  Enable L1 data and program caches.
   162         *
   163         *  To enable a subset of the caches, set this parameter
   164         *  to 'false' and call Cache_enable() within main, passing it only
   165         *  the {@link Cache#Type Cache_Type(s)} to be enabled.
   166         *
   167         *  Data caching requires the MMU and the memory section/page
   168         *  descriptor cacheable attribute to be enabled.
   169         *
   170         *  NOTE: this flag is not used when {@link #skipEarlyCacheStartup}
   171         *  is true.
   172         */
   173        override config Bool enableCache = true;
   174    
   175        /*!
   176         *  Don't install Cache_startup() during boot
   177         *
   178         *  The Cache_startup() function will normally be called during
   179         *  the early boot Reset functions array.  Cache_startup() also
   180         *  starts the MPU via the MPU_startup() function.  Both these
   181         *  functions disable the caches at one point or another, which
   182         *  can have undesired consequences when the R5 is operating in
   183         *  certain states or modes.
   184         *
   185         *  In addition to above, some systems set up the cache and MPU
   186         *  before loading/running the SYS/BIOS application, in which case
   187         *  SYS/BIOS should not do additional setup that might conflict with
   188         *  or undo pre-SYS/BIOS system setup.
   189         *
   190         *  NOTE: when set to true, the {@link #enableCache} setting becomes
   191         *  "don't care" as it is not used when skipEarlyCacheStartup is true.
   192         */
   193        config Bool skipEarlyCacheStartup = false;
   194    
   195        /*!
   196         *  Enable ACTLR FWT (Force Write Thru) bit during Cache_startup()
   197         *
   198         *  "Force write-thru" forces write-thru behavior for write-back regions.
   199         *
   200         *  NOTE: this flag is not used when {@link #skipEarlyCacheStartup}
   201         *  is true or {@link #enableCache} is false.
   202         */
   203        config Bool enableForceWrThru = false;
   204    
   205        /*!
   206         *  Disable Cache Line Fill Optimization
   207         *
   208         *  In normal cache operation there can be numerous outstanding data
   209         *  cache line fill operations at a given time.  Set this flag to 'true'
   210         *  to limit outstanding cache line fill operations to 2 (by setting
   211         *  ACTLR.DLFO bit).
   212         *
   213         *  There is no default value for this because Core modules for parts
   214         *  that use this Cache module will have their own idea about disabling
   215         *  LF optimization.  This flag exists solely for user configuration
   216         *  file to use in order to override the part's Core module decision.
   217         */
   218        metaonly config Bool disableLFOptimization;
   219    
   220        /*!
   221         *  ======== disable ========
   222         *  Disables the 'type' cache(s)
   223         *
   224         *  This function internally disables interrupts to ensure the cache
   225         *  operations performed before disabling the cache are not interrupted.
   226         *  Since cache maintenance operations can take a long time, this
   227         *  function may disable interrupts for a long period of time.
   228         *
   229         *  On certain Cortex-R devices, the FIQ interrupt cannot be disabled
   230         *  by software. Therefore, this function only disables IRQ interrupts
   231         *  on such devices. If this function needs to be called to disable
   232         *  interrupts, then care must be take that the FIQ ISR does not
   233         *  interfere with the cache flush maintenance operations performed
   234         *  by this function before disabling the cache.
   235         */
   236        override Void disable(Bits16 type);
   237    
   238        /*! @_nodoc
   239         *  ======== getEnabled ========
   240         *  Get the 'type' bitmask of cache(s) enabled.
   241         */
   242        Bits16 getEnabled();
   243    
   244        /*!
   245         *  ======== invL1dAll ========
   246         *  Invalidate all of L1 data cache.
   247         *
   248         *  This function should be used with caution.  In general, the
   249         *  L1 data cache may contain some stack variable or valid data
   250         *  that should not be invalidated.  This function should be used
   251         *  only when all contents of L1 data cache is unwanted.
   252         */
   253        /* REQ_TAG(SYSBIOS-1245) */
   254        Void invL1dAll();
   255    
   256        /*!
   257         *  ======== invL1pAll ========
   258         *  Invalidate all of L1 program cache.
   259         */
   260        /* REQ_TAG(SYSBIOS-1246) */
   261        Void invL1pAll();
   262    
   263    internal:
   264    
   265        /*
   266         *  ======== initModuleState ========
   267         *  Initializes the module state.
   268         *
   269         *  This function initializes module state fields like
   270         *  L1D/L1P cache size and number of cache lines/sets. It
   271         *  is registered as a first function.
   272         */
   273        Void initModuleState();
   274    
   275        /*
   276         *  ======== startup ========
   277         *  startup function to enable cache early during climb-up (run as a reset
   278         *  function)
   279         */
   280        Void startup();
   281    
   282        /*!
   283         *  ======== disableL1d ========
   284         *  Disable L1 data cache
   285         *
   286         *  This function performs a write back invalidate all of
   287         *  L1 data cache before it disables the cache.
   288         */
   289        Void disableL1d();
   290    
   291        /*!
   292         *  ======== disableL1p ========
   293         *  Disable L1 Program cache
   294         *
   295         *  This function performs an invalidate all of L1 program cache
   296         *  before it disables the cache.
   297         */
   298        Void disableL1p();
   299    
   300        /*!
   301         *  ======== enableL1d ========
   302         *  Enable L1 data cache.
   303         */
   304        Void enableL1d();
   305    
   306        /*!
   307         *  ======== enableL1p ========
   308         *  Enable L1 program cache.
   309         */
   310        Void enableL1p();
   311    
   312        /*
   313         *  ======== invL1d ========
   314         *  Invalidates range in L1 data cache.
   315         */
   316        Void invL1d(Ptr blockPtr, SizeT byteCnt, Bool wait);
   317    
   318        /*
   319         *  ======== invL1p ========
   320         *  Invalidates range in L1 program cache.
   321         */
   322        Void invL1p(Ptr blockPtr, SizeT byteCnt, Bool wait);
   323    
   324        /*
   325         *  ======== wbInvAllI ========
   326         *  Write back invalidate all caches
   327         */
   328        Void wbInvAllI();
   329    
   330        /*
   331         *  ======== getCacheLevelInfo ========
   332         *  returns Cache Size Id Register of corresponding Cache level
   333         *
   334         *  level values
   335         *      0 = L1D
   336         *      1 = L1P
   337         */
   338        Bits32 getCacheLevelInfo(UInt level);
   339    
   340        /*
   341         *  ======== configForceWrThru ========
   342         *  Configure ACTLR FWT bit
   343         */
   344        Void configForceWrThru(Bool enable);
   345    
   346        /*
   347         *  ======== setDLFO ========
   348         *  Set ACTLR.DLFO bit
   349         */
   350        Void setDLFO();
   351    
   352        struct Module_State {
   353            UInt32  l1dCacheLineSize;   // Size of L1D cache line in bytes
   354            UInt32  l1pCacheLineSize;   // Size of L1P cache line in bytes
   355            Bits32  l1dInfo;
   356            Bits32  l1pInfo;
   357        }
   358    }