1// SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
2/*
3 * Copyright (c) Meta Platforms, Inc. and affiliates.
4 * All rights reserved.
5 *
6 * This source code is licensed under both the BSD-style license (found in the
7 * LICENSE file in the root directory of this source tree) and the GPLv2 (found
8 * in the COPYING file in the root directory of this source tree).
9 * You may select, at your option, one of the above-listed licenses.
10 */
11
12 /*-*************************************
13 * Dependencies
14 ***************************************/
15#include "zstd_compress_sequences.h"
16
17/*
18 * -log2(x / 256) lookup table for x in [0, 256).
19 * If x == 0: Return 0
20 * Else: Return floor(-log2(x / 256) * 256)
21 */
22static unsigned const kInverseProbabilityLog256[256] = {
23 0, 2048, 1792, 1642, 1536, 1453, 1386, 1329, 1280, 1236, 1197, 1162,
24 1130, 1100, 1073, 1047, 1024, 1001, 980, 960, 941, 923, 906, 889,
25 874, 859, 844, 830, 817, 804, 791, 779, 768, 756, 745, 734,
26 724, 714, 704, 694, 685, 676, 667, 658, 650, 642, 633, 626,
27 618, 610, 603, 595, 588, 581, 574, 567, 561, 554, 548, 542,
28 535, 529, 523, 517, 512, 506, 500, 495, 489, 484, 478, 473,
29 468, 463, 458, 453, 448, 443, 438, 434, 429, 424, 420, 415,
30 411, 407, 402, 398, 394, 390, 386, 382, 377, 373, 370, 366,
31 362, 358, 354, 350, 347, 343, 339, 336, 332, 329, 325, 322,
32 318, 315, 311, 308, 305, 302, 298, 295, 292, 289, 286, 282,
33 279, 276, 273, 270, 267, 264, 261, 258, 256, 253, 250, 247,
34 244, 241, 239, 236, 233, 230, 228, 225, 222, 220, 217, 215,
35 212, 209, 207, 204, 202, 199, 197, 194, 192, 190, 187, 185,
36 182, 180, 178, 175, 173, 171, 168, 166, 164, 162, 159, 157,
37 155, 153, 151, 149, 146, 144, 142, 140, 138, 136, 134, 132,
38 130, 128, 126, 123, 121, 119, 117, 115, 114, 112, 110, 108,
39 106, 104, 102, 100, 98, 96, 94, 93, 91, 89, 87, 85,
40 83, 82, 80, 78, 76, 74, 73, 71, 69, 67, 66, 64,
41 62, 61, 59, 57, 55, 54, 52, 50, 49, 47, 46, 44,
42 42, 41, 39, 37, 36, 34, 33, 31, 30, 28, 26, 25,
43 23, 22, 20, 19, 17, 16, 14, 13, 11, 10, 8, 7,
44 5, 4, 2, 1,
45};
46
47static unsigned ZSTD_getFSEMaxSymbolValue(FSE_CTable const* ctable) {
48 void const* ptr = ctable;
49 U16 const* u16ptr = (U16 const*)ptr;
50 U32 const maxSymbolValue = MEM_read16(memPtr: u16ptr + 1);
51 return maxSymbolValue;
52}
53
54/*
55 * Returns true if we should use ncount=-1 else we should
56 * use ncount=1 for low probability symbols instead.
57 */
58static unsigned ZSTD_useLowProbCount(size_t const nbSeq)
59{
60 /* Heuristic: This should cover most blocks <= 16K and
61 * start to fade out after 16K to about 32K depending on
62 * compressibility.
63 */
64 return nbSeq >= 2048;
65}
66
67/*
68 * Returns the cost in bytes of encoding the normalized count header.
69 * Returns an error if any of the helper functions return an error.
70 */
71static size_t ZSTD_NCountCost(unsigned const* count, unsigned const max,
72 size_t const nbSeq, unsigned const FSELog)
73{
74 BYTE wksp[FSE_NCOUNTBOUND];
75 S16 norm[MaxSeq + 1];
76 const U32 tableLog = FSE_optimalTableLog(maxTableLog: FSELog, srcSize: nbSeq, maxSymbolValue: max);
77 FORWARD_IF_ERROR(FSE_normalizeCount(norm, tableLog, count, nbSeq, max, ZSTD_useLowProbCount(nbSeq)), "");
78 return FSE_writeNCount(buffer: wksp, bufferSize: sizeof(wksp), normalizedCounter: norm, maxSymbolValue: max, tableLog);
79}
80
81/*
82 * Returns the cost in bits of encoding the distribution described by count
83 * using the entropy bound.
84 */
85static size_t ZSTD_entropyCost(unsigned const* count, unsigned const max, size_t const total)
86{
87 unsigned cost = 0;
88 unsigned s;
89
90 assert(total > 0);
91 for (s = 0; s <= max; ++s) {
92 unsigned norm = (unsigned)((256 * count[s]) / total);
93 if (count[s] != 0 && norm == 0)
94 norm = 1;
95 assert(count[s] < total);
96 cost += count[s] * kInverseProbabilityLog256[norm];
97 }
98 return cost >> 8;
99}
100
101/*
102 * Returns the cost in bits of encoding the distribution in count using ctable.
103 * Returns an error if ctable cannot represent all the symbols in count.
104 */
105size_t ZSTD_fseBitCost(
106 FSE_CTable const* ctable,
107 unsigned const* count,
108 unsigned const max)
109{
110 unsigned const kAccuracyLog = 8;
111 size_t cost = 0;
112 unsigned s;
113 FSE_CState_t cstate;
114 FSE_initCState(statePtr: &cstate, ct: ctable);
115 if (ZSTD_getFSEMaxSymbolValue(ctable) < max) {
116 DEBUGLOG(5, "Repeat FSE_CTable has maxSymbolValue %u < %u",
117 ZSTD_getFSEMaxSymbolValue(ctable), max);
118 return ERROR(GENERIC);
119 }
120 for (s = 0; s <= max; ++s) {
121 unsigned const tableLog = cstate.stateLog;
122 unsigned const badCost = (tableLog + 1) << kAccuracyLog;
123 unsigned const bitCost = FSE_bitCost(symbolTTPtr: cstate.symbolTT, tableLog, symbolValue: s, accuracyLog: kAccuracyLog);
124 if (count[s] == 0)
125 continue;
126 if (bitCost >= badCost) {
127 DEBUGLOG(5, "Repeat FSE_CTable has Prob[%u] == 0", s);
128 return ERROR(GENERIC);
129 }
130 cost += (size_t)count[s] * bitCost;
131 }
132 return cost >> kAccuracyLog;
133}
134
135/*
136 * Returns the cost in bits of encoding the distribution in count using the
137 * table described by norm. The max symbol support by norm is assumed >= max.
138 * norm must be valid for every symbol with non-zero probability in count.
139 */
140size_t ZSTD_crossEntropyCost(short const* norm, unsigned accuracyLog,
141 unsigned const* count, unsigned const max)
142{
143 unsigned const shift = 8 - accuracyLog;
144 size_t cost = 0;
145 unsigned s;
146 assert(accuracyLog <= 8);
147 for (s = 0; s <= max; ++s) {
148 unsigned const normAcc = (norm[s] != -1) ? (unsigned)norm[s] : 1;
149 unsigned const norm256 = normAcc << shift;
150 assert(norm256 > 0);
151 assert(norm256 < 256);
152 cost += count[s] * kInverseProbabilityLog256[norm256];
153 }
154 return cost >> 8;
155}
156
157SymbolEncodingType_e
158ZSTD_selectEncodingType(
159 FSE_repeat* repeatMode, unsigned const* count, unsigned const max,
160 size_t const mostFrequent, size_t nbSeq, unsigned const FSELog,
161 FSE_CTable const* prevCTable,
162 short const* defaultNorm, U32 defaultNormLog,
163 ZSTD_DefaultPolicy_e const isDefaultAllowed,
164 ZSTD_strategy const strategy)
165{
166 ZSTD_STATIC_ASSERT(ZSTD_defaultDisallowed == 0 && ZSTD_defaultAllowed != 0);
167 if (mostFrequent == nbSeq) {
168 *repeatMode = FSE_repeat_none;
169 if (isDefaultAllowed && nbSeq <= 2) {
170 /* Prefer set_basic over set_rle when there are 2 or fewer symbols,
171 * since RLE uses 1 byte, but set_basic uses 5-6 bits per symbol.
172 * If basic encoding isn't possible, always choose RLE.
173 */
174 DEBUGLOG(5, "Selected set_basic");
175 return set_basic;
176 }
177 DEBUGLOG(5, "Selected set_rle");
178 return set_rle;
179 }
180 if (strategy < ZSTD_lazy) {
181 if (isDefaultAllowed) {
182 size_t const staticFse_nbSeq_max = 1000;
183 size_t const mult = 10 - strategy;
184 size_t const baseLog = 3;
185 size_t const dynamicFse_nbSeq_min = (((size_t)1 << defaultNormLog) * mult) >> baseLog; /* 28-36 for offset, 56-72 for lengths */
186 assert(defaultNormLog >= 5 && defaultNormLog <= 6); /* xx_DEFAULTNORMLOG */
187 assert(mult <= 9 && mult >= 7);
188 if ( (*repeatMode == FSE_repeat_valid)
189 && (nbSeq < staticFse_nbSeq_max) ) {
190 DEBUGLOG(5, "Selected set_repeat");
191 return set_repeat;
192 }
193 if ( (nbSeq < dynamicFse_nbSeq_min)
194 || (mostFrequent < (nbSeq >> (defaultNormLog-1))) ) {
195 DEBUGLOG(5, "Selected set_basic");
196 /* The format allows default tables to be repeated, but it isn't useful.
197 * When using simple heuristics to select encoding type, we don't want
198 * to confuse these tables with dictionaries. When running more careful
199 * analysis, we don't need to waste time checking both repeating tables
200 * and default tables.
201 */
202 *repeatMode = FSE_repeat_none;
203 return set_basic;
204 }
205 }
206 } else {
207 size_t const basicCost = isDefaultAllowed ? ZSTD_crossEntropyCost(norm: defaultNorm, accuracyLog: defaultNormLog, count, max) : ERROR(GENERIC);
208 size_t const repeatCost = *repeatMode != FSE_repeat_none ? ZSTD_fseBitCost(ctable: prevCTable, count, max) : ERROR(GENERIC);
209 size_t const NCountCost = ZSTD_NCountCost(count, max, nbSeq, FSELog);
210 size_t const compressedCost = (NCountCost << 3) + ZSTD_entropyCost(count, max, total: nbSeq);
211
212 if (isDefaultAllowed) {
213 assert(!ZSTD_isError(basicCost));
214 assert(!(*repeatMode == FSE_repeat_valid && ZSTD_isError(repeatCost)));
215 }
216 assert(!ZSTD_isError(NCountCost));
217 assert(compressedCost < ERROR(maxCode));
218 DEBUGLOG(5, "Estimated bit costs: basic=%u\trepeat=%u\tcompressed=%u",
219 (unsigned)basicCost, (unsigned)repeatCost, (unsigned)compressedCost);
220 if (basicCost <= repeatCost && basicCost <= compressedCost) {
221 DEBUGLOG(5, "Selected set_basic");
222 assert(isDefaultAllowed);
223 *repeatMode = FSE_repeat_none;
224 return set_basic;
225 }
226 if (repeatCost <= compressedCost) {
227 DEBUGLOG(5, "Selected set_repeat");
228 assert(!ZSTD_isError(repeatCost));
229 return set_repeat;
230 }
231 assert(compressedCost < basicCost && compressedCost < repeatCost);
232 }
233 DEBUGLOG(5, "Selected set_compressed");
234 *repeatMode = FSE_repeat_check;
235 return set_compressed;
236}
237
238typedef struct {
239 S16 norm[MaxSeq + 1];
240 U32 wksp[FSE_BUILD_CTABLE_WORKSPACE_SIZE_U32(MaxSeq, MaxFSELog)];
241} ZSTD_BuildCTableWksp;
242
243size_t
244ZSTD_buildCTable(void* dst, size_t dstCapacity,
245 FSE_CTable* nextCTable, U32 FSELog, SymbolEncodingType_e type,
246 unsigned* count, U32 max,
247 const BYTE* codeTable, size_t nbSeq,
248 const S16* defaultNorm, U32 defaultNormLog, U32 defaultMax,
249 const FSE_CTable* prevCTable, size_t prevCTableSize,
250 void* entropyWorkspace, size_t entropyWorkspaceSize)
251{
252 BYTE* op = (BYTE*)dst;
253 const BYTE* const oend = op + dstCapacity;
254 DEBUGLOG(6, "ZSTD_buildCTable (dstCapacity=%u)", (unsigned)dstCapacity);
255
256 switch (type) {
257 case set_rle:
258 FORWARD_IF_ERROR(FSE_buildCTable_rle(nextCTable, (BYTE)max), "");
259 RETURN_ERROR_IF(dstCapacity==0, dstSize_tooSmall, "not enough space");
260 *op = codeTable[0];
261 return 1;
262 case set_repeat:
263 ZSTD_memcpy(nextCTable, prevCTable, prevCTableSize);
264 return 0;
265 case set_basic:
266 FORWARD_IF_ERROR(FSE_buildCTable_wksp(nextCTable, defaultNorm, defaultMax, defaultNormLog, entropyWorkspace, entropyWorkspaceSize), ""); /* note : could be pre-calculated */
267 return 0;
268 case set_compressed: {
269 ZSTD_BuildCTableWksp* wksp = (ZSTD_BuildCTableWksp*)entropyWorkspace;
270 size_t nbSeq_1 = nbSeq;
271 const U32 tableLog = FSE_optimalTableLog(maxTableLog: FSELog, srcSize: nbSeq, maxSymbolValue: max);
272 if (count[codeTable[nbSeq-1]] > 1) {
273 count[codeTable[nbSeq-1]]--;
274 nbSeq_1--;
275 }
276 assert(nbSeq_1 > 1);
277 assert(entropyWorkspaceSize >= sizeof(ZSTD_BuildCTableWksp));
278 (void)entropyWorkspaceSize;
279 FORWARD_IF_ERROR(FSE_normalizeCount(wksp->norm, tableLog, count, nbSeq_1, max, ZSTD_useLowProbCount(nbSeq_1)), "FSE_normalizeCount failed");
280 assert(oend >= op);
281 { size_t const NCountSize = FSE_writeNCount(buffer: op, bufferSize: (size_t)(oend - op), normalizedCounter: wksp->norm, maxSymbolValue: max, tableLog); /* overflow protected */
282 FORWARD_IF_ERROR(NCountSize, "FSE_writeNCount failed");
283 FORWARD_IF_ERROR(FSE_buildCTable_wksp(nextCTable, wksp->norm, max, tableLog, wksp->wksp, sizeof(wksp->wksp)), "FSE_buildCTable_wksp failed");
284 return NCountSize;
285 }
286 }
287 default: assert(0); RETURN_ERROR(GENERIC, "impossible to reach");
288 }
289}
290
291FORCE_INLINE_TEMPLATE size_t
292ZSTD_encodeSequences_body(
293 void* dst, size_t dstCapacity,
294 FSE_CTable const* CTable_MatchLength, BYTE const* mlCodeTable,
295 FSE_CTable const* CTable_OffsetBits, BYTE const* ofCodeTable,
296 FSE_CTable const* CTable_LitLength, BYTE const* llCodeTable,
297 SeqDef const* sequences, size_t nbSeq, int longOffsets)
298{
299 BIT_CStream_t blockStream;
300 FSE_CState_t stateMatchLength;
301 FSE_CState_t stateOffsetBits;
302 FSE_CState_t stateLitLength;
303
304 RETURN_ERROR_IF(
305 ERR_isError(BIT_initCStream(&blockStream, dst, dstCapacity)),
306 dstSize_tooSmall, "not enough space remaining");
307 DEBUGLOG(6, "available space for bitstream : %i (dstCapacity=%u)",
308 (int)(blockStream.endPtr - blockStream.startPtr),
309 (unsigned)dstCapacity);
310
311 /* first symbols */
312 FSE_initCState2(statePtr: &stateMatchLength, ct: CTable_MatchLength, symbol: mlCodeTable[nbSeq-1]);
313 FSE_initCState2(statePtr: &stateOffsetBits, ct: CTable_OffsetBits, symbol: ofCodeTable[nbSeq-1]);
314 FSE_initCState2(statePtr: &stateLitLength, ct: CTable_LitLength, symbol: llCodeTable[nbSeq-1]);
315 BIT_addBits(bitC: &blockStream, value: sequences[nbSeq-1].litLength, nbBits: LL_bits[llCodeTable[nbSeq-1]]);
316 if (MEM_32bits()) BIT_flushBits(bitC: &blockStream);
317 BIT_addBits(bitC: &blockStream, value: sequences[nbSeq-1].mlBase, nbBits: ML_bits[mlCodeTable[nbSeq-1]]);
318 if (MEM_32bits()) BIT_flushBits(bitC: &blockStream);
319 if (longOffsets) {
320 U32 const ofBits = ofCodeTable[nbSeq-1];
321 unsigned const extraBits = ofBits - MIN(ofBits, STREAM_ACCUMULATOR_MIN-1);
322 if (extraBits) {
323 BIT_addBits(bitC: &blockStream, value: sequences[nbSeq-1].offBase, nbBits: extraBits);
324 BIT_flushBits(bitC: &blockStream);
325 }
326 BIT_addBits(bitC: &blockStream, value: sequences[nbSeq-1].offBase >> extraBits,
327 nbBits: ofBits - extraBits);
328 } else {
329 BIT_addBits(bitC: &blockStream, value: sequences[nbSeq-1].offBase, nbBits: ofCodeTable[nbSeq-1]);
330 }
331 BIT_flushBits(bitC: &blockStream);
332
333 { size_t n;
334 for (n=nbSeq-2 ; n<nbSeq ; n--) { /* intentional underflow */
335 BYTE const llCode = llCodeTable[n];
336 BYTE const ofCode = ofCodeTable[n];
337 BYTE const mlCode = mlCodeTable[n];
338 U32 const llBits = LL_bits[llCode];
339 U32 const ofBits = ofCode;
340 U32 const mlBits = ML_bits[mlCode];
341 DEBUGLOG(6, "encoding: litlen:%2u - matchlen:%2u - offCode:%7u",
342 (unsigned)sequences[n].litLength,
343 (unsigned)sequences[n].mlBase + MINMATCH,
344 (unsigned)sequences[n].offBase);
345 /* 32b*/ /* 64b*/
346 /* (7)*/ /* (7)*/
347 FSE_encodeSymbol(bitC: &blockStream, statePtr: &stateOffsetBits, symbol: ofCode); /* 15 */ /* 15 */
348 FSE_encodeSymbol(bitC: &blockStream, statePtr: &stateMatchLength, symbol: mlCode); /* 24 */ /* 24 */
349 if (MEM_32bits()) BIT_flushBits(bitC: &blockStream); /* (7)*/
350 FSE_encodeSymbol(bitC: &blockStream, statePtr: &stateLitLength, symbol: llCode); /* 16 */ /* 33 */
351 if (MEM_32bits() || (ofBits+mlBits+llBits >= 64-7-(LLFSELog+MLFSELog+OffFSELog)))
352 BIT_flushBits(bitC: &blockStream); /* (7)*/
353 BIT_addBits(bitC: &blockStream, value: sequences[n].litLength, nbBits: llBits);
354 if (MEM_32bits() && ((llBits+mlBits)>24)) BIT_flushBits(bitC: &blockStream);
355 BIT_addBits(bitC: &blockStream, value: sequences[n].mlBase, nbBits: mlBits);
356 if (MEM_32bits() || (ofBits+mlBits+llBits > 56)) BIT_flushBits(bitC: &blockStream);
357 if (longOffsets) {
358 unsigned const extraBits = ofBits - MIN(ofBits, STREAM_ACCUMULATOR_MIN-1);
359 if (extraBits) {
360 BIT_addBits(bitC: &blockStream, value: sequences[n].offBase, nbBits: extraBits);
361 BIT_flushBits(bitC: &blockStream); /* (7)*/
362 }
363 BIT_addBits(bitC: &blockStream, value: sequences[n].offBase >> extraBits,
364 nbBits: ofBits - extraBits); /* 31 */
365 } else {
366 BIT_addBits(bitC: &blockStream, value: sequences[n].offBase, nbBits: ofBits); /* 31 */
367 }
368 BIT_flushBits(bitC: &blockStream); /* (7)*/
369 DEBUGLOG(7, "remaining space : %i", (int)(blockStream.endPtr - blockStream.ptr));
370 } }
371
372 DEBUGLOG(6, "ZSTD_encodeSequences: flushing ML state with %u bits", stateMatchLength.stateLog);
373 FSE_flushCState(bitC: &blockStream, statePtr: &stateMatchLength);
374 DEBUGLOG(6, "ZSTD_encodeSequences: flushing Off state with %u bits", stateOffsetBits.stateLog);
375 FSE_flushCState(bitC: &blockStream, statePtr: &stateOffsetBits);
376 DEBUGLOG(6, "ZSTD_encodeSequences: flushing LL state with %u bits", stateLitLength.stateLog);
377 FSE_flushCState(bitC: &blockStream, statePtr: &stateLitLength);
378
379 { size_t const streamSize = BIT_closeCStream(bitC: &blockStream);
380 RETURN_ERROR_IF(streamSize==0, dstSize_tooSmall, "not enough space");
381 return streamSize;
382 }
383}
384
385static size_t
386ZSTD_encodeSequences_default(
387 void* dst, size_t dstCapacity,
388 FSE_CTable const* CTable_MatchLength, BYTE const* mlCodeTable,
389 FSE_CTable const* CTable_OffsetBits, BYTE const* ofCodeTable,
390 FSE_CTable const* CTable_LitLength, BYTE const* llCodeTable,
391 SeqDef const* sequences, size_t nbSeq, int longOffsets)
392{
393 return ZSTD_encodeSequences_body(dst, dstCapacity,
394 CTable_MatchLength, mlCodeTable,
395 CTable_OffsetBits, ofCodeTable,
396 CTable_LitLength, llCodeTable,
397 sequences, nbSeq, longOffsets);
398}
399
400
401#if DYNAMIC_BMI2
402
403static BMI2_TARGET_ATTRIBUTE size_t
404ZSTD_encodeSequences_bmi2(
405 void* dst, size_t dstCapacity,
406 FSE_CTable const* CTable_MatchLength, BYTE const* mlCodeTable,
407 FSE_CTable const* CTable_OffsetBits, BYTE const* ofCodeTable,
408 FSE_CTable const* CTable_LitLength, BYTE const* llCodeTable,
409 SeqDef const* sequences, size_t nbSeq, int longOffsets)
410{
411 return ZSTD_encodeSequences_body(dst, dstCapacity,
412 CTable_MatchLength, mlCodeTable,
413 CTable_OffsetBits, ofCodeTable,
414 CTable_LitLength, llCodeTable,
415 sequences, nbSeq, longOffsets);
416}
417
418#endif
419
420size_t ZSTD_encodeSequences(
421 void* dst, size_t dstCapacity,
422 FSE_CTable const* CTable_MatchLength, BYTE const* mlCodeTable,
423 FSE_CTable const* CTable_OffsetBits, BYTE const* ofCodeTable,
424 FSE_CTable const* CTable_LitLength, BYTE const* llCodeTable,
425 SeqDef const* sequences, size_t nbSeq, int longOffsets, int bmi2)
426{
427 DEBUGLOG(5, "ZSTD_encodeSequences: dstCapacity = %u", (unsigned)dstCapacity);
428#if DYNAMIC_BMI2
429 if (bmi2) {
430 return ZSTD_encodeSequences_bmi2(dst, dstCapacity,
431 CTable_MatchLength, mlCodeTable,
432 CTable_OffsetBits, ofCodeTable,
433 CTable_LitLength, llCodeTable,
434 sequences, nbSeq, longOffsets);
435 }
436#endif
437 (void)bmi2;
438 return ZSTD_encodeSequences_default(dst, dstCapacity,
439 CTable_MatchLength, mlCodeTable,
440 CTable_OffsetBits, ofCodeTable,
441 CTable_LitLength, llCodeTable,
442 sequences, nbSeq, longOffsets);
443}
444

source code of linux/lib/zstd/compress/zstd_compress_sequences.c