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 \96 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 \96 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
 179   @param  DestinationBuffer Pointer to the destination buffer to compare.
 180   @param  SourceBuffer      Pointer to the source buffer to compare.
 181   @param  Length            Number of bytes to compare.
 182
 183   @return 0                 All Length bytes of the two buffers are identical.
 184   @retval Non-zero          The first mismatched byte in SourceBuffer subtracted from the first
 185                             mismatched byte in DestinationBuffer.
 186
 187 **/
 188 INTN
 189 EFIAPI
 190 CompareMem (
 191   IN CONST VOID  *DestinationBuffer,
 192   IN CONST VOID  *SourceBuffer,
 193   IN UINTN       Length
 194   );
 195
 196 /**
 197   Scans a target buffer for an 8-bit value, and returns a pointer to the matching 8-bit value
 198   in the target buffer.
 199
 200   This function searches target the buffer specified by Buffer and Length from the lowest
 201   address to the highest address for an 8-bit value that matches Value.  If a match is found,
 202   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 203   then NULL is returned.  If Length is 0, then NULL is returned.
 204   If Length > 0 and Buffer is NULL, then ASSERT().
 205   If Length is greater than (MAX_ADDRESS \96 Buffer + 1), then ASSERT().
 206
 207   @param  Buffer      Pointer to the target buffer to scan.
 208   @param  Length      Number of bytes in Buffer to scan.
 209   @param  Value       Value to search for in the target buffer.
 210
 211   @return A pointer to the matching byte in the target buffer or NULL otherwise.
 212
 213 **/
 214 VOID *
 215 EFIAPI
 216 ScanMem8 (
 217   IN CONST VOID  *Buffer,
 218   IN UINTN       Length,
 219   IN UINT8       Value
 220   );
 221
 222 /**
 223   Scans a target buffer for a 16-bit value, and returns a pointer to the matching 16-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 a 16-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   If Length > 0 and Buffer is NULL, then ASSERT().
 231   If Buffer is not aligned on a 16-bit boundary, then ASSERT().
 232   If Length is greater than (MAX_ADDRESS \96 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 greater than (MAX_ADDRESS \96 Buffer + 1), then ASSERT().
 260
 261   @param  Buffer      Pointer to the target buffer to scan.
 262   @param  Length      Number of bytes in Buffer to scan.
 263   @param  Value       Value to search for in the target buffer.
 264
 265   @return A pointer to the matching byte in the target buffer or NULL otherwise.
 266
 267 **/
 268 VOID *
 269 EFIAPI
 270 ScanMem32 (
 271   IN CONST VOID  *Buffer,
 272   IN UINTN       Length,
 273   IN UINT32      Value
 274   );
 275
 276 /**
 277   Scans a target buffer for a 64-bit value, and returns a pointer to the matching 64-bit value
 278   in the target buffer.
 279
 280   This function searches target the buffer specified by Buffer and Length from the lowest
 281   address to the highest address for a 64-bit value that matches Value.  If a match is found,
 282   then a pointer to the matching byte in the target buffer is returned.  If no match is found,
 283   then NULL is returned.  If Length is 0, then NULL is returned.
 284   If Length > 0 and Buffer is NULL, then ASSERT().
 285   If Buffer is not aligned on a 64-bit boundary, then ASSERT().
 286   If Length is greater than (MAX_ADDRESS \96 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 64-bit boundary, then ASSERT().
 357   If Length is greater than (MAX_ADDRESS \96 Buffer + 1), then ASSERT().
 358
 359   @param  Buffer  Pointer to the target buffer to scan.
 360   @param  Length  Number of bytes in Buffer to scan.
 361   @param  Guid    Value to search for in the target buffer.
 362
 363   @return A pointer to the matching Guid in the target buffer or NULL otherwise.
 364
 365 **/
 366 VOID *
 367 EFIAPI
 368 ScanGuid (
 369   IN CONST VOID  *Buffer,
 370   IN UINTN       Length,
 371   IN CONST GUID  *Guid
 372   );
 373
 374 #endif