MdePkg/Library/BaseUefiDecompressLib/BaseUefiDecompressLibInternals.h

   1 /** @file
   2   Internal data structure defintions for Base UEFI Decompress Library.
   3
   4   Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef __BASE_UEFI_DECOMPRESS_LIB_INTERNALS_H__
  10 #define __BASE_UEFI_DECOMPRESS_LIB_INTERNALS_H__
  11
  12 #include <Base.h>
  13 #include <Library/BaseLib.h>
  14 #include <Library/DebugLib.h>
  15 #include <Library/BaseMemoryLib.h>
  16 #include <Library/UefiDecompressLib.h>
  17 //
  18 // Decompression algorithm begins here
  19 //
  20 #define BITBUFSIZ  32
  21 #define MAXMATCH   256
  22 #define THRESHOLD  3
  23 #define CODE_BIT   16
  24 #define BAD_TABLE  - 1
  25
  26 //
  27 // C: Char&Len Set; P: Position Set; T: exTra Set
  28 //
  29 #define NC       (0xff + MAXMATCH + 2 - THRESHOLD)
  30 #define CBIT     9
  31 #define MAXPBIT  5
  32 #define TBIT     5
  33 #define MAXNP    ((1U << MAXPBIT) - 1)
  34 #define NT       (CODE_BIT + 3)
  35 #if NT > MAXNP
  36 #define NPT  NT
  37 #else
  38 #define NPT  MAXNP
  39 #endif
  40
  41 typedef struct {
  42   UINT8     *mSrcBase; // The starting address of compressed data
  43   UINT8     *mDstBase; // The starting address of decompressed data
  44   UINT32    mOutBuf;
  45   UINT32    mInBuf;
  46
  47   UINT16    mBitCount;
  48   UINT32    mBitBuf;
  49   UINT32    mSubBitBuf;
  50   UINT16    mBlockSize;
  51   UINT32    mCompSize;
  52   UINT32    mOrigSize;
  53
  54   UINT16    mBadTableFlag;
  55
  56   UINT16    mLeft[2 * NC - 1];
  57   UINT16    mRight[2 * NC - 1];
  58   UINT8     mCLen[NC];
  59   UINT8     mPTLen[NPT];
  60   UINT16    mCTable[4096];
  61   UINT16    mPTTable[256];
  62
  63   ///
  64   /// The length of the field 'Position Set Code Length Array Size' in Block Header.
  65   /// For UEFI 2.0 de/compression algorithm, mPBit = 4.
  66   /// For Tiano de/compression algorithm, mPBit = 5.
  67   ///
  68   UINT8     mPBit;
  69 } SCRATCH_DATA;
  70
  71 /**
  72   Read NumOfBit of bits from source into mBitBuf.
  73
  74   Shift mBitBuf NumOfBits left. Read in NumOfBits of bits from source.
  75
  76   @param  Sd        The global scratch data.
  77   @param  NumOfBits The number of bits to shift and read.
  78
  79 **/
  80 VOID
  81 FillBuf (
  82   IN  SCRATCH_DATA  *Sd,
  83   IN  UINT16        NumOfBits
  84   );
  85
  86 /**
  87   Get NumOfBits of bits out from mBitBuf.
  88
  89   Get NumOfBits of bits out from mBitBuf. Fill mBitBuf with subsequent
  90   NumOfBits of bits from source. Returns NumOfBits of bits that are
  91   popped out.
  92
  93   @param  Sd        The global scratch data.
  94   @param  NumOfBits The number of bits to pop and read.
  95
  96   @return The bits that are popped out.
  97
  98 **/
  99 UINT32
 100 GetBits (
 101   IN  SCRATCH_DATA  *Sd,
 102   IN  UINT16        NumOfBits
 103   );
 104
 105 /**
 106   Creates Huffman Code mapping table according to code length array.
 107
 108   Creates Huffman Code mapping table for Extra Set, Char&Len Set
 109   and Position Set according to code length array.
 110   If TableBits > 16, then ASSERT ().
 111
 112   @param  Sd        The global scratch data.
 113   @param  NumOfChar The number of symbols in the symbol set.
 114   @param  BitLen    Code length array.
 115   @param  TableBits The width of the mapping table.
 116   @param  Table     The table to be created.
 117
 118   @retval  0 OK.
 119   @retval  BAD_TABLE The table is corrupted.
 120
 121 **/
 122 UINT16
 123 MakeTable (
 124   IN  SCRATCH_DATA  *Sd,
 125   IN  UINT16        NumOfChar,
 126   IN  UINT8         *BitLen,
 127   IN  UINT16        TableBits,
 128   OUT UINT16        *Table
 129   );
 130
 131 /**
 132   Decodes a position value.
 133
 134   Get a position value according to Position Huffman Table.
 135
 136   @param  Sd The global scratch data.
 137
 138   @return The position value decoded.
 139
 140 **/
 141 UINT32
 142 DecodeP (
 143   IN  SCRATCH_DATA  *Sd
 144   );
 145
 146 /**
 147   Reads code lengths for the Extra Set or the Position Set.
 148
 149   Read in the Extra Set or Position Set Length Array, then
 150   generate the Huffman code mapping for them.
 151
 152   @param  Sd      The global scratch data.
 153   @param  nn      The number of symbols.
 154   @param  nbit    The number of bits needed to represent nn.
 155   @param  Special The special symbol that needs to be taken care of.
 156
 157   @retval  0 OK.
 158   @retval  BAD_TABLE Table is corrupted.
 159
 160 **/
 161 UINT16
 162 ReadPTLen (
 163   IN  SCRATCH_DATA  *Sd,
 164   IN  UINT16        nn,
 165   IN  UINT16        nbit,
 166   IN  UINT16        Special
 167   );
 168
 169 /**
 170   Reads code lengths for Char&Len Set.
 171
 172   Read in and decode the Char&Len Set Code Length Array, then
 173   generate the Huffman Code mapping table for the Char&Len Set.
 174
 175   @param  Sd The global scratch data.
 176
 177 **/
 178 VOID
 179 ReadCLen (
 180   SCRATCH_DATA  *Sd
 181   );
 182
 183 /**
 184   Decode a character/length value.
 185
 186   Read one value from mBitBuf, Get one code from mBitBuf. If it is at block boundary, generates
 187   Huffman code mapping table for Extra Set, Code&Len Set and
 188   Position Set.
 189
 190   @param  Sd The global scratch data.
 191
 192   @return The value decoded.
 193
 194 **/
 195 UINT16
 196 DecodeC (
 197   SCRATCH_DATA  *Sd
 198   );
 199
 200 /**
 201   Decode the source data and put the resulting data into the destination buffer.
 202
 203   @param  Sd The global scratch data.
 204
 205 **/
 206 VOID
 207 Decode (
 208   SCRATCH_DATA  *Sd
 209   );
 210
 211 /**
 212   Decompresses a compressed source buffer.
 213
 214   Extracts decompressed data to its original form.
 215   This function is designed so that the decompression algorithm can be implemented
 216   without using any memory services.  As a result, this function is not allowed to
 217   call any memory allocation services in its implementation.  It is the caller's
 218   responsibility to allocate and free the Destination and Scratch buffers.
 219   If the compressed source data specified by Source is successfully decompressed
 220   into Destination, then RETURN_SUCCESS is returned.  If the compressed source data
 221   specified by Source is not in a valid compressed data format,
 222   then RETURN_INVALID_PARAMETER is returned.
 223
 224   If Source is NULL, then ASSERT().
 225   If Destination is NULL, then ASSERT().
 226   If the required scratch buffer size > 0 and Scratch is NULL, then ASSERT().
 227
 228   @param  Source      The source buffer containing the compressed data.
 229   @param  Destination The destination buffer to store the decompressed data.
 230   @param  Scratch     A temporary scratch buffer that is used to perform the decompression.
 231                       This is an optional parameter that may be NULL if the
 232                       required scratch buffer size is 0.
 233   @param  Version     1 for UEFI Decompress algoruthm, 2 for Tiano Decompess algorithm.
 234
 235   @retval  RETURN_SUCCESS Decompression completed successfully, and
 236                           the uncompressed buffer is returned in Destination.
 237   @retval  RETURN_INVALID_PARAMETER
 238                           The source buffer specified by Source is corrupted
 239                           (not in a valid compressed format).
 240 **/
 241 RETURN_STATUS
 242 UefiTianoDecompress (
 243   IN CONST VOID  *Source,
 244   IN OUT VOID    *Destination,
 245   IN OUT VOID    *Scratch,
 246   IN UINT32      Version
 247   );
 248
 249 #endif