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