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