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 implementations 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 - 2018, Intel Corporation. All rights reserved.<BR>
   9 This program and the accompanying materials are licensed and made available under
  10 the terms and conditions of the BSD License that accompanies this distribution.
  11 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
  29   If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then ASSERT().
  30   If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT().
  31
  32   @param  DestinationBuffer   The pointer to the destination buffer of the memory copy.
  33   @param  SourceBuffer        The pointer to the source buffer of the memory copy.
  34   @param  Length              The number of bytes to copy from SourceBuffer to DestinationBuffer.
  35
  36   @return DestinationBuffer.
  37
  38 **/
  39 VOID *
  40 EFIAPI
  41 CopyMem (
  42   OUT VOID       *DestinationBuffer,
  43   IN CONST VOID  *SourceBuffer,
  44   IN UINTN       Length
  45   );
  46
  47 /**
  48   Fills a target buffer with a byte value, and returns the target buffer.
  49
  50   This function fills Length bytes of Buffer with Value, and returns Buffer.
  51
  52   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
  53
  54   @param  Buffer    The memory to set.
  55   @param  Length    The number of bytes to set.
  56   @param  Value     The value with which to fill Length bytes of Buffer.
  57
  58   @return Buffer.
  59
  60 **/
  61 VOID *
  62 EFIAPI
  63 SetMem (
  64   OUT VOID  *Buffer,
  65   IN UINTN  Length,
  66   IN UINT8  Value
  67   );
  68
  69 /**
  70   Fills a target buffer with a 16-bit value, and returns the target buffer.
  71
  72   This function fills Length bytes of Buffer with the 16-bit value specified by
  73   Value, and returns Buffer. Value is repeated every 16-bits in for Length
  74   bytes of Buffer.
  75
  76   If Length > 0 and Buffer is NULL, then ASSERT().
  77   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
  78   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
  79   If Length is not aligned on a 16-bit boundary, then ASSERT().
  80
  81   @param  Buffer  The pointer to the target buffer to fill.
  82   @param  Length  The number of bytes in Buffer to fill.
  83   @param  Value   The value with which to fill Length bytes of Buffer.
  84
  85   @return Buffer.
  86
  87 **/
  88 VOID *
  89 EFIAPI
  90 SetMem16 (
  91   OUT VOID   *Buffer,
  92   IN UINTN   Length,
  93   IN UINT16  Value
  94   );
  95
  96 /**
  97   Fills a target buffer with a 32-bit value, and returns the target buffer.
  98
  99   This function fills Length bytes of Buffer with the 32-bit value specified by
 100   Value, and returns Buffer. Value is repeated every 32-bits in for Length
 101   bytes of Buffer.
 102
 103   If Length > 0 and Buffer is NULL, then ASSERT().
 104   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 105   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
 106   If Length is not aligned on a 32-bit boundary, then ASSERT().
 107
 108   @param  Buffer  The pointer to the target buffer to fill.
 109   @param  Length  The number of bytes in Buffer to fill.
 110   @param  Value   The value with which to fill Length bytes of Buffer.
 111
 112   @return Buffer.
 113
 114 **/
 115 VOID *
 116 EFIAPI
 117 SetMem32 (
 118   OUT VOID   *Buffer,
 119   IN UINTN   Length,
 120   IN UINT32  Value
 121   );
 122
 123 /**
 124   Fills a target buffer with a 64-bit value, and returns the target buffer.
 125
 126   This function fills Length bytes of Buffer with the 64-bit value specified by
 127   Value, and returns Buffer. Value is repeated every 64-bits in for Length
 128   bytes of Buffer.
 129
 130   If Length > 0 and Buffer is NULL, then ASSERT().
 131   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 132   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
 133   If Length is not aligned on a 64-bit boundary, then ASSERT().
 134
 135   @param  Buffer  The pointer to the target buffer to fill.
 136   @param  Length  The number of bytes in Buffer to fill.
 137   @param  Value   The value with which to fill Length bytes of Buffer.
 138
 139   @return Buffer.
 140
 141 **/
 142 VOID *
 143 EFIAPI
 144 SetMem64 (
 145   OUT VOID   *Buffer,
 146   IN UINTN   Length,
 147   IN UINT64  Value
 148   );
 149
 150 /**
 151   Fills a target buffer with a value that is size UINTN, and returns the target buffer.
 152
 153   This function fills Length bytes of Buffer with the UINTN sized value specified by
 154   Value, and returns Buffer. Value is repeated every sizeof(UINTN) bytes for Length
 155   bytes of Buffer.
 156
 157   If Length > 0 and Buffer is NULL, then ASSERT().
 158   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 159   If Buffer is not aligned on a UINTN boundary, then ASSERT().
 160   If Length is not aligned on a UINTN boundary, then ASSERT().
 161
 162   @param  Buffer  The pointer to the target buffer to fill.
 163   @param  Length  The number of bytes in Buffer to fill.
 164   @param  Value   The value with which to fill Length bytes of Buffer.
 165
 166   @return Buffer.
 167
 168 **/
 169 VOID *
 170 EFIAPI
 171 SetMemN (
 172   OUT VOID  *Buffer,
 173   IN UINTN  Length,
 174   IN UINTN  Value
 175   );
 176
 177 /**
 178   Fills a target buffer with zeros, and returns the target buffer.
 179
 180   This function fills Length bytes of Buffer with zeros, and returns Buffer.
 181
 182   If Length > 0 and Buffer is NULL, then ASSERT().
 183   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 184
 185   @param  Buffer      The pointer to the target buffer to fill with zeros.
 186   @param  Length      The number of bytes in Buffer to fill with zeros.
 187
 188   @return Buffer.
 189
 190 **/
 191 VOID *
 192 EFIAPI
 193 ZeroMem (
 194   OUT VOID  *Buffer,
 195   IN UINTN  Length
 196   );
 197
 198 /**
 199   Compares the contents of two buffers.
 200
 201   This function compares Length bytes of SourceBuffer to Length bytes of DestinationBuffer.
 202   If all Length bytes of the two buffers are identical, then 0 is returned.  Otherwise, the
 203   value returned is the first mismatched byte in SourceBuffer subtracted from the first
 204   mismatched byte in DestinationBuffer.
 205
 206   If Length > 0 and DestinationBuffer is NULL, then ASSERT().
 207   If Length > 0 and SourceBuffer is NULL, then ASSERT().
 208   If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then ASSERT().
 209   If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT().
 210
 211   @param  DestinationBuffer The pointer to the destination buffer to compare.
 212   @param  SourceBuffer      The pointer to the source buffer to compare.
 213   @param  Length            The number of bytes to compare.
 214
 215   @return 0                 All Length bytes of the two buffers are identical.
 216   @retval Non-zero          The first mismatched byte in SourceBuffer subtracted from the first
 217                             mismatched byte in DestinationBuffer.
 218
 219 **/
 220 INTN
 221 EFIAPI
 222 CompareMem (
 223   IN CONST VOID  *DestinationBuffer,
 224   IN CONST VOID  *SourceBuffer,
 225   IN UINTN       Length
 226   );
 227
 228 /**
 229   Scans a target buffer for an 8-bit value, and returns a pointer to the matching 8-bit value
 230   in the target buffer.
 231
 232   This function searches target the buffer specified by Buffer and Length from the lowest
 233   address to the highest address for an 8-bit value that matches Value.  If a match is found,
 234   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 235   then NULL is returned.  If Length is 0, then NULL is returned.
 236
 237   If Length > 0 and Buffer is NULL, then ASSERT().
 238   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 239
 240   @param  Buffer      The pointer to the target buffer to scan.
 241   @param  Length      The number of bytes in Buffer to scan.
 242   @param  Value       The value to search for in the target buffer.
 243
 244   @return A pointer to the matching byte in the target buffer, otherwise NULL.
 245
 246 **/
 247 VOID *
 248 EFIAPI
 249 ScanMem8 (
 250   IN CONST VOID  *Buffer,
 251   IN UINTN       Length,
 252   IN UINT8       Value
 253   );
 254
 255 /**
 256   Scans a target buffer for a 16-bit value, and returns a pointer to the matching 16-bit value
 257   in the target buffer.
 258
 259   This function searches target the buffer specified by Buffer and Length from the lowest
 260   address to the highest address for a 16-bit value that matches Value.  If a match is found,
 261   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 262   then NULL is returned.  If Length is 0, then NULL is returned.
 263
 264   If Length > 0 and Buffer is NULL, then ASSERT().
 265   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 266   If Length is not aligned on a 16-bit boundary, then ASSERT().
 267   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 268
 269   @param  Buffer      The pointer to the target buffer to scan.
 270   @param  Length      The number of bytes in Buffer to scan.
 271   @param  Value       The value to search for in the target buffer.
 272
 273   @return A pointer to the matching byte in the target buffer, otherwise NULL.
 274
 275 **/
 276 VOID *
 277 EFIAPI
 278 ScanMem16 (
 279   IN CONST VOID  *Buffer,
 280   IN UINTN       Length,
 281   IN UINT16      Value
 282   );
 283
 284 /**
 285   Scans a target buffer for a 32-bit value, and returns a pointer to the matching 32-bit value
 286   in the target buffer.
 287
 288   This function searches target the buffer specified by Buffer and Length from the lowest
 289   address to the highest address for a 32-bit value that matches Value.  If a match is found,
 290   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 291   then NULL is returned.  If Length is 0, then NULL is returned.
 292
 293   If Length > 0 and Buffer is NULL, then ASSERT().
 294   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
 295   If Length is not aligned on a 32-bit boundary, then ASSERT().
 296   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 297
 298   @param  Buffer      The pointer to the target buffer to scan.
 299   @param  Length      The number of bytes in Buffer to scan.
 300   @param  Value       The value to search for in the target buffer.
 301
 302   @return A pointer to the matching byte in the target buffer, otherwise NULL.
 303
 304 **/
 305 VOID *
 306 EFIAPI
 307 ScanMem32 (
 308   IN CONST VOID  *Buffer,
 309   IN UINTN       Length,
 310   IN UINT32      Value
 311   );
 312
 313 /**
 314   Scans a target buffer for a 64-bit value, and returns a pointer to the matching 64-bit value
 315   in the target buffer.
 316
 317   This function searches target the buffer specified by Buffer and Length from the lowest
 318   address to the highest address for a 64-bit value that matches Value.  If a match is found,
 319   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 320   then NULL is returned.  If Length is 0, then NULL is returned.
 321
 322   If Length > 0 and Buffer is NULL, then ASSERT().
 323   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
 324   If Length is not aligned on a 64-bit boundary, then ASSERT().
 325   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 326
 327   @param  Buffer      The pointer to the target buffer to scan.
 328   @param  Length      The number of bytes in Buffer to scan.
 329   @param  Value       The value to search for in the target buffer.
 330
 331   @return A pointer to the matching byte in the target buffer, otherwise NULL.
 332
 333 **/
 334 VOID *
 335 EFIAPI
 336 ScanMem64 (
 337   IN CONST VOID  *Buffer,
 338   IN UINTN       Length,
 339   IN UINT64      Value
 340   );
 341
 342 /**
 343   Scans a target buffer for a UINTN sized value, and returns a pointer to the matching
 344   UINTN sized value in the target buffer.
 345
 346   This function searches target the buffer specified by Buffer and Length from the lowest
 347   address to the highest address for a UINTN sized value that matches Value.  If a match is found,
 348   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 349   then NULL is returned.  If Length is 0, then NULL is returned.
 350
 351   If Length > 0 and Buffer is NULL, then ASSERT().
 352   If Buffer is not aligned on a UINTN boundary, then ASSERT().
 353   If Length is not aligned on a UINTN boundary, then ASSERT().
 354   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 355
 356   @param  Buffer      The pointer to the target buffer to scan.
 357   @param  Length      The number of bytes in Buffer to scan.
 358   @param  Value       The value to search for in the target buffer.
 359
 360   @return A pointer to the matching byte in the target buffer, otherwise NULL.
 361
 362 **/
 363 VOID *
 364 EFIAPI
 365 ScanMemN (
 366   IN CONST VOID  *Buffer,
 367   IN UINTN       Length,
 368   IN UINTN       Value
 369   );
 370
 371 /**
 372   Copies a source GUID to a destination GUID.
 373
 374   This function copies the contents of the 128-bit GUID specified by SourceGuid to
 375   DestinationGuid, and returns DestinationGuid.
 376
 377   If DestinationGuid is NULL, then ASSERT().
 378   If SourceGuid is NULL, then ASSERT().
 379
 380   @param  DestinationGuid   The pointer to the destination GUID.
 381   @param  SourceGuid        The pointer to the source GUID.
 382
 383   @return DestinationGuid.
 384
 385 **/
 386 GUID *
 387 EFIAPI
 388 CopyGuid (
 389   OUT GUID       *DestinationGuid,
 390   IN CONST GUID  *SourceGuid
 391   );
 392
 393 /**
 394   Compares two GUIDs.
 395
 396   This function compares Guid1 to Guid2.  If the GUIDs are identical then TRUE is returned.
 397   If there are any bit differences in the two GUIDs, then FALSE is returned.
 398
 399   If Guid1 is NULL, then ASSERT().
 400   If Guid2 is NULL, then ASSERT().
 401
 402   @param  Guid1       A pointer to a 128 bit GUID.
 403   @param  Guid2       A pointer to a 128 bit GUID.
 404
 405   @retval TRUE        Guid1 and Guid2 are identical.
 406   @retval FALSE       Guid1 and Guid2 are not identical.
 407
 408 **/
 409 BOOLEAN
 410 EFIAPI
 411 CompareGuid (
 412   IN CONST GUID  *Guid1,
 413   IN CONST GUID  *Guid2
 414   );
 415
 416 /**
 417   Scans a target buffer for a GUID, and returns a pointer to the matching GUID
 418   in the target buffer.
 419
 420   This function searches target the buffer specified by Buffer and Length from
 421   the lowest address to the highest address at 128-bit increments for the 128-bit
 422   GUID value that matches Guid.  If a match is found, then a pointer to the matching
 423   GUID in the target buffer is returned.  If no match is found, then NULL is returned.
 424   If Length is 0, then NULL is returned.
 425
 426   If Length > 0 and Buffer is NULL, then ASSERT().
 427   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
 428   If Length is not aligned on a 128-bit boundary, then ASSERT().
 429   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 430
 431   @param  Buffer  The pointer to the target buffer to scan.
 432   @param  Length  The number of bytes in Buffer to scan.
 433   @param  Guid    The value to search for in the target buffer.
 434
 435   @return A pointer to the matching Guid in the target buffer, otherwise NULL.
 436
 437 **/
 438 VOID *
 439 EFIAPI
 440 ScanGuid (
 441   IN CONST VOID  *Buffer,
 442   IN UINTN       Length,
 443   IN CONST GUID  *Guid
 444   );
 445
 446 /**
 447   Checks if the given GUID is a zero GUID.
 448
 449   This function checks whether the given GUID is a zero GUID. If the GUID is
 450   identical to a zero GUID then TRUE is returned. Otherwise, FALSE is returned.
 451
 452   If Guid is NULL, then ASSERT().
 453
 454   @param  Guid        The pointer to a 128 bit GUID.
 455
 456   @retval TRUE        Guid is a zero GUID.
 457   @retval FALSE       Guid is not a zero GUID.
 458
 459 **/
 460 BOOLEAN
 461 EFIAPI
 462 IsZeroGuid (
 463   IN CONST GUID  *Guid
 464   );
 465
 466 /**
 467   Checks if the contents of a buffer are all zeros.
 468
 469   This function checks whether the contents of a buffer are all zeros. If the
 470   contents are all zeros, return TRUE. Otherwise, return FALSE.
 471
 472   If Length > 0 and Buffer is NULL, then ASSERT().
 473   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 474
 475   @param  Buffer      The pointer to the buffer to be checked.
 476   @param  Length      The size of the buffer (in bytes) to be checked.
 477
 478   @retval TRUE        Contents of the buffer are all zeros.
 479   @retval FALSE       Contents of the buffer are not all zeros.
 480
 481 **/
 482 BOOLEAN
 483 EFIAPI
 484 IsZeroBuffer (
 485   IN CONST VOID  *Buffer,
 486   IN UINTN       Length
 487   );
 488
 489 #endif