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