EdkCompatibilityPkg/Foundation/Protocol/CustomizedDecompress/CustomizedDecompress.h

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