1    /* 
     2     * Copyright (c) 2012, 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.hal.unicache;
    37    
    38    import xdc.rov.ViewInfo;
    39    import xdc.runtime.Error;
    40    import xdc.runtime.Types;
    41    
    42    import ti.sysbios.interfaces.ICache;
    43    import ti.sysbios.hal.Hwi;
    44    
    45    /*!
    46     *  ======== Cache ========
    47     *  The unicache Cache module used by the omap4 Tesla and Ducati cores
    48     *
    49     *  The Tesla and Ducati UniCaches do not support separate program and 
    50     *  data caches. Therefore none of the unique Cache_Type L1P/L1D/L2P/L2D
    51     *  operations can be precisely supported. The APIs in this module ignore 
    52     *  the P/D and observe only the L1/L2 designations (ie Cache_Type_L1P 
    53     *  is functionally equivalent to Cache_Type_L1D and Cache_Type_L1).
    54     *
    55     *  @a(Restrictions)
    56     *  When used within a dual M3 core (Ducati arrangement), care must be
    57     *  taken when initializing this shared resource. 
    58     *  The "Shared Resources" note provided
    59     *  in the {@link ti.sysbios.family.arm.ducati ducati} package discusses
    60     *  the management of the various hardware and software resources
    61     *  shared by the two M3 cores.
    62     *
    63     *  As the unicache is shared between the two M3 cores, it should only
    64     *  be initialized and enabled once.
    65     *  It is intended that Core 0 will {@link #configureCache configure} 
    66     *  the unicache at startup and then either {@link #enableCache enable} 
    67     *  it at that time or later on by manually invoking 
    68     *  {@link #enable Cache_enable()}.
    69     *
    70     *  The unicache Cache module is a Gated module. In a dual M3 core (Ducati) 
    71     *  environment, the unicache Cache module employs a 
    72     *  {@link ti.sysbios.family.arm.ducati.GateDualCore GateDualCore} gate
    73     *  to arbitrate the usage of the shared unicache registers. In a non 
    74     *  shared environment such as the C64T core in an OMAP4 device, a 
    75     *  {@link ti.sysbios.gates.GateHwi GateHwi} gate is used to avoid multi
    76     *  thread conflicts.
    77     *
    78     *  @a
    79     *
    80     *  @p(html)
    81     *  <h3> Calling Context </h3>
    82     *  <table border="1" cellpadding="3">
    83     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    84     *    </colgroup>
    85     *
    86     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    87     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    88     *    <!--                                                                  -->
    89     *    <tr><td> {@link #disable}     </td><td>   Y    </td><td>   Y    </td>
    90     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    91     *    <tr><td> {@link #enable}      </td><td>   Y    </td><td>   Y    </td>
    92     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    93     *    <tr><td> {@link #inv}         </td><td>   Y    </td><td>   Y    </td>
    94     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    95     *    <tr><td> {@link #wb}          </td><td>   Y    </td><td>   Y    </td>
    96     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    97     *    <tr><td> {@link #wbInv}       </td><td>   Y    </td><td>   Y    </td>
    98     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    99     *    <tr><td> {@link #wait}        </td><td>   Y    </td><td>   Y    </td>
   100     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   101     *    <tr><td colspan="6"> Definitions: <br />
   102     *       <ul>
   103     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   104     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   105     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   106     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   107     *           <ul>
   108     *             <li> In your module startup after this module is started 
   109     *    (e.g. Cache_Module_startupDone() returns TRUE). </li>
   110     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   111     *             <li> During main().</li>
   112     *             <li> During BIOS.startupFxns.</li>
   113     *           </ul>
   114     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   115     *           <ul>
   116     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   117     *             <li> In your module startup before this module is started 
   118     *    (e.g. Cache_Module_startupDone() returns FALSE).</li>
   119     *           </ul>
   120     *       </ul>
   121     *    </td></tr>
   122     *
   123     *  </table>
   124     *  @p
   125     */
   126    
   127    @ModuleStartup
   128    @Gated
   129    
   130    module Cache inherits ti.sysbios.interfaces.ICache 
   131    {
   132        
   133        // -------- Module Types --------
   134    
   135        /*!
   136         *  Runtime representation of the Cache registers
   137         */
   138        struct CACHE {
   139            UInt32 L1_INFO;         /* 0000 */
   140            UInt32 L1_CONFIG;       /* 0004 */
   141            UInt32 L1_INT;          /* 0008 */
   142            UInt32 L1_OCP;          /* 000C */
   143            UInt32 L1_MAINT;        /* 0010 */
   144            Ptr    L1_MTSTART;      /* 0014 */
   145            Ptr    L1_MTEND;        /* 0018 */
   146            Ptr    L1_CTADDR;       /* 001c */
   147            UInt32 L1_CTDATA;       /* 0020 */
   148    
   149            UInt32 Reserved[0x77];  /* 0024 - 001fc */
   150    
   151            UInt32 L2_INFO;         /* 0200 */
   152            UInt32 L2_CONFIG;       /* 0204 */
   153            UInt32 L2_INT;          /* 0208 */
   154            UInt32 L2_OCP;          /* 020C */
   155            UInt32 L2_MAINT;        /* 0210 */
   156            Ptr    L2_MTSTART;      /* 0214 */
   157            Ptr    L2_MTEND;        /* 0218 */
   158            Ptr    L2_CTADDR;       /* 021c */
   159            UInt32 L2_CTDATA;       /* 0220 */
   160        };
   161    
   162        /*! 
   163         *  This device's unicache register set address.
   164         *  Initialized internally according to build target/device.
   165         */
   166        extern volatile CACHE cache;
   167    
   168        /*!
   169         *  OCP Interface Configuration Register Settings.
   170         */
   171        struct OCPConfig {
   172            UInt8 wrap;
   173            UInt8 wrbuffer;
   174            UInt8 prefetch;
   175            UInt8 cleanbuf;
   176        }
   177    
   178        /*!
   179         *  CONFIG Configuration Register Settings.
   180         */
   181        struct SecurityConfig {
   182            UInt8 secure;
   183            UInt8 nbypass;
   184            UInt8 secint;
   185            UInt8 secport;
   186            UInt8 secmain;
   187        }
   188    
   189        // -------- ROV view --------
   190        
   191        /*! @_nodoc */
   192        metaonly struct ModuleView {
   193            Bool        cacheEnabled;
   194        };
   195    
   196        /*! @_nodoc */
   197        @Facet
   198        metaonly config ViewInfo.Instance rovViewInfo = 
   199            ViewInfo.create({
   200                viewMap: [
   201                    ['Module',   {type: ViewInfo.MODULE,   viewInitFxn: 'viewInitModule',   structName: 'ModuleView'}],
   202               ]
   203           });
   204    
   205        // Errors
   206    
   207        /*!
   208         *  Error raised when a Cache interrupt occurs
   209         *  Reason bits are contents of Cache Interrupt Register
   210         */
   211        config Error.Id E_exception = {
   212            msg: "E_exception: L%d reason: 0x%x"
   213        };
   214    
   215        // -------- Configuration Parameters --------
   216    
   217        /*!
   218         *  L1_OCP register settings
   219         */
   220        metaonly config OCPConfig ocpL1 = {
   221            wrap : 0, 
   222            wrbuffer : 0, 
   223            prefetch : 0
   224        };
   225    
   226        /*!
   227         *  L1_CONFIG register settings
   228         */
   229        metaonly config SecurityConfig configL1 = {
   230            secure : 0, 
   231            nbypass : 0, 
   232            secint : 1, 
   233            secport : 1, 
   234            secmain : 1
   235        };
   236    
   237        /*!
   238         *  L2_OCP register settings
   239         */
   240        metaonly config OCPConfig ocpL2 = {
   241            wrap : 0, 
   242            wrbuffer : 0, 
   243            prefetch : 0, 
   244            cleanbuf : 0
   245        };
   246    
   247        /*!
   248         *  L2_CONFIG register settings
   249         */
   250        metaonly config SecurityConfig configL2 = {
   251            secure : 0, 
   252            nbypass : 0, 
   253            secint : 1, 
   254            secport : 1, 
   255            secmain : 1
   256        };
   257    
   258        /*!
   259         *  Configure cache at startup?
   260         *
   261         *  It is possible to configure the Cache at startup and not 
   262         *  {@link #enableCache enable} it.
   263         *  However, it is not possible to enable the Cache at startup
   264         *  without configuring it. 
   265         *
   266         *  Enabling the Cache will automatically enable configuring
   267         *  the Cache.
   268         */
   269        config Bool configureCache = false;
   270        
   271        /*!
   272         *  Enable cache at startup?
   273         *  
   274         *  Enabling the Cache at startup will force 
   275         *  {@link #configureCache configuring} the Cache at startup.
   276         */
   277        config Bool enableCache = false;
   278        
   279        /*!
   280         *  Maximum buffer size to use discrete cache line operations with.
   281         *  
   282         *  For buffers below a certain size, cache maintenance operations are
   283         *  more efficient if performed on single cache lines at a time
   284         *  rather than on an entire region.
   285         *  
   286         *  For buffer sizes equal to or less than this setting, the {@link #inv},
   287         *  {@link #wb}, and {@link #wbInv} APIs will use a series of individual
   288         *  cache line operations. For buffer sizes large than this setting, a
   289         *  a single block mode operation will be performed.
   290         *
   291         *  For M3 cores, the default setting is 1024 bytes.
   292         *  For 64T cores, the default setting is 4096 bytes.
   293         */
   294        config SizeT maxLineModeBufSize;
   295        
   296        /*! 
   297         *  L1 Interrupt Handler. 
   298         *  Default is set to an internal L1 interrupt handler
   299         */
   300        metaonly config Hwi.FuncPtr l1InterruptHandler;
   301    
   302        /*! 
   303         *  L1 Interrupt number. 
   304         *  Default is device unique but can be set in the user config file.
   305         */
   306        metaonly config UInt l1InterruptNumber;
   307    
   308        /*! 
   309         *  L1 Interrupt priority. 
   310         *  Default is device unique but can be set in the user config file.
   311         */
   312        metaonly config UInt l1InterruptPriority;
   313    
   314        /*! 
   315         *  L2 Interrupt Handler. 
   316         *  Default is set to an internal L2 interrupt handler
   317         */
   318        metaonly config Hwi.FuncPtr l2InterruptHandler;
   319    
   320        /*! 
   321         *  L2 Interrupt number. 
   322         *  Default is device unique but can be set in the user config file.
   323         */
   324        metaonly config UInt l2InterruptNumber;
   325    
   326        /*! 
   327         *  L2 Interrupt priority. 
   328         *  Default is device unique but can be set in the user config file.
   329         */
   330        metaonly config UInt l2InterruptPriority;
   331    
   332        // -------- Module Functions --------
   333    
   334        /*!
   335         *  ======== lock ========
   336         *  Locks a memory block into the cache.
   337         *
   338         *  @param(blockPtr) start address of range to be locked
   339         *  @param(byteCnt)  number of bytes to be locked
   340         *  @param(type)     bit mask of Cache type
   341         *  @param(wait)     wait until the operation is completed
   342         */
   343        @DirectCall
   344        Void lock(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
   345    
   346        /*!
   347         *  ======== unlock ========
   348         *  Unlocks a cached memory block.
   349         *
   350         *  @param(blockPtr) start address of range to be locked
   351         *  @param(byteCnt)  number of bytes to be locked
   352         *  @param(type)     bit mask of Cache type
   353         *  @param(wait)     wait until the operation is completed
   354         */
   355        @DirectCall
   356        Void unlock(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
   357    
   358        /*!
   359         *  ======== preload ========
   360         *  Loads a memory block into the cache.
   361         *
   362         *  @param(blockPtr) start address of range to be loaded
   363         *  @param(byteCnt)  number of bytes to be loaded
   364         *  @param(type)     bit mask of Cache type
   365         *  @param(wait)     wait until the operation is completed
   366         */
   367        @DirectCall
   368        Void preload(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
   369    
   370        /*!
   371         *  ======== preloadLock ========
   372         *  Loads and locks a memory block into the cache.
   373         *
   374         *  @param(blockPtr) start address of range to be loaded
   375         *  @param(byteCnt)  number of bytes to be loaded
   376         *  @param(type)     bit mask of Cache type
   377         *  @param(wait)     wait until the operation is completed
   378         */
   379        @DirectCall
   380        Void preloadLock(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
   381    
   382        /*!
   383         *  ======== wbAll ========
   384         *  Write back all caches
   385         *
   386         *  Perform a global write back.
   387         *  All cache lines are left valid in L1 and L2 caches and the data in L1 
   388         *  cache is written back to L2 or external.  All cache lines are left 
   389         *  valid in L2 cache and the data in L2 cache is written back to 
   390         *  external.
   391         *  Waits for completion.
   392         */
   393        @DirectCall
   394        override Void wbAll();
   395    
   396        /*!
   397         *  ======== invAll ========
   398         *  Invalidate all caches
   399         *
   400         *  Perform a global invalidate.  All cache lines are
   401         *  invalidated in L1 and L2 caches. 
   402         *  Waits for completion.
   403         */
   404        @DirectCall
   405        Void invAll();
   406    
   407        /*!
   408         *  ======== wbInvAll ========
   409         *  Write back invalidate all caches
   410         *
   411         *  Perform a global write back.
   412         *  Then perform a global invalidate.  
   413         *  All cache lines are invalidated in L1 and L2 caches.
   414         *  Waits for completion.
   415         */
   416        @DirectCall
   417        override Void wbInvAll();
   418    
   419        /*!
   420         *  ======== read ========
   421         *  Read a block of memory from the cache.
   422         *  Only whole numbers of 32 bit words are transferred.
   423         *  byteCnt is divided by 4 to convert to number of words.
   424         *
   425         *  @param(blockPtr) start address of range to be loaded
   426         *  @param(byteCnt)  number of bytes to be loaded
   427         *  @param(type)     bit mask of Cache type
   428         *  @param(destBuf)  address of destination buffer
   429         */
   430        @DirectCall
   431        Void read(Ptr blockPtr, SizeT byteCnt, Bits16 type, Ptr destBuf);
   432    
   433        /*!
   434         *  @_nodoc
   435         *  ======== dumpRegs ========
   436         *  formatted dump of cache registers
   437         */
   438        Void dumpRegs();
   439    
   440    internal:
   441    
   442        /* initial L1 register settings */
   443        config Bits32 l1ocpConfig;
   444        config Bits32 l1secConfig;
   445    
   446        /* initial L2 register settings */
   447        config Bits32 l2ocpConfig;
   448        config Bits32 l2secConfig;
   449    
   450        /* device-specific L2 support enabled flag */
   451        readonly config Bool l2CacheSupported;
   452    
   453        /* base address of Cache registers */
   454        metaonly config Ptr baseAddr;
   455    
   456        /*!
   457         *  ======== seizeRegs ========
   458         *  seize the cache registers
   459         */
   460        UInt seizeRegs();
   461    
   462        /*!
   463         *  ======== releaseRegs ========
   464         *  release the cache registers
   465         */
   466        Void releaseRegs(UInt key);
   467      
   468        /*
   469         *  ======== ISR ========
   470         *  Cache Interrupt Service Routine
   471         */
   472        Void ISR(UArg level);
   473      
   474        /*!
   475         *  ======== printInfo ========
   476         *  formatted dump of cache registers helper
   477         */
   478        Void printInfo(UInt info, UInt level);
   479    
   480        /*!
   481         *  ======== printConfig ========
   482         *  formatted dump of cache registers helper
   483         */
   484        Void printConfig(UInt cfg, UInt level);
   485    
   486        /*!
   487         *  ======== printOCP ========
   488         *  formatted dump of cache registers helper
   489         */
   490        Void printOCP(UInt cfg, UInt level);
   491    }
   492    
   493    /*
   494     *  @(#) ti.sysbios.hal.unicache; 2, 0, 0, 0,262; 2-24-2012 11:40:47; /db/vtree/library/trees/avala/avala-q28x/src/ xlibrary
   495    
   496     */
   497