1    /*
     2     * Copyright (c) 2019, 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 C66 family-specific implementations of the
    45     *  APIs defined in {@link ti.sysbios.interfaces.ICache ICache}.  It also
    46     *  provides additional C66 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    module Cache inherits ti.sysbios.interfaces.ICache
   101    {
   102        // -------- Module Types --------
   103    
   104        /*!
   105         *  ======== ModuleView ========
   106         *  @_nodoc
   107         */
   108        metaonly struct ModuleView {
   109            String  L1PCacheSize;
   110            String  L1PMode;
   111            String  L1DCacheSize;
   112            String  L1DMode;
   113            String  L2CacheSize;
   114            String  L2Mode;
   115        };
   116    
   117        /*!
   118         *  ======== rovViewInfo ========
   119         *  @_nodoc
   120         */
   121        @Facet
   122        metaonly config ViewInfo.Instance rovViewInfo =
   123            ViewInfo.create({
   124                viewMap: [
   125                    ['Module',
   126                        {
   127                            type: ViewInfo.MODULE,
   128                            viewInitFxn: 'viewInitModule',
   129                            structName: 'ModuleView'
   130                        }
   131                    ],
   132                ]
   133            });
   134    
   135        /*! Lists of cache modes for L1/L2 caches */
   136        enum Mode {
   137            Mode_FREEZE,    /*! No new cache lines are allocated */
   138            Mode_BYPASS,    /*! All access result in long-distance access */
   139            Mode_NORMAL     /*! Normal operation of cache */
   140        };
   141    
   142        /*! Level 1 cache size type definition. Can be used for both L1D & L1P */
   143        enum L1Size {
   144            L1Size_0K = 0,  /*! Amount of cache is 0K, Amount of SRAM is 32K */
   145            L1Size_4K = 1,  /*! Amount of cache is 4K, Amount of SRAM is 28K */
   146            L1Size_8K = 2,  /*! Amount of cache is 8K, Amount of SRAM is 24K */
   147            L1Size_16K = 3, /*! Amount of cache is 16K, Amount of SRAM is 16K */
   148            L1Size_32K = 4  /*! Amount of cache is 32K, Amount of SRAM is 0K */
   149        };
   150    
   151        /*! Level 2 cache size type definition. */
   152        enum L2Size {
   153            L2Size_0K = 0,   /*! L2 is all SRAM */
   154            L2Size_32K = 1,  /*! Amount of cache is 32K */
   155            L2Size_64K = 2,  /*! Amount of cache is 64K */
   156            L2Size_128K = 3, /*! Amount of cache is 128K */
   157            L2Size_256K = 4, /*! Amount of cache is 256K */
   158            L2Size_512K = 5, /*! Amount of cache is 512K */
   159            L2Size_1024K = 6 /*! Amount of cache is 1024K */
   160        };
   161    
   162        const UInt32 PC  = 1;     /*! Permit Caching                     */
   163        const UInt32 WTE = 2;     /*! Write through enabled              */
   164        const UInt32 PCX = 4;     /*! Permit caching in external cache   */
   165        const UInt32 PFX = 8;     /*! Prefetchable by external engines   */
   166    
   167        /*! Structure for specifying all cache sizes. */
   168        struct Size {
   169            L1Size l1pSize;         /*! L1 Program cache size */
   170            L1Size l1dSize;         /*! L1 Data data size */
   171            L2Size l2Size;          /*! L2 cache size */
   172        };
   173    
   174        /*! Default sizes of caches.
   175         * @_nodoc
   176         */
   177        config Size initSize = {
   178            l1pSize: L1Size_32K,
   179            l1dSize: L1Size_32K,
   180            l2Size: L2Size_0K
   181        };
   182    
   183        /*! @_nodoc
   184         *
   185         *  This parameter is used to break up large blocks into multiple
   186         *  small blocks which are done atomically.  Each block of the
   187         *  specified size waits for the cache operation to finish before
   188         *  starting the next block.  Setting this size to 0, means the
   189         *  cache operations are not done atomically.
   190         */
   191        config UInt32 atomicBlockSize = 1024;
   192    
   193        /*!
   194         *  ======== disable ========
   195         *  Disables the 'type' cache(s)
   196         *
   197         *  Disabling of L2 cache is currently not supported.
   198         */
   199        override Void disable(Bits16 type);
   200    
   201        /*!
   202         *  ======== getSize ========
   203         *  Get sizes of all caches
   204         *
   205         *  @param(size)    pointer to structure of type Cache_Size
   206         */
   207        Void getSize(Size *size);
   208    
   209        /*!
   210         *  ======== setSize ========
   211         *  Set sizes of all caches
   212         *
   213         *  @param(size)    pointer to structure of type Cache_Size
   214         */
   215        Void setSize(Size *size);
   216    
   217        /*!
   218         *  ======== wbAll ========
   219         *  Write back all caches
   220         *
   221         *  Perform a global write back.  There is no effect on L1P cache.
   222         *  All cache lines are left valid in L1D cache and dirty lines in L1D cache
   223         *  are written back to L2 or external.  All cache lines are left valid in
   224         *  L2 cache and dirty lines in L2 cache are written back to external.
   225         *  This function does not wait for write back operation to perculate
   226         *  through the whole memory system before returing. Call Cache_wait(),
   227         *  after this function if necessary.
   228         */
   229        override Void wbAll();
   230    
   231        /*!
   232         *  ======== wbL1dAll ========
   233         *  Write back L1D cache
   234         *
   235         *  Perform a global write back of L1D cache. There is no effect on L1P
   236         *  or L2 cache.  All cache lines are left valid in L1D cache and the
   237         *  dirty lines in L1D cache are written back to L2 or external.
   238         *  This function does not wait for write back operation to perculate
   239         *  through the whole memory system before returing. Call Cache_wait(),
   240         *  after this function if necessary.
   241         */
   242        Void wbL1dAll();
   243    
   244        /*!
   245         *  ======== wbInvAll ========
   246         *  Write back invalidate all caches
   247         *
   248         *  Performs a global write back and invalidate.  All cache lines are
   249         *  invalidated in L1P cache.  All dirty cache lines are written back to L2
   250         *  or external and then invalidated in L1D cache.  All dirty cache lines
   251         *  are written back to external and then invalidated in L2 cache.
   252         *  This function does not wait for write back operation to perculate
   253         *  through the whole memory system before returing. Call Cache_wait(),
   254         *  after this function if necessary.
   255         */
   256        override Void wbInvAll();
   257    
   258        /*!
   259         *  ======== wbInvL1dAll ========
   260         *  Write back invalidate L1D cache
   261         *
   262         *  Performs a global write back and invalidate of L1D cache.
   263         *  All dirty cache lines are written back to L2 or
   264         *  external and then invalidated in L1D cache.
   265         *  This function does not wait for write back operation to perculate
   266         *  through the whole memory system before returing. Call Cache_wait(),
   267         *  after this function if necessary.
   268         */
   269        Void wbInvL1dAll();
   270    
   271        Void setL2CFG(UInt size);
   272        ULong getL2CFG();
   273        Void setL1DCFG(UInt size);
   274        ULong getL1DCFG();
   275        Void setL2WB(UInt flag);
   276        Void setL2WBINV(UInt flag);
   277        Void setL1DWB(UInt flag);
   278        Void setL1DWBINV(UInt flag);
   279    
   280    internal:
   281    
   282        /*
   283         *  ======== startup ========
   284         *  startup function to enable cache early during climb-up
   285         */
   286        Void startup();
   287    }