/** @file\r
- Return UEFI Decompress Protocol \r
+ Provides services to decompress a buffer using the UEFI Decompress algorithm.\r
\r
- Copyright (c) 2006, Intel Corporation \r
- All rights reserved. This program and the accompanying materials \r
- are licensed and made available under the terms and conditions of the BSD License \r
- which accompanies this distribution. The full text of the license may be found at \r
- http://opensource.org/licenses/bsd-license.php \r
+ The UEFI Decompress Library enables the decompression of objects that\r
+ were compressed using the UEFI compression scheme. The UEFI Decompress\r
+ Library is independent of environment and requires the caller to allocate\r
+ all required memory buffers.\r
\r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
-\r
- Module Name: UefiDecompressLib.h\r
+Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
+SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef __UEFI_DECPOMPRESS_LIB_H__\r
#define __UEFI_DECPOMPRESS_LIB_H__\r
\r
+/**\r
+ Given a compressed source buffer, this function retrieves the size of\r
+ the uncompressed buffer and the size of the scratch buffer required\r
+ to decompress the compressed source buffer.\r
+\r
+ Retrieves the size of the uncompressed buffer and the temporary scratch buffer\r
+ required to decompress the buffer specified by Source and SourceSize.\r
+ If the size of the uncompressed buffer or the size of the scratch buffer cannot\r
+ be determined from the compressed data specified by Source and SourceData,\r
+ then RETURN_INVALID_PARAMETER is returned. Otherwise, the size of the uncompressed\r
+ buffer is returned in DestinationSize, the size of the scratch buffer is returned\r
+ in ScratchSize, and RETURN_SUCCESS is returned.\r
+ This function does not have scratch buffer available to perform a thorough\r
+ checking of the validity of the source data. It just retrieves the "Original Size"\r
+ field from the beginning bytes of the source data and output it as DestinationSize.\r
+ And ScratchSize is specific to the decompression implementation.\r
+\r
+ If Source is NULL, then ASSERT().\r
+ If DestinationSize is NULL, then ASSERT().\r
+ If ScratchSize is NULL, then ASSERT().\r
+\r
+ @param Source The source buffer containing the compressed data.\r
+ @param SourceSize The size, in bytes, of the source buffer.\r
+ @param DestinationSize A pointer to the size, in bytes, of the uncompressed buffer\r
+ that will be generated when the compressed buffer specified\r
+ by Source and SourceSize is decompressed.\r
+ @param ScratchSize A pointer to the size, in bytes, of the scratch buffer that\r
+ is required to decompress the compressed buffer specified\r
+ by Source and SourceSize.\r
+\r
+ @retval RETURN_SUCCESS The size of the uncompressed data was returned\r
+ in DestinationSize and the size of the scratch\r
+ buffer was returned in ScratchSize.\r
+ @retval RETURN_INVALID_PARAMETER\r
+ The size of the uncompressed data or the size of\r
+ the scratch buffer cannot be determined from\r
+ the compressed data specified by Source\r
+ and SourceSize.\r
+**/\r
RETURN_STATUS\r
EFIAPI\r
UefiDecompressGetInfo (\r
OUT UINT32 *ScratchSize\r
);\r
\r
+/**\r
+ Decompresses a compressed source buffer.\r
+\r
+ Extracts decompressed data to its original form.\r
+ This function is designed so that the decompression algorithm can be implemented\r
+ without using any memory services. As a result, this function is not allowed to\r
+ call any memory allocation services in its implementation. It is the caller's\r
+ responsibility to allocate and free the Destination and Scratch buffers.\r
+ If the compressed source data specified by Source is successfully decompressed\r
+ into Destination, then RETURN_SUCCESS is returned. If the compressed source data\r
+ specified by Source is not in a valid compressed data format,\r
+ then RETURN_INVALID_PARAMETER is returned.\r
+\r
+ If Source is NULL, then ASSERT().\r
+ If Destination is NULL, then ASSERT().\r
+ If the required scratch buffer size > 0 and Scratch is NULL, then ASSERT().\r
+\r
+ @param Source The source buffer containing the compressed data.\r
+ @param Destination The destination buffer to store the decompressed data\r
+ @param Scratch A temporary scratch buffer that is used to perform the decompression.\r
+ This is an optional parameter that may be NULL if the\r
+ required scratch buffer size is 0.\r
+\r
+ @retval RETURN_SUCCESS Decompression completed successfully, and\r
+ the uncompressed buffer is returned in Destination.\r
+ @retval RETURN_INVALID_PARAMETER\r
+ The source buffer specified by Source is corrupted\r
+ (not in a valid compressed format).\r
+**/\r
RETURN_STATUS\r
EFIAPI\r
UefiDecompress (\r
IN CONST VOID *Source,\r
IN OUT VOID *Destination,\r
- IN OUT VOID *Scratch\r
+ IN OUT VOID *Scratch OPTIONAL\r
);\r
\r
#endif\r
projects / mirror_edk2.git / blobdiff