MdePkg/Include/Library/CacheMaintenanceLib.h

   1 /** @file
   2   Cache Maintenance Functions
   3
   4   Copyright (c) 2006, Intel Corporation
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13   Module Name:  CacheMaintenanceLib.h
  14
  15 **/
  16
  17 #ifndef __CACHE_MAINTENANCE_LIB__
  18 #define __CACHE_MAINTENANCE_LIB__
  19
  20 /**
  21   Invalidates the entire instruction cache in cache coherency domain of the
  22   calling CPU.
  23
  24   Invalidates the entire instruction cache in cache coherency domain of the
  25   calling CPU.
  26
  27 **/
  28 VOID
  29 EFIAPI
  30 InvalidateInstructionCache (
  31   VOID
  32   );
  33
  34 /**
  35   Invalidates a range of instruction cache lines in the cache coherency domain
  36   of the calling CPU.
  37
  38   Invalidates the instruction cache lines specified by Address and Length. If
  39   Address is not aligned on a cache line boundary, then entire instruction
  40   cache line containing Address is invalidated. If Address + Length is not
  41   aligned on a cache line boundary, then the entire instruction cache line
  42   containing Address + Length -1 is invalidated. This function may choose to
  43   invalidate the entire instruction cache if that is more efficient than
  44   invalidating the specified range. If Length is 0, the no instruction cache
  45   lines are invalidated. Address is returned.
  46
  47   If Length is greater than (MAX_ADDRESS - Address + 1), then ASSERT().
  48
  49   @param  Address The base address of the instruction cache lines to
  50                   invalidate. If the CPU is in a physical addressing mode, then
  51                   Address is a physical address. If the CPU is in a virtual
  52                   addressing mode, then Address is a virtual address.
  53
  54   @param  Length  The number of bytes to invalidate from the instruction cache.
  55
  56   @return Address
  57
  58 **/
  59 VOID *
  60 EFIAPI
  61 InvalidateInstructionCacheRange (
  62   IN      VOID                      *Address,
  63   IN      UINTN                     Length
  64   );
  65
  66 /**
  67   Writes Back and Invalidates the entire data cache in cache coherency domain
  68   of the calling CPU.
  69
  70   Writes Back and Invalidates the entire data cache in cache coherency domain
  71   of the calling CPU. This function guarantees that all dirty cache lines are
  72   written back to system memory, and also invalidates all the data cache lines
  73   in the cache coherency domain of the calling CPU.
  74
  75 **/
  76 VOID
  77 EFIAPI
  78 WriteBackInvalidateDataCache (
  79   VOID
  80   );
  81
  82 /**
  83   Writes Back and Invalidates a range of data cache lines in the cache
  84   coherency domain of the calling CPU.
  85
  86   Writes Back and Invalidate the data cache lines specified by Address and
  87   Length. If Address is not aligned on a cache line boundary, then entire data
  88   cache line containing Address is written back and invalidated. If Address +
  89   Length is not aligned on a cache line boundary, then the entire data cache
  90   line containing Address + Length -1 is written back and invalidated. This
  91   function may choose to write back and invalidate the entire data cache if
  92   that is more efficient than writing back and invalidating the specified
  93   range. If Length is 0, the no data cache lines are written back and
  94   invalidated. Address is returned.
  95
  96   If Length is greater than (MAX_ADDRESS - Address + 1), then ASSERT().
  97
  98   @param  Address The base address of the data cache lines to write back and
  99                   invalidate. If the CPU is in a physical addressing mode, then
 100                   Address is a physical address. If the CPU is in a virtual
 101                   addressing mode, then Address is a virtual address.
 102   @param  Length  The number of bytes to write back and invalidate from the
 103                   data cache.
 104
 105   @return Address
 106
 107 **/
 108 VOID *
 109 EFIAPI
 110 WriteBackInvalidateDataCacheRange (
 111   IN      VOID                      *Address,
 112   IN      UINTN                     Length
 113   );
 114
 115 /**
 116   Writes Back the entire data cache in cache coherency domain of the calling
 117   CPU.
 118
 119   Writes Back the entire data cache in cache coherency domain of the calling
 120   CPU. This function guarantees that all dirty cache lines are written back to
 121   system memory. This function may also invalidate all the data cache lines in
 122   the cache coherency domain of the calling CPU.
 123
 124 **/
 125 VOID
 126 EFIAPI
 127 WriteBackDataCache (
 128   VOID
 129   );
 130
 131 /**
 132   Writes Back a range of data cache lines in the cache coherency domain of the
 133   calling CPU.
 134
 135   Writes Back the data cache lines specified by Address and Length. If Address
 136   is not aligned on a cache line boundary, then entire data cache line
 137   containing Address is written back. If Address + Length is not aligned on a
 138   cache line boundary, then the entire data cache line containing Address +
 139   Length -1 is written back. This function may choose to write back the entire
 140   data cache if that is more efficient than writing back the specified range.
 141   If Length is 0, the no data cache lines are written back. This function may
 142   also invalidate all the data cache lines in the specified range of the cache
 143   coherency domain of the calling CPU. Address is returned.
 144
 145   If Length is greater than (MAX_ADDRESS - Address + 1), then ASSERT().
 146
 147   @param  Address The base address of the data cache lines to write back. If
 148                   the CPU is in a physical addressing mode, then Address is a
 149                   physical address. If the CPU is in a virtual addressing
 150                   mode, then Address is a virtual address.
 151   @param  Length  The number of bytes to write back from the data cache.
 152
 153   @return Address
 154
 155 **/
 156 VOID *
 157 EFIAPI
 158 WriteBackDataCacheRange (
 159   IN      VOID                      *Address,
 160   IN      UINTN                     Length
 161   );
 162
 163 /**
 164   Invalidates the entire data cache in cache coherency domain of the calling
 165   CPU.
 166
 167   Invalidates the entire data cache in cache coherency domain of the calling
 168   CPU. This function must be used with care because dirty cache lines are not
 169   written back to system memory. It is typically used for cache diagnostics. If
 170   the CPU does not support invalidation of the entire data cache, then a write
 171   back and invalidate operation should be performed on the entire data cache.
 172
 173 **/
 174 VOID
 175 EFIAPI
 176 InvalidateDataCache (
 177   VOID
 178   );
 179
 180 /**
 181   Invalidates a range of data cache lines in the cache coherency domain of the
 182   calling CPU.
 183
 184   Invalidates the data cache lines specified by Address and Length. If Address
 185   is not aligned on a cache line boundary, then entire data cache line
 186   containing Address is invalidated. If Address + Length is not aligned on a
 187   cache line boundary, then the entire data cache line containing Address +
 188   Length -1 is invalidated. This function must never invalidate any cache lines
 189   outside the specified range. If Length is 0, the no data cache lines are
 190   invalidated. Address is returned. This function must be used with care
 191   because dirty cache lines are not written back to system memory. It is
 192   typically used for cache diagnostics. If the CPU does not support
 193   invalidation of a data cache range, then a write back and invalidate
 194   operation should be performed on the data cache range.
 195
 196   If Length is greater than (MAX_ADDRESS - Address + 1), then ASSERT().
 197
 198   @param  Address The base address of the data cache lines to invalidate. If
 199                   the CPU is in a physical addressing mode, then Address is a
 200                   physical address. If the CPU is in a virtual addressing mode,
 201                   then Address is a virtual address.
 202   @param  Length  The number of bytes to invalidate from the data cache.
 203
 204   @return Address
 205
 206 **/
 207 VOID *
 208 EFIAPI
 209 InvalidateDataCacheRange (
 210   IN      VOID                      *Address,
 211   IN      UINTN                     Length
 212   );
 213
 214 #endif