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
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
133  * struct zstd_frame_parameters - zstd frame parameters
135  *                   frame header (when known).
136  * @checksumFlag:    Controls whether a 32-bit checksum is generated at the
137  *                   end of the frame for error detection.
138  * @noDictIDFlag:    Controls whether dictID will be saved into the frame
146  * struct zstd_parameters - zstd parameters
148  * @fParams: The frame parameters.
153  * zstd_get_params() - returns zstd_parameters for selected level
164  * zstd_get_cparams() - returns zstd_compression_parameters for selected level
179  * zstd_cctx_set_param() - sets a compression parameter
188 /* ======   Single-pass Compression   ====== */
191  * zstd_cctx_workspace_bound() - max memory needed to initialize a zstd_cctx
204  * zstd_cctx_workspace_bound_with_ext_seq_prod() - max memory needed to
205  * initialize a zstd_cctx when using the block-level external sequence
218  * zstd_init_cctx() - initialize a zstd compression context
229  * zstd_compress_cctx() - compress src into dst with the initialized parameters
231  * @dst:          The buffer to compress src into.
232  * @dst_capacity: The size of the destination buffer. May be any size, but
245  * zstd_create_cctx_advanced() - Create compression context
253  * zstd_free_cctx() - Free compression context
261  * struct zstd_cdict - Compression dictionary.
267  * zstd_create_cdict_byreference() - Create compression dictionary
268  * @dict:              Pointer to dictionary buffer.
269  * @dict_size:         Size of the dictionary buffer.
285  * zstd_free_cdict() - Free compression dictionary
293  * zstd_compress_using_cdict() - compress src into dst using a dictionary
295  * @dst:          The buffer to compress src into.
296  * @dst_capacity: The size of the destination buffer. May be any size, but
309 /* ======   Single-pass Decompression   ====== */
314  * zstd_dctx_workspace_bound() - max memory needed to initialize a zstd_dctx
322  * zstd_init_dctx() - initialize a zstd decompression context
333  * zstd_decompress_dctx() - decompress zstd compressed src into dst
335  * @dst:          The buffer to decompress src into.
336  * @dst_capacity: The size of the destination buffer. Must be at least as large
350  * struct zstd_ddict - Decompression dictionary.
356  * zstd_create_ddict_byreference() - Create decompression dictionary
357  * @dict:              Pointer to dictionary buffer.
358  * @dict_size:         Size of the dictionary buffer.
372  * zstd_free_ddict() - Free decompression dictionary
380  * zstd_create_dctx_advanced() - Create decompression context
388  * zstd_free_dctx() -- Free decompression context
395  * zstd_decompress_using_ddict() - decompress src into dst using a dictionary
397  * @dst:          The buffer to decompress src into.
398  * @dst_capacity: The size of the destination buffer. Must be at least as large
417  * struct zstd_in_buffer - input buffer for streaming
418  * @src:  Start of the input buffer.
419  * @size: Size of the input buffer.
428  * struct zstd_out_buffer - output buffer for streaming
429  * @dst:  Start of the output buffer.
430  * @size: Size of the output buffer.
443  * zstd_cstream_workspace_bound() - memory needed to initialize a zstd_cstream
452  * zstd_cstream_workspace_bound_with_ext_seq_prod() - memory needed to initialize
453  * a zstd_cstream when using the block-level external sequence producer API.
462  * zstd_init_cstream() - initialize a zstd streaming compression context
471  *                    Use zstd_cstream_workspace_bound(params->cparams) to
480  * zstd_reset_cstream() - reset the context using parameters from creation
485  * loading, since it can be reused. If `pledged_src_size` is non-zero the frame
486  * content size is always written into the frame header.
495  * zstd_compress_stream() - streaming compress some of input into output
497  * @output:  Destination buffer. `output->pos` is updated to indicate how much
499  * @input:   Source buffer. `input->pos` is updated to indicate how much data
501  *           case `input->pos < input->size`, and it's up to the caller to
515  * zstd_flush_stream() - flush internal buffers into output
517  * @output:  Destination buffer. `output->pos` is updated to indicate how much
530  * zstd_end_stream() - flush internal buffers into output and end the frame
532  * @output:  Destination buffer. `output->pos` is updated to indicate how much
536  * been flushed and the frame epilogue has been written.
548  * zstd_dstream_workspace_bound() - memory needed to initialize a zstd_dstream
557  * zstd_init_dstream() - initialize a zstd streaming decompression context
571  * zstd_reset_dstream() - reset the context using parameters from creation
582  * zstd_decompress_stream() - streaming decompress some of input into output
584  * @output:  Destination buffer. `output.pos` is updated to indicate how much
586  * @input:   Source buffer. `input.pos` is updated to indicate how much data was
593  * zstd_decompress_stream() will not consume the last byte of the frame until
594  * the entire frame is flushed.
596  * Return:   Returns 0 iff a frame is completely decoded and fully flushed.
600  *           frame.
605 /* ======   Frame Inspection Functions ====== */
608  * zstd_find_frame_compressed_size() - returns the size of a compressed frame
609  * @src:      Source buffer. It should point to the start of a zstd encoded
610  *            frame or a skippable frame.
611  * @src_size: The size of the source buffer. It must be at least as large as the
612  *            size of the frame.
614  * Return:    The compressed size of the frame pointed to by `src` or an error,
621  * zstd_register_sequence_producer() - exposes the zstd library function
622  * ZSTD_registerSequenceProducer(). This is used for the block-level external
633  * struct zstd_frame_params - zstd frame parameters stored in the frame header
634  * @frameContentSize: The frame content size, or ZSTD_CONTENTSIZE_UNKNOWN if not
636  * @windowSize:       The window size, or 0 if the frame is a skippable frame.
638  * @frameType:        The frame type (zstd or skippable)
639  * @headerSize:       The size of the frame header.
648  * zstd_get_frame_header() - extracts parameters from a zstd or skippable frame
649  * @params:   On success the frame parameters are written here.
650  * @src:      The source buffer. It must point to a zstd or skippable frame.
651  * @src_size: The size of the source buffer.
661  * struct zstd_sequence - a sequence of literals or a match
671  * zstd_compress_sequences_and_literals() - compress an array of zstd_sequence and literals
674  * @dst: The buffer to compress the data into.
675  * @dst_capacity: The size of the destination buffer.
679  * @lit_size: The size of the literals in the literals buffer.
680  * @lit_capacity: The size of the literals buffer.