X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=MdePkg%2FInclude%2FLibrary%2FBaseMemoryLib.h;h=38f6c489d5dca3937b0ccfdd8d7d96f13dcd13aa;hp=5994530b55c0faca11f9a9ec4156d245be67c565;hb=24e25d11c0460dfb39fade685375c0e58cbcb40e;hpb=878ddf1fc3540a715f63594ed22b6929e881afb4 diff --git a/MdePkg/Include/Library/BaseMemoryLib.h b/MdePkg/Include/Library/BaseMemoryLib.h index 5994530b55..38f6c489d5 100644 --- a/MdePkg/Include/Library/BaseMemoryLib.h +++ b/MdePkg/Include/Library/BaseMemoryLib.h @@ -1,16 +1,16 @@ /** @file - Memory-only library functions with no library constructor/destructor + Memory-only library functions with no library constructor/destructor - 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 + 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 PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + 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 + Module Name: BaseMemoryLib.h **/ @@ -18,51 +18,48 @@ #define __BASE_MEMORY_LIB__ /** - Copy Length bytes from Source to Destination. + Copies a source buffer to a destination buffer, and returns the destination buffer. - 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. + 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(). - 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. - @param Destination Target of copy - @param Source Place to copy from - @param Length Number of bytes to copy - - @return Destination + @return DestinationBuffer. **/ VOID * EFIAPI CopyMem ( - OUT VOID *DestinationBuffer, - IN CONST VOID *SourceBuffer, - IN UINTN Length + OUT VOID *DestinationBuffer, + IN CONST VOID *SourceBuffer, + IN UINTN Length ); /** - Set Buffer to Value for Size bytes. + 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(). - If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). - - @param Buffer Memory to set. - @param Size Number of bytes to set - @param Value Value of the set operation. + @param Buffer Memory to set. + @param Length Number of bytes to set + @param Value Value of the set operation. - @return Buffer + @return Buffer. **/ VOID * EFIAPI SetMem ( - OUT VOID *Buffer, - IN UINTN Length, - IN UINT8 Value + OUT VOID *Buffer, + IN UINTN Length, + IN UINT8 Value ); /** @@ -72,7 +69,7 @@ SetMem ( Value, and returns Buffer. Value is repeated every 16-bits in for Length bytes of Buffer. - If Buffer is NULL and Length > 0, then ASSERT(). + 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 16-bit boundary, then ASSERT(). If Length is not aligned on a 16-bit boundary, then ASSERT(). @@ -81,15 +78,15 @@ SetMem ( @param Length Number of bytes in Buffer to fill. @param Value Value with which to fill Length bytes of Buffer. - @return Buffer + @return Buffer. **/ VOID * EFIAPI SetMem16 ( - OUT VOID *Buffer, - IN UINTN Length, - IN UINT16 Value + OUT VOID *Buffer, + IN UINTN Length, + IN UINT16 Value ); /** @@ -99,7 +96,7 @@ SetMem16 ( Value, and returns Buffer. Value is repeated every 32-bits in for Length bytes of Buffer. - If Buffer is NULL and Length > 0, then ASSERT(). + 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 32-bit boundary, then ASSERT(). If Length is not aligned on a 32-bit boundary, then ASSERT(). @@ -108,15 +105,15 @@ SetMem16 ( @param Length Number of bytes in Buffer to fill. @param Value Value with which to fill Length bytes of Buffer. - @return Buffer + @return Buffer. **/ VOID * EFIAPI SetMem32 ( - OUT VOID *Buffer, - IN UINTN Length, - IN UINT32 Value + OUT VOID *Buffer, + IN UINTN Length, + IN UINT32 Value ); /** @@ -126,7 +123,7 @@ SetMem32 ( Value, and returns Buffer. Value is repeated every 64-bits in for Length bytes of Buffer. - If Buffer is NULL and Length > 0, then ASSERT(). + 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 64-bit boundary, then ASSERT(). If Length is not aligned on a 64-bit boundary, then ASSERT(). @@ -135,232 +132,215 @@ SetMem32 ( @param Length Number of bytes in Buffer to fill. @param Value Value with which to fill Length bytes of Buffer. - @return Buffer + @return Buffer. **/ VOID * EFIAPI SetMem64 ( - OUT VOID *Buffer, - IN UINTN Length, - IN UINT64 Value + OUT VOID *Buffer, + IN UINTN Length, + IN UINT64 Value ); /** - Set Buffer to 0 for Size bytes. + 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 Buffer is NULL and Length > 0, then ASSERT(). - If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT(). - - @param Buffer Memory to set. - @param Size Number of bytes to set + @param Buffer Pointer to the target buffer to fill with zeros. + @param Length Number of bytes in Buffer to fill with zeros. - @return Buffer + @return Buffer. **/ VOID * EFIAPI ZeroMem ( - OUT VOID *Buffer, - IN UINTN Length + OUT VOID *Buffer, + IN UINTN Length ); /** - Compares two memory buffers of a given length. + Compares the contents of two buffers. - This function compares Length bytes of SourceBuffer to Length bytes of - DestinationBuffer. 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. + This function compares Length bytes of SourceBuffer to Length bytes of DestinationBuffer. + 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(). - If DestinationBuffer is NULL and Length > 0, then ASSERT(). - If 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 First memory buffer - @param SourceBuffer Second memory buffer - @param Length Length of DestinationBuffer and SourceBuffer memory - regions to compare + @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. - @retval 0 if DestinationBuffer == SourceBuffer - @retval Non-zero if DestinationBuffer != SourceBuffer + @return 0 All Length bytes of the two buffers are identical. + @retval Non-zero The first mismatched byte in SourceBuffer subtracted from the first + mismatched byte in DestinationBuffer. **/ INTN EFIAPI CompareMem ( - IN CONST VOID *DestinationBuffer, - IN CONST VOID *SourceBuffer, - IN UINTN Length + IN CONST VOID *DestinationBuffer, + IN CONST VOID *SourceBuffer, + IN UINTN Length ); /** - Scans a target buffer for an 8-bit value, and returns a pointer to the - matching 8-bit value in the target buffer. + Scans a target buffer for an 8-bit value, and returns a pointer to the matching 8-bit 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 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. + This function searches target the buffer specified by Buffer and Length from the lowest + 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 Buffer is NULL, 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 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. - - @return Pointer to the first occurrence or NULL if not found. - @retval NULL if Length == 0 or Value was not found. + @return A pointer to the matching byte in the target buffer or NULL otherwise. **/ VOID * EFIAPI ScanMem8 ( - IN CONST VOID *Buffer, - IN UINTN Length, - IN UINT8 Value + IN CONST VOID *Buffer, + IN UINTN Length, + IN UINT8 Value ); /** - Scans a target buffer for a 16-bit value, and returns a pointer to the - matching 16-bit value in the target buffer. - - This function searches target the buffer specified by Buffer and Length from - the lowest address to the highest address at 16-bit increments for a 16-bit - value that matches Value. If a match is found, then a pointer to the matching - value in the target buffer is returned. If no match is found, then NULL is - returned. If Length is 0, then NULL is returned. + Scans a target buffer for a 16-bit value, and returns a pointer to the matching 16-bit value + in the target buffer. - If Buffer is NULL, then ASSERT(). + This function searches target the buffer specified by Buffer and Length from the lowest + 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 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 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. - @return Pointer to the first occurrence. - @retval NULL if Length == 0 or Value was not found. + @return A pointer to the matching byte in the target buffer or NULL otherwise. **/ VOID * EFIAPI ScanMem16 ( - IN CONST VOID *Buffer, - IN UINTN Length, - IN UINT16 Value + IN CONST VOID *Buffer, + IN UINTN Length, + IN UINT16 Value ); /** - Scans a target buffer for a 32-bit value, and returns a pointer to the - matching 32-bit value in the target buffer. - - This function searches target the buffer specified by Buffer and Length from - the lowest address to the highest address at 32-bit increments for a 32-bit - value that matches Value. If a match is found, then a pointer to the matching - value in the target buffer is returned. If no match is found, then NULL is - returned. If Length is 0, then NULL is returned. + Scans a target buffer for a 32-bit value, and returns a pointer to the matching 32-bit value + in the target buffer. - If Buffer is NULL, then ASSERT(). + This function searches target the buffer specified by Buffer and Length from the lowest + 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 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 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. - @return Pointer to the first occurrence or NULL if not found. - @retval NULL if Length == 0 or Value was not found. + @return A pointer to the matching byte in the target buffer or NULL otherwise. **/ VOID * EFIAPI ScanMem32 ( - IN CONST VOID *Buffer, - IN UINTN Length, - IN UINT32 Value + IN CONST VOID *Buffer, + IN UINTN Length, + IN UINT32 Value ); /** - Scans a target buffer for a 64-bit value, and returns a pointer to the - matching 64-bit value in the target buffer. - - This function searches target the buffer specified by Buffer and Length from - the lowest address to the highest address at 64-bit increments for a 64-bit - value that matches Value. If a match is found, then a pointer to the matching - value in the target buffer is returned. If no match is found, then NULL is - returned. If Length is 0, then NULL is returned. + Scans a target buffer for a 64-bit value, and returns a pointer to the matching 64-bit value + in the target buffer. - If Buffer is NULL, then ASSERT(). + This function searches target the buffer specified by Buffer and Length from the lowest + 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 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 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. - @return Pointer to the first occurrence or NULL if not found. - @retval NULL if Length == 0 or Value was not found. + @return A pointer to the matching byte in the target buffer or NULL otherwise. **/ VOID * EFIAPI ScanMem64 ( - IN CONST VOID *Buffer, - IN UINTN Length, - IN UINT64 Value + IN CONST VOID *Buffer, + IN UINTN Length, + IN UINT64 Value ); /** - This function 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. + 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 Pointer to the destination GUID. + @param SourceGuid Pointer to the source GUID. - @return DestinationGuid + @return DestinationGuid. **/ GUID * EFIAPI CopyGuid ( - OUT GUID *DestinationGuid, - IN CONST GUID *SourceGuid + OUT GUID *DestinationGuid, + IN CONST GUID *SourceGuid ); /** - Compares two GUIDs - - 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. + Compares two GUIDs. + 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(). - @param Guid1 guid to compare - @param Guid2 guid to compare + @param Guid1 A pointer to a 128 bit GUID. + @param Guid2 A pointer to a 128 bit GUID. - @retval TRUE if Guid1 == Guid2 - @retval FALSE if Guid1 != Guid2 + @retval TRUE Guid1 and Guid2 are identical. + @retval FALSE Guid1 and Guid2 are not identical. **/ BOOLEAN EFIAPI CompareGuid ( - IN CONST GUID *Guid1, - IN CONST GUID *Guid2 + IN CONST GUID *Guid1, + IN CONST GUID *Guid2 ); /** @@ -368,28 +348,27 @@ CompareGuid ( in the target buffer. This function searches target the buffer specified by Buffer and Length from - the lowest address to the highest address at 128-bit increments for the - 128-bit 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 Buffer is NULL, then ASSERT(). + the lowest address to the highest address at 128-bit increments for the 128-bit + 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 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 Guid Value to search for in the target buffer. - @return Pointer to the first occurrence. - @retval NULL if Length == 0 or Guid was not found. + @return A pointer to the matching Guid in the target buffer or NULL otherwise. + **/ VOID * EFIAPI ScanGuid ( - IN CONST VOID *Buffer, - IN UINTN Length, - IN CONST GUID *Guid + IN CONST VOID *Buffer, + IN UINTN Length, + IN CONST GUID *Guid ); #endif