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