1    /*
     2     * Copyright (c) 2013-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     *  ======== ICache.xdc ========
    34     *
    35     *
    36     */
    37    
    38    /*!
    39     *  ======== ICache ========
    40     *  Cache Interface
    41     */
    42    
    43    @DirectCall
    44    interface ICache
    45    {
    46        /*! Lists of bitmask cache types */
    47        enum Type {
    48            Type_L1P = 0x1,         /*! Level 1 Program cache */
    49            Type_L1D = 0x2,         /*! Level 1 Data cache */
    50            Type_L1  = 0x3,         /*! Level 1 caches */
    51            Type_L2P = 0x4,         /*! Level 2 Program cache */
    52            Type_L2D = 0x8,         /*! Level 2 Data cache */
    53            Type_L2  = 0xC,         /*! Level 2 caches */
    54            Type_ALLP = 0x5,        /*! All Program caches */
    55            Type_ALLD = 0xA,        /*! All Data caches */
    56            Type_ALL = 0x7fff       /*! All caches */
    57        };
    58    
    59        /*!
    60         *  ======== enableCache ========
    61         *  Enable supported caches during startup
    62         *
    63         *  Not implemented by all architectures.  Refer to specific
    64         *  architecture Cache module for details.
    65         */
    66        config Bool enableCache = true;
    67    
    68        /*!
    69         *  ======== enable ========
    70         *  Enables all cache(s)
    71         *
    72         *  @param(type)    bit mask of Cache type
    73         */
    74        Void enable(Bits16 type);
    75    
    76        /*!
    77         *  ======== disable ========
    78         *  Disables the 'type' cache(s)
    79         *
    80         *  @param(type)    bit mask of Cache type
    81         */
    82        Void disable(Bits16 type);
    83    
    84        /*!
    85         *  ======== inv ========
    86         *  Invalidate the range of memory within the specified starting
    87         *  address and byte count.  The range of addresses operated on
    88         *  gets quantized to whole cache lines in each cache.  All lines
    89         *  in range are invalidated for all the 'type' caches.
    90         *
    91         *  @param(blockPtr) start address of range to be invalidated
    92         *  @param(byteCnt)  number of bytes to be invalidated
    93         *  @param(type)     bit mask of Cache type
    94         *  @param(wait)     wait until the operation is completed
    95         */
    96        Void inv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
    97    
    98        /*!
    99         *  ======== wb ========
   100         *  Writes back a range of memory from all cache(s)
   101         *
   102         *  Writes back the range of memory within the specified starting
   103         *  address and byte count.  The range of addresses operated on
   104         *  gets quantized to whole cache lines in each cache.  All lines
   105         *  within the range are left valid in the 'type' caches and the data
   106         *  within the range will be written back to the source memory.
   107         *
   108         *  @param(blockPtr) start address of range to be invalidated
   109         *  @param(byteCnt)  number of bytes to be invalidated
   110         *  @param(type)     bit mask of Cache type
   111         *  @param(wait)     wait until the operation is completed
   112         */
   113        Void wb(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
   114    
   115        /*!
   116         *  ======== wbInv ========
   117         *  Writes back and invalidates the range of memory within the
   118         *  specified starting address and byte count.  The range of
   119         *  addresses operated on gets quantized to whole cache lines in
   120         *  each cache.  All lines within the range are written back to the
   121         *  source memory and then invalidated for all 'type' caches.
   122         *
   123         *  @param(blockPtr) start address of range to be invalidated
   124         *  @param(byteCnt)  number of bytes to be invalidated
   125         *  @param(type)     bit mask of Cache type
   126         *  @param(wait)     wait until the operation is completed
   127         */
   128        Void wbInv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
   129    
   130        /*!
   131         *  ======== wbAll ========
   132         *  Write back all caches
   133         *
   134         *  Perform a global write back.  There is no effect on program cache.
   135         *  All data cache lines are left valid.
   136         */
   137        Void wbAll();
   138    
   139        /*!
   140         *  ======== wbInvAll ========
   141         *  Write back invalidate all caches
   142         *
   143         *  Performs a global write back and invalidate.  All cache lines
   144         *  are written out to physical memory and then invalidated.  
   145         */
   146        Void wbInvAll();
   147    
   148        /*!
   149         *  ======== wait ========
   150         *  Wait for a previous cache operation to complete
   151         *
   152         *  Wait for the cache wb/wbInv/inv operation to complete.  A cache
   153         *  operation is not truly complete until it has worked its way
   154         *  through all buffering and all memory writes have landed in the
   155         *  source memory.
   156         */
   157        Void wait();
   158    
   159    }
   160