ceph/src/zstd/lib/common/fse.h

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