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