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 */ 22 static 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 47 static 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(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 */ 58 static 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 */ 71 static 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(FSELog, nbSeq, max); 77 FORWARD_IF_ERROR(FSE_normalizeCount(norm, tableLog, count, nbSeq, max, ZSTD_useLowProbCount(nbSeq)), ""); 78 return FSE_writeNCount(wksp, sizeof(wksp), norm, max, tableLog); 79 } 80 81 /* 82 * Returns the cost in bits of encoding the distribution described by count 83 * using the entropy bound. 84 */ 85 static 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 */ 105 size_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(&cstate, 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(cstate.symbolTT, tableLog, s, 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 */ 140 size_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 157 SymbolEncodingType_e 158 ZSTD_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(defaultNorm, defaultNormLog, count, max) : ERROR(GENERIC); 208 size_t const repeatCost = *repeatMode != FSE_repeat_none ? ZSTD_fseBitCost(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, 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 238 typedef struct { 239 S16 norm[MaxSeq + 1]; 240 U32 wksp[FSE_BUILD_CTABLE_WORKSPACE_SIZE_U32(MaxSeq, MaxFSELog)]; 241 } ZSTD_BuildCTableWksp; 242 243 size_t 244 ZSTD_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(FSELog, nbSeq, 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(op, (size_t)(oend - op), wksp->norm, 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 291 FORCE_INLINE_TEMPLATE size_t 292 ZSTD_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(&stateMatchLength, CTable_MatchLength, mlCodeTable[nbSeq-1]); 313 FSE_initCState2(&stateOffsetBits, CTable_OffsetBits, ofCodeTable[nbSeq-1]); 314 FSE_initCState2(&stateLitLength, CTable_LitLength, llCodeTable[nbSeq-1]); 315 BIT_addBits(&blockStream, sequences[nbSeq-1].litLength, LL_bits[llCodeTable[nbSeq-1]]); 316 if (MEM_32bits()) BIT_flushBits(&blockStream); 317 BIT_addBits(&blockStream, sequences[nbSeq-1].mlBase, ML_bits[mlCodeTable[nbSeq-1]]); 318 if (MEM_32bits()) BIT_flushBits(&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(&blockStream, sequences[nbSeq-1].offBase, extraBits); 324 BIT_flushBits(&blockStream); 325 } 326 BIT_addBits(&blockStream, sequences[nbSeq-1].offBase >> extraBits, 327 ofBits - extraBits); 328 } else { 329 BIT_addBits(&blockStream, sequences[nbSeq-1].offBase, ofCodeTable[nbSeq-1]); 330 } 331 BIT_flushBits(&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(&blockStream, &stateOffsetBits, ofCode); /* 15 */ /* 15 */ 348 FSE_encodeSymbol(&blockStream, &stateMatchLength, mlCode); /* 24 */ /* 24 */ 349 if (MEM_32bits()) BIT_flushBits(&blockStream); /* (7)*/ 350 FSE_encodeSymbol(&blockStream, &stateLitLength, llCode); /* 16 */ /* 33 */ 351 if (MEM_32bits() || (ofBits+mlBits+llBits >= 64-7-(LLFSELog+MLFSELog+OffFSELog))) 352 BIT_flushBits(&blockStream); /* (7)*/ 353 BIT_addBits(&blockStream, sequences[n].litLength, llBits); 354 if (MEM_32bits() && ((llBits+mlBits)>24)) BIT_flushBits(&blockStream); 355 BIT_addBits(&blockStream, sequences[n].mlBase, mlBits); 356 if (MEM_32bits() || (ofBits+mlBits+llBits > 56)) BIT_flushBits(&blockStream); 357 if (longOffsets) { 358 unsigned const extraBits = ofBits - MIN(ofBits, STREAM_ACCUMULATOR_MIN-1); 359 if (extraBits) { 360 BIT_addBits(&blockStream, sequences[n].offBase, extraBits); 361 BIT_flushBits(&blockStream); /* (7)*/ 362 } 363 BIT_addBits(&blockStream, sequences[n].offBase >> extraBits, 364 ofBits - extraBits); /* 31 */ 365 } else { 366 BIT_addBits(&blockStream, sequences[n].offBase, ofBits); /* 31 */ 367 } 368 BIT_flushBits(&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(&blockStream, &stateMatchLength); 374 DEBUGLOG(6, "ZSTD_encodeSequences: flushing Off state with %u bits", stateOffsetBits.stateLog); 375 FSE_flushCState(&blockStream, &stateOffsetBits); 376 DEBUGLOG(6, "ZSTD_encodeSequences: flushing LL state with %u bits", stateLitLength.stateLog); 377 FSE_flushCState(&blockStream, &stateLitLength); 378 379 { size_t const streamSize = BIT_closeCStream(&blockStream); 380 RETURN_ERROR_IF(streamSize==0, dstSize_tooSmall, "not enough space"); 381 return streamSize; 382 } 383 } 384 385 static size_t 386 ZSTD_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 403 static BMI2_TARGET_ATTRIBUTE size_t 404 ZSTD_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 420 size_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