X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=MdePkg%2FInclude%2FLibrary%2FBaseMemoryLib.h;h=46026ffd1a511188d65ff272e979b205fabbb10e;hb=9344f0921518309295da89c221d10cbead8531aa;hp=66051525ec513459f213239a7b7c1a5149818e2e;hpb=fb3df220f89e6eecaf1862b9241d8a1214eeda1c;p=mirror_edk2.git diff --git a/MdePkg/Include/Library/BaseMemoryLib.h b/MdePkg/Include/Library/BaseMemoryLib.h index 66051525ec..46026ffd1a 100644 --- a/MdePkg/Include/Library/BaseMemoryLib.h +++ b/MdePkg/Include/Library/BaseMemoryLib.h @@ -1,16 +1,12 @@ /** @file - Memory-only library functions with no library constructor/destructor + Provides copy memory, fill memory, zero memory, and GUID functions. - Copyright (c) 2006, Intel Corporation - All rights reserved. This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php + The Base Memory Library provides optimized implementations for common memory-based operations. + These functions should be used in place of coding your own loops to do equivalent common functions. + This allows optimized library implementations to help increase performance. - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - - Module Name: BaseMemoryLib.h +Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.
+SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -23,12 +19,13 @@ This function copies Length bytes from SourceBuffer to DestinationBuffer, and returns DestinationBuffer. The implementation must be reentrant, and it must handle the case where SourceBuffer overlaps DestinationBuffer. - If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then ASSERT(). - If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT(). - @param DestinationBuffer Pointer to the destination buffer of the memory copy. - @param SourceBuffer Pointer to the source buffer of the memory copy. - @param Length Number of bytes to copy from SourceBuffer to DestinationBuffer. + If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT(). + + @param DestinationBuffer The pointer to the destination buffer of the memory copy. + @param SourceBuffer The pointer to the source buffer of the memory copy. + @param Length The number of bytes to copy from SourceBuffer to DestinationBuffer. @return DestinationBuffer. @@ -45,11 +42,12 @@ CopyMem ( Fills a target buffer with a byte value, and returns the target buffer. This function fills Length bytes of Buffer with Value, and returns Buffer. - If Length is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT(). - @param Buffer Memory to set. - @param Length Number of bytes to set. - @param Value Value of the set operation. + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + + @param Buffer The memory to set. + @param Length The number of bytes to set. + @param Value The value with which to fill Length bytes of Buffer. @return Buffer. @@ -74,9 +72,9 @@ SetMem ( If Buffer is not aligned on a 16-bit boundary, then ASSERT(). If Length is not aligned on a 16-bit boundary, then ASSERT(). - @param Buffer Pointer to the target buffer to fill. - @param Length Number of bytes in Buffer to fill. - @param Value Value with which to fill Length bytes of Buffer. + @param Buffer The pointer to the target buffer to fill. + @param Length The number of bytes in Buffer to fill. + @param Value The value with which to fill Length bytes of Buffer. @return Buffer. @@ -101,9 +99,9 @@ SetMem16 ( If Buffer is not aligned on a 32-bit boundary, then ASSERT(). If Length is not aligned on a 32-bit boundary, then ASSERT(). - @param Buffer Pointer to the target buffer to fill. - @param Length Number of bytes in Buffer to fill. - @param Value Value with which to fill Length bytes of Buffer. + @param Buffer The pointer to the target buffer to fill. + @param Length The number of bytes in Buffer to fill. + @param Value The value with which to fill Length bytes of Buffer. @return Buffer. @@ -128,9 +126,9 @@ SetMem32 ( If Buffer is not aligned on a 64-bit boundary, then ASSERT(). If Length is not aligned on a 64-bit boundary, then ASSERT(). - @param Buffer Pointer to the target buffer to fill. - @param Length Number of bytes in Buffer to fill. - @param Value Value with which to fill Length bytes of Buffer. + @param Buffer The pointer to the target buffer to fill. + @param Length The number of bytes in Buffer to fill. + @param Value The value with which to fill Length bytes of Buffer. @return Buffer. @@ -143,15 +141,43 @@ SetMem64 ( IN UINT64 Value ); +/** + Fills a target buffer with a value that is size UINTN, and returns the target buffer. + + This function fills Length bytes of Buffer with the UINTN sized value specified by + Value, and returns Buffer. Value is repeated every sizeof(UINTN) bytes for Length + bytes of Buffer. + + If Length > 0 and Buffer is NULL, then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + If Buffer is not aligned on a UINTN boundary, then ASSERT(). + If Length is not aligned on a UINTN boundary, then ASSERT(). + + @param Buffer The pointer to the target buffer to fill. + @param Length The number of bytes in Buffer to fill. + @param Value The value with which to fill Length bytes of Buffer. + + @return Buffer. + +**/ +VOID * +EFIAPI +SetMemN ( + OUT VOID *Buffer, + IN UINTN Length, + IN UINTN Value + ); + /** Fills a target buffer with zeros, and returns the target buffer. This function fills Length bytes of Buffer with zeros, and returns Buffer. + If Length > 0 and Buffer is NULL, then ASSERT(). - If Length is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). - @param Buffer Pointer to the target buffer to fill with zeros. - @param Length Number of bytes in Buffer to fill with zeros. + @param Buffer The pointer to the target buffer to fill with zeros. + @param Length The number of bytes in Buffer to fill with zeros. @return Buffer. @@ -170,14 +196,15 @@ ZeroMem ( If all Length bytes of the two buffers are identical, then 0 is returned. Otherwise, the value returned is the first mismatched byte in SourceBuffer subtracted from the first mismatched byte in DestinationBuffer. - If Length > 0 and DestinationBuffer is NULL and Length > 0, then ASSERT(). - If Length > 0 and SourceBuffer is NULL and Length > 0, then ASSERT(). - If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then ASSERT(). - If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT(). - @param DestinationBuffer Pointer to the destination buffer to compare. - @param SourceBuffer Pointer to the source buffer to compare. - @param Length Number of bytes to compare. + If Length > 0 and DestinationBuffer is NULL, then ASSERT(). + If Length > 0 and SourceBuffer is NULL, then ASSERT(). + If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT(). + + @param DestinationBuffer The pointer to the destination buffer to compare. + @param SourceBuffer The pointer to the source buffer to compare. + @param Length The number of bytes to compare. @return 0 All Length bytes of the two buffers are identical. @retval Non-zero The first mismatched byte in SourceBuffer subtracted from the first @@ -200,14 +227,15 @@ CompareMem ( address to the highest address for an 8-bit value that matches Value. If a match is found, then a pointer to the matching byte in the target buffer is returned. If no match is found, then NULL is returned. If Length is 0, then NULL is returned. + If Length > 0 and Buffer is NULL, then ASSERT(). - If Length is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). - @param Buffer Pointer to the target buffer to scan. - @param Length Number of bytes in Buffer to scan. - @param Value Value to search for in the target buffer. + @param Buffer The pointer to the target buffer to scan. + @param Length The number of bytes in Buffer to scan. + @param Value The value to search for in the target buffer. - @return A pointer to the matching byte in the target buffer or NULL otherwise. + @return A pointer to the matching byte in the target buffer, otherwise NULL. **/ VOID * @@ -226,16 +254,17 @@ ScanMem8 ( address to the highest address for a 16-bit value that matches Value. If a match is found, then a pointer to the matching byte in the target buffer is returned. If no match is found, then NULL is returned. If Length is 0, then NULL is returned. + If Length > 0 and Buffer is NULL, then ASSERT(). If Buffer is not aligned on a 16-bit boundary, then ASSERT(). If Length is not aligned on a 16-bit boundary, then ASSERT(). - If Length is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). - @param Buffer Pointer to the target buffer to scan. - @param Length Number of bytes in Buffer to scan. - @param Value Value to search for in the target buffer. + @param Buffer The pointer to the target buffer to scan. + @param Length The number of bytes in Buffer to scan. + @param Value The value to search for in the target buffer. - @return A pointer to the matching byte in the target buffer or NULL otherwise. + @return A pointer to the matching byte in the target buffer, otherwise NULL. **/ VOID * @@ -254,16 +283,17 @@ ScanMem16 ( address to the highest address for a 32-bit value that matches Value. If a match is found, then a pointer to the matching byte in the target buffer is returned. If no match is found, then NULL is returned. If Length is 0, then NULL is returned. + If Length > 0 and Buffer is NULL, then ASSERT(). If Buffer is not aligned on a 32-bit boundary, then ASSERT(). If Length is not aligned on a 32-bit boundary, then ASSERT(). - If Length is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). - @param Buffer Pointer to the target buffer to scan. - @param Length Number of bytes in Buffer to scan. - @param Value Value to search for in the target buffer. + @param Buffer The pointer to the target buffer to scan. + @param Length The number of bytes in Buffer to scan. + @param Value The value to search for in the target buffer. - @return A pointer to the matching byte in the target buffer or NULL otherwise. + @return A pointer to the matching byte in the target buffer, otherwise NULL. **/ VOID * @@ -282,16 +312,17 @@ ScanMem32 ( address to the highest address for a 64-bit value that matches Value. If a match is found, then a pointer to the matching byte in the target buffer is returned. If no match is found, then NULL is returned. If Length is 0, then NULL is returned. + If Length > 0 and Buffer is NULL, then ASSERT(). If Buffer is not aligned on a 64-bit boundary, then ASSERT(). If Length is not aligned on a 64-bit boundary, then ASSERT(). - If Length is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). - @param Buffer Pointer to the target buffer to scan. - @param Length Number of bytes in Buffer to scan. - @param Value Value to search for in the target buffer. + @param Buffer The pointer to the target buffer to scan. + @param Length The number of bytes in Buffer to scan. + @param Value The value to search for in the target buffer. - @return A pointer to the matching byte in the target buffer or NULL otherwise. + @return A pointer to the matching byte in the target buffer, otherwise NULL. **/ VOID * @@ -302,16 +333,46 @@ ScanMem64 ( IN UINT64 Value ); +/** + Scans a target buffer for a UINTN sized value, and returns a pointer to the matching + UINTN sized value in the target buffer. + + This function searches target the buffer specified by Buffer and Length from the lowest + address to the highest address for a UINTN sized value that matches Value. If a match is found, + then a pointer to the matching byte in the target buffer is returned. If no match is found, + then NULL is returned. If Length is 0, then NULL is returned. + + If Length > 0 and Buffer is NULL, then ASSERT(). + If Buffer is not aligned on a UINTN boundary, then ASSERT(). + If Length is not aligned on a UINTN boundary, then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + + @param Buffer The pointer to the target buffer to scan. + @param Length The number of bytes in Buffer to scan. + @param Value The value to search for in the target buffer. + + @return A pointer to the matching byte in the target buffer, otherwise NULL. + +**/ +VOID * +EFIAPI +ScanMemN ( + IN CONST VOID *Buffer, + IN UINTN Length, + IN UINTN Value + ); + /** Copies a source GUID to a destination GUID. This function copies the contents of the 128-bit GUID specified by SourceGuid to DestinationGuid, and returns DestinationGuid. + If DestinationGuid is NULL, then ASSERT(). If SourceGuid is NULL, then ASSERT(). - @param DestinationGuid Pointer to the destination GUID. - @param SourceGuid Pointer to the source GUID. + @param DestinationGuid The pointer to the destination GUID. + @param SourceGuid The pointer to the source GUID. @return DestinationGuid. @@ -328,6 +389,7 @@ CopyGuid ( This function compares Guid1 to Guid2. If the GUIDs are identical then TRUE is returned. If there are any bit differences in the two GUIDs, then FALSE is returned. + If Guid1 is NULL, then ASSERT(). If Guid2 is NULL, then ASSERT(). @@ -354,16 +416,17 @@ CompareGuid ( GUID value that matches Guid. If a match is found, then a pointer to the matching GUID in the target buffer is returned. If no match is found, then NULL is returned. If Length is 0, then NULL is returned. + If Length > 0 and Buffer is NULL, then ASSERT(). If Buffer is not aligned on a 32-bit boundary, then ASSERT(). If Length is not aligned on a 128-bit boundary, then ASSERT(). - If Length is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). - @param Buffer Pointer to the target buffer to scan. - @param Length Number of bytes in Buffer to scan. - @param Guid Value to search for in the target buffer. + @param Buffer The pointer to the target buffer to scan. + @param Length The number of bytes in Buffer to scan. + @param Guid The value to search for in the target buffer. - @return A pointer to the matching Guid in the target buffer or NULL otherwise. + @return A pointer to the matching Guid in the target buffer, otherwise NULL. **/ VOID * @@ -374,4 +437,47 @@ ScanGuid ( IN CONST GUID *Guid ); +/** + Checks if the given GUID is a zero GUID. + + This function checks whether the given GUID is a zero GUID. If the GUID is + identical to a zero GUID then TRUE is returned. Otherwise, FALSE is returned. + + If Guid is NULL, then ASSERT(). + + @param Guid The pointer to a 128 bit GUID. + + @retval TRUE Guid is a zero GUID. + @retval FALSE Guid is not a zero GUID. + +**/ +BOOLEAN +EFIAPI +IsZeroGuid ( + IN CONST GUID *Guid + ); + +/** + Checks if the contents of a buffer are all zeros. + + This function checks whether the contents of a buffer are all zeros. If the + contents are all zeros, return TRUE. Otherwise, return FALSE. + + If Length > 0 and Buffer is NULL, then ASSERT(). + If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). + + @param Buffer The pointer to the buffer to be checked. + @param Length The size of the buffer (in bytes) to be checked. + + @retval TRUE Contents of the buffer are all zeros. + @retval FALSE Contents of the buffer are not all zeros. + +**/ +BOOLEAN +EFIAPI +IsZeroBuffer ( + IN CONST VOID *Buffer, + IN UINTN Length + ); + #endif