OldMdePkg/Include/Protocol/Decompress.h

   1 /** @file
   2   The Decompress Protocol Interface
   3
   4   Copyright (c) 2006, Intel Corporation
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13   Module Name:  Decompress.h
  14
  15 **/
  16
  17 #ifndef __DECOMPRESS_H__
  18 #define __DECOMPRESS_H__
  19
  20 #define EFI_DECOMPRESS_PROTOCOL_GUID \
  21   { \
  22     0xd8117cfe, 0x94a6, 0x11d4, {0x9a, 0x3a, 0x0, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \
  23   }
  24
  25 typedef struct _EFI_DECOMPRESS_PROTOCOL  EFI_DECOMPRESS_PROTOCOL;
  26
  27 /**
  28   The GetInfo() function retrieves the size of the uncompressed buffer
  29   and the temporary scratch buffer required to decompress the buffer
  30   specified by Source and SourceSize.  If the size of the uncompressed
  31   buffer or the size of the scratch buffer cannot be determined from
  32   the compressed data specified by Source and SourceData, then
  33   EFI_INVALID_PARAMETER is returned.  Otherwise, the size of the uncompressed
  34   buffer is returned in DestinationSize, the size of the scratch buffer is
  35   returned in ScratchSize, and EFI_SUCCESS is returned.
  36
  37   The GetInfo() function does not have scratch buffer available to perform
  38   a thorough checking of the validity of the source data. It just retrieves
  39   the 'Original Size' field from the beginning bytes of the source data and
  40   output it as DestinationSize.  And ScratchSize is specific to the decompression
  41   implementation.
  42
  43   @param  This            The protocol instance pointer
  44   @param  Source          The source buffer containing the compressed data.
  45   @param  SourceSize      The size, in bytes, of source buffer.
  46   @param  DestinationSize A pointer to the size, in bytes, of the uncompressed buffer
  47                           that will be generated when the compressed buffer specified
  48                           by Source and SourceSize is decompressed.
  49   @param  ScratchSize     A pointer to the size, in bytes, of the scratch buffer that
  50                           is required to decompress the compressed buffer specified by
  51                           Source and SourceSize.
  52
  53   @retval  EFI_SUCCESS           The size of the uncompressed data was returned in DestinationSize
  54                                  and the size of the scratch buffer was returned in ScratchSize.
  55   @retval  EFI_INVALID_PARAMETER The size of the uncompressed data or the size of the scratch
  56                                  buffer cannot be determined from the compressed data specified by
  57                                  Source and SourceData.
  58
  59 **/
  60 typedef
  61 EFI_STATUS
  62 (EFIAPI *EFI_DECOMPRESS_GET_INFO) (
  63   IN EFI_DECOMPRESS_PROTOCOL            *This,
  64   IN   VOID                             *Source,
  65   IN   UINT32                           SourceSize,
  66   OUT  UINT32                           *DestinationSize,
  67   OUT  UINT32                           *ScratchSize
  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 The source buffer specified by Source and SourceSize is
  99                                 corrupted (not in a valid compressed format).
 100
 101 **/
 102 typedef
 103 EFI_STATUS
 104 (EFIAPI *EFI_DECOMPRESS_DECOMPRESS) (
 105   IN EFI_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_DECOMPRESS_PROTOCOL {
 115   EFI_DECOMPRESS_GET_INFO   GetInfo;
 116   EFI_DECOMPRESS_DECOMPRESS Decompress;
 117 };
 118
 119 extern EFI_GUID gEfiDecompressProtocolGuid;
 120
 121 #endif