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