deps/libchdr/deps/zstd-1.5.6/lib/common/fse.h

   1 /* ******************************************************************
   2  * FSE : Finite State Entropy codec
   3  * Public Prototypes declaration
   4  * Copyright (c) Meta Platforms, Inc. and affiliates.
   5  *
   6  * You can contact the author at :
   7  * - Source repository : https://github.com/Cyan4973/FiniteStateEntropy
   8  *
   9  * This source code is licensed under both the BSD-style license (found in the
  10  * LICENSE file in the root directory of this source tree) and the GPLv2 (found
  11  * in the COPYING file in the root directory of this source tree).
  12  * You may select, at your option, one of the above-listed licenses.
  13 ****************************************************************** */
  14
  15 #if defined (__cplusplus)
  16 extern "C" {
  17 #endif
  18
  19 #ifndef FSE_H
  20 #define FSE_H
  21
  22
  23 /*-*****************************************
  24 *  Dependencies
  25 ******************************************/
  26 #include "zstd_deps.h"    /* size_t, ptrdiff_t */
  27
  28
  29 /*-*****************************************
  30 *  FSE_PUBLIC_API : control library symbols visibility
  31 ******************************************/
  32 #if defined(FSE_DLL_EXPORT) && (FSE_DLL_EXPORT==1) && defined(__GNUC__) && (__GNUC__ >= 4)
  33 #  define FSE_PUBLIC_API __attribute__ ((visibility ("default")))
  34 #elif defined(FSE_DLL_EXPORT) && (FSE_DLL_EXPORT==1)   /* Visual expected */
  35 #  define FSE_PUBLIC_API __declspec(dllexport)
  36 #elif defined(FSE_DLL_IMPORT) && (FSE_DLL_IMPORT==1)
  37 #  define FSE_PUBLIC_API __declspec(dllimport) /* It isn't required but allows to generate better code, saving a function pointer load from the IAT and an indirect jump.*/
  38 #else
  39 #  define FSE_PUBLIC_API
  40 #endif
  41
  42 /*------   Version   ------*/
  43 #define FSE_VERSION_MAJOR    0
  44 #define FSE_VERSION_MINOR    9
  45 #define FSE_VERSION_RELEASE  0
  46
  47 #define FSE_LIB_VERSION FSE_VERSION_MAJOR.FSE_VERSION_MINOR.FSE_VERSION_RELEASE
  48 #define FSE_QUOTE(str) #str
  49 #define FSE_EXPAND_AND_QUOTE(str) FSE_QUOTE(str)
  50 #define FSE_VERSION_STRING FSE_EXPAND_AND_QUOTE(FSE_LIB_VERSION)
  51
  52 #define FSE_VERSION_NUMBER  (FSE_VERSION_MAJOR *100*100 + FSE_VERSION_MINOR *100 + FSE_VERSION_RELEASE)
  53 FSE_PUBLIC_API unsigned FSE_versionNumber(void);   /**< library version number; to be used when checking dll version */
  54
  55
  56 /*-*****************************************
  57 *  Tool functions
  58 ******************************************/
  59 FSE_PUBLIC_API size_t FSE_compressBound(size_t size);       /* maximum compressed size */
  60
  61 /* Error Management */
  62 FSE_PUBLIC_API unsigned    FSE_isError(size_t code);        /* tells if a return value is an error code */
  63 FSE_PUBLIC_API const char* FSE_getErrorName(size_t code);   /* provides error code string (useful for debugging) */
  64
  65
  66 /*-*****************************************
  67 *  FSE detailed API
  68 ******************************************/
  69 /*!
  70 FSE_compress() does the following:
  71 1. count symbol occurrence from source[] into table count[] (see hist.h)
  72 2. normalize counters so that sum(count[]) == Power_of_2 (2^tableLog)
  73 3. save normalized counters to memory buffer using writeNCount()
  74 4. build encoding table 'CTable' from normalized counters
  75 5. encode the data stream using encoding table 'CTable'
  76
  77 FSE_decompress() does the following:
  78 1. read normalized counters with readNCount()
  79 2. build decoding table 'DTable' from normalized counters
  80 3. decode the data stream using decoding table 'DTable'
  81
  82 The following API allows targeting specific sub-functions for advanced tasks.
  83 For example, it's possible to compress several blocks using the same 'CTable',
  84 or to save and provide normalized distribution using external method.
  85 */
  86
  87 /* *** COMPRESSION *** */
  88
  89 /*! FSE_optimalTableLog():
  90     dynamically downsize 'tableLog' when conditions are met.
  91     It saves CPU time, by using smaller tables, while preserving or even improving compression ratio.
  92     @return : recommended tableLog (necessarily <= 'maxTableLog') */
  93 FSE_PUBLIC_API unsigned FSE_optimalTableLog(unsigned maxTableLog, size_t srcSize, unsigned maxSymbolValue);
  94
  95 /*! FSE_normalizeCount():
  96     normalize counts so that sum(count[]) == Power_of_2 (2^tableLog)
  97     'normalizedCounter' is a table of short, of minimum size (maxSymbolValue+1).
  98     useLowProbCount is a boolean parameter which trades off compressed size for
  99     faster header decoding. When it is set to 1, the compressed data will be slightly
 100     smaller. And when it is set to 0, FSE_readNCount() and FSE_buildDTable() will be
 101     faster. If you are compressing a small amount of data (< 2 KB) then useLowProbCount=0
 102     is a good default, since header deserialization makes a big speed difference.
 103     Otherwise, useLowProbCount=1 is a good default, since the speed difference is small.
 104     @return : tableLog,
 105               or an errorCode, which can be tested using FSE_isError() */
 106 FSE_PUBLIC_API size_t FSE_normalizeCount(short* normalizedCounter, unsigned tableLog,
 107                     const unsigned* count, size_t srcSize, unsigned maxSymbolValue, unsigned useLowProbCount);
 108
 109 /*! FSE_NCountWriteBound():
 110     Provides the maximum possible size of an FSE normalized table, given 'maxSymbolValue' and 'tableLog'.
 111     Typically useful for allocation purpose. */
 112 FSE_PUBLIC_API size_t FSE_NCountWriteBound(unsigned maxSymbolValue, unsigned tableLog);
 113
 114 /*! FSE_writeNCount():
 115     Compactly save 'normalizedCounter' into 'buffer'.
 116     @return : size of the compressed table,
 117               or an errorCode, which can be tested using FSE_isError(). */
 118 FSE_PUBLIC_API size_t FSE_writeNCount (void* buffer, size_t bufferSize,
 119                                  const short* normalizedCounter,
 120                                  unsigned maxSymbolValue, unsigned tableLog);
 121
 122 /*! Constructor and Destructor of FSE_CTable.
 123     Note that FSE_CTable size depends on 'tableLog' and 'maxSymbolValue' */
 124 typedef unsigned FSE_CTable;   /* don't allocate that. It's only meant to be more restrictive than void* */
 125
 126 /*! FSE_buildCTable():
 127     Builds `ct`, which must be already allocated, using FSE_createCTable().
 128     @return : 0, or an errorCode, which can be tested using FSE_isError() */
 129 FSE_PUBLIC_API size_t FSE_buildCTable(FSE_CTable* ct, const short* normalizedCounter, unsigned maxSymbolValue, unsigned tableLog);
 130
 131 /*! FSE_compress_usingCTable():
 132     Compress `src` using `ct` into `dst` which must be already allocated.
 133     @return : size of compressed data (<= `dstCapacity`),
 134               or 0 if compressed data could not fit into `dst`,
 135               or an errorCode, which can be tested using FSE_isError() */
 136 FSE_PUBLIC_API size_t FSE_compress_usingCTable (void* dst, size_t dstCapacity, const void* src, size_t srcSize, const FSE_CTable* ct);
 137
 138 /*!
 139 Tutorial :
 140 ----------
 141 The first step is to count all symbols. FSE_count() does this job very fast.
 142 Result will be saved into 'count', a table of unsigned int, which must be already allocated, and have 'maxSymbolValuePtr[0]+1' cells.
 143 'src' is a table of bytes of size 'srcSize'. All values within 'src' MUST be <= maxSymbolValuePtr[0]
 144 maxSymbolValuePtr[0] will be updated, with its real value (necessarily <= original value)
 145 FSE_count() will return the number of occurrence of the most frequent symbol.
 146 This can be used to know if there is a single symbol within 'src', and to quickly evaluate its compressibility.
 147 If there is an error, the function will return an ErrorCode (which can be tested using FSE_isError()).
 148
 149 The next step is to normalize the frequencies.
 150 FSE_normalizeCount() will ensure that sum of frequencies is == 2 ^'tableLog'.
 151 It also guarantees a minimum of 1 to any Symbol with frequency >= 1.
 152 You can use 'tableLog'==0 to mean "use default tableLog value".
 153 If you are unsure of which tableLog value to use, you can ask FSE_optimalTableLog(),
 154 which will provide the optimal valid tableLog given sourceSize, maxSymbolValue, and a user-defined maximum (0 means "default").
 155
 156 The result of FSE_normalizeCount() will be saved into a table,
 157 called 'normalizedCounter', which is a table of signed short.
 158 'normalizedCounter' must be already allocated, and have at least 'maxSymbolValue+1' cells.
 159 The return value is tableLog if everything proceeded as expected.
 160 It is 0 if there is a single symbol within distribution.
 161 If there is an error (ex: invalid tableLog value), the function will return an ErrorCode (which can be tested using FSE_isError()).
 162
 163 'normalizedCounter' can be saved in a compact manner to a memory area using FSE_writeNCount().
 164 'buffer' must be already allocated.
 165 For guaranteed success, buffer size must be at least FSE_headerBound().
 166 The result of the function is the number of bytes written into 'buffer'.
 167 If there is an error, the function will return an ErrorCode (which can be tested using FSE_isError(); ex : buffer size too small).
 168
 169 'normalizedCounter' can then be used to create the compression table 'CTable'.
 170 The space required by 'CTable' must be already allocated, using FSE_createCTable().
 171 You can then use FSE_buildCTable() to fill 'CTable'.
 172 If there is an error, both functions will return an ErrorCode (which can be tested using FSE_isError()).
 173
 174 'CTable' can then be used to compress 'src', with FSE_compress_usingCTable().
 175 Similar to FSE_count(), the convention is that 'src' is assumed to be a table of char of size 'srcSize'
 176 The function returns the size of compressed data (without header), necessarily <= `dstCapacity`.
 177 If it returns '0', compressed data could not fit into 'dst'.
 178 If there is an error, the function will return an ErrorCode (which can be tested using FSE_isError()).
 179 */
 180
 181
 182 /* *** DECOMPRESSION *** */
 183
 184 /*! FSE_readNCount():
 185     Read compactly saved 'normalizedCounter' from 'rBuffer'.
 186     @return : size read from 'rBuffer',
 187               or an errorCode, which can be tested using FSE_isError().
 188               maxSymbolValuePtr[0] and tableLogPtr[0] will also be updated with their respective values */
 189 FSE_PUBLIC_API size_t FSE_readNCount (short* normalizedCounter,
 190                            unsigned* maxSymbolValuePtr, unsigned* tableLogPtr,
 191                            const void* rBuffer, size_t rBuffSize);
 192
 193 /*! FSE_readNCount_bmi2():
 194  * Same as FSE_readNCount() but pass bmi2=1 when your CPU supports BMI2 and 0 otherwise.
 195  */
 196 FSE_PUBLIC_API size_t FSE_readNCount_bmi2(short* normalizedCounter,
 197                            unsigned* maxSymbolValuePtr, unsigned* tableLogPtr,
 198                            const void* rBuffer, size_t rBuffSize, int bmi2);
 199
 200 typedef unsigned FSE_DTable;   /* don't allocate that. It's just a way to be more restrictive than void* */
 201
 202 /*!
 203 Tutorial :
 204 ----------
 205 (Note : these functions only decompress FSE-compressed blocks.
 206  If block is uncompressed, use memcpy() instead
 207  If block is a single repeated byte, use memset() instead )
 208
 209 The first step is to obtain the normalized frequencies of symbols.
 210 This can be performed by FSE_readNCount() if it was saved using FSE_writeNCount().
 211 'normalizedCounter' must be already allocated, and have at least 'maxSymbolValuePtr[0]+1' cells of signed short.
 212 In practice, that means it's necessary to know 'maxSymbolValue' beforehand,
 213 or size the table to handle worst case situations (typically 256).
 214 FSE_readNCount() will provide 'tableLog' and 'maxSymbolValue'.
 215 The result of FSE_readNCount() is the number of bytes read from 'rBuffer'.
 216 Note that 'rBufferSize' must be at least 4 bytes, even if useful information is less than that.
 217 If there is an error, the function will return an error code, which can be tested using FSE_isError().
 218
 219 The next step is to build the decompression tables 'FSE_DTable' from 'normalizedCounter'.
 220 This is performed by the function FSE_buildDTable().
 221 The space required by 'FSE_DTable' must be already allocated using FSE_createDTable().
 222 If there is an error, the function will return an error code, which can be tested using FSE_isError().
 223
 224 `FSE_DTable` can then be used to decompress `cSrc`, with FSE_decompress_usingDTable().
 225 `cSrcSize` must be strictly correct, otherwise decompression will fail.
 226 FSE_decompress_usingDTable() result will tell how many bytes were regenerated (<=`dstCapacity`).
 227 If there is an error, the function will return an error code, which can be tested using FSE_isError(). (ex: dst buffer too small)
 228 */
 229
 230 #endif  /* FSE_H */
 231
 232
 233 #if defined(FSE_STATIC_LINKING_ONLY) && !defined(FSE_H_FSE_STATIC_LINKING_ONLY)
 234 #define FSE_H_FSE_STATIC_LINKING_ONLY
 235
 236 /* *** Dependency *** */
 237 #include "bitstream.h"
 238
 239
 240 /* *****************************************
 241 *  Static allocation
 242 *******************************************/
 243 /* FSE buffer bounds */
 244 #define FSE_NCOUNTBOUND 512
 245 #define FSE_BLOCKBOUND(size) ((size) + ((size)>>7) + 4 /* fse states */ + sizeof(size_t) /* bitContainer */)
 246 #define FSE_COMPRESSBOUND(size) (FSE_NCOUNTBOUND + FSE_BLOCKBOUND(size))   /* Macro version, useful for static allocation */
 247
 248 /* It is possible to statically allocate FSE CTable/DTable as a table of FSE_CTable/FSE_DTable using below macros */
 249 #define FSE_CTABLE_SIZE_U32(maxTableLog, maxSymbolValue)   (1 + (1<<((maxTableLog)-1)) + (((maxSymbolValue)+1)*2))
 250 #define FSE_DTABLE_SIZE_U32(maxTableLog)                   (1 + (1<<(maxTableLog)))
 251
 252 /* or use the size to malloc() space directly. Pay attention to alignment restrictions though */
 253 #define FSE_CTABLE_SIZE(maxTableLog, maxSymbolValue)   (FSE_CTABLE_SIZE_U32(maxTableLog, maxSymbolValue) * sizeof(FSE_CTable))
 254 #define FSE_DTABLE_SIZE(maxTableLog)                   (FSE_DTABLE_SIZE_U32(maxTableLog) * sizeof(FSE_DTable))
 255
 256
 257 /* *****************************************
 258  *  FSE advanced API
 259  ***************************************** */
 260
 261 unsigned FSE_optimalTableLog_internal(unsigned maxTableLog, size_t srcSize, unsigned maxSymbolValue, unsigned minus);
 262 /**< same as FSE_optimalTableLog(), which used `minus==2` */
 263
 264 size_t FSE_buildCTable_rle (FSE_CTable* ct, unsigned char symbolValue);
 265 /**< build a fake FSE_CTable, designed to compress always the same symbolValue */
 266
 267 /* FSE_buildCTable_wksp() :
 268  * Same as FSE_buildCTable(), but using an externally allocated scratch buffer (`workSpace`).
 269  * `wkspSize` must be >= `FSE_BUILD_CTABLE_WORKSPACE_SIZE_U32(maxSymbolValue, tableLog)` of `unsigned`.
 270  * See FSE_buildCTable_wksp() for breakdown of workspace usage.
 271  */
 272 #define FSE_BUILD_CTABLE_WORKSPACE_SIZE_U32(maxSymbolValue, tableLog) (((maxSymbolValue + 2) + (1ull << (tableLog)))/2 + sizeof(U64)/sizeof(U32) /* additional 8 bytes for potential table overwrite */)
 273 #define FSE_BUILD_CTABLE_WORKSPACE_SIZE(maxSymbolValue, tableLog) (sizeof(unsigned) * FSE_BUILD_CTABLE_WORKSPACE_SIZE_U32(maxSymbolValue, tableLog))
 274 size_t FSE_buildCTable_wksp(FSE_CTable* ct, const short* normalizedCounter, unsigned maxSymbolValue, unsigned tableLog, void* workSpace, size_t wkspSize);
 275
 276 #define FSE_BUILD_DTABLE_WKSP_SIZE(maxTableLog, maxSymbolValue) (sizeof(short) * (maxSymbolValue + 1) + (1ULL << maxTableLog) + 8)
 277 #define FSE_BUILD_DTABLE_WKSP_SIZE_U32(maxTableLog, maxSymbolValue) ((FSE_BUILD_DTABLE_WKSP_SIZE(maxTableLog, maxSymbolValue) + sizeof(unsigned) - 1) / sizeof(unsigned))
 278 FSE_PUBLIC_API size_t FSE_buildDTable_wksp(FSE_DTable* dt, const short* normalizedCounter, unsigned maxSymbolValue, unsigned tableLog, void* workSpace, size_t wkspSize);
 279 /**< Same as FSE_buildDTable(), using an externally allocated `workspace` produced with `FSE_BUILD_DTABLE_WKSP_SIZE_U32(maxSymbolValue)` */
 280
 281 #define FSE_DECOMPRESS_WKSP_SIZE_U32(maxTableLog, maxSymbolValue) (FSE_DTABLE_SIZE_U32(maxTableLog) + 1 + FSE_BUILD_DTABLE_WKSP_SIZE_U32(maxTableLog, maxSymbolValue) + (FSE_MAX_SYMBOL_VALUE + 1) / 2 + 1)
 282 #define FSE_DECOMPRESS_WKSP_SIZE(maxTableLog, maxSymbolValue) (FSE_DECOMPRESS_WKSP_SIZE_U32(maxTableLog, maxSymbolValue) * sizeof(unsigned))
 283 size_t FSE_decompress_wksp_bmi2(void* dst, size_t dstCapacity, const void* cSrc, size_t cSrcSize, unsigned maxLog, void* workSpace, size_t wkspSize, int bmi2);
 284 /**< same as FSE_decompress(), using an externally allocated `workSpace` produced with `FSE_DECOMPRESS_WKSP_SIZE_U32(maxLog, maxSymbolValue)`.
 285  * Set bmi2 to 1 if your CPU supports BMI2 or 0 if it doesn't */
 286
 287 typedef enum {
 288    FSE_repeat_none,  /**< Cannot use the previous table */
 289    FSE_repeat_check, /**< Can use the previous table but it must be checked */
 290    FSE_repeat_valid  /**< Can use the previous table and it is assumed to be valid */
 291  } FSE_repeat;
 292
 293 /* *****************************************
 294 *  FSE symbol compression API
 295 *******************************************/
 296 /*!
 297    This API consists of small unitary functions, which highly benefit from being inlined.
 298    Hence their body are included in next section.
 299 */
 300 typedef struct {
 301     ptrdiff_t   value;
 302     const void* stateTable;
 303     const void* symbolTT;
 304     unsigned    stateLog;
 305 } FSE_CState_t;
 306
 307 static void FSE_initCState(FSE_CState_t* CStatePtr, const FSE_CTable* ct);
 308
 309 static void FSE_encodeSymbol(BIT_CStream_t* bitC, FSE_CState_t* CStatePtr, unsigned symbol);
 310
 311 static void FSE_flushCState(BIT_CStream_t* bitC, const FSE_CState_t* CStatePtr);
 312
 313 /**<
 314 These functions are inner components of FSE_compress_usingCTable().
 315 They allow the creation of custom streams, mixing multiple tables and bit sources.
 316
 317 A key property to keep in mind is that encoding and decoding are done **in reverse direction**.
 318 So the first symbol you will encode is the last you will decode, like a LIFO stack.
 319
 320 You will need a few variables to track your CStream. They are :
 321
 322 FSE_CTable    ct;         // Provided by FSE_buildCTable()
 323 BIT_CStream_t bitStream;  // bitStream tracking structure
 324 FSE_CState_t  state;      // State tracking structure (can have several)
 325
 326
 327 The first thing to do is to init bitStream and state.
 328     size_t errorCode = BIT_initCStream(&bitStream, dstBuffer, maxDstSize);
 329     FSE_initCState(&state, ct);
 330
 331 Note that BIT_initCStream() can produce an error code, so its result should be tested, using FSE_isError();
 332 You can then encode your input data, byte after byte.
 333 FSE_encodeSymbol() outputs a maximum of 'tableLog' bits at a time.
 334 Remember decoding will be done in reverse direction.
 335     FSE_encodeByte(&bitStream, &state, symbol);
 336
 337 At any time, you can also add any bit sequence.
 338 Note : maximum allowed nbBits is 25, for compatibility with 32-bits decoders
 339     BIT_addBits(&bitStream, bitField, nbBits);
 340
 341 The above methods don't commit data to memory, they just store it into local register, for speed.
 342 Local register size is 64-bits on 64-bits systems, 32-bits on 32-bits systems (size_t).
 343 Writing data to memory is a manual operation, performed by the flushBits function.
 344     BIT_flushBits(&bitStream);
 345
 346 Your last FSE encoding operation shall be to flush your last state value(s).
 347     FSE_flushState(&bitStream, &state);
 348
 349 Finally, you must close the bitStream.
 350 The function returns the size of CStream in bytes.
 351 If data couldn't fit into dstBuffer, it will return a 0 ( == not compressible)
 352 If there is an error, it returns an errorCode (which can be tested using FSE_isError()).
 353     size_t size = BIT_closeCStream(&bitStream);
 354 */
 355
 356
 357 /* *****************************************
 358 *  FSE symbol decompression API
 359 *******************************************/
 360 typedef struct {
 361     size_t      state;
 362     const void* table;   /* precise table may vary, depending on U16 */
 363 } FSE_DState_t;
 364
 365
 366 static void     FSE_initDState(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD, const FSE_DTable* dt);
 367
 368 static unsigned char FSE_decodeSymbol(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD);
 369
 370 static unsigned FSE_endOfDState(const FSE_DState_t* DStatePtr);
 371
 372 /**<
 373 Let's now decompose FSE_decompress_usingDTable() into its unitary components.
 374 You will decode FSE-encoded symbols from the bitStream,
 375 and also any other bitFields you put in, **in reverse order**.
 376
 377 You will need a few variables to track your bitStream. They are :
 378
 379 BIT_DStream_t DStream;    // Stream context
 380 FSE_DState_t  DState;     // State context. Multiple ones are possible
 381 FSE_DTable*   DTablePtr;  // Decoding table, provided by FSE_buildDTable()
 382
 383 The first thing to do is to init the bitStream.
 384     errorCode = BIT_initDStream(&DStream, srcBuffer, srcSize);
 385
 386 You should then retrieve your initial state(s)
 387 (in reverse flushing order if you have several ones) :
 388     errorCode = FSE_initDState(&DState, &DStream, DTablePtr);
 389
 390 You can then decode your data, symbol after symbol.
 391 For information the maximum number of bits read by FSE_decodeSymbol() is 'tableLog'.
 392 Keep in mind that symbols are decoded in reverse order, like a LIFO stack (last in, first out).
 393     unsigned char symbol = FSE_decodeSymbol(&DState, &DStream);
 394
 395 You can retrieve any bitfield you eventually stored into the bitStream (in reverse order)
 396 Note : maximum allowed nbBits is 25, for 32-bits compatibility
 397     size_t bitField = BIT_readBits(&DStream, nbBits);
 398
 399 All above operations only read from local register (which size depends on size_t).
 400 Refueling the register from memory is manually performed by the reload method.
 401     endSignal = FSE_reloadDStream(&DStream);
 402
 403 BIT_reloadDStream() result tells if there is still some more data to read from DStream.
 404 BIT_DStream_unfinished : there is still some data left into the DStream.
 405 BIT_DStream_endOfBuffer : Dstream reached end of buffer. Its container may no longer be completely filled.
 406 BIT_DStream_completed : Dstream reached its exact end, corresponding in general to decompression completed.
 407 BIT_DStream_tooFar : Dstream went too far. Decompression result is corrupted.
 408
 409 When reaching end of buffer (BIT_DStream_endOfBuffer), progress slowly, notably if you decode multiple symbols per loop,
 410 to properly detect the exact end of stream.
 411 After each decoded symbol, check if DStream is fully consumed using this simple test :
 412     BIT_reloadDStream(&DStream) >= BIT_DStream_completed
 413
 414 When it's done, verify decompression is fully completed, by checking both DStream and the relevant states.
 415 Checking if DStream has reached its end is performed by :
 416     BIT_endOfDStream(&DStream);
 417 Check also the states. There might be some symbols left there, if some high probability ones (>50%) are possible.
 418     FSE_endOfDState(&DState);
 419 */
 420
 421
 422 /* *****************************************
 423 *  FSE unsafe API
 424 *******************************************/
 425 static unsigned char FSE_decodeSymbolFast(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD);
 426 /* faster, but works only if nbBits is always >= 1 (otherwise, result will be corrupted) */
 427
 428
 429 /* *****************************************
 430 *  Implementation of inlined functions
 431 *******************************************/
 432 typedef struct {
 433     int deltaFindState;
 434     U32 deltaNbBits;
 435 } FSE_symbolCompressionTransform; /* total 8 bytes */
 436
 437 MEM_STATIC void FSE_initCState(FSE_CState_t* statePtr, const FSE_CTable* ct)
 438 {
 439     const void* ptr = ct;
 440     const U16* u16ptr = (const U16*) ptr;
 441     const U32 tableLog = MEM_read16(ptr);
 442     statePtr->value = (ptrdiff_t)1<<tableLog;
 443     statePtr->stateTable = u16ptr+2;
 444     statePtr->symbolTT = ct + 1 + (tableLog ? (1<<(tableLog-1)) : 1);
 445     statePtr->stateLog = tableLog;
 446 }
 447
 448
 449 /*! FSE_initCState2() :
 450 *   Same as FSE_initCState(), but the first symbol to include (which will be the last to be read)
 451 *   uses the smallest state value possible, saving the cost of this symbol */
 452 MEM_STATIC void FSE_initCState2(FSE_CState_t* statePtr, const FSE_CTable* ct, U32 symbol)
 453 {
 454     FSE_initCState(statePtr, ct);
 455     {   const FSE_symbolCompressionTransform symbolTT = ((const FSE_symbolCompressionTransform*)(statePtr->symbolTT))[symbol];
 456         const U16* stateTable = (const U16*)(statePtr->stateTable);
 457         U32 nbBitsOut  = (U32)((symbolTT.deltaNbBits + (1<<15)) >> 16);
 458         statePtr->value = (nbBitsOut << 16) - symbolTT.deltaNbBits;
 459         statePtr->value = stateTable[(statePtr->value >> nbBitsOut) + symbolTT.deltaFindState];
 460     }
 461 }
 462
 463 MEM_STATIC void FSE_encodeSymbol(BIT_CStream_t* bitC, FSE_CState_t* statePtr, unsigned symbol)
 464 {
 465     FSE_symbolCompressionTransform const symbolTT = ((const FSE_symbolCompressionTransform*)(statePtr->symbolTT))[symbol];
 466     const U16* const stateTable = (const U16*)(statePtr->stateTable);
 467     U32 const nbBitsOut  = (U32)((statePtr->value + symbolTT.deltaNbBits) >> 16);
 468     BIT_addBits(bitC,  (size_t)statePtr->value, nbBitsOut);
 469     statePtr->value = stateTable[ (statePtr->value >> nbBitsOut) + symbolTT.deltaFindState];
 470 }
 471
 472 MEM_STATIC void FSE_flushCState(BIT_CStream_t* bitC, const FSE_CState_t* statePtr)
 473 {
 474     BIT_addBits(bitC, (size_t)statePtr->value, statePtr->stateLog);
 475     BIT_flushBits(bitC);
 476 }
 477
 478
 479 /* FSE_getMaxNbBits() :
 480  * Approximate maximum cost of a symbol, in bits.
 481  * Fractional get rounded up (i.e. a symbol with a normalized frequency of 3 gives the same result as a frequency of 2)
 482  * note 1 : assume symbolValue is valid (<= maxSymbolValue)
 483  * note 2 : if freq[symbolValue]==0, @return a fake cost of tableLog+1 bits */
 484 MEM_STATIC U32 FSE_getMaxNbBits(const void* symbolTTPtr, U32 symbolValue)
 485 {
 486     const FSE_symbolCompressionTransform* symbolTT = (const FSE_symbolCompressionTransform*) symbolTTPtr;
 487     return (symbolTT[symbolValue].deltaNbBits + ((1<<16)-1)) >> 16;
 488 }
 489
 490 /* FSE_bitCost() :
 491  * Approximate symbol cost, as fractional value, using fixed-point format (accuracyLog fractional bits)
 492  * note 1 : assume symbolValue is valid (<= maxSymbolValue)
 493  * note 2 : if freq[symbolValue]==0, @return a fake cost of tableLog+1 bits */
 494 MEM_STATIC U32 FSE_bitCost(const void* symbolTTPtr, U32 tableLog, U32 symbolValue, U32 accuracyLog)
 495 {
 496     const FSE_symbolCompressionTransform* symbolTT = (const FSE_symbolCompressionTransform*) symbolTTPtr;
 497     U32 const minNbBits = symbolTT[symbolValue].deltaNbBits >> 16;
 498     U32 const threshold = (minNbBits+1) << 16;
 499     assert(tableLog < 16);
 500     assert(accuracyLog < 31-tableLog);  /* ensure enough room for renormalization double shift */
 501     {   U32 const tableSize = 1 << tableLog;
 502         U32 const deltaFromThreshold = threshold - (symbolTT[symbolValue].deltaNbBits + tableSize);
 503         U32 const normalizedDeltaFromThreshold = (deltaFromThreshold << accuracyLog) >> tableLog;   /* linear interpolation (very approximate) */
 504         U32 const bitMultiplier = 1 << accuracyLog;
 505         assert(symbolTT[symbolValue].deltaNbBits + tableSize <= threshold);
 506         assert(normalizedDeltaFromThreshold <= bitMultiplier);
 507         return (minNbBits+1)*bitMultiplier - normalizedDeltaFromThreshold;
 508     }
 509 }
 510
 511
 512 /* ======    Decompression    ====== */
 513
 514 typedef struct {
 515     U16 tableLog;
 516     U16 fastMode;
 517 } FSE_DTableHeader;   /* sizeof U32 */
 518
 519 typedef struct
 520 {
 521     unsigned short newState;
 522     unsigned char  symbol;
 523     unsigned char  nbBits;
 524 } FSE_decode_t;   /* size == U32 */
 525
 526 MEM_STATIC void FSE_initDState(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD, const FSE_DTable* dt)
 527 {
 528     const void* ptr = dt;
 529     const FSE_DTableHeader* const DTableH = (const FSE_DTableHeader*)ptr;
 530     DStatePtr->state = BIT_readBits(bitD, DTableH->tableLog);
 531     BIT_reloadDStream(bitD);
 532     DStatePtr->table = dt + 1;
 533 }
 534
 535 MEM_STATIC BYTE FSE_peekSymbol(const FSE_DState_t* DStatePtr)
 536 {
 537     FSE_decode_t const DInfo = ((const FSE_decode_t*)(DStatePtr->table))[DStatePtr->state];
 538     return DInfo.symbol;
 539 }
 540
 541 MEM_STATIC void FSE_updateState(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD)
 542 {
 543     FSE_decode_t const DInfo = ((const FSE_decode_t*)(DStatePtr->table))[DStatePtr->state];
 544     U32 const nbBits = DInfo.nbBits;
 545     size_t const lowBits = BIT_readBits(bitD, nbBits);
 546     DStatePtr->state = DInfo.newState + lowBits;
 547 }
 548
 549 MEM_STATIC BYTE FSE_decodeSymbol(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD)
 550 {
 551     FSE_decode_t const DInfo = ((const FSE_decode_t*)(DStatePtr->table))[DStatePtr->state];
 552     U32 const nbBits = DInfo.nbBits;
 553     BYTE const symbol = DInfo.symbol;
 554     size_t const lowBits = BIT_readBits(bitD, nbBits);
 555
 556     DStatePtr->state = DInfo.newState + lowBits;
 557     return symbol;
 558 }
 559
 560 /*! FSE_decodeSymbolFast() :
 561     unsafe, only works if no symbol has a probability > 50% */
 562 MEM_STATIC BYTE FSE_decodeSymbolFast(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD)
 563 {
 564     FSE_decode_t const DInfo = ((const FSE_decode_t*)(DStatePtr->table))[DStatePtr->state];
 565     U32 const nbBits = DInfo.nbBits;
 566     BYTE const symbol = DInfo.symbol;
 567     size_t const lowBits = BIT_readBitsFast(bitD, nbBits);
 568
 569     DStatePtr->state = DInfo.newState + lowBits;
 570     return symbol;
 571 }
 572
 573 MEM_STATIC unsigned FSE_endOfDState(const FSE_DState_t* DStatePtr)
 574 {
 575     return DStatePtr->state == 0;
 576 }
 577
 578
 579
 580 #ifndef FSE_COMMONDEFS_ONLY
 581
 582 /* **************************************************************
 583 *  Tuning parameters
 584 ****************************************************************/
 585 /*!MEMORY_USAGE :
 586 *  Memory usage formula : N->2^N Bytes (examples : 10 -> 1KB; 12 -> 4KB ; 16 -> 64KB; 20 -> 1MB; etc.)
 587 *  Increasing memory usage improves compression ratio
 588 *  Reduced memory usage can improve speed, due to cache effect
 589 *  Recommended max value is 14, for 16KB, which nicely fits into Intel x86 L1 cache */
 590 #ifndef FSE_MAX_MEMORY_USAGE
 591 #  define FSE_MAX_MEMORY_USAGE 14
 592 #endif
 593 #ifndef FSE_DEFAULT_MEMORY_USAGE
 594 #  define FSE_DEFAULT_MEMORY_USAGE 13
 595 #endif
 596 #if (FSE_DEFAULT_MEMORY_USAGE > FSE_MAX_MEMORY_USAGE)
 597 #  error "FSE_DEFAULT_MEMORY_USAGE must be <= FSE_MAX_MEMORY_USAGE"
 598 #endif
 599
 600 /*!FSE_MAX_SYMBOL_VALUE :
 601 *  Maximum symbol value authorized.
 602 *  Required for proper stack allocation */
 603 #ifndef FSE_MAX_SYMBOL_VALUE
 604 #  define FSE_MAX_SYMBOL_VALUE 255
 605 #endif
 606
 607 /* **************************************************************
 608 *  template functions type & suffix
 609 ****************************************************************/
 610 #define FSE_FUNCTION_TYPE BYTE
 611 #define FSE_FUNCTION_EXTENSION
 612 #define FSE_DECODE_TYPE FSE_decode_t
 613
 614
 615 #endif   /* !FSE_COMMONDEFS_ONLY */
 616
 617
 618 /* ***************************************************************
 619 *  Constants
 620 *****************************************************************/
 621 #define FSE_MAX_TABLELOG  (FSE_MAX_MEMORY_USAGE-2)
 622 #define FSE_MAX_TABLESIZE (1U<<FSE_MAX_TABLELOG)
 623 #define FSE_MAXTABLESIZE_MASK (FSE_MAX_TABLESIZE-1)
 624 #define FSE_DEFAULT_TABLELOG (FSE_DEFAULT_MEMORY_USAGE-2)
 625 #define FSE_MIN_TABLELOG 5
 626
 627 #define FSE_TABLELOG_ABSOLUTE_MAX 15
 628 #if FSE_MAX_TABLELOG > FSE_TABLELOG_ABSOLUTE_MAX
 629 #  error "FSE_MAX_TABLELOG > FSE_TABLELOG_ABSOLUTE_MAX is not supported"
 630 #endif
 631
 632 #define FSE_TABLESTEP(tableSize) (((tableSize)>>1) + ((tableSize)>>3) + 3)
 633
 634
 635 #endif /* FSE_STATIC_LINKING_ONLY */
 636
 637
 638 #if defined (__cplusplus)
 639 }
 640 #endif