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
81  * zstd_default_clevel() - default compression level
88  * struct zstd_custom_mem - custom memory allocation
93  * struct zstd_dict_load_method - Dictionary load method.
99  * struct zstd_dict_content_type - Dictionary context type.
107  * enum zstd_strategy - zstd compression search strategy
114  * struct zstd_compression_parameters - zstd compression parameters
124  * @targetLength: Acceptable match size for optimal parser (only). Larger means
133  * struct zstd_frame_parameters - zstd frame parameters
134  * @contentSizeFlag: Controls whether content size will be present in the
136  * @checksumFlag:    Controls whether a 32-bit checksum is generated at the
146  * struct zstd_parameters - zstd parameters
153  * zstd_get_params() - returns zstd_parameters for selected level
155  * @estimated_src_size: The estimated source size to compress or 0
165  * zstd_get_cparams() - returns zstd_compression_parameters for selected level
167  * @estimated_src_size: The estimated source size to compress or 0
169  * @dict_size:          Dictionary size.
176 /* ======   Single-pass Compression   ====== */
181  * zstd_cctx_workspace_bound() - max memory needed to initialize a zstd_cctx
186  * size.
188  * Return:      A lower bound on the size of the workspace that is passed to
194  * zstd_init_cctx() - initialize a zstd compression context
197  * @workspace_size: The size of workspace. Use zstd_cctx_workspace_bound() to
205  * zstd_compress_cctx() - compress src into dst with the initialized parameters
207  * @dst:          The buffer to compress src into.
208  * @dst_capacity: The size of the destination buffer. May be any size, but
211  * @src_size:     The size of the data to compress.
214  * Return:        The compressed size or an error, which can be checked using
221  * zstd_create_cctx_advanced() - Create compression context
229  * zstd_free_cctx() - Free compression context
237  * struct zstd_cdict - Compression dictionary.
243  * zstd_create_cdict_byreference() - Create compression dictionary
244  * @dict:              Pointer to dictionary buffer.
245  * @dict_size:         Size of the dictionary buffer.
261  * zstd_free_cdict() - Free compression dictionary
269  * zstd_compress_using_cdict() - compress src into dst using a dictionary
271  * @dst:          The buffer to compress src into.
272  * @dst_capacity: The size of the destination buffer. May be any size, but
275  * @src_size:     The size of the data to compress.
278  * Return:        The compressed size or an error, which can be checked using
285 /* ======   Single-pass Decompression   ====== */
290  * zstd_dctx_workspace_bound() - max memory needed to initialize a zstd_dctx
292  * Return: A lower bound on the size of the workspace that is passed to
298  * zstd_init_dctx() - initialize a zstd decompression context
301  * @workspace_size: The size of workspace. Use zstd_dctx_workspace_bound() to
309  * zstd_decompress_dctx() - decompress zstd compressed src into dst
311  * @dst:          The buffer to decompress src into.
312  * @dst_capacity: The size of the destination buffer. Must be at least as large
313  *                as the decompressed size. If the caller cannot upper bound the
314  *                decompressed size, then it's better to use the streaming API.
317  * @src_size:     The exact size of the data to decompress.
319  * Return:        The decompressed size or an error, which can be checked using
326  * struct zstd_ddict - Decompression dictionary.
332  * zstd_create_ddict_byreference() - Create decompression dictionary
333  * @dict:              Pointer to dictionary buffer.
334  * @dict_size:         Size of the dictionary buffer.
348  * zstd_free_ddict() - Free decompression dictionary
356  * zstd_create_dctx_advanced() - Create decompression context
364  * zstd_free_dctx() -- Free decompression context
371  * zstd_decompress_using_ddict() - decompress src into dst using a dictionary
373  * @dst:          The buffer to decompress src into.
374  * @dst_capacity: The size of the destination buffer. Must be at least as large
375  *                as the decompressed size. If the caller cannot upper bound the
376  *                decompressed size, then it's better to use the streaming API.
379  * @src_size:     The exact size of the data to decompress.
382  * Return:        The decompressed size or an error, which can be checked using
393  * struct zstd_in_buffer - input buffer for streaming
394  * @src:  Start of the input buffer.
395  * @size: Size of the input buffer.
397  *        Necessarily 0 <= pos <= size.
404  * struct zstd_out_buffer - output buffer for streaming
405  * @dst:  Start of the output buffer.
406  * @size: Size of the output buffer.
408  *        Necessarily 0 <= pos <= size.
419  * zstd_cstream_workspace_bound() - memory needed to initialize a zstd_cstream
422  * Return:   A lower bound on the size of the workspace that is passed to
428  * zstd_init_cstream() - initialize a zstd streaming compression context
431  *                    must pass the source size (zero means empty source).
433  *                    size, or zero if unknown.
436  * @workspace_size:   The size of workspace.
437  *                    Use zstd_cstream_workspace_bound(params->cparams) to
446  * zstd_reset_cstream() - reset the context using parameters from creation
448  * @pledged_src_size: Optionally the source size, or zero if unknown.
451  * loading, since it can be reused. If `pledged_src_size` is non-zero the frame
452  * content size is always written into the frame header.
461  * zstd_compress_stream() - streaming compress some of input into output
463  * @output:  Destination buffer. `output->pos` is updated to indicate how much
465  * @input:   Source buffer. `input->pos` is updated to indicate how much data
467  *           case `input->pos < input->size`, and it's up to the caller to
470  * The `input` and `output` buffers may be any size. Guaranteed to make some
481  * zstd_flush_stream() - flush internal buffers into output
483  * @output:  Destination buffer. `output->pos` is updated to indicate how much
496  * zstd_end_stream() - flush internal buffers into output and end the frame
498  * @output:  Destination buffer. `output->pos` is updated to indicate how much
514  * zstd_dstream_workspace_bound() - memory needed to initialize a zstd_dstream
515  * @max_window_size: The maximum window size allowed for compressed frames.
517  * Return:           A lower bound on the size of the workspace that is passed
523  * zstd_init_dstream() - initialize a zstd streaming decompression context
524  * @max_window_size: The maximum window size allowed for compressed frames.
527  * @workspaceSize:   The size of workspace.
537  * zstd_reset_dstream() - reset the context using parameters from creation
548  * zstd_decompress_stream() - streaming decompress some of input into output
550  * @output:  Destination buffer. `output.pos` is updated to indicate how much
552  * @input:   Source buffer. `input.pos` is updated to indicate how much data was
554  *           `input.pos < input.size`, and it's up to the caller to present
557  * The `input` and `output` buffers may be any size. Guaranteed to make some
565  *           using zstd_is_error(). The size hint will never load more than the
574  * zstd_find_frame_compressed_size() - returns the size of a compressed frame
575  * @src:      Source buffer. It should point to the start of a zstd encoded
577  * @src_size: The size of the source buffer. It must be at least as large as the
578  *            size of the frame.
580  * Return:    The compressed size of the frame pointed to by `src` or an error,
587  * struct zstd_frame_params - zstd frame parameters stored in the frame header
588  * @frameContentSize: The frame content size, or ZSTD_CONTENTSIZE_UNKNOWN if not
590  * @windowSize:       The window size, or 0 if the frame is a skippable frame.
591  * @blockSizeMax:     The maximum block size.
593  * @headerSize:       The size of the frame header.
602  * zstd_get_frame_header() - extracts parameters from a zstd or skippable frame
604  * @src:      The source buffer. It must point to a zstd or skippable frame.
605  * @src_size: The size of the source buffer.