EdkModulePkg/Include/Protocol/EdkDecompress.h

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