MdeModulePkg/Include/Protocol/CustomizedDecompress.h

   1 /** @file
   2
   3   The user Customized Decompress Protocol Interface
   4
   5 Copyright (c) 2006 - 2008, Intel Corporation
   6 All rights reserved. This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef __CUSTOMIZED_DECOMPRESS_H__
  17 #define __CUSTOMIZED_DECOMPRESS_H__
  18
  19 #define EFI_CUSTOMIZED_DECOMPRESS_PROTOCOL_GUID \
  20   { 0x9a44198e, 0xa4a2, 0x44e6, {0x8a, 0x1f, 0x39, 0xbe, 0xfd, 0xac, 0x89, 0x6f } }
  21
  22 typedef struct _EFI_CUSTOMIZED_DECOMPRESS_PROTOCOL    EFI_CUSTOMIZED_DECOMPRESS_PROTOCOL;
  23
  24 /**
  25
  26   The GetInfo() function retrieves the size of the uncompressed buffer
  27   and the temporary scratch buffer required to decompress the buffer
  28   specified by Source and SourceSize.  If the size of the uncompressed
  29   buffer or the size of the scratch buffer cannot be determined from
  30   the compressed data specified by Source and SourceData, then
  31   EFI_INVALID_PARAMETER is returned.  Otherwise, the size of the uncompressed
  32   buffer is returned in DestinationSize, the size of the scratch buffer is
  33   returned in ScratchSize, and EFI_SUCCESS is returned.
  34
  35   The GetInfo() function does not have scratch buffer available to perform
  36   a thorough checking of the validity of the source data. It just retrieves
  37   the 'Original Size' field from the beginning bytes of the source data and
  38   output it as DestinationSize.  And ScratchSize is specific to the decompression
  39   implementation.
  40
  41   @param  This              The protocol instance pointer
  42   @param  Source            The source buffer containing the compressed data.
  43   @param  SourceSize        The size, in bytes, of source buffer.
  44   @param  DestinationSize   A pointer to the size, in bytes, of the uncompressed buffer
  45                             that will be generated when the compressed buffer specified
  46                             by Source and SourceSize is decompressed.
  47   @param  ScratchSize       A pointer to the size, in bytes, of the scratch buffer that
  48                             is required to decompress the compressed buffer specified by
  49                             Source and SourceSize.
  50
  51   @retval EFI_SUCCESS       The size of the uncompressed data was returned in DestinationSize
  52                             and the size of the scratch buffer was returned in ScratchSize.
  53   @retval EFI_INVALID_PARAMETER
  54                             The size of the uncompressed data or the size of the scratch
  55                             buffer cannot be determined from the compressed data specified by
  56                             Source and SourceData.
  57
  58 --*/
  59 typedef
  60 EFI_STATUS
  61 (EFIAPI *EFI_CUSTOMIZED_DECOMPRESS_GET_INFO) (
  62   IN EFI_CUSTOMIZED_DECOMPRESS_PROTOCOL       *This,
  63   IN   VOID                                   *Source,
  64   IN   UINT32                                 SourceSize,
  65   OUT  UINT32                                 *DestinationSize,
  66   OUT  UINT32                                 *ScratchSize
  67   );
  68
  69 /**
  70
  71   The Decompress() function extracts decompressed data to its original form.
  72
  73   This protocol is designed so that the decompression algorithm can be
  74   implemented without using any memory services.  As a result, the
  75   Decompress() function is not allowed to call AllocatePool() or
  76   AllocatePages() in its implementation.  It is the caller's responsibility
  77   to allocate and free the Destination and Scratch buffers.
  78
  79   If the compressed source data specified by Source and SourceSize is
  80   sucessfully decompressed into Destination, then EFI_SUCCESS is returned.
  81   If the compressed source data specified by Source and SourceSize is not in
  82   a valid compressed data format, then EFI_INVALID_PARAMETER is returned.
  83
  84   @param  This              The protocol instance pointer
  85   @param  Source            The source buffer containing the compressed data.
  86   @param  SourceSize        The size of source data.
  87   @param  Destination       On output, the destination buffer that contains
  88                             the uncompressed data.
  89   @param  DestinationSize   The size of destination buffer. The size of destination
  90                             buffer needed is obtained from GetInfo().
  91   @param  Scratch           A temporary scratch buffer that is used to perform the
  92                             decompression.
  93   @param  ScratchSize       The size of scratch buffer. The size of scratch buffer needed
  94                             is obtained from GetInfo().
  95
  96   @retval  EFI_SUCCESS     Decompression completed successfully, and the uncompressed
  97                            buffer is returned in Destination.
  98   @retval  EFI_INVALID_PARAMETER
  99                            The source buffer specified by Source and SourceSize is
 100                            corrupted (not in a valid compressed format).
 101 **/
 102 typedef
 103 EFI_STATUS
 104 (EFIAPI *EFI_CUSTOMIZED_DECOMPRESS_DECOMPRESS) (
 105   IN EFI_CUSTOMIZED_DECOMPRESS_PROTOCOL         *This,
 106   IN     VOID*                                  Source,
 107   IN     UINT32                                 SourceSize,
 108   IN OUT VOID*                                  Destination,
 109   IN     UINT32                                 DestinationSize,
 110   IN OUT VOID*                                  Scratch,
 111   IN     UINT32                                 ScratchSize
 112   );
 113
 114 struct _EFI_CUSTOMIZED_DECOMPRESS_PROTOCOL {
 115   EFI_CUSTOMIZED_DECOMPRESS_GET_INFO    GetInfo;
 116   EFI_CUSTOMIZED_DECOMPRESS_DECOMPRESS  Decompress;
 117 };
 118
 119 extern EFI_GUID gEfiCustomizedDecompressProtocolGuid;
 120
 121 #endif