1    /*
     2     * Copyright (c) 2019-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.c7x;
    37    
    38    import xdc.rov.ViewInfo;
    39    
    40    /*!
    41     *  ======== Cache ========
    42     *  Cache Module
    43     *
    44     *  This Cache module provides c7x family-specific implementations of the
    45     *  APIs defined in {@link ti.sysbios.interfaces.ICache ICache}.  It also
    46     *  provides additional c7x specific cache functions.
    47     *
    48     *  Unconstrained Functions
    49     *  All functions
    50     *
    51     *  @p(html)
    52     *  <h3> Calling Context </h3>
    53     *  <table border="1" cellpadding="3">
    54     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    55     *
    56     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    57     *    <!--                                                                                                                 -->
    58     *    <tr><td> {@link #disable}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    59     *    <tr><td> {@link #enable}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    60     *    <tr><td> {@link #getMar*}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    61     *    <tr><td> {@link #getMode*}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    62     *    <tr><td> {@link #getSize*}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    63     *    <tr><td> {@link #inv}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    64     *    <tr><td> {@link #invL1pAll*} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    65     *    <tr><td> {@link #setMar*}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    66     *    <tr><td> {@link #setMode*}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    67     *    <tr><td> {@link #setSize*}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    68     *    <tr><td> {@link #wait}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    69     *    <tr><td> {@link #wb}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    70     *    <tr><td> {@link #wbAll*}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    71     *    <tr><td> {@link #wbL1dAll}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    72     *    <tr><td> {@link #wbInv}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    73     *    <tr><td> {@link #wbInvAll}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    74     *    <tr><td> {@link #wbInvL1dAll}</td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    75     *    <tr><td colspan="6"> Definitions: <br />
    76     *       <ul>
    77     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    78     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    79     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    80     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    81     *           <ul>
    82     *             <li> In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE). </li>
    83     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    84     *             <li> During main().</li>
    85     *             <li> During BIOS.startupFxns.</li>
    86     *           </ul>
    87     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    88     *           <ul>
    89     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    90     *             <li> In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).</li>
    91     *           </ul>
    92     *       <li> <b>*</b>: These APIs are intended to be made at initialization time, but are not restricted to this. </li>
    93     *       </ul>
    94     *    </td></tr>
    95     *
    96     *  </table>
    97     *  @p
    98     */
    99    
   100    @ModuleStartup
   101    
   102    module Cache inherits ti.sysbios.interfaces.ICache
   103    {
   104        // -------- Module Types --------
   105    
   106        /*!
   107         *  ======== ModuleView ========
   108         *  @_nodoc
   109         */
   110        metaonly struct ModuleView {
   111            String  L1DCacheSize;
   112            String  L2CacheSize;
   113        };
   114    
   115        /*!
   116         *  ======== rovViewInfo ========
   117         *  @_nodoc
   118         */
   119        @Facet
   120        metaonly config ViewInfo.Instance rovViewInfo =
   121            ViewInfo.create({
   122                viewMap: [
   123                    ['Module',
   124                        {
   125                            type: ViewInfo.MODULE,
   126                            viewInitFxn: 'viewInitModule',
   127                            structName: 'ModuleView'
   128                        }
   129                    ],
   130                ]
   131            });
   132    
   133        /*! Lists of cache modes for L1/L2 caches */
   134        enum Mode {
   135            Mode_FREEZE,    /*! No new cache lines are allocated */
   136            Mode_BYPASS,    /*! All access result in long-distance access */
   137            Mode_NORMAL     /*! Normal operation of cache */
   138        };
   139    
   140        /*! Level 1 cache size type definition. Can be used for both L1D & L1P */
   141        enum L1Size {
   142            L1Size_0K = 0,  /*! Amount of cache is 0K, Amount of SRAM is 32K */
   143            L1Size_4K = 1,  /*! Amount of cache is 4K, Amount of SRAM is 28K */
   144            L1Size_8K = 2,  /*! Amount of cache is 8K, Amount of SRAM is 24K */
   145            L1Size_16K = 3, /*! Amount of cache is 16K, Amount of SRAM is 16K */
   146            L1Size_32K = 4  /*! Amount of cache is 32K, Amount of SRAM is 0K */
   147        };
   148    
   149        /*! Level 2 cache size type definition. */
   150        enum L2Size {
   151            L2Size_0K = 0,   /*! L2 is all SRAM */
   152            L2Size_32K = 1,  /*! Amount of cache is 32K */
   153            L2Size_64K = 2,  /*! Amount of cache is 64K */
   154            L2Size_128K = 3, /*! Amount of cache is 128K */
   155            L2Size_256K = 4, /*! Amount of cache is 256K */
   156            L2Size_512K = 5, /*! Amount of cache is 512K */
   157            L2Size_1024K = 6 /*! Amount of cache is 1024K */
   158        };
   159    
   160        const UInt32 PC  = 1;     /*! Permit Caching                     */
   161        const UInt32 WTE = 2;     /*! Write through enabled              */
   162        const UInt32 PCX = 4;     /*! Permit caching in external cache   */
   163        const UInt32 PFX = 8;     /*! Prefetchable by external engines   */
   164    
   165        /*! Structure for specifying all cache sizes. */
   166        struct Size {
   167            L1Size l1pSize;         /*! L1 Program cache size */
   168            L1Size l1dSize;         /*! L1 Data data size */
   169            L2Size l2Size;          /*! L2 cache size */
   170        };
   171    
   172        /*! Default sizes of caches.
   173         * @_nodoc
   174         */
   175        config Size initSize = {
   176            l1pSize: L1Size_32K,
   177            l1dSize: L1Size_32K,
   178            l2Size: L2Size_0K
   179        };
   180    
   181        /*! @_nodoc
   182         *
   183         *  This parameter is used to break up large blocks into multiple
   184         *  small blocks which are done atomically.  Each block of the
   185         *  specified size waits for the cache operation to finish before
   186         *  starting the next block.  Setting this size to 0, means the
   187         *  cache operations are not done atomically.
   188         */
   189        config UInt32 atomicBlockSize = 1024;
   190    
   191        /*!
   192         *  ======== disable ========
   193         *  Disables the 'type' cache(s)
   194         *
   195         *  Disabling of L2 cache is currently not supported.
   196         */
   197        override Void disable(Bits16 type);
   198    
   199        /*!
   200         *  ======== getSize ========
   201         *  Get sizes of all caches
   202         *
   203         *  @param(size)    pointer to structure of type Cache_Size
   204         */
   205        Void getSize(Size *size);
   206    
   207        /*!
   208         *  ======== setSize ========
   209         *  Set sizes of all caches
   210         *
   211         *  @param(size)    pointer to structure of type Cache_Size
   212         */
   213        Void setSize(Size *size);
   214    
   215        /*!
   216         *  ======== wbAll ========
   217         *  Write back all caches
   218         *
   219         *  Perform a global write back.  There is no effect on L1P cache.
   220         *  All cache lines are left valid in L1D cache and dirty lines in L1D cache
   221         *  are written back to L2 or external.  All cache lines are left valid in
   222         *  L2 cache and dirty lines in L2 cache are written back to external.
   223         *  This function does not wait for write back operation to perculate
   224         *  through the whole memory system before returing. Call Cache_wait(),
   225         *  after this function if necessary.
   226         */
   227        override Void wbAll();
   228    
   229        /*!
   230         *  ======== wbL1dAll ========
   231         *  Write back L1D cache
   232         *
   233         *  Perform a global write back of L1D cache. There is no effect on L1P
   234         *  or L2 cache.  All cache lines are left valid in L1D cache and the
   235         *  dirty lines in L1D cache are written back to L2 or external.
   236         *  This function does not wait for write back operation to perculate
   237         *  through the whole memory system before returing. Call Cache_wait(),
   238         *  after this function if necessary.
   239         */
   240        Void wbL1dAll();
   241    
   242        /*!
   243         *  ======== wbInvAll ========
   244         *  Write back invalidate all caches
   245         *
   246         *  Performs a global write back and invalidate.  All cache lines are
   247         *  invalidated in L1P cache.  All dirty cache lines are written back to L2
   248         *  or external and then invalidated in L1D cache.  All dirty cache lines
   249         *  are written back to external and then invalidated in L2 cache.
   250         *  This function does not wait for write back operation to perculate
   251         *  through the whole memory system before returing. Call Cache_wait(),
   252         *  after this function if necessary.
   253         */
   254        override Void wbInvAll();
   255    
   256        /*!
   257         *  ======== wbInvL1dAll ========
   258         *  Write back invalidate L1D cache
   259         *
   260         *  Performs a global write back and invalidate of L1D cache.
   261         *  All dirty cache lines are written back to L2 or
   262         *  external and then invalidated in L1D cache.
   263         *  This function does not wait for write back operation to perculate
   264         *  through the whole memory system before returing. Call Cache_wait(),
   265         *  after this function if necessary.
   266         */
   267        Void wbInvL1dAll();
   268    
   269        Void setL2CFG(UInt size);
   270        ULong getL2CFG();
   271        Void setL1DCFG(UInt size);
   272        ULong getL1DCFG();
   273        Void setL2WB(UInt flag);
   274        Void setL2WBINV(UInt flag);
   275        Void setL1DWB(UInt flag);
   276        Void setL1DWBINV(UInt flag);
   277    
   278    internal:
   279    
   280        /*
   281         *  ======== startup ========
   282         *  startup function to enable cache early during climb-up
   283         */
   284        Void startup();
   285    
   286        struct Module_State {
   287            UInt64 L1DCFG;
   288            UInt64 L2CFG;
   289        };
   290    }