MdePkg/Include/Library/BaseMemoryLib.h

   1 /** @file
   2   Provides copy memory, fill memory, zero memory, and GUID functions.
   3
   4 Copyright (c) 2006 - 2008, 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 **/
  14
  15 #ifndef __BASE_MEMORY_LIB__
  16 #define __BASE_MEMORY_LIB__
  17
  18 /**
  19   Copies a source buffer to a destination buffer, and returns the destination buffer.
  20
  21   This function copies Length bytes from SourceBuffer to DestinationBuffer, and returns
  22   DestinationBuffer.  The implementation must be reentrant, and it must handle the case
  23   where SourceBuffer overlaps DestinationBuffer.
  24   If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then ASSERT().
  25   If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT().
  26
  27   @param  DestinationBuffer   Pointer to the destination buffer of the memory copy.
  28   @param  SourceBuffer        Pointer to the source buffer of the memory copy.
  29   @param  Length              Number of bytes to copy from SourceBuffer to DestinationBuffer.
  30
  31   @return DestinationBuffer.
  32
  33 **/
  34 VOID *
  35 EFIAPI
  36 CopyMem (
  37   OUT VOID       *DestinationBuffer,
  38   IN CONST VOID  *SourceBuffer,
  39   IN UINTN       Length
  40   );
  41
  42 /**
  43   Fills a target buffer with a byte value, and returns the target buffer.
  44
  45   This function fills Length bytes of Buffer with Value, and returns Buffer.
  46   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
  47
  48   @param  Buffer    Memory to set.
  49   @param  Length    Number of bytes to set.
  50   @param  Value     Value of the set operation.
  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  Pointer to the target buffer to fill.
  76   @param  Length  Number of bytes in Buffer to fill.
  77   @param  Value   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  Pointer to the target buffer to fill.
 103   @param  Length  Number of bytes in Buffer to fill.
 104   @param  Value   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  Pointer to the target buffer to fill.
 130   @param  Length  Number of bytes in Buffer to fill.
 131   @param  Value   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 zeros, and returns the target buffer.
 146
 147   This function fills Length bytes of Buffer with zeros, and returns Buffer.
 148   If Length > 0 and Buffer is NULL, then ASSERT().
 149   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 150
 151   @param  Buffer      Pointer to the target buffer to fill with zeros.
 152   @param  Length      Number of bytes in Buffer to fill with zeros.
 153
 154   @return Buffer.
 155
 156 **/
 157 VOID *
 158 EFIAPI
 159 ZeroMem (
 160   OUT VOID  *Buffer,
 161   IN UINTN  Length
 162   );
 163
 164 /**
 165   Compares the contents of two buffers.
 166
 167   This function compares Length bytes of SourceBuffer to Length bytes of DestinationBuffer.
 168   If all Length bytes of the two buffers are identical, then 0 is returned.  Otherwise, the
 169   value returned is the first mismatched byte in SourceBuffer subtracted from the first
 170   mismatched byte in DestinationBuffer.
 171   If Length > 0 and DestinationBuffer is NULL, then ASSERT().
 172   If Length > 0 and SourceBuffer is NULL, then ASSERT().
 173   If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then ASSERT().
 174   If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT().
 175
 176   @param  DestinationBuffer Pointer to the destination buffer to compare.
 177   @param  SourceBuffer      Pointer to the source buffer to compare.
 178   @param  Length            Number of bytes to compare.
 179
 180   @return 0                 All Length bytes of the two buffers are identical.
 181   @retval Non-zero          The first mismatched byte in SourceBuffer subtracted from the first
 182                             mismatched byte in DestinationBuffer.
 183
 184 **/
 185 INTN
 186 EFIAPI
 187 CompareMem (
 188   IN CONST VOID  *DestinationBuffer,
 189   IN CONST VOID  *SourceBuffer,
 190   IN UINTN       Length
 191   );
 192
 193 /**
 194   Scans a target buffer for an 8-bit value, and returns a pointer to the matching 8-bit value
 195   in the target buffer.
 196
 197   This function searches target the buffer specified by Buffer and Length from the lowest
 198   address to the highest address for an 8-bit value that matches Value.  If a match is found,
 199   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 200   then NULL is returned.  If Length is 0, then NULL is returned.
 201   If Length > 0 and Buffer is NULL, then ASSERT().
 202   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 203
 204   @param  Buffer      Pointer to the target buffer to scan.
 205   @param  Length      Number of bytes in Buffer to scan.
 206   @param  Value       Value to search for in the target buffer.
 207
 208   @return A pointer to the matching byte in the target buffer or NULL otherwise.
 209
 210 **/
 211 VOID *
 212 EFIAPI
 213 ScanMem8 (
 214   IN CONST VOID  *Buffer,
 215   IN UINTN       Length,
 216   IN UINT8       Value
 217   );
 218
 219 /**
 220   Scans a target buffer for a 16-bit value, and returns a pointer to the matching 16-bit value
 221   in the target buffer.
 222
 223   This function searches target the buffer specified by Buffer and Length from the lowest
 224   address to the highest address for a 16-bit value that matches Value.  If a match is found,
 225   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 226   then NULL is returned.  If Length is 0, then NULL is returned.
 227   If Length > 0 and Buffer is NULL, then ASSERT().
 228   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 229   If Length is not aligned on a 16-bit boundary, then ASSERT().
 230   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 231
 232   @param  Buffer      Pointer to the target buffer to scan.
 233   @param  Length      Number of bytes in Buffer to scan.
 234   @param  Value       Value to search for in the target buffer.
 235
 236   @return A pointer to the matching byte in the target buffer or NULL otherwise.
 237
 238 **/
 239 VOID *
 240 EFIAPI
 241 ScanMem16 (
 242   IN CONST VOID  *Buffer,
 243   IN UINTN       Length,
 244   IN UINT16      Value
 245   );
 246
 247 /**
 248   Scans a target buffer for a 32-bit value, and returns a pointer to the matching 32-bit value
 249   in the target buffer.
 250
 251   This function searches target the buffer specified by Buffer and Length from the lowest
 252   address to the highest address for a 32-bit value that matches Value.  If a match is found,
 253   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 254   then NULL is returned.  If Length is 0, then NULL is returned.
 255   If Length > 0 and Buffer is NULL, then ASSERT().
 256   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
 257   If Length is not aligned on a 32-bit boundary, then ASSERT().
 258   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 259
 260   @param  Buffer      Pointer to the target buffer to scan.
 261   @param  Length      Number of bytes in Buffer to scan.
 262   @param  Value       Value to search for in the target buffer.
 263
 264   @return A pointer to the matching byte in the target buffer or NULL otherwise.
 265
 266 **/
 267 VOID *
 268 EFIAPI
 269 ScanMem32 (
 270   IN CONST VOID  *Buffer,
 271   IN UINTN       Length,
 272   IN UINT32      Value
 273   );
 274
 275 /**
 276   Scans a target buffer for a 64-bit value, and returns a pointer to the matching 64-bit value
 277   in the target buffer.
 278
 279   This function searches target the buffer specified by Buffer and Length from the lowest
 280   address to the highest address for a 64-bit value that matches Value.  If a match is found,
 281   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 282   then NULL is returned.  If Length is 0, then NULL is returned.
 283   If Length > 0 and Buffer is NULL, then ASSERT().
 284   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
 285   If Length is not aligned on a 64-bit boundary, then ASSERT().
 286   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 287
 288   @param  Buffer      Pointer to the target buffer to scan.
 289   @param  Length      Number of bytes in Buffer to scan.
 290   @param  Value       Value to search for in the target buffer.
 291
 292   @return A pointer to the matching byte in the target buffer or NULL otherwise.
 293
 294 **/
 295 VOID *
 296 EFIAPI
 297 ScanMem64 (
 298   IN CONST VOID  *Buffer,
 299   IN UINTN       Length,
 300   IN UINT64      Value
 301   );
 302
 303 /**
 304   Copies a source GUID to a destination GUID.
 305
 306   This function copies the contents of the 128-bit GUID specified by SourceGuid to
 307   DestinationGuid, and returns DestinationGuid.
 308   If DestinationGuid is NULL, then ASSERT().
 309   If SourceGuid is NULL, then ASSERT().
 310
 311   @param  DestinationGuid   Pointer to the destination GUID.
 312   @param  SourceGuid        Pointer to the source GUID.
 313
 314   @return DestinationGuid.
 315
 316 **/
 317 GUID *
 318 EFIAPI
 319 CopyGuid (
 320   OUT GUID       *DestinationGuid,
 321   IN CONST GUID  *SourceGuid
 322   );
 323
 324 /**
 325   Compares two GUIDs.
 326
 327   This function compares Guid1 to Guid2.  If the GUIDs are identical then TRUE is returned.
 328   If there are any bit differences in the two GUIDs, then FALSE is returned.
 329   If Guid1 is NULL, then ASSERT().
 330   If Guid2 is NULL, then ASSERT().
 331
 332   @param  Guid1       A pointer to a 128 bit GUID.
 333   @param  Guid2       A pointer to a 128 bit GUID.
 334
 335   @retval TRUE        Guid1 and Guid2 are identical.
 336   @retval FALSE       Guid1 and Guid2 are not identical.
 337
 338 **/
 339 BOOLEAN
 340 EFIAPI
 341 CompareGuid (
 342   IN CONST GUID  *Guid1,
 343   IN CONST GUID  *Guid2
 344   );
 345
 346 /**
 347   Scans a target buffer for a GUID, and returns a pointer to the matching GUID
 348   in the target buffer.
 349
 350   This function searches target the buffer specified by Buffer and Length from
 351   the lowest address to the highest address at 128-bit increments for the 128-bit
 352   GUID value that matches Guid.  If a match is found, then a pointer to the matching
 353   GUID in the target buffer is returned.  If no match is found, then NULL is returned.
 354   If Length is 0, then NULL is returned.
 355   If Length > 0 and Buffer is NULL, then ASSERT().
 356   If Buffer is not aligned on a 32-bit boundary, then ASSERT().
 357   If Length is not aligned on a 128-bit boundary, then ASSERT().
 358   If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 359
 360   @param  Buffer  Pointer to the target buffer to scan.
 361   @param  Length  Number of bytes in Buffer to scan.
 362   @param  Guid    Value to search for in the target buffer.
 363
 364   @return A pointer to the matching Guid in the target buffer or NULL otherwise.
 365
 366 **/
 367 VOID *
 368 EFIAPI
 369 ScanGuid (
 370   IN CONST VOID  *Buffer,
 371   IN UINTN       Length,
 372   IN CONST GUID  *Guid
 373   );
 374
 375 #endif