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 - 2008, Intel Corporation<BR>
   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
  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   Pointer to the destination buffer of the memory copy.
  33   @param  SourceBuffer        Pointer to the source buffer of the memory copy.
  34   @param  Length              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    Memory to set.
  55   @param  Length    Number of bytes to set.
  56   @param  Value     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  Pointer to the target buffer to fill.
  82   @param  Length  Number of bytes in Buffer to fill.
  83   @param  Value   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  Pointer to the target buffer to fill.
 109   @param  Length  Number of bytes in Buffer to fill.
 110   @param  Value   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  Pointer to the target buffer to fill.
 136   @param  Length  Number of bytes in Buffer to fill.
 137   @param  Value   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 zeros, and returns the target buffer.
 152
 153   This function fills Length bytes of Buffer with zeros, and returns Buffer.
 154
 155   If Length > 0 and Buffer is NULL, then ASSERT().
 156   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 157
 158   @param  Buffer      Pointer to the target buffer to fill with zeros.
 159   @param  Length      Number of bytes in Buffer to fill with zeros.
 160
 161   @return Buffer.
 162
 163 **/
 164 VOID *
 165 EFIAPI
 166 ZeroMem (
 167   OUT VOID  *Buffer,
 168   IN UINTN  Length
 169   );
 170
 171 /**
 172   Compares the contents of two buffers.
 173
 174   This function compares Length bytes of SourceBuffer to Length bytes of DestinationBuffer.
 175   If all Length bytes of the two buffers are identical, then 0 is returned.  Otherwise, the
 176   value returned is the first mismatched byte in SourceBuffer subtracted from the first
 177   mismatched byte in DestinationBuffer.
 178
 179   If Length > 0 and DestinationBuffer is NULL, then ASSERT().
 180   If Length > 0 and SourceBuffer is NULL, then ASSERT().
 181   If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then ASSERT().
 182   If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT().
 183
 184   @param  DestinationBuffer Pointer to the destination buffer to compare.
 185   @param  SourceBuffer      Pointer to the source buffer to compare.
 186   @param  Length            Number of bytes to compare.
 187
 188   @return 0                 All Length bytes of the two buffers are identical.
 189   @retval Non-zero          The first mismatched byte in SourceBuffer subtracted from the first
 190                             mismatched byte in DestinationBuffer.
 191
 192 **/
 193 INTN
 194 EFIAPI
 195 CompareMem (
 196   IN CONST VOID  *DestinationBuffer,
 197   IN CONST VOID  *SourceBuffer,
 198   IN UINTN       Length
 199   );
 200
 201 /**
 202   Scans a target buffer for an 8-bit value, and returns a pointer to the matching 8-bit value
 203   in the target buffer.
 204
 205   This function searches target the buffer specified by Buffer and Length from the lowest
 206   address to the highest address for an 8-bit value that matches Value.  If a match is found,
 207   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 208   then NULL is returned.  If Length is 0, then NULL is returned.
 209
 210   If Length > 0 and Buffer is NULL, then ASSERT().
 211   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 212
 213   @param  Buffer      Pointer to the target buffer to scan.
 214   @param  Length      Number of bytes in Buffer to scan.
 215   @param  Value       Value to search for in the target buffer.
 216
 217   @return A pointer to the matching byte in the target buffer or NULL otherwise.
 218
 219 **/
 220 VOID *
 221 EFIAPI
 222 ScanMem8 (
 223   IN CONST VOID  *Buffer,
 224   IN UINTN       Length,
 225   IN UINT8       Value
 226   );
 227
 228 /**
 229   Scans a target buffer for a 16-bit value, and returns a pointer to the matching 16-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 a 16-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 Buffer is not aligned on a 16-bit boundary, then ASSERT().
 239   If Length is not aligned on a 16-bit boundary, then ASSERT().
 240   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 241
 242   @param  Buffer      Pointer to the target buffer to scan.
 243   @param  Length      Number of bytes in Buffer to scan.
 244   @param  Value       Value to search for in the target buffer.
 245
 246   @return A pointer to the matching byte in the target buffer or NULL otherwise.
 247
 248 **/
 249 VOID *
 250 EFIAPI
 251 ScanMem16 (
 252   IN CONST VOID  *Buffer,
 253   IN UINTN       Length,
 254   IN UINT16      Value
 255   );
 256
 257 /**
 258   Scans a target buffer for a 32-bit value, and returns a pointer to the matching 32-bit value
 259   in the target buffer.
 260
 261   This function searches target the buffer specified by Buffer and Length from the lowest
 262   address to the highest address for a 32-bit value that matches Value.  If a match is found,
 263   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 264   then NULL is returned.  If Length is 0, then NULL is returned.
 265
 266   If Length > 0 and Buffer is NULL, then ASSERT().
 267   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
 268   If Length is not aligned on a 32-bit boundary, then ASSERT().
 269   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 270
 271   @param  Buffer      Pointer to the target buffer to scan.
 272   @param  Length      Number of bytes in Buffer to scan.
 273   @param  Value       Value to search for in the target buffer.
 274
 275   @return A pointer to the matching byte in the target buffer or NULL otherwise.
 276
 277 **/
 278 VOID *
 279 EFIAPI
 280 ScanMem32 (
 281   IN CONST VOID  *Buffer,
 282   IN UINTN       Length,
 283   IN UINT32      Value
 284   );
 285
 286 /**
 287   Scans a target buffer for a 64-bit value, and returns a pointer to the matching 64-bit value
 288   in the target buffer.
 289
 290   This function searches target the buffer specified by Buffer and Length from the lowest
 291   address to the highest address for a 64-bit value that matches Value.  If a match is found,
 292   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 293   then NULL is returned.  If Length is 0, then NULL is returned.
 294
 295   If Length > 0 and Buffer is NULL, then ASSERT().
 296   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
 297   If Length is not aligned on a 64-bit boundary, then ASSERT().
 298   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 299
 300   @param  Buffer      Pointer to the target buffer to scan.
 301   @param  Length      Number of bytes in Buffer to scan.
 302   @param  Value       Value to search for in the target buffer.
 303
 304   @return A pointer to the matching byte in the target buffer or NULL otherwise.
 305
 306 **/
 307 VOID *
 308 EFIAPI
 309 ScanMem64 (
 310   IN CONST VOID  *Buffer,
 311   IN UINTN       Length,
 312   IN UINT64      Value
 313   );
 314
 315 /**
 316   Copies a source GUID to a destination GUID.
 317
 318   This function copies the contents of the 128-bit GUID specified by SourceGuid to
 319   DestinationGuid, and returns DestinationGuid.
 320
 321   If DestinationGuid is NULL, then ASSERT().
 322   If SourceGuid is NULL, then ASSERT().
 323
 324   @param  DestinationGuid   Pointer to the destination GUID.
 325   @param  SourceGuid        Pointer to the source GUID.
 326
 327   @return DestinationGuid.
 328
 329 **/
 330 GUID *
 331 EFIAPI
 332 CopyGuid (
 333   OUT GUID       *DestinationGuid,
 334   IN CONST GUID  *SourceGuid
 335   );
 336
 337 /**
 338   Compares two GUIDs.
 339
 340   This function compares Guid1 to Guid2.  If the GUIDs are identical then TRUE is returned.
 341   If there are any bit differences in the two GUIDs, then FALSE is returned.
 342
 343   If Guid1 is NULL, then ASSERT().
 344   If Guid2 is NULL, then ASSERT().
 345
 346   @param  Guid1       A pointer to a 128 bit GUID.
 347   @param  Guid2       A pointer to a 128 bit GUID.
 348
 349   @retval TRUE        Guid1 and Guid2 are identical.
 350   @retval FALSE       Guid1 and Guid2 are not identical.
 351
 352 **/
 353 BOOLEAN
 354 EFIAPI
 355 CompareGuid (
 356   IN CONST GUID  *Guid1,
 357   IN CONST GUID  *Guid2
 358   );
 359
 360 /**
 361   Scans a target buffer for a GUID, and returns a pointer to the matching GUID
 362   in the target buffer.
 363
 364   This function searches target the buffer specified by Buffer and Length from
 365   the lowest address to the highest address at 128-bit increments for the 128-bit
 366   GUID value that matches Guid.  If a match is found, then a pointer to the matching
 367   GUID in the target buffer is returned.  If no match is found, then NULL is returned.
 368   If Length is 0, then NULL is returned.
 369
 370   If Length > 0 and Buffer is NULL, then ASSERT().
 371   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
 372   If Length is not aligned on a 128-bit boundary, then ASSERT().
 373   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 374
 375   @param  Buffer  Pointer to the target buffer to scan.
 376   @param  Length  Number of bytes in Buffer to scan.
 377   @param  Guid    Value to search for in the target buffer.
 378
 379   @return A pointer to the matching Guid in the target buffer or NULL otherwise.
 380
 381 **/
 382 VOID *
 383 EFIAPI
 384 ScanGuid (
 385   IN CONST VOID  *Buffer,
 386   IN UINTN       Length,
 387   IN CONST GUID  *Guid
 388   );
 389
 390 #endif