include/linux/zstd.h

1 /* SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause */
6  * This source code is licensed under both the BSD-style license (found in the
10  * above-listed licenses.
17  * This is a kernel-style API that wraps the upstream zstd API, which cannot be
30  * zstd_compress_bound() - maximum compressed size in worst case scenario
31  * @src_size: The size of the data to compress.
33  * Return:    The maximum compressed size in the worst case scenario.
38  * zstd_is_error() - tells if a size_t function result is an error code
41  * Return: Non-zero iff the code is an error.
46  * enum zstd_error_code - zstd error codes
51  * zstd_get_error_code() - translates an error function result to an error code
59  * zstd_get_error_name() - translates an error function result to a string
67  * zstd_min_clevel() - minimum allowed compression level
74  * zstd_max_clevel() - maximum allowed compression level
83  * enum zstd_strategy - zstd compression search strategy
90  * struct zstd_compression_parameters - zstd compression parameters
100  * @targetLength: Acceptable match size for optimal parser (only). Larger means
109  * struct zstd_frame_parameters - zstd frame parameters
110  * @contentSizeFlag: Controls whether content size will be present in the
111  *                   frame header (when known).
112  * @checksumFlag:    Controls whether a 32-bit checksum is generated at the
113  *                   end of the frame for error detection.
114  * @noDictIDFlag:    Controls whether dictID will be saved into the frame
122  * struct zstd_parameters - zstd parameters
124  * @fParams: The frame parameters.
129  * zstd_get_params() - returns zstd_parameters for selected level
131  * @estimated_src_size: The estimated source size to compress or 0
139 /* ======   Single-pass Compression   ====== */
144  * zstd_cctx_workspace_bound() - max memory needed to initialize a zstd_cctx
149  * size.
151  * Return:      A lower bound on the size of the workspace that is passed to
157  * zstd_init_cctx() - initialize a zstd compression context
160  * @workspace_size: The size of workspace. Use zstd_cctx_workspace_bound() to
168  * zstd_compress_cctx() - compress src into dst with the initialized parameters
171  * @dst_capacity: The size of the destination buffer. May be any size, but
174  * @src_size:     The size of the data to compress.
177  * Return:        The compressed size or an error, which can be checked using
183 /* ======   Single-pass Decompression   ====== */
188  * zstd_dctx_workspace_bound() - max memory needed to initialize a zstd_dctx
190  * Return: A lower bound on the size of the workspace that is passed to
196  * zstd_init_dctx() - initialize a zstd decompression context
199  * @workspace_size: The size of workspace. Use zstd_dctx_workspace_bound() to
207  * zstd_decompress_dctx() - decompress zstd compressed src into dst
210  * @dst_capacity: The size of the destination buffer. Must be at least as large
211  *                as the decompressed size. If the caller cannot upper bound the
212  *                decompressed size, then it's better to use the streaming API.
215  * @src_size:     The exact size of the data to decompress.
217  * Return:        The decompressed size or an error, which can be checked using
226  * struct zstd_in_buffer - input buffer for streaming
228  * @size: Size of the input buffer.
230  *        Necessarily 0 <= pos <= size.
237  * struct zstd_out_buffer - output buffer for streaming
239  * @size: Size of the output buffer.
241  *        Necessarily 0 <= pos <= size.
252  * zstd_cstream_workspace_bound() - memory needed to initialize a zstd_cstream
255  * Return:   A lower bound on the size of the workspace that is passed to
261  * zstd_init_cstream() - initialize a zstd streaming compression context
264  *                    must pass the source size (zero means empty source).
266  *                    size, or zero if unknown.
269  * @workspace_size:   The size of workspace.
270  *                    Use zstd_cstream_workspace_bound(params->cparams) to
279  * zstd_reset_cstream() - reset the context using parameters from creation
281  * @pledged_src_size: Optionally the source size, or zero if unknown.
284  * loading, since it can be reused. If `pledged_src_size` is non-zero the frame
285  * content size is always written into the frame header.
294  * zstd_compress_stream() - streaming compress some of input into output
296  * @output:  Destination buffer. `output->pos` is updated to indicate how much
298  * @input:   Source buffer. `input->pos` is updated to indicate how much data
300  *           case `input->pos < input->size`, and it's up to the caller to
303  * The `input` and `output` buffers may be any size. Guaranteed to make some
314  * zstd_flush_stream() - flush internal buffers into output
316  * @output:  Destination buffer. `output->pos` is updated to indicate how much
329  * zstd_end_stream() - flush internal buffers into output and end the frame
331  * @output:  Destination buffer. `output->pos` is updated to indicate how much
335  * been flushed and the frame epilogue has been written.
347  * zstd_dstream_workspace_bound() - memory needed to initialize a zstd_dstream
348  * @max_window_size: The maximum window size allowed for compressed frames.
350  * Return:           A lower bound on the size of the workspace that is passed
356  * zstd_init_dstream() - initialize a zstd streaming decompression context
357  * @max_window_size: The maximum window size allowed for compressed frames.
360  * @workspaceSize:   The size of workspace.
370  * zstd_reset_dstream() - reset the context using parameters from creation
381  * zstd_decompress_stream() - streaming decompress some of input into output
387  *           `input.pos < input.size`, and it's up to the caller to present
390  * The `input` and `output` buffers may be any size. Guaranteed to make some
392  * zstd_decompress_stream() will not consume the last byte of the frame until
393  * the entire frame is flushed.
395  * Return:   Returns 0 iff a frame is completely decoded and fully flushed.
398  *           using zstd_is_error(). The size hint will never load more than the
399  *           frame.
404 /* ======   Frame Inspection Functions ====== */
407  * zstd_find_frame_compressed_size() - returns the size of a compressed frame
409  *            frame or a skippable frame.
410  * @src_size: The size of the source buffer. It must be at least as large as the
411  *            size of the frame.
413  * Return:    The compressed size of the frame pointed to by `src` or an error,
420  * struct zstd_frame_params - zstd frame parameters stored in the frame header
421  * @frameContentSize: The frame content size, or ZSTD_CONTENTSIZE_UNKNOWN if not
423  * @windowSize:       The window size, or 0 if the frame is a skippable frame.
424  * @blockSizeMax:     The maximum block size.
425  * @frameType:        The frame type (zstd or skippable)
426  * @headerSize:       The size of the frame header.
435  * zstd_get_frame_header() - extracts parameters from a zstd or skippable frame
436  * @params:   On success the frame parameters are written here.
437  * @src:      The source buffer. It must point to a zstd or skippable frame.
438  * @src_size: The size of the source buffer.