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