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 - 2016, Intel Corporation. All rights reserved.<BR> 9 This program and the accompanying materials are licensed and made available under 10 the terms and conditions of the BSD License that accompanies this distribution. 11 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 The pointer to the destination buffer of the memory copy. 33 @param SourceBuffer The pointer to the source buffer of the memory copy. 34 @param Length The 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 The memory to set. 55 @param Length The number of bytes to set. 56 @param Value The 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 The pointer to the target buffer to fill. 82 @param Length The number of bytes in Buffer to fill. 83 @param Value The 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 The pointer to the target buffer to fill. 109 @param Length The number of bytes in Buffer to fill. 110 @param Value The 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 The pointer to the target buffer to fill. 136 @param Length The number of bytes in Buffer to fill. 137 @param Value The 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 a value that is size UINTN, and returns the target buffer. 152 153 This function fills Length bytes of Buffer with the UINTN sized value specified by 154 Value, and returns Buffer. Value is repeated every sizeof(UINTN) bytes for Length 155 bytes of Buffer. 156 157 If Length > 0 and Buffer is NULL, then ASSERT(). 158 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 159 If Buffer is not aligned on a UINTN boundary, then ASSERT(). 160 If Length is not aligned on a UINTN boundary, then ASSERT(). 161 162 @param Buffer The pointer to the target buffer to fill. 163 @param Length The number of bytes in Buffer to fill. 164 @param Value The value with which to fill Length bytes of Buffer. 165 166 @return Buffer. 167 168 **/ 169 VOID * 170 EFIAPI 171 SetMemN ( 172 OUT VOID *Buffer, 173 IN UINTN Length, 174 IN UINTN Value 175 ); 176 177 /** 178 Fills a target buffer with zeros, and returns the target buffer. 179 180 This function fills Length bytes of Buffer with zeros, and returns Buffer. 181 182 If Length > 0 and Buffer is NULL, then ASSERT(). 183 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 184 185 @param Buffer The pointer to the target buffer to fill with zeros. 186 @param Length The number of bytes in Buffer to fill with zeros. 187 188 @return Buffer. 189 190 **/ 191 VOID * 192 EFIAPI 193 ZeroMem ( 194 OUT VOID *Buffer, 195 IN UINTN Length 196 ); 197 198 /** 199 Compares the contents of two buffers. 200 201 This function compares Length bytes of SourceBuffer to Length bytes of DestinationBuffer. 202 If all Length bytes of the two buffers are identical, then 0 is returned. Otherwise, the 203 value returned is the first mismatched byte in SourceBuffer subtracted from the first 204 mismatched byte in DestinationBuffer. 205 206 If Length > 0 and DestinationBuffer is NULL, then ASSERT(). 207 If Length > 0 and SourceBuffer is NULL, then ASSERT(). 208 If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then ASSERT(). 209 If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT(). 210 211 @param DestinationBuffer The pointer to the destination buffer to compare. 212 @param SourceBuffer The pointer to the source buffer to compare. 213 @param Length The number of bytes to compare. 214 215 @return 0 All Length bytes of the two buffers are identical. 216 @retval Non-zero The first mismatched byte in SourceBuffer subtracted from the first 217 mismatched byte in DestinationBuffer. 218 219 **/ 220 INTN 221 EFIAPI 222 CompareMem ( 223 IN CONST VOID *DestinationBuffer, 224 IN CONST VOID *SourceBuffer, 225 IN UINTN Length 226 ); 227 228 /** 229 Scans a target buffer for an 8-bit value, and returns a pointer to the matching 8-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 an 8-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 Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 239 240 @param Buffer The pointer to the target buffer to scan. 241 @param Length The number of bytes in Buffer to scan. 242 @param Value The value to search for in the target buffer. 243 244 @return A pointer to the matching byte in the target buffer, otherwise NULL. 245 246 **/ 247 VOID * 248 EFIAPI 249 ScanMem8 ( 250 IN CONST VOID *Buffer, 251 IN UINTN Length, 252 IN UINT8 Value 253 ); 254 255 /** 256 Scans a target buffer for a 16-bit value, and returns a pointer to the matching 16-bit value 257 in the target buffer. 258 259 This function searches target the buffer specified by Buffer and Length from the lowest 260 address to the highest address for a 16-bit value that matches Value. If a match is found, 261 then a pointer to the matching byte in the target buffer is returned. If no match is found, 262 then NULL is returned. If Length is 0, then NULL is returned. 263 264 If Length > 0 and Buffer is NULL, then ASSERT(). 265 If Buffer is not aligned on a 16-bit boundary, then ASSERT(). 266 If Length is not aligned on a 16-bit boundary, then ASSERT(). 267 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 268 269 @param Buffer The pointer to the target buffer to scan. 270 @param Length The number of bytes in Buffer to scan. 271 @param Value The value to search for in the target buffer. 272 273 @return A pointer to the matching byte in the target buffer, otherwise NULL. 274 275 **/ 276 VOID * 277 EFIAPI 278 ScanMem16 ( 279 IN CONST VOID *Buffer, 280 IN UINTN Length, 281 IN UINT16 Value 282 ); 283 284 /** 285 Scans a target buffer for a 32-bit value, and returns a pointer to the matching 32-bit value 286 in the target buffer. 287 288 This function searches target the buffer specified by Buffer and Length from the lowest 289 address to the highest address for a 32-bit value that matches Value. If a match is found, 290 then a pointer to the matching byte in the target buffer is returned. If no match is found, 291 then NULL is returned. If Length is 0, then NULL is returned. 292 293 If Length > 0 and Buffer is NULL, then ASSERT(). 294 If Buffer is not aligned on a 32-bit boundary, then ASSERT(). 295 If Length is not aligned on a 32-bit boundary, then ASSERT(). 296 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 297 298 @param Buffer The pointer to the target buffer to scan. 299 @param Length The number of bytes in Buffer to scan. 300 @param Value The value to search for in the target buffer. 301 302 @return A pointer to the matching byte in the target buffer, otherwise NULL. 303 304 **/ 305 VOID * 306 EFIAPI 307 ScanMem32 ( 308 IN CONST VOID *Buffer, 309 IN UINTN Length, 310 IN UINT32 Value 311 ); 312 313 /** 314 Scans a target buffer for a 64-bit value, and returns a pointer to the matching 64-bit value 315 in the target buffer. 316 317 This function searches target the buffer specified by Buffer and Length from the lowest 318 address to the highest address for a 64-bit value that matches Value. If a match is found, 319 then a pointer to the matching byte in the target buffer is returned. If no match is found, 320 then NULL is returned. If Length is 0, then NULL is returned. 321 322 If Length > 0 and Buffer is NULL, then ASSERT(). 323 If Buffer is not aligned on a 64-bit boundary, then ASSERT(). 324 If Length is not aligned on a 64-bit boundary, then ASSERT(). 325 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 326 327 @param Buffer The pointer to the target buffer to scan. 328 @param Length The number of bytes in Buffer to scan. 329 @param Value The value to search for in the target buffer. 330 331 @return A pointer to the matching byte in the target buffer, otherwise NULL. 332 333 **/ 334 VOID * 335 EFIAPI 336 ScanMem64 ( 337 IN CONST VOID *Buffer, 338 IN UINTN Length, 339 IN UINT64 Value 340 ); 341 342 /** 343 Scans a target buffer for a UINTN sized value, and returns a pointer to the matching 344 UINTN sized value in the target buffer. 345 346 This function searches target the buffer specified by Buffer and Length from the lowest 347 address to the highest address for a UINTN sized value that matches Value. If a match is found, 348 then a pointer to the matching byte in the target buffer is returned. If no match is found, 349 then NULL is returned. If Length is 0, then NULL is returned. 350 351 If Length > 0 and Buffer is NULL, then ASSERT(). 352 If Buffer is not aligned on a UINTN boundary, then ASSERT(). 353 If Length is not aligned on a UINTN boundary, then ASSERT(). 354 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 355 356 @param Buffer The pointer to the target buffer to scan. 357 @param Length The number of bytes in Buffer to scan. 358 @param Value The value to search for in the target buffer. 359 360 @return A pointer to the matching byte in the target buffer, otherwise NULL. 361 362 **/ 363 VOID * 364 EFIAPI 365 ScanMemN ( 366 IN CONST VOID *Buffer, 367 IN UINTN Length, 368 IN UINTN Value 369 ); 370 371 /** 372 Copies a source GUID to a destination GUID. 373 374 This function copies the contents of the 128-bit GUID specified by SourceGuid to 375 DestinationGuid, and returns DestinationGuid. 376 377 If DestinationGuid is NULL, then ASSERT(). 378 If SourceGuid is NULL, then ASSERT(). 379 380 @param DestinationGuid The pointer to the destination GUID. 381 @param SourceGuid The pointer to the source GUID. 382 383 @return DestinationGuid. 384 385 **/ 386 GUID * 387 EFIAPI 388 CopyGuid ( 389 OUT GUID *DestinationGuid, 390 IN CONST GUID *SourceGuid 391 ); 392 393 /** 394 Compares two GUIDs. 395 396 This function compares Guid1 to Guid2. If the GUIDs are identical then TRUE is returned. 397 If there are any bit differences in the two GUIDs, then FALSE is returned. 398 399 If Guid1 is NULL, then ASSERT(). 400 If Guid2 is NULL, then ASSERT(). 401 402 @param Guid1 A pointer to a 128 bit GUID. 403 @param Guid2 A pointer to a 128 bit GUID. 404 405 @retval TRUE Guid1 and Guid2 are identical. 406 @retval FALSE Guid1 and Guid2 are not identical. 407 408 **/ 409 BOOLEAN 410 EFIAPI 411 CompareGuid ( 412 IN CONST GUID *Guid1, 413 IN CONST GUID *Guid2 414 ); 415 416 /** 417 Scans a target buffer for a GUID, and returns a pointer to the matching GUID 418 in the target buffer. 419 420 This function searches target the buffer specified by Buffer and Length from 421 the lowest address to the highest address at 128-bit increments for the 128-bit 422 GUID value that matches Guid. If a match is found, then a pointer to the matching 423 GUID in the target buffer is returned. If no match is found, then NULL is returned. 424 If Length is 0, then NULL is returned. 425 426 If Length > 0 and Buffer is NULL, then ASSERT(). 427 If Buffer is not aligned on a 32-bit boundary, then ASSERT(). 428 If Length is not aligned on a 128-bit boundary, then ASSERT(). 429 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 430 431 @param Buffer The pointer to the target buffer to scan. 432 @param Length The number of bytes in Buffer to scan. 433 @param Guid The value to search for in the target buffer. 434 435 @return A pointer to the matching Guid in the target buffer, otherwise NULL. 436 437 **/ 438 VOID * 439 EFIAPI 440 ScanGuid ( 441 IN CONST VOID *Buffer, 442 IN UINTN Length, 443 IN CONST GUID *Guid 444 ); 445 446 /** 447 Checks if the given GUID is a zero GUID. 448 449 This function checks whether the given GUID is a zero GUID. If the GUID is 450 identical to a zero GUID then TRUE is returned. Otherwise, FALSE is returned. 451 452 If Guid is NULL, then ASSERT(). 453 454 @param Guid The pointer to a 128 bit GUID. 455 456 @retval TRUE Guid is a zero GUID. 457 @retval FALSE Guid is not a zero GUID. 458 459 **/ 460 BOOLEAN 461 EFIAPI 462 IsZeroGuid ( 463 IN CONST GUID *Guid 464 ); 465 466 /** 467 Checks if the contents of a buffer are all zeros. 468 469 This function checks whether the contents of a buffer are all zeros. If the 470 contents are all zeros, return TRUE. Otherwise, return FALSE. 471 472 If Length > 0 and Buffer is NULL, then ASSERT(). 473 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). 474 475 @param Buffer The pointer to the buffer to be checked. 476 @param Length The size of the buffer (in bytes) to be checked. 477 478 @retval TRUE Contents of the buffer are all zeros. 479 @retval FALSE Contents of the buffer are not all zeros. 480 481 **/ 482 BOOLEAN 483 EFIAPI 484 IsZeroBuffer ( 485 IN CONST VOID *Buffer, 486 IN UINTN Length 487 ); 488 489 #endif 490