MdePkg/Include/Library/BaseMemoryLib.h

   1 /** @file
   2         Memory-only library functions with no library constructor/destructor
   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:    BaseMemoryLib.h
  14
  15 **/
  16
  17 #ifndef __BASE_MEMORY_LIB__
  18 #define __BASE_MEMORY_LIB__
  19
  20 /**
  21   Copy Length bytes from Source to Destination.
  22
  23   This function copies Length bytes from SourceBuffer to DestinationBuffer, and
  24   returns DestinationBuffer. The implementation must be reentrant, and it must
  25   handle the case where SourceBuffer overlaps DestinationBuffer.
  26
  27   If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then
  28   ASSERT().
  29   If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT().
  30
  31   @param  Destination Target of copy
  32   @param  Source Place to copy from
  33   @param  Length Number of bytes to copy
  34
  35   @return Destination
  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   Set Buffer to Value for Size bytes.
  48
  49   This function fills Length bytes of Buffer with Value, and returns Buffer.
  50
  51   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
  52
  53   @param  Buffer Memory to set.
  54   @param  Size Number of bytes to set
  55   @param  Value Value of the set operation.
  56
  57   @return Buffer
  58
  59 **/
  60 VOID *
  61 EFIAPI
  62 SetMem (
  63   OUT     VOID                      *Buffer,
  64   IN      UINTN                     Length,
  65   IN      UINT8                     Value
  66   );
  67
  68 /**
  69   Fills a target buffer with a 16-bit value, and returns the target buffer.
  70
  71   This function fills Length bytes of Buffer with the 16-bit value specified by
  72   Value, and returns Buffer. Value is repeated every 16-bits in for Length
  73   bytes of Buffer.
  74
  75   If Buffer is NULL and Length > 0, then ASSERT().
  76   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
  77   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
  78   If Length is not aligned on a 16-bit boundary, then ASSERT().
  79
  80   @param  Buffer  Pointer to the target buffer to fill.
  81   @param  Length  Number of bytes in Buffer to fill.
  82   @param  Value   Value with which to fill Length bytes of Buffer.
  83
  84   @return Buffer
  85
  86 **/
  87 VOID *
  88 EFIAPI
  89 SetMem16 (
  90   OUT     VOID                      *Buffer,
  91   IN      UINTN                     Length,
  92   IN      UINT16                    Value
  93   );
  94
  95 /**
  96   Fills a target buffer with a 32-bit value, and returns the target buffer.
  97
  98   This function fills Length bytes of Buffer with the 32-bit value specified by
  99   Value, and returns Buffer. Value is repeated every 32-bits in for Length
 100   bytes of Buffer.
 101
 102   If Buffer is NULL and Length > 0, then ASSERT().
 103   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 104   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
 105   If Length is not aligned on a 32-bit boundary, then ASSERT().
 106
 107   @param  Buffer  Pointer to the target buffer to fill.
 108   @param  Length  Number of bytes in Buffer to fill.
 109   @param  Value   Value with which to fill Length bytes of Buffer.
 110
 111   @return Buffer
 112
 113 **/
 114 VOID *
 115 EFIAPI
 116 SetMem32 (
 117   OUT     VOID                      *Buffer,
 118   IN      UINTN                     Length,
 119   IN      UINT32                    Value
 120   );
 121
 122 /**
 123   Fills a target buffer with a 64-bit value, and returns the target buffer.
 124
 125   This function fills Length bytes of Buffer with the 64-bit value specified by
 126   Value, and returns Buffer. Value is repeated every 64-bits in for Length
 127   bytes of Buffer.
 128
 129   If Buffer is NULL and Length > 0, then ASSERT().
 130   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 131   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
 132   If Length is not aligned on a 64-bit boundary, then ASSERT().
 133
 134   @param  Buffer  Pointer to the target buffer to fill.
 135   @param  Length  Number of bytes in Buffer to fill.
 136   @param  Value   Value with which to fill Length bytes of Buffer.
 137
 138   @return Buffer
 139
 140 **/
 141 VOID *
 142 EFIAPI
 143 SetMem64 (
 144   OUT     VOID                      *Buffer,
 145   IN      UINTN                     Length,
 146   IN      UINT64                    Value
 147   );
 148
 149 /**
 150   Set Buffer to 0 for Size bytes.
 151
 152   This function fills Length bytes of Buffer with zeros, and returns Buffer.
 153
 154   If Buffer is NULL and Length > 0, then ASSERT().
 155   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 156
 157   @param  Buffer Memory to set.
 158   @param  Size Number of bytes to set
 159
 160   @return Buffer
 161
 162 **/
 163 VOID *
 164 EFIAPI
 165 ZeroMem (
 166   OUT     VOID                      *Buffer,
 167   IN      UINTN                     Length
 168   );
 169
 170 /**
 171   Compares two memory buffers of a given length.
 172
 173   This function compares Length bytes of SourceBuffer to Length bytes of
 174   DestinationBuffer. If all Length bytes of the two buffers are identical, then
 175   0 is returned. Otherwise, the value returned is the first mismatched byte in
 176   SourceBuffer subtracted from the first mismatched byte in DestinationBuffer.
 177
 178   If DestinationBuffer is NULL and Length > 0, then ASSERT().
 179   If SourceBuffer is NULL and Length > 0, then ASSERT().
 180   If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then
 181   ASSERT().
 182   If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT().
 183
 184   @param  DestinationBuffer First memory buffer
 185   @param  SourceBuffer      Second memory buffer
 186   @param  Length            Length of DestinationBuffer and SourceBuffer memory
 187                             regions to compare
 188
 189   @retval 0         if DestinationBuffer == SourceBuffer
 190   @retval Non-zero  if DestinationBuffer != SourceBuffer
 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
 203   matching 8-bit value in the target buffer.
 204
 205   This function searches target the buffer specified by Buffer and Length from
 206   the lowest address to the highest address for an 8-bit value that matches
 207   Value. If a match is found, then a pointer to the matching byte in the target
 208   buffer is returned. If no match is found, then NULL is returned. If Length is
 209   0, then NULL is returned.
 210
 211   If Buffer is NULL, then ASSERT().
 212   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 213
 214   @param  Buffer  Pointer to the target buffer to scan.
 215   @param  Length  Number of bytes in Buffer to scan.
 216   @param  Value   Value to search for in the target buffer.
 217
 218   @return Pointer to the first occurrence or NULL if not found.
 219   @retval NULL  if Length == 0 or Value was not found.
 220
 221 **/
 222 VOID *
 223 EFIAPI
 224 ScanMem8 (
 225   IN      CONST VOID                *Buffer,
 226   IN      UINTN                     Length,
 227   IN      UINT8                     Value
 228   );
 229
 230 /**
 231   Scans a target buffer for a 16-bit value, and returns a pointer to the
 232   matching 16-bit value in the target buffer.
 233
 234   This function searches target the buffer specified by Buffer and Length from
 235   the lowest address to the highest address at 16-bit increments for a 16-bit
 236   value that matches Value. If a match is found, then a pointer to the matching
 237   value in the target buffer is returned. If no match is found, then NULL is
 238   returned. If Length is 0, then NULL is returned.
 239
 240   If Buffer is NULL, then ASSERT().
 241   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 242   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 243
 244   @param  Buffer  Pointer to the target buffer to scan.
 245   @param  Length  Number of bytes in Buffer to scan.
 246   @param  Value   Value to search for in the target buffer.
 247
 248   @return Pointer to the first occurrence.
 249   @retval NULL  if Length == 0 or Value was not found.
 250
 251 **/
 252 VOID *
 253 EFIAPI
 254 ScanMem16 (
 255   IN      CONST VOID                *Buffer,
 256   IN      UINTN                     Length,
 257   IN      UINT16                    Value
 258   );
 259
 260 /**
 261   Scans a target buffer for a 32-bit value, and returns a pointer to the
 262   matching 32-bit value in the target buffer.
 263
 264   This function searches target the buffer specified by Buffer and Length from
 265   the lowest address to the highest address at 32-bit increments for a 32-bit
 266   value that matches Value. If a match is found, then a pointer to the matching
 267   value in the target buffer is returned. If no match is found, then NULL is
 268   returned. If Length is 0, then NULL is returned.
 269
 270   If Buffer is NULL, then ASSERT().
 271   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
 272   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 273
 274   @param  Buffer  Pointer to the target buffer to scan.
 275   @param  Length  Number of bytes in Buffer to scan.
 276   @param  Value   Value to search for in the target buffer.
 277
 278   @return Pointer to the first occurrence or NULL if not found.
 279   @retval NULL  if Length == 0 or Value was not found.
 280
 281 **/
 282 VOID *
 283 EFIAPI
 284 ScanMem32 (
 285   IN      CONST VOID                *Buffer,
 286   IN      UINTN                     Length,
 287   IN      UINT32                    Value
 288   );
 289
 290 /**
 291   Scans a target buffer for a 64-bit value, and returns a pointer to the
 292   matching 64-bit value in the target buffer.
 293
 294   This function searches target the buffer specified by Buffer and Length from
 295   the lowest address to the highest address at 64-bit increments for a 64-bit
 296   value that matches Value. If a match is found, then a pointer to the matching
 297   value in the target buffer is returned. If no match is found, then NULL is
 298   returned. If Length is 0, then NULL is returned.
 299
 300   If Buffer is NULL, then ASSERT().
 301   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
 302   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 303
 304   @param  Buffer  Pointer to the target buffer to scan.
 305   @param  Length  Number of bytes in Buffer to scan.
 306   @param  Value   Value to search for in the target buffer.
 307
 308   @return Pointer to the first occurrence or NULL if not found.
 309   @retval NULL  if Length == 0 or Value was not found.
 310
 311 **/
 312 VOID *
 313 EFIAPI
 314 ScanMem64 (
 315   IN      CONST VOID                *Buffer,
 316   IN      UINTN                     Length,
 317   IN      UINT64                    Value
 318   );
 319
 320 /**
 321   This function copies a source GUID to a destination GUID.
 322
 323   This function copies the contents of the 128-bit GUID specified by SourceGuid
 324   to DestinationGuid, and returns DestinationGuid.
 325
 326   If DestinationGuid is NULL, then ASSERT().
 327   If SourceGuid is NULL, then ASSERT().
 328
 329   @param  DestinationGuid Pointer to the destination GUID.
 330   @param  SourceGuid Pointer to the source GUID.
 331
 332   @return DestinationGuid
 333
 334 **/
 335 GUID *
 336 EFIAPI
 337 CopyGuid (
 338   OUT     GUID                      *DestinationGuid,
 339   IN      CONST GUID                *SourceGuid
 340   );
 341
 342 /**
 343   Compares two GUIDs
 344
 345   This function compares Guid1 to Guid2. If the GUIDs are identical then TRUE
 346   is returned. If there are any bit differences in the two GUIDs, then FALSE is
 347   returned.
 348
 349   If Guid1 is NULL, then ASSERT().
 350   If Guid2 is NULL, then ASSERT().
 351
 352   @param  Guid1 guid to compare
 353   @param  Guid2 guid to compare
 354
 355   @retval TRUE  if Guid1 == Guid2
 356   @retval FALSE if Guid1 != Guid2
 357
 358 **/
 359 BOOLEAN
 360 EFIAPI
 361 CompareGuid (
 362   IN      CONST GUID                *Guid1,
 363   IN      CONST GUID                *Guid2
 364   );
 365
 366 /**
 367   Scans a target buffer for a GUID, and returns a pointer to the matching GUID
 368   in the target buffer.
 369
 370   This function searches target the buffer specified by Buffer and Length from
 371   the lowest address to the highest address at 128-bit increments for the
 372   128-bit GUID value that matches Guid. If a match is found, then a pointer to
 373   the matching GUID in the target buffer is returned. If no match is found,
 374   then NULL is returned. If Length is 0, then NULL is returned.
 375
 376   If Buffer is NULL, then ASSERT().
 377   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
 378   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 379
 380   @param  Buffer  Pointer to the target buffer to scan.
 381   @param  Length  Number of bytes in Buffer to scan.
 382   @param  Guid    Value to search for in the target buffer.
 383
 384   @return Pointer to the first occurrence.
 385   @retval NULL  if Length == 0 or Guid was not found.
 386 **/
 387 VOID *
 388 EFIAPI
 389 ScanGuid (
 390   IN      CONST VOID                *Buffer,
 391   IN      UINTN                     Length,
 392   IN      CONST GUID                *Guid
 393   );
 394
 395 #endif