include/linux/xz.h

1 /* SPDX-License-Identifier: 0BSD */
7  *          Igor Pavlov <https://7-zip.org/>
22  * enum xz_mode - Operation mode
24  * @XZ_SINGLE:              Single-call mode. This uses less RAM than
25  *                          multi-call modes, because the LZMA2
30  * @XZ_PREALLOC:            Multi-call mode with preallocated LZMA2
34  * @XZ_DYNALLOC:            Multi-call mode. The LZMA2 dictionary is
40  * It is possible to enable support only for a subset of the above
53  * enum xz_ret - Return codes
54  * @XZ_OK:                  Everything is OK so far. More input or more
56  *                          return code is possible only in multi-call mode
60  *                          is still possible in multi-call mode by simply
62  *                          Note that this return value is used only if
68  *                          possible only if the decoder was initialized
75  *                          only in multi-call mode (XZ_PREALLOC or
76  *                          XZ_DYNALLOC); the single-call mode (XZ_SINGLE)
86  *                          different between multi-call and single-call
89  * In multi-call mode, XZ_BUF_ERROR is returned when two consecutive calls
90  * to XZ code cannot consume any input and cannot produce any new output.
91  * This happens when there is no new input available, or the output buffer
93  * code is not buggy, you can get this error only when decoding a compressed
96  * In single-call mode, XZ_BUF_ERROR is returned only when the output buffer
97  * is too small or the compressed input is corrupt in a way that makes the
99  * (relatively) clear that the compressed input is truncated, XZ_DATA_ERROR
115  * struct xz_buf - Passing input and output buffers to XZ code
116  * @in:         Beginning of the input buffer. This may be NULL if and only
118  * @in_pos:     Current position in the input buffer. This must not exceed
120  * @in_size:    Size of the input buffer
121  * @out:        Beginning of the output buffer. This may be NULL if and only
127  * Only the contents of the output buffer from out[out_pos] onward, and
141  * struct xz_dec - Opaque type to hold the XZ decoder state
146  * xz_dec_init() - Allocate and initialize a XZ decoder state
149  *              multi-call decoding. This is ignored in single-call mode
151  *              or 2^n + 2^(n-1) bytes (the latter sizes are less common
154  *              512 KiB, and 1 MiB are probably the only reasonable values,
158  * Single-call mode (XZ_SINGLE): xz_dec_run() decodes the whole stream at
165  * a big dictionary are not a problem in single-call mode. It is enough that
169  * Multi-call mode with preallocated dictionary (XZ_PREALLOC): dict_max bytes
173  * small for decoding the given input stream, xz_dec_run() will return
177  * Multi-call mode with dynamically allocated dictionary (XZ_DYNALLOC):
191  * xz_dec_run() - Run the XZ decoder
193  * @b:          Input and output buffers
198  * Note that if an error occurs in single-call mode (return value is not
199  * XZ_STREAM_END), b->in_pos and b->out_pos are not modified and the
200  * contents of the output buffer from b->out[b->out_pos] onward are
204  * cannot give the single-call decoder a too small buffer and then expect to
206  * the multi-call decoder if you don't want to uncompress the whole stream.
211  * xz_dec_reset() - Reset an already allocated decoder state
214  * This function can be used to reset the multi-call decoder state without
217  * In single-call mode, xz_dec_reset() is always called in the beginning of
218  * xz_dec_run(). Thus, explicit call to xz_dec_reset() is useful only in
219  * multi-call mode.
224  * xz_dec_end() - Free the memory allocated for the decoder state
237  * whose first byte (always 0x00) has been replaced with bitwise-negation
240  * Just like with LZMA2, lc + lp <= 4 must be true. The LZMA end-of-stream
245  * struct xz_dec_microlzma - Opaque type to hold the MicroLZMA decoder state
250  * xz_dec_microlzma_alloc() - Allocate memory for the MicroLZMA decoder
255  * In contrast to xz_dec_init(), this function only allocates the memory
270  * xz_dec_microlzma_reset() - Reset the MicroLZMA decoder state
272  * @comp_size:  Compressed size of the input stream
273  * @uncomp_size:  Uncompressed size of the input stream. A value smaller
274  *              than the real uncompressed size of the input stream can
287  * xz_dec_microlzma_run() - Run the MicroLZMA decoder
289  * @b:          Input and output buffers
292  * Only the differences are documented here.
294  * The only possible return values are XZ_OK, XZ_STREAM_END, and
296  * is possible due to lack of input data or output space, this function will
298  * will eventually provide input and output space matching (or exceeding)
300  * If the caller cannot do this (for example, if the input file is truncated
308  * With XZ_PREALLOC only: As an extra feature, b->out may be NULL to skip over
312  * With XZ_SINGLE only: In contrast to xz_dec_run(), the return value XZ_OK
313  * is also possible and thus XZ_SINGLE is actually a limited multi-call mode.
315  * It is possible to continue decoding but the variables b->out and b->out_pos
316  * MUST NOT be changed by the caller. Increasing the value of b->out_size is
318  * space for the whole uncompressed data on the first call. The input buffer
319  * may be changed normally like with XZ_PREALLOC. This way input data can be
320  * provided from non-contiguous memory.
325  * xz_dec_microlzma_end() - Free the memory allocated for the decoder state
332  * Standalone build (userspace build or in-kernel build for boot time use)
333  * needs a CRC32 implementation. For normal in-kernel use, kernel's own
353  * Update CRC32 value using the polynomial from IEEE-802.3. To start a new