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