EdkCompatibilityPkg/Foundation/Efi/Protocol/Decompress/Decompress.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   Decompress.h
  15
  16 Abstract:
  17
  18   The Decompress Protocol Interface
  19
  20 --*/
  21
  22 #ifndef _DECOMPRESS_H_
  23 #define _DECOMPRESS_H_
  24
  25 #define EFI_DECOMPRESS_PROTOCOL_GUID \
  26   { \
  27     0xd8117cfe, 0x94a6, 0x11d4, 0x9a, 0x3a, 0x0, 0x90, 0x27, 0x3f, 0xc1, 0x4d \
  28   }
  29
  30 EFI_FORWARD_DECLARATION (EFI_DECOMPRESS_PROTOCOL);
  31
  32 typedef
  33 EFI_STATUS
  34 (EFIAPI *EFI_DECOMPRESS_GET_INFO) (
  35   IN EFI_DECOMPRESS_PROTOCOL            * This,
  36   IN   VOID                             *Source,
  37   IN   UINT32                           SourceSize,
  38   OUT  UINT32                           *DestinationSize,
  39   OUT  UINT32                           *ScratchSize
  40   );
  41
  42 /*++
  43
  44 Routine Description:
  45
  46   The GetInfo() function retrieves the size of the uncompressed buffer
  47   and the temporary scratch buffer required to decompress the buffer
  48   specified by Source and SourceSize.  If the size of the uncompressed
  49   buffer or the size of the scratch buffer cannot be determined from
  50   the compressed data specified by Source and SourceData, then
  51   EFI_INVALID_PARAMETER is returned.  Otherwise, the size of the uncompressed
  52   buffer is returned in DestinationSize, the size of the scratch buffer is
  53   returned in ScratchSize, and EFI_SUCCESS is returned.
  54
  55   The GetInfo() function does not have scratch buffer available to perform
  56   a thorough checking of the validity of the source data. It just retrieves
  57   the 'Original Size' field from the beginning bytes of the source data and
  58   output it as DestinationSize.  And ScratchSize is specific to the decompression
  59   implementation.
  60
  61 Arguments:
  62
  63   This            - The protocol instance pointer
  64   Source          - The source buffer containing the compressed data.
  65   SourceSize      - The size, in bytes, of source buffer.
  66   DestinationSize - A pointer to the size, in bytes, of the uncompressed buffer
  67                     that will be generated when the compressed buffer specified
  68                     by Source and SourceSize is decompressed.
  69   ScratchSize     - A pointer to the size, in bytes, of the scratch buffer that
  70                     is required to decompress the compressed buffer specified by
  71                     Source and SourceSize.
  72
  73 Returns:
  74   EFI_SUCCESS     - The size of the uncompressed data was returned in DestinationSize
  75                     and the size of the scratch buffer was returned in ScratchSize.
  76   EFI_INVALID_PARAMETER - The size of the uncompressed data or the size of the scratch
  77                   buffer cannot be determined from the compressed data specified by
  78                   Source and SourceData.
  79
  80 --*/
  81 typedef
  82 EFI_STATUS
  83 (EFIAPI *EFI_DECOMPRESS_DECOMPRESS) (
  84   IN EFI_DECOMPRESS_PROTOCOL              * This,
  85   IN     VOID                             *Source,
  86   IN     UINT32                           SourceSize,
  87   IN OUT VOID                             *Destination,
  88   IN     UINT32                           DestinationSize,
  89   IN OUT VOID                             *Scratch,
  90   IN     UINT32                           ScratchSize
  91   );
  92
  93 /*++
  94
  95 Routine Description:
  96
  97   The Decompress() function extracts decompressed data to its original form.
  98
  99   This protocol is designed so that the decompression algorithm can be
 100   implemented without using any memory services.  As a result, the
 101   Decompress() function is not allowed to call AllocatePool() or
 102   AllocatePages() in its implementation.  It is the caller's responsibility
 103   to allocate and free the Destination and Scratch buffers.
 104
 105   If the compressed source data specified by Source and SourceSize is
 106   sucessfully decompressed into Destination, then EFI_SUCCESS is returned.
 107   If the compressed source data specified by Source and SourceSize is not in
 108   a valid compressed data format, then EFI_INVALID_PARAMETER is returned.
 109
 110 Arguments:
 111
 112   This            - The protocol instance pointer
 113   Source          - The source buffer containing the compressed data.
 114   SourceSize      - The size of source data.
 115   Destination     - On output, the destination buffer that contains
 116                     the uncompressed data.
 117   DestinationSize - The size of destination buffer. The size of destination
 118                     buffer needed is obtained from GetInfo().
 119   Scratch         - A temporary scratch buffer that is used to perform the
 120                     decompression.
 121   ScratchSize     - The size of scratch buffer. The size of scratch buffer needed
 122                     is obtained from GetInfo().
 123
 124 Returns:
 125
 126   EFI_SUCCESS     - Decompression completed successfully, and the uncompressed
 127                     buffer is returned in Destination.
 128   EFI_INVALID_PARAMETER
 129                   - The source buffer specified by Source and SourceSize is
 130                     corrupted (not in a valid compressed format).
 131
 132 --*/
 133 typedef struct _EFI_DECOMPRESS_PROTOCOL {
 134   EFI_DECOMPRESS_GET_INFO   GetInfo;
 135   EFI_DECOMPRESS_DECOMPRESS Decompress;
 136 } EFI_DECOMPRESS_PROTOCOL;
 137
 138 extern EFI_GUID gEfiDecompressProtocolGuid;
 139
 140 #endif