}
return 0;
}
+
+/*
+ * Builds a fast huffman decoding table from a canonical huffman code lengths
+ * table. Based on code written by David Tritscher.
+ *
+ * @decode_table: The array in which to create the fast huffman decoding
+ * table. It must have a length of at least
+ * (2**num_bits) + 2 * num_syms to guarantee
+ * that there is enough space.
+ *
+ * @num_syms: Total number of symbols in the Huffman tree.
+ *
+ * @num_bits: Any symbols with a code length of num_bits or less can be
+ * decoded in one lookup of the table. 2**num_bits
+ * must be greater than or equal to @num_syms if there are
+ * any Huffman codes longer than @num_bits.
+ *
+ * @lens: An array of length @num_syms, indexable by symbol, that
+ * gives the length of that symbol. Because the Huffman
+ * tree is in canonical form, it can be reconstructed by
+ * only knowing the length of the code for each symbol.
+ *
+ * @make_codeword_len: An integer that gives the longest possible codeword
+ * length.
+ *
+ * Returns 0 on success; returns 1 if the length values do not correspond to a
+ * valid Huffman tree, or if there are codes of length greater than @num_bits
+ * but 2**num_bits < num_syms.
+ *
+ * What exactly is the format of the fast Huffman decoding table? The first
+ * (1 << num_bits) entries of the table are indexed by chunks of the input of
+ * size @num_bits. If the next Huffman code in the input happens to have a
+ * length of exactly @num_bits, the symbol is simply read directly from the
+ * decoding table. Alternatively, if the next Huffman code has length _less
+ * than_ @num_bits, the symbol is also read directly from the decode table; this
+ * is possible because every entry in the table that is indexed by an integer
+ * that has the shorter code as a binary prefix is filled in with the
+ * appropriate symbol. If a code has length n <= num_bits, it will have
+ * 2**(num_bits - n) possible suffixes, and thus that many entries in the
+ * decoding table.
+ *
+ * It's a bit more complicated if the next Huffman code has length of more than
+ * @num_bits. The table entry indexed by the first @num_bits of that code
+ * cannot give the appropriate symbol directly, because that entry is guaranteed
+ * to be referenced by the Huffman codes for multiple symbols. And while the
+ * LZX compression format does not allow codes longer than 16 bits, a table of
+ * size (2 ** 16) = 65536 entries would be too slow to create.
+ *
+ * There are several different ways to make it possible to look up the symbols
+ * for codes longer than @num_bits. A common way is to make the entries for the
+ * prefixes of length @num_bits of those entries be pointers to additional
+ * decoding tables that are indexed by some number of additional bits of the
+ * code symbol. The technique used here is a bit simpler, however. We just
+ * store the needed subtrees of the Huffman tree in the decoding table after the
+ * lookup entries, beginning at index (2**num_bits). Real pointers are
+ * replaced by indices into the decoding table, and we distinguish symbol
+ * entries from pointers by the fact that values less than @num_syms must be
+ * symbol values.
+ */
+int make_huffman_decode_table(u16 decode_table[], uint num_syms,
+ uint num_bits, const u8 lens[],
+ uint max_code_len)
+{
+ /* Number of entries in the decode table. */
+ u32 table_num_entries = 1 << num_bits;
+
+ /* Current position in the decode table. */
+ u32 decode_table_pos = 0;
+
+ /* Fill entries for codes short enough for a direct mapping. Here we
+ * are taking advantage of the ordering of the codes, since they are for
+ * a canonical Huffman tree. It must be the case that all the codes of
+ * some length @code_length, zero-extended or one-extended, numerically
+ * precede all the codes of length @code_length + 1. Furthermore, if we
+ * have 2 symbols A and B, such that A is listed before B in the lens
+ * array, and both symbols have the same code length, then we know that
+ * the code for A numerically precedes the code for B.
+ * */
+ for (uint code_len = 1; code_len <= num_bits; code_len++) {
+
+ /* Number of entries that a code of length @code_length would
+ * need. */
+ u32 code_num_entries = 1 << (num_bits - code_len);
+
+
+ /* For each symbol of length @code_len, fill in its entries in
+ * the decode table. */
+ for (uint sym = 0; sym < num_syms; sym++) {
+
+ if (lens[sym] != code_len)
+ continue;
+
+
+ /* Check for table overrun. This can only happen if the
+ * given lengths do not correspond to a valid Huffman
+ * tree. */
+ if (decode_table_pos >= table_num_entries) {
+ ERROR("Huffman decoding table overrun: "
+ "pos = %u, num_entries = %u\n",
+ decode_table_pos,
+ table_num_entries);
+ return 1;
+ }
+
+ /* Fill all possible lookups of this symbol with
+ * the symbol itself. */
+ for (uint i = 0; i < code_num_entries; i++)
+ decode_table[decode_table_pos + i] = sym;
+
+ /* Increment the position in the decode table by
+ * the number of entries that were just filled
+ * in. */
+ decode_table_pos += code_num_entries;
+ }
+ }
+
+ /* If all entries of the decode table have been filled in, there are no
+ * codes longer than num_bits, so we are done filling in the decode
+ * table. */
+ if (decode_table_pos == table_num_entries)
+ return 0;
+
+ /* Otherwise, fill in the remaining entries, which correspond to codes longer
+ * than @num_bits. */
+
+
+ /* First, zero out the rest of the entries; this is necessary so
+ * that the entries appear as "unallocated" in the next part. */
+ for (uint i = decode_table_pos; i < table_num_entries; i++)
+ decode_table[i] = 0;
+
+ /* Assert that 2**num_bits is at least num_syms. If this wasn't the
+ * case, we wouldn't be able to distinguish pointer entries from symbol
+ * entries. */
+ wimlib_assert((1 << num_bits) >= num_syms);
+
+
+ /* The current Huffman code. */
+ uint current_code = decode_table_pos;
+
+ /* The tree nodes are allocated starting at
+ * decode_table[table_num_entries]. Remember that the full size of the
+ * table, including the extra space for the tree nodes, is actually
+ * 2**num_bits + 2 * num_syms slots, while table_num_entries is only
+ * 2**num_bits. */
+ uint next_free_tree_slot = table_num_entries;
+
+ /* Go through every codeword of length greater than @num_bits. Note:
+ * the LZX format guarantees that the codeword length can be at most 16
+ * bits. */
+ for (uint code_len = num_bits + 1; code_len <= max_code_len;
+ code_len++)
+ {
+ current_code <<= 1;
+ for (uint sym = 0; sym < num_syms; sym++) {
+ if (lens[sym] != code_len)
+ continue;
+
+
+ /* i is the index of the current node; find it from the
+ * prefix of the current Huffman code. */
+ uint i = current_code >> (code_len - num_bits);
+
+ if (i >= (1 << num_bits)) {
+ ERROR("Invalid canonical Huffman code!\n");
+ return 1;
+ }
+
+ /* Go through each bit of the current Huffman code
+ * beyond the prefix of length num_bits and walk the
+ * tree, "allocating" slots that have not yet been
+ * allocated. */
+ for (int bit_num = num_bits + 1; bit_num <= code_len; bit_num++) {
+
+ /* If the current tree node points to nowhere
+ * but we need to follow it, allocate a new node
+ * for it to point to. */
+ if (decode_table[i] == 0) {
+ decode_table[i] = next_free_tree_slot;
+ decode_table[next_free_tree_slot++] = 0;
+ decode_table[next_free_tree_slot++] = 0;
+ }
+
+ i = decode_table[i];
+
+ /* Is the next bit 0 or 1? If 0, go left;
+ * otherwise, go right (by incrementing i by 1) */
+ int bit_pos = code_len - bit_num;
+
+ int bit = (current_code & (1 << bit_pos)) >>
+ bit_pos;
+ i += bit;
+ }
+
+ /* i is now the index of the leaf entry into which the
+ * actual symbol will go. */
+ decode_table[i] = sym;
+
+ /* Increment decode_table_pos only if the prefix of the
+ * Huffman code changes. */
+ if (current_code >> (code_len - num_bits) !=
+ (current_code + 1) >> (code_len - num_bits))
+ decode_table_pos++;
+
+ /* current_code is always incremented because this is
+ * how canonical Huffman codes are generated (add 1 for
+ * each code, then left shift whenever the code length
+ * increases) */
+ current_code++;
+ }
+ }
+
+
+ /* If the lengths really represented a valid Huffman tree, all
+ * @table_num_entries in the table will have been filled. However, it
+ * is also possible that the tree is completely empty (as noted
+ * earlier) with all 0 lengths, and this is expected to succeed. */
+
+ if (decode_table_pos != table_num_entries) {
+
+ for (uint i = 0; i < num_syms; i++) {
+ if (lens[i] != 0) {
+ ERROR("Lengths do not form a valid "
+ "canonical Huffman tree "
+ "(only filled %u of %u decode "
+ "table slots)!\n", decode_table_pos,
+ table_num_entries);
+ return 1;
+ }
+ }
+ }
+ return 0;
+}
+
+/* Reads a Huffman-encoded symbol when it is known there are less than
+ * MAX_CODE_LEN bits remaining in the bitstream. */
+static int read_huffsym_near_end_of_input(struct input_bitstream *istream,
+ const u16 decode_table[],
+ const u8 lens[],
+ uint num_syms,
+ uint table_bits,
+ uint *n)
+{
+ uint bitsleft = istream->bitsleft;
+ uint key_size;
+ u16 sym;
+ u16 key_bits;
+
+ if (table_bits > bitsleft) {
+ key_size = bitsleft;
+ bitsleft = 0;
+ key_bits = bitstream_peek_bits(istream, key_size) <<
+ (table_bits - key_size);
+ } else {
+ key_size = table_bits;
+ bitsleft -= table_bits;
+ key_bits = bitstream_peek_bits(istream, table_bits);
+ }
+
+ sym = decode_table[key_bits];
+ if (sym >= num_syms) {
+ bitstream_remove_bits(istream, key_size);
+ do {
+ if (bitsleft == 0) {
+ ERROR("Input stream exhausted!\n");
+ return 1;
+ }
+ key_bits = sym + bitstream_peek_bits(istream, 1);
+ bitstream_remove_bits(istream, 1);
+ bitsleft--;
+ } while ((sym = decode_table[key_bits]) >= num_syms);
+ } else {
+ bitstream_remove_bits(istream, lens[sym]);
+ }
+ *n = sym;
+ return 0;
+}
+
+/*
+ * Reads a Huffman-encoded symbol from a bitstream.
+ *
+ * This function may be called hundreds of millions of times when extracting a
+ * large WIM file. I'm not sure it could be made much faster that it is,
+ * especially since there isn't enough time to make a big table that allows
+ * decoding multiple symbols per lookup. But if extracting files to a hard
+ * disk, the IO will be the bottleneck anyway.
+ *
+ * @buf: The input buffer from which the symbol will be read.
+ * @decode_table: The fast Huffman decoding table for the Huffman tree.
+ * @lengths: The table that gives the length of the code for each
+ * symbol.
+ * @num_symbols: The number of symbols in the Huffman code.
+ * @table_bits: Huffman codes this length or less can be looked up
+ * directory in the decode_table, as the
+ * decode_table contains 2**table_bits entries.
+ */
+int read_huffsym(struct input_bitstream *stream,
+ const u16 decode_table[],
+ const u8 lengths[],
+ unsigned num_symbols,
+ unsigned table_bits,
+ uint *n,
+ unsigned max_codeword_len)
+{
+ /* In the most common case, there are at least max_codeword_len bits
+ * remaining in the stream. */
+ if (bitstream_ensure_bits(stream, max_codeword_len) == 0) {
+
+ /* Use the next table_bits of the input as an index into the
+ * decode_table. */
+ u16 key_bits = bitstream_peek_bits(stream, table_bits);
+
+ u16 sym = decode_table[key_bits];
+
+ /* If the entry in the decode table is not a valid symbol, it is
+ * the offset of the root of its Huffman subtree. */
+ if (sym >= num_symbols) {
+ bitstream_remove_bits(stream, table_bits);
+ do {
+ key_bits = sym + bitstream_peek_bits(stream, 1);
+ bitstream_remove_bits(stream, 1);
+
+ wimlib_assert(key_bits < num_symbols * 2 +
+ (1 << table_bits));
+ } while ((sym = decode_table[key_bits]) >= num_symbols);
+ } else {
+ wimlib_assert(lengths[sym] <= table_bits);
+ bitstream_remove_bits(stream, lengths[sym]);
+ }
+ *n = sym;
+ return 0;
+ } else {
+ /* Otherwise, we must be careful to use only the bits that are
+ * actually remaining. Don't inline this part since it is very
+ * rarely used. */
+ return read_huffsym_near_end_of_input(stream, decode_table, lengths,
+ num_symbols, table_bits, n);
+ }
+}
git://wimlib.net / wimlib / blobdiff