MdePkg/Include/Library/BaseMemoryLib.h

   1 /** @file
   2   Provides copy memory, fill memory, zero memory, and GUID functions.
   3
   4   The Base Memory Library provides optimized implementions for common memory-based operations.
   5   These functions should be used in place of coding your own loops to do equivalent common functions.
   6   This allows optimized library implementations to help increase performance.
   7
   8 Copyright (c) 2006 - 2008, Intel Corporation
   9 All rights reserved. This program and the accompanying materials
  10 are licensed and made available under the terms and conditions of the BSD License
  11 which accompanies this distribution.  The full text of the license may be found at
  12 http://opensource.org/licenses/bsd-license.php
  13
  14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  16
  17 **/
  18
  19 #ifndef __BASE_MEMORY_LIB__
  20 #define __BASE_MEMORY_LIB__
  21
  22 /**
  23   Copies a source buffer to a destination buffer, and returns the destination buffer.
  24
  25   This function copies Length bytes from SourceBuffer to DestinationBuffer, and returns
  26   DestinationBuffer.  The implementation must be reentrant, and it must handle the case
  27   where SourceBuffer overlaps DestinationBuffer.
  28   If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then ASSERT().
  29   If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT().
  30
  31   @param  DestinationBuffer   Pointer to the destination buffer of the memory copy.
  32   @param  SourceBuffer        Pointer to the source buffer of the memory copy.
  33   @param  Length              Number of bytes to copy from SourceBuffer to DestinationBuffer.
  34
  35   @return DestinationBuffer.
  36
  37 **/
  38 VOID *
  39 EFIAPI
  40 CopyMem (
  41   OUT VOID       *DestinationBuffer,
  42   IN CONST VOID  *SourceBuffer,
  43   IN UINTN       Length
  44   );
  45
  46 /**
  47   Fills a target buffer with a byte value, and returns the target buffer.
  48
  49   This function fills Length bytes of Buffer with Value, and returns Buffer.
  50   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
  51
  52   @param  Buffer    Memory to set.
  53   @param  Length    Number of bytes to set.
  54   @param  Value     Value with which to fill Length bytes of Buffer.
  55
  56   @return Buffer.
  57
  58 **/
  59 VOID *
  60 EFIAPI
  61 SetMem (
  62   OUT VOID  *Buffer,
  63   IN UINTN  Length,
  64   IN UINT8  Value
  65   );
  66
  67 /**
  68   Fills a target buffer with a 16-bit value, and returns the target buffer.
  69
  70   This function fills Length bytes of Buffer with the 16-bit value specified by
  71   Value, and returns Buffer. Value is repeated every 16-bits in for Length
  72   bytes of Buffer.
  73
  74   If Length > 0 and Buffer is NULL, then ASSERT().
  75   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
  76   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
  77   If Length is not aligned on a 16-bit boundary, then ASSERT().
  78
  79   @param  Buffer  Pointer to the target buffer to fill.
  80   @param  Length  Number of bytes in Buffer to fill.
  81   @param  Value   Value with which to fill Length bytes of Buffer.
  82
  83   @return Buffer.
  84
  85 **/
  86 VOID *
  87 EFIAPI
  88 SetMem16 (
  89   OUT VOID   *Buffer,
  90   IN UINTN   Length,
  91   IN UINT16  Value
  92   );
  93
  94 /**
  95   Fills a target buffer with a 32-bit value, and returns the target buffer.
  96
  97   This function fills Length bytes of Buffer with the 32-bit value specified by
  98   Value, and returns Buffer. Value is repeated every 32-bits in for Length
  99   bytes of Buffer.
 100
 101   If Length > 0 and Buffer is NULL, then ASSERT().
 102   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 103   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
 104   If Length is not aligned on a 32-bit boundary, then ASSERT().
 105
 106   @param  Buffer  Pointer to the target buffer to fill.
 107   @param  Length  Number of bytes in Buffer to fill.
 108   @param  Value   Value with which to fill Length bytes of Buffer.
 109
 110   @return Buffer.
 111
 112 **/
 113 VOID *
 114 EFIAPI
 115 SetMem32 (
 116   OUT VOID   *Buffer,
 117   IN UINTN   Length,
 118   IN UINT32  Value
 119   );
 120
 121 /**
 122   Fills a target buffer with a 64-bit value, and returns the target buffer.
 123
 124   This function fills Length bytes of Buffer with the 64-bit value specified by
 125   Value, and returns Buffer. Value is repeated every 64-bits in for Length
 126   bytes of Buffer.
 127
 128   If Length > 0 and Buffer is NULL, then ASSERT().
 129   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 130   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
 131   If Length is not aligned on a 64-bit boundary, then ASSERT().
 132
 133   @param  Buffer  Pointer to the target buffer to fill.
 134   @param  Length  Number of bytes in Buffer to fill.
 135   @param  Value   Value with which to fill Length bytes of Buffer.
 136
 137   @return Buffer.
 138
 139 **/
 140 VOID *
 141 EFIAPI
 142 SetMem64 (
 143   OUT VOID   *Buffer,
 144   IN UINTN   Length,
 145   IN UINT64  Value
 146   );
 147
 148 /**
 149   Fills a target buffer with zeros, and returns the target buffer.
 150
 151   This function fills Length bytes of Buffer with zeros, and returns Buffer.
 152   If Length > 0 and Buffer is NULL, then ASSERT().
 153   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 154
 155   @param  Buffer      Pointer to the target buffer to fill with zeros.
 156   @param  Length      Number of bytes in Buffer to fill with zeros.
 157
 158   @return Buffer.
 159
 160 **/
 161 VOID *
 162 EFIAPI
 163 ZeroMem (
 164   OUT VOID  *Buffer,
 165   IN UINTN  Length
 166   );
 167
 168 /**
 169   Compares the contents of two buffers.
 170
 171   This function compares Length bytes of SourceBuffer to Length bytes of DestinationBuffer.
 172   If all Length bytes of the two buffers are identical, then 0 is returned.  Otherwise, the
 173   value returned is the first mismatched byte in SourceBuffer subtracted from the first
 174   mismatched byte in DestinationBuffer.
 175   If Length > 0 and DestinationBuffer is NULL, then ASSERT().
 176   If Length > 0 and SourceBuffer is NULL, then ASSERT().
 177   If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then ASSERT().
 178   If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT().
 179
 180   @param  DestinationBuffer Pointer to the destination buffer to compare.
 181   @param  SourceBuffer      Pointer to the source buffer to compare.
 182   @param  Length            Number of bytes to compare.
 183
 184   @return 0                 All Length bytes of the two buffers are identical.
 185   @retval Non-zero          The first mismatched byte in SourceBuffer subtracted from the first
 186                             mismatched byte in DestinationBuffer.
 187
 188 **/
 189 INTN
 190 EFIAPI
 191 CompareMem (
 192   IN CONST VOID  *DestinationBuffer,
 193   IN CONST VOID  *SourceBuffer,
 194   IN UINTN       Length
 195   );
 196
 197 /**
 198   Scans a target buffer for an 8-bit value, and returns a pointer to the matching 8-bit value
 199   in the target buffer.
 200
 201   This function searches target the buffer specified by Buffer and Length from the lowest
 202   address to the highest address for an 8-bit value that matches Value.  If a match is found,
 203   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 204   then NULL is returned.  If Length is 0, then NULL is returned.
 205   If Length > 0 and Buffer is NULL, then ASSERT().
 206   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 207
 208   @param  Buffer      Pointer to the target buffer to scan.
 209   @param  Length      Number of bytes in Buffer to scan.
 210   @param  Value       Value to search for in the target buffer.
 211
 212   @return A pointer to the matching byte in the target buffer or NULL otherwise.
 213
 214 **/
 215 VOID *
 216 EFIAPI
 217 ScanMem8 (
 218   IN CONST VOID  *Buffer,
 219   IN UINTN       Length,
 220   IN UINT8       Value
 221   );
 222
 223 /**
 224   Scans a target buffer for a 16-bit value, and returns a pointer to the matching 16-bit value
 225   in the target buffer.
 226
 227   This function searches target the buffer specified by Buffer and Length from the lowest
 228   address to the highest address for a 16-bit value that matches Value.  If a match is found,
 229   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 230   then NULL is returned.  If Length is 0, then NULL is returned.
 231   If Length > 0 and Buffer is NULL, then ASSERT().
 232   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 233   If Length is not aligned on a 16-bit boundary, then ASSERT().
 234   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 235
 236   @param  Buffer      Pointer to the target buffer to scan.
 237   @param  Length      Number of bytes in Buffer to scan.
 238   @param  Value       Value to search for in the target buffer.
 239
 240   @return A pointer to the matching byte in the target buffer or NULL otherwise.
 241
 242 **/
 243 VOID *
 244 EFIAPI
 245 ScanMem16 (
 246   IN CONST VOID  *Buffer,
 247   IN UINTN       Length,
 248   IN UINT16      Value
 249   );
 250
 251 /**
 252   Scans a target buffer for a 32-bit value, and returns a pointer to the matching 32-bit value
 253   in the target buffer.
 254
 255   This function searches target the buffer specified by Buffer and Length from the lowest
 256   address to the highest address for a 32-bit value that matches Value.  If a match is found,
 257   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 258   then NULL is returned.  If Length is 0, then NULL is returned.
 259   If Length > 0 and Buffer is NULL, then ASSERT().
 260   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
 261   If Length is not aligned on a 32-bit boundary, then ASSERT().
 262   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 263
 264   @param  Buffer      Pointer to the target buffer to scan.
 265   @param  Length      Number of bytes in Buffer to scan.
 266   @param  Value       Value to search for in the target buffer.
 267
 268   @return A pointer to the matching byte in the target buffer or NULL otherwise.
 269
 270 **/
 271 VOID *
 272 EFIAPI
 273 ScanMem32 (
 274   IN CONST VOID  *Buffer,
 275   IN UINTN       Length,
 276   IN UINT32      Value
 277   );
 278
 279 /**
 280   Scans a target buffer for a 64-bit value, and returns a pointer to the matching 64-bit value
 281   in the target buffer.
 282
 283   This function searches target the buffer specified by Buffer and Length from the lowest
 284   address to the highest address for a 64-bit value that matches Value.  If a match is found,
 285   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 286   then NULL is returned.  If Length is 0, then NULL is returned.
 287   If Length > 0 and Buffer is NULL, then ASSERT().
 288   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
 289   If Length is not aligned on a 64-bit boundary, then ASSERT().
 290   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 291
 292   @param  Buffer      Pointer to the target buffer to scan.
 293   @param  Length      Number of bytes in Buffer to scan.
 294   @param  Value       Value to search for in the target buffer.
 295
 296   @return A pointer to the matching byte in the target buffer or NULL otherwise.
 297
 298 **/
 299 VOID *
 300 EFIAPI
 301 ScanMem64 (
 302   IN CONST VOID  *Buffer,
 303   IN UINTN       Length,
 304   IN UINT64      Value
 305   );
 306
 307 /**
 308   Copies a source GUID to a destination GUID.
 309
 310   This function copies the contents of the 128-bit GUID specified by SourceGuid to
 311   DestinationGuid, and returns DestinationGuid.
 312   If DestinationGuid is NULL, then ASSERT().
 313   If SourceGuid is NULL, then ASSERT().
 314
 315   @param  DestinationGuid   Pointer to the destination GUID.
 316   @param  SourceGuid        Pointer to the source GUID.
 317
 318   @return DestinationGuid.
 319
 320 **/
 321 GUID *
 322 EFIAPI
 323 CopyGuid (
 324   OUT GUID       *DestinationGuid,
 325   IN CONST GUID  *SourceGuid
 326   );
 327
 328 /**
 329   Compares two GUIDs.
 330
 331   This function compares Guid1 to Guid2.  If the GUIDs are identical then TRUE is returned.
 332   If there are any bit differences in the two GUIDs, then FALSE is returned.
 333   If Guid1 is NULL, then ASSERT().
 334   If Guid2 is NULL, then ASSERT().
 335
 336   @param  Guid1       A pointer to a 128 bit GUID.
 337   @param  Guid2       A pointer to a 128 bit GUID.
 338
 339   @retval TRUE        Guid1 and Guid2 are identical.
 340   @retval FALSE       Guid1 and Guid2 are not identical.
 341
 342 **/
 343 BOOLEAN
 344 EFIAPI
 345 CompareGuid (
 346   IN CONST GUID  *Guid1,
 347   IN CONST GUID  *Guid2
 348   );
 349
 350 /**
 351   Scans a target buffer for a GUID, and returns a pointer to the matching GUID
 352   in the target buffer.
 353
 354   This function searches target the buffer specified by Buffer and Length from
 355   the lowest address to the highest address at 128-bit increments for the 128-bit
 356   GUID value that matches Guid.  If a match is found, then a pointer to the matching
 357   GUID in the target buffer is returned.  If no match is found, then NULL is returned.
 358   If Length is 0, then NULL is returned.
 359   If Length > 0 and Buffer is NULL, then ASSERT().
 360   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
 361   If Length is not aligned on a 128-bit boundary, then ASSERT().
 362   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 363
 364   @param  Buffer  Pointer to the target buffer to scan.
 365   @param  Length  Number of bytes in Buffer to scan.
 366   @param  Guid    Value to search for in the target buffer.
 367
 368   @return A pointer to the matching Guid in the target buffer or NULL otherwise.
 369
 370 **/
 371 VOID *
 372 EFIAPI
 373 ScanGuid (
 374   IN CONST VOID  *Buffer,
 375   IN UINTN       Length,
 376   IN CONST GUID  *Guid
 377   );
 378
 379 #endif