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     *  ======== Cache.xdc ========
    34     *
    35     */
    36    
    37    package ti.sysbios.family.arm.arm9;
    38    
    39    /*!
    40     *  ======== Cache ========
    41     *  ARM Cache Module
    42     *
    43     *  This module manages the data and instruction caches on ARM processors.
    44     *  It provides a list of functions that perform cache operations.  The
    45     *  functions operate on a per cache line except for the 'All' functions
    46     *  which operate on the entire cache specified.  Any Address that is not
    47     *  aligned to a cache line gets rounded down to the address of
    48     *  the nearest cache line.
    49     *
    50     *  The L1 data and program caches are enabled 
    51     *  by default early during the startup sequence (prior to any Module_startup()s).  
    52     *  Data caching requires the MMU to be enabled and the cacheable 
    53     *  attribute of the section/page descriptor for a corresponding
    54     *  memory region to be enabled.  
    55     *  Program caching does not require the MMU to be enabled and therefore 
    56     *  occurs when the L1 program cache is enabled.
    57     *
    58     *  Note: See the {@link ti.sysbios.family.arm.arm9.Mmu} module for 
    59     *        information about the MMU.
    60     *
    61     *  Unconstrained Functions
    62     *  All functions
    63     *
    64     *  @p(html)
    65     *  <h3> Calling Context </h3>
    66     *  <table border="1" cellpadding="3">
    67     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    68     *
    69     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    70     *    <!--                                                                                                                 -->
    71     *    <tr><td> {@link #disable}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    72     *    <tr><td> {@link #enable}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    73     *    <tr><td> {@link #inv}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    74     *    <tr><td> {@link #invL1dAll}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    75     *    <tr><td> {@link #invL1pAll}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    76     *    <tr><td> {@link #wait}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    77     *    <tr><td> {@link #wb}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    78     *    <tr><td> {@link #wbInv}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    79     *    <tr><td> {@link #wbInvL1dAll} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    80     *    <tr><td> {@link #wbL1dAll}    </td><td>   Y    </td><td>   Y    </td><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 (e.g. Cache_Module_startupDone() returns TRUE). </li>
    89     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    90     *             <li> During main().</li>
    91     *             <li> During BIOS.startupFxns.</li>
    92     *           </ul>
    93     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    94     *           <ul>
    95     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    96     *             <li> In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).</li>
    97     *           </ul>
    98     *       </ul>
    99     *    </td></tr>
   100     *
   101     *  </table>
   102     *  @p
   103     */
   104    
   105    module Cache inherits ti.sysbios.interfaces.ICache
   106    {
   107        /*!
   108         *  Size of L1 data cache Line
   109         */
   110        const UInt sizeL1dCacheLine = 32;
   111    
   112        /*!
   113         *  Size of L1 program cache Line
   114         */
   115        const UInt sizeL1pCacheLine = 32;
   116        
   117        /*!
   118         *  Enable L1 data and program caches.
   119         *
   120         *  To enable a subset of the caches, set this parameter
   121         *  to 'false' and call Cache_enable() within main, passing it only 
   122         *  the {@link Cache#Type Cache_Type(s)} to be enabled.
   123         *
   124         *  Data caching requires the MMU and the memory section/page
   125         *  descriptor cacheable attribute to be enabled.
   126         */
   127        config Bool enableCache = true;
   128        
   129        /*! @_nodoc
   130         *  ======== getEnabled ========
   131         *  Get the 'type' bitmask of cache(s) enabled.
   132         */
   133        Bits16 getEnabled();
   134    
   135        /*!
   136         *  ======== invL1dAll ========
   137         *  Invalidate all of L1 data cache.
   138         *
   139         *  This function should be used with caution.  In general, the
   140         *  L1 data cache may contain some stack variable or valid data
   141         *  that should not be invalidated.  This function should be used
   142         *  only when all contents of L1 data cache is unwanted.
   143         */
   144        Void invL1dAll();
   145    
   146        /*!
   147         *  ======== invL1pAll ========
   148         *  Invalidate all of L1 program cache.
   149         */
   150        Void invL1pAll();
   151     
   152    
   153    internal:
   154    
   155        /*!
   156         *  ======== startup ========
   157         *  startup function to enable cache early during climb-up
   158         */
   159        Void startup();
   160        
   161        /*!
   162         *  ======== disableL1d ========
   163         *  Disable L1 data cache
   164         *
   165         *  This function performs a write back invalidate all of
   166         *  L1 data cache before it disables the cache.
   167         */
   168        Void disableL1d();
   169    
   170        /*!
   171         *  ======== disableL1p ========
   172         *  Disable L1 Program cache
   173         *
   174         *  This function performs an invalidate all of L1 program cache
   175         *  before it disables the cache.
   176         */
   177        Void disableL1p();
   178    
   179        /*!
   180         *  ======== enableL1d ========
   181         *  Enable L1 data cache.
   182         */
   183        Void enableL1d();
   184    
   185        /*!
   186         *  ======== enableL1p ========
   187         *  Enable L1 program cache.
   188         */
   189        Void enableL1p();
   190    
   191        /*!
   192         *  ======== invL1d ========
   193         *  Invalidates range in L1 data cache.
   194         */
   195        Void invL1d(Ptr blockPtr, SizeT byteCnt, Bool wait);
   196    
   197        /*!
   198         *  ======== invL1p ========
   199         *  Invalidates range in L1 program cache.
   200         */
   201        Void invL1p(Ptr blockPtr, SizeT byteCnt, Bool wait);
   202    
   203    }