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