1*e0c1b49fSNick Terrell /* SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause */ 273f3d1b4SNick Terrell /* 3cf30f6a5SNick Terrell * Copyright (c) Yann Collet, Facebook, Inc. 473f3d1b4SNick Terrell * All rights reserved. 573f3d1b4SNick Terrell * 6cf30f6a5SNick Terrell * This source code is licensed under both the BSD-style license (found in the 7cf30f6a5SNick Terrell * LICENSE file in the root directory of https://github.com/facebook/zstd) and 8cf30f6a5SNick Terrell * the GPLv2 (found in the COPYING file in the root directory of 9cf30f6a5SNick Terrell * https://github.com/facebook/zstd). You may select, at your option, one of the 10cf30f6a5SNick Terrell * above-listed licenses. 1173f3d1b4SNick Terrell */ 1273f3d1b4SNick Terrell 13cf30f6a5SNick Terrell #ifndef LINUX_ZSTD_H 14cf30f6a5SNick Terrell #define LINUX_ZSTD_H 15cf30f6a5SNick Terrell 16cf30f6a5SNick Terrell /** 17cf30f6a5SNick Terrell * This is a kernel-style API that wraps the upstream zstd API, which cannot be 18cf30f6a5SNick Terrell * used directly because the symbols aren't exported. It exposes the minimal 19cf30f6a5SNick Terrell * functionality which is currently required by users of zstd in the kernel. 20cf30f6a5SNick Terrell * Expose extra functions from lib/zstd/zstd.h as needed. 21cf30f6a5SNick Terrell */ 2273f3d1b4SNick Terrell 2373f3d1b4SNick Terrell /* ====== Dependency ====== */ 24cf30f6a5SNick Terrell #include <linux/types.h> 25*e0c1b49fSNick Terrell #include <linux/zstd_errors.h> 26cf30f6a5SNick Terrell #include <linux/zstd_lib.h> 2773f3d1b4SNick Terrell 28cf30f6a5SNick Terrell /* ====== Helper Functions ====== */ 2973f3d1b4SNick Terrell /** 30cf30f6a5SNick Terrell * zstd_compress_bound() - maximum compressed size in worst case scenario 31cf30f6a5SNick Terrell * @src_size: The size of the data to compress. 3273f3d1b4SNick Terrell * 3373f3d1b4SNick Terrell * Return: The maximum compressed size in the worst case scenario. 3473f3d1b4SNick Terrell */ 35cf30f6a5SNick Terrell size_t zstd_compress_bound(size_t src_size); 36cf30f6a5SNick Terrell 3773f3d1b4SNick Terrell /** 38cf30f6a5SNick Terrell * zstd_is_error() - tells if a size_t function result is an error code 3973f3d1b4SNick Terrell * @code: The function result to check for error. 4073f3d1b4SNick Terrell * 4173f3d1b4SNick Terrell * Return: Non-zero iff the code is an error. 4273f3d1b4SNick Terrell */ 43cf30f6a5SNick Terrell unsigned int zstd_is_error(size_t code); 4473f3d1b4SNick Terrell 4573f3d1b4SNick Terrell /** 46cf30f6a5SNick Terrell * enum zstd_error_code - zstd error codes 4773f3d1b4SNick Terrell */ 48cf30f6a5SNick Terrell typedef ZSTD_ErrorCode zstd_error_code; 4973f3d1b4SNick Terrell 5073f3d1b4SNick Terrell /** 51cf30f6a5SNick Terrell * zstd_get_error_code() - translates an error function result to an error code 52cf30f6a5SNick Terrell * @code: The function result for which zstd_is_error(code) is true. 53cf30f6a5SNick Terrell * 54cf30f6a5SNick Terrell * Return: A unique error code for this error. 55cf30f6a5SNick Terrell */ 56cf30f6a5SNick Terrell zstd_error_code zstd_get_error_code(size_t code); 57cf30f6a5SNick Terrell 58cf30f6a5SNick Terrell /** 59cf30f6a5SNick Terrell * zstd_get_error_name() - translates an error function result to a string 60cf30f6a5SNick Terrell * @code: The function result for which zstd_is_error(code) is true. 61cf30f6a5SNick Terrell * 62cf30f6a5SNick Terrell * Return: An error string corresponding to the error code. 63cf30f6a5SNick Terrell */ 64cf30f6a5SNick Terrell const char *zstd_get_error_name(size_t code); 65cf30f6a5SNick Terrell 66cf30f6a5SNick Terrell /** 67cf30f6a5SNick Terrell * zstd_min_clevel() - minimum allowed compression level 68cf30f6a5SNick Terrell * 69cf30f6a5SNick Terrell * Return: The minimum allowed compression level. 70cf30f6a5SNick Terrell */ 71cf30f6a5SNick Terrell int zstd_min_clevel(void); 72cf30f6a5SNick Terrell 73cf30f6a5SNick Terrell /** 74cf30f6a5SNick Terrell * zstd_max_clevel() - maximum allowed compression level 75cf30f6a5SNick Terrell * 76cf30f6a5SNick Terrell * Return: The maximum allowed compression level. 77cf30f6a5SNick Terrell */ 78cf30f6a5SNick Terrell int zstd_max_clevel(void); 79cf30f6a5SNick Terrell 80cf30f6a5SNick Terrell /* ====== Parameter Selection ====== */ 81cf30f6a5SNick Terrell 82cf30f6a5SNick Terrell /** 83cf30f6a5SNick Terrell * enum zstd_strategy - zstd compression search strategy 84cf30f6a5SNick Terrell * 85cf30f6a5SNick Terrell * From faster to stronger. See zstd_lib.h. 86cf30f6a5SNick Terrell */ 87cf30f6a5SNick Terrell typedef ZSTD_strategy zstd_strategy; 88cf30f6a5SNick Terrell 89cf30f6a5SNick Terrell /** 90cf30f6a5SNick Terrell * struct zstd_compression_parameters - zstd compression parameters 9173f3d1b4SNick Terrell * @windowLog: Log of the largest match distance. Larger means more 9273f3d1b4SNick Terrell * compression, and more memory needed during decompression. 93cf30f6a5SNick Terrell * @chainLog: Fully searched segment. Larger means more compression, 94cf30f6a5SNick Terrell * slower, and more memory (useless for fast). 9573f3d1b4SNick Terrell * @hashLog: Dispatch table. Larger means more compression, 9673f3d1b4SNick Terrell * slower, and more memory. 9773f3d1b4SNick Terrell * @searchLog: Number of searches. Larger means more compression and slower. 9873f3d1b4SNick Terrell * @searchLength: Match length searched. Larger means faster decompression, 9973f3d1b4SNick Terrell * sometimes less compression. 10073f3d1b4SNick Terrell * @targetLength: Acceptable match size for optimal parser (only). Larger means 10173f3d1b4SNick Terrell * more compression, and slower. 10273f3d1b4SNick Terrell * @strategy: The zstd compression strategy. 10373f3d1b4SNick Terrell * 104cf30f6a5SNick Terrell * See zstd_lib.h. 10573f3d1b4SNick Terrell */ 106cf30f6a5SNick Terrell typedef ZSTD_compressionParameters zstd_compression_parameters; 10773f3d1b4SNick Terrell 10873f3d1b4SNick Terrell /** 109cf30f6a5SNick Terrell * struct zstd_frame_parameters - zstd frame parameters 110cf30f6a5SNick Terrell * @contentSizeFlag: Controls whether content size will be present in the 111cf30f6a5SNick Terrell * frame header (when known). 112cf30f6a5SNick Terrell * @checksumFlag: Controls whether a 32-bit checksum is generated at the 113cf30f6a5SNick Terrell * end of the frame for error detection. 114cf30f6a5SNick Terrell * @noDictIDFlag: Controls whether dictID will be saved into the frame 115cf30f6a5SNick Terrell * header when using dictionary compression. 116cf30f6a5SNick Terrell * 117cf30f6a5SNick Terrell * The default value is all fields set to 0. See zstd_lib.h. 118cf30f6a5SNick Terrell */ 119cf30f6a5SNick Terrell typedef ZSTD_frameParameters zstd_frame_parameters; 120cf30f6a5SNick Terrell 121cf30f6a5SNick Terrell /** 122cf30f6a5SNick Terrell * struct zstd_parameters - zstd parameters 12373f3d1b4SNick Terrell * @cParams: The compression parameters. 12473f3d1b4SNick Terrell * @fParams: The frame parameters. 12573f3d1b4SNick Terrell */ 126cf30f6a5SNick Terrell typedef ZSTD_parameters zstd_parameters; 12773f3d1b4SNick Terrell 12873f3d1b4SNick Terrell /** 129cf30f6a5SNick Terrell * zstd_get_params() - returns zstd_parameters for selected level 130cf30f6a5SNick Terrell * @level: The compression level 131cf30f6a5SNick Terrell * @estimated_src_size: The estimated source size to compress or 0 132cf30f6a5SNick Terrell * if unknown. 13373f3d1b4SNick Terrell * 134cf30f6a5SNick Terrell * Return: The selected zstd_parameters. 13573f3d1b4SNick Terrell */ 136cf30f6a5SNick Terrell zstd_parameters zstd_get_params(int level, 137cf30f6a5SNick Terrell unsigned long long estimated_src_size); 138cf30f6a5SNick Terrell 139cf30f6a5SNick Terrell /* ====== Single-pass Compression ====== */ 140cf30f6a5SNick Terrell 141cf30f6a5SNick Terrell typedef ZSTD_CCtx zstd_cctx; 14273f3d1b4SNick Terrell 14373f3d1b4SNick Terrell /** 144cf30f6a5SNick Terrell * zstd_cctx_workspace_bound() - max memory needed to initialize a zstd_cctx 145cf30f6a5SNick Terrell * @parameters: The compression parameters to be used. 14673f3d1b4SNick Terrell * 14773f3d1b4SNick Terrell * If multiple compression parameters might be used, the caller must call 148cf30f6a5SNick Terrell * zstd_cctx_workspace_bound() for each set of parameters and use the maximum 14973f3d1b4SNick Terrell * size. 15073f3d1b4SNick Terrell * 15173f3d1b4SNick Terrell * Return: A lower bound on the size of the workspace that is passed to 152cf30f6a5SNick Terrell * zstd_init_cctx(). 15373f3d1b4SNick Terrell */ 154cf30f6a5SNick Terrell size_t zstd_cctx_workspace_bound(const zstd_compression_parameters *parameters); 15573f3d1b4SNick Terrell 15673f3d1b4SNick Terrell /** 157cf30f6a5SNick Terrell * zstd_init_cctx() - initialize a zstd compression context 15873f3d1b4SNick Terrell * @workspace: The workspace to emplace the context into. It must outlive 15973f3d1b4SNick Terrell * the returned context. 160cf30f6a5SNick Terrell * @workspace_size: The size of workspace. Use zstd_cctx_workspace_bound() to 16173f3d1b4SNick Terrell * determine how large the workspace must be. 16273f3d1b4SNick Terrell * 163cf30f6a5SNick Terrell * Return: A zstd compression context or NULL on error. 16473f3d1b4SNick Terrell */ 165cf30f6a5SNick Terrell zstd_cctx *zstd_init_cctx(void *workspace, size_t workspace_size); 16673f3d1b4SNick Terrell 16773f3d1b4SNick Terrell /** 168cf30f6a5SNick Terrell * zstd_compress_cctx() - compress src into dst with the initialized parameters 169cf30f6a5SNick Terrell * @cctx: The context. Must have been initialized with zstd_init_cctx(). 17073f3d1b4SNick Terrell * @dst: The buffer to compress src into. 171cf30f6a5SNick Terrell * @dst_capacity: The size of the destination buffer. May be any size, but 17273f3d1b4SNick Terrell * ZSTD_compressBound(srcSize) is guaranteed to be large enough. 17373f3d1b4SNick Terrell * @src: The data to compress. 174cf30f6a5SNick Terrell * @src_size: The size of the data to compress. 175cf30f6a5SNick Terrell * @parameters: The compression parameters to be used. 17673f3d1b4SNick Terrell * 17773f3d1b4SNick Terrell * Return: The compressed size or an error, which can be checked using 178cf30f6a5SNick Terrell * zstd_is_error(). 17973f3d1b4SNick Terrell */ 180cf30f6a5SNick Terrell size_t zstd_compress_cctx(zstd_cctx *cctx, void *dst, size_t dst_capacity, 181cf30f6a5SNick Terrell const void *src, size_t src_size, const zstd_parameters *parameters); 182cf30f6a5SNick Terrell 183cf30f6a5SNick Terrell /* ====== Single-pass Decompression ====== */ 184cf30f6a5SNick Terrell 185cf30f6a5SNick Terrell typedef ZSTD_DCtx zstd_dctx; 18673f3d1b4SNick Terrell 18773f3d1b4SNick Terrell /** 188cf30f6a5SNick Terrell * zstd_dctx_workspace_bound() - max memory needed to initialize a zstd_dctx 18973f3d1b4SNick Terrell * 19073f3d1b4SNick Terrell * Return: A lower bound on the size of the workspace that is passed to 191cf30f6a5SNick Terrell * zstd_init_dctx(). 19273f3d1b4SNick Terrell */ 193cf30f6a5SNick Terrell size_t zstd_dctx_workspace_bound(void); 19473f3d1b4SNick Terrell 19573f3d1b4SNick Terrell /** 196cf30f6a5SNick Terrell * zstd_init_dctx() - initialize a zstd decompression context 19773f3d1b4SNick Terrell * @workspace: The workspace to emplace the context into. It must outlive 19873f3d1b4SNick Terrell * the returned context. 199cf30f6a5SNick Terrell * @workspace_size: The size of workspace. Use zstd_dctx_workspace_bound() to 20073f3d1b4SNick Terrell * determine how large the workspace must be. 20173f3d1b4SNick Terrell * 202cf30f6a5SNick Terrell * Return: A zstd decompression context or NULL on error. 20373f3d1b4SNick Terrell */ 204cf30f6a5SNick Terrell zstd_dctx *zstd_init_dctx(void *workspace, size_t workspace_size); 20573f3d1b4SNick Terrell 20673f3d1b4SNick Terrell /** 207cf30f6a5SNick Terrell * zstd_decompress_dctx() - decompress zstd compressed src into dst 208cf30f6a5SNick Terrell * @dctx: The decompression context. 20973f3d1b4SNick Terrell * @dst: The buffer to decompress src into. 210cf30f6a5SNick Terrell * @dst_capacity: The size of the destination buffer. Must be at least as large 21173f3d1b4SNick Terrell * as the decompressed size. If the caller cannot upper bound the 21273f3d1b4SNick Terrell * decompressed size, then it's better to use the streaming API. 21373f3d1b4SNick Terrell * @src: The zstd compressed data to decompress. Multiple concatenated 21473f3d1b4SNick Terrell * frames and skippable frames are allowed. 215cf30f6a5SNick Terrell * @src_size: The exact size of the data to decompress. 21673f3d1b4SNick Terrell * 21773f3d1b4SNick Terrell * Return: The decompressed size or an error, which can be checked using 218cf30f6a5SNick Terrell * zstd_is_error(). 21973f3d1b4SNick Terrell */ 220cf30f6a5SNick Terrell size_t zstd_decompress_dctx(zstd_dctx *dctx, void *dst, size_t dst_capacity, 221cf30f6a5SNick Terrell const void *src, size_t src_size); 22273f3d1b4SNick Terrell 223cf30f6a5SNick Terrell /* ====== Streaming Buffers ====== */ 22473f3d1b4SNick Terrell 22573f3d1b4SNick Terrell /** 226cf30f6a5SNick Terrell * struct zstd_in_buffer - input buffer for streaming 22773f3d1b4SNick Terrell * @src: Start of the input buffer. 22873f3d1b4SNick Terrell * @size: Size of the input buffer. 22973f3d1b4SNick Terrell * @pos: Position where reading stopped. Will be updated. 23073f3d1b4SNick Terrell * Necessarily 0 <= pos <= size. 231cf30f6a5SNick Terrell * 232cf30f6a5SNick Terrell * See zstd_lib.h. 23373f3d1b4SNick Terrell */ 234cf30f6a5SNick Terrell typedef ZSTD_inBuffer zstd_in_buffer; 23573f3d1b4SNick Terrell 23673f3d1b4SNick Terrell /** 237cf30f6a5SNick Terrell * struct zstd_out_buffer - output buffer for streaming 23873f3d1b4SNick Terrell * @dst: Start of the output buffer. 23973f3d1b4SNick Terrell * @size: Size of the output buffer. 24073f3d1b4SNick Terrell * @pos: Position where writing stopped. Will be updated. 24173f3d1b4SNick Terrell * Necessarily 0 <= pos <= size. 242cf30f6a5SNick Terrell * 243cf30f6a5SNick Terrell * See zstd_lib.h. 24473f3d1b4SNick Terrell */ 245cf30f6a5SNick Terrell typedef ZSTD_outBuffer zstd_out_buffer; 24673f3d1b4SNick Terrell 247cf30f6a5SNick Terrell /* ====== Streaming Compression ====== */ 24873f3d1b4SNick Terrell 249cf30f6a5SNick Terrell typedef ZSTD_CStream zstd_cstream; 25073f3d1b4SNick Terrell 25173f3d1b4SNick Terrell /** 252cf30f6a5SNick Terrell * zstd_cstream_workspace_bound() - memory needed to initialize a zstd_cstream 253cf30f6a5SNick Terrell * @cparams: The compression parameters to be used for compression. 25473f3d1b4SNick Terrell * 25573f3d1b4SNick Terrell * Return: A lower bound on the size of the workspace that is passed to 256cf30f6a5SNick Terrell * zstd_init_cstream(). 25773f3d1b4SNick Terrell */ 258cf30f6a5SNick Terrell size_t zstd_cstream_workspace_bound(const zstd_compression_parameters *cparams); 25973f3d1b4SNick Terrell 26073f3d1b4SNick Terrell /** 261cf30f6a5SNick Terrell * zstd_init_cstream() - initialize a zstd streaming compression context 262cf30f6a5SNick Terrell * @parameters The zstd parameters to use for compression. 263cf30f6a5SNick Terrell * @pledged_src_size: If params.fParams.contentSizeFlag == 1 then the caller 264cf30f6a5SNick Terrell * must pass the source size (zero means empty source). 265cf30f6a5SNick Terrell * Otherwise, the caller may optionally pass the source 266cf30f6a5SNick Terrell * size, or zero if unknown. 26773f3d1b4SNick Terrell * @workspace: The workspace to emplace the context into. It must outlive 26873f3d1b4SNick Terrell * the returned context. 269cf30f6a5SNick Terrell * @workspace_size: The size of workspace. 270cf30f6a5SNick Terrell * Use zstd_cstream_workspace_bound(params->cparams) to 271cf30f6a5SNick Terrell * determine how large the workspace must be. 27273f3d1b4SNick Terrell * 273cf30f6a5SNick Terrell * Return: The zstd streaming compression context or NULL on error. 27473f3d1b4SNick Terrell */ 275cf30f6a5SNick Terrell zstd_cstream *zstd_init_cstream(const zstd_parameters *parameters, 276cf30f6a5SNick Terrell unsigned long long pledged_src_size, void *workspace, size_t workspace_size); 27773f3d1b4SNick Terrell 27873f3d1b4SNick Terrell /** 279cf30f6a5SNick Terrell * zstd_reset_cstream() - reset the context using parameters from creation 280cf30f6a5SNick Terrell * @cstream: The zstd streaming compression context to reset. 281cf30f6a5SNick Terrell * @pledged_src_size: Optionally the source size, or zero if unknown. 28273f3d1b4SNick Terrell * 28373f3d1b4SNick Terrell * Resets the context using the parameters from creation. Skips dictionary 284cf30f6a5SNick Terrell * loading, since it can be reused. If `pledged_src_size` is non-zero the frame 28573f3d1b4SNick Terrell * content size is always written into the frame header. 28673f3d1b4SNick Terrell * 287cf30f6a5SNick Terrell * Return: Zero or an error, which can be checked using 288cf30f6a5SNick Terrell * zstd_is_error(). 28973f3d1b4SNick Terrell */ 290cf30f6a5SNick Terrell size_t zstd_reset_cstream(zstd_cstream *cstream, 291cf30f6a5SNick Terrell unsigned long long pledged_src_size); 292cf30f6a5SNick Terrell 29373f3d1b4SNick Terrell /** 294cf30f6a5SNick Terrell * zstd_compress_stream() - streaming compress some of input into output 295cf30f6a5SNick Terrell * @cstream: The zstd streaming compression context. 29673f3d1b4SNick Terrell * @output: Destination buffer. `output->pos` is updated to indicate how much 29773f3d1b4SNick Terrell * compressed data was written. 298cf30f6a5SNick Terrell * @input: Source buffer. `input->pos` is updated to indicate how much data 299cf30f6a5SNick Terrell * was read. Note that it may not consume the entire input, in which 300cf30f6a5SNick Terrell * case `input->pos < input->size`, and it's up to the caller to 301cf30f6a5SNick Terrell * present remaining data again. 30273f3d1b4SNick Terrell * 30373f3d1b4SNick Terrell * The `input` and `output` buffers may be any size. Guaranteed to make some 30473f3d1b4SNick Terrell * forward progress if `input` and `output` are not empty. 30573f3d1b4SNick Terrell * 30673f3d1b4SNick Terrell * Return: A hint for the number of bytes to use as the input for the next 30773f3d1b4SNick Terrell * function call or an error, which can be checked using 308cf30f6a5SNick Terrell * zstd_is_error(). 30973f3d1b4SNick Terrell */ 310cf30f6a5SNick Terrell size_t zstd_compress_stream(zstd_cstream *cstream, zstd_out_buffer *output, 311cf30f6a5SNick Terrell zstd_in_buffer *input); 312cf30f6a5SNick Terrell 31373f3d1b4SNick Terrell /** 314cf30f6a5SNick Terrell * zstd_flush_stream() - flush internal buffers into output 315cf30f6a5SNick Terrell * @cstream: The zstd streaming compression context. 31673f3d1b4SNick Terrell * @output: Destination buffer. `output->pos` is updated to indicate how much 31773f3d1b4SNick Terrell * compressed data was written. 31873f3d1b4SNick Terrell * 319cf30f6a5SNick Terrell * zstd_flush_stream() must be called until it returns 0, meaning all the data 320cf30f6a5SNick Terrell * has been flushed. Since zstd_flush_stream() causes a block to be ended, 32173f3d1b4SNick Terrell * calling it too often will degrade the compression ratio. 32273f3d1b4SNick Terrell * 32373f3d1b4SNick Terrell * Return: The number of bytes still present within internal buffers or an 324cf30f6a5SNick Terrell * error, which can be checked using zstd_is_error(). 32573f3d1b4SNick Terrell */ 326cf30f6a5SNick Terrell size_t zstd_flush_stream(zstd_cstream *cstream, zstd_out_buffer *output); 327cf30f6a5SNick Terrell 32873f3d1b4SNick Terrell /** 329cf30f6a5SNick Terrell * zstd_end_stream() - flush internal buffers into output and end the frame 330cf30f6a5SNick Terrell * @cstream: The zstd streaming compression context. 33173f3d1b4SNick Terrell * @output: Destination buffer. `output->pos` is updated to indicate how much 33273f3d1b4SNick Terrell * compressed data was written. 33373f3d1b4SNick Terrell * 334cf30f6a5SNick Terrell * zstd_end_stream() must be called until it returns 0, meaning all the data has 33573f3d1b4SNick Terrell * been flushed and the frame epilogue has been written. 33673f3d1b4SNick Terrell * 33773f3d1b4SNick Terrell * Return: The number of bytes still present within internal buffers or an 338cf30f6a5SNick Terrell * error, which can be checked using zstd_is_error(). 33973f3d1b4SNick Terrell */ 340cf30f6a5SNick Terrell size_t zstd_end_stream(zstd_cstream *cstream, zstd_out_buffer *output); 341cf30f6a5SNick Terrell 342cf30f6a5SNick Terrell /* ====== Streaming Decompression ====== */ 343cf30f6a5SNick Terrell 344cf30f6a5SNick Terrell typedef ZSTD_DStream zstd_dstream; 34573f3d1b4SNick Terrell 34673f3d1b4SNick Terrell /** 347cf30f6a5SNick Terrell * zstd_dstream_workspace_bound() - memory needed to initialize a zstd_dstream 348cf30f6a5SNick Terrell * @max_window_size: The maximum window size allowed for compressed frames. 34973f3d1b4SNick Terrell * 350cf30f6a5SNick Terrell * Return: A lower bound on the size of the workspace that is passed 351cf30f6a5SNick Terrell * to zstd_init_dstream(). 35273f3d1b4SNick Terrell */ 353cf30f6a5SNick Terrell size_t zstd_dstream_workspace_bound(size_t max_window_size); 35473f3d1b4SNick Terrell 35573f3d1b4SNick Terrell /** 356cf30f6a5SNick Terrell * zstd_init_dstream() - initialize a zstd streaming decompression context 357cf30f6a5SNick Terrell * @max_window_size: The maximum window size allowed for compressed frames. 35873f3d1b4SNick Terrell * @workspace: The workspace to emplace the context into. It must outlive 35973f3d1b4SNick Terrell * the returned context. 36073f3d1b4SNick Terrell * @workspaceSize: The size of workspace. 361cf30f6a5SNick Terrell * Use zstd_dstream_workspace_bound(max_window_size) to 362cf30f6a5SNick Terrell * determine how large the workspace must be. 36373f3d1b4SNick Terrell * 36473f3d1b4SNick Terrell * Return: The zstd streaming decompression context. 36573f3d1b4SNick Terrell */ 366cf30f6a5SNick Terrell zstd_dstream *zstd_init_dstream(size_t max_window_size, void *workspace, 367cf30f6a5SNick Terrell size_t workspace_size); 36873f3d1b4SNick Terrell 36973f3d1b4SNick Terrell /** 370cf30f6a5SNick Terrell * zstd_reset_dstream() - reset the context using parameters from creation 371cf30f6a5SNick Terrell * @dstream: The zstd streaming decompression context to reset. 37273f3d1b4SNick Terrell * 37373f3d1b4SNick Terrell * Resets the context using the parameters from creation. Skips dictionary 37473f3d1b4SNick Terrell * loading, since it can be reused. 37573f3d1b4SNick Terrell * 376cf30f6a5SNick Terrell * Return: Zero or an error, which can be checked using zstd_is_error(). 37773f3d1b4SNick Terrell */ 378cf30f6a5SNick Terrell size_t zstd_reset_dstream(zstd_dstream *dstream); 379cf30f6a5SNick Terrell 38073f3d1b4SNick Terrell /** 381cf30f6a5SNick Terrell * zstd_decompress_stream() - streaming decompress some of input into output 382cf30f6a5SNick Terrell * @dstream: The zstd streaming decompression context. 38373f3d1b4SNick Terrell * @output: Destination buffer. `output.pos` is updated to indicate how much 38473f3d1b4SNick Terrell * decompressed data was written. 38573f3d1b4SNick Terrell * @input: Source buffer. `input.pos` is updated to indicate how much data was 38673f3d1b4SNick Terrell * read. Note that it may not consume the entire input, in which case 38773f3d1b4SNick Terrell * `input.pos < input.size`, and it's up to the caller to present 38873f3d1b4SNick Terrell * remaining data again. 38973f3d1b4SNick Terrell * 39073f3d1b4SNick Terrell * The `input` and `output` buffers may be any size. Guaranteed to make some 39173f3d1b4SNick Terrell * forward progress if `input` and `output` are not empty. 392cf30f6a5SNick Terrell * zstd_decompress_stream() will not consume the last byte of the frame until 39373f3d1b4SNick Terrell * the entire frame is flushed. 39473f3d1b4SNick Terrell * 39573f3d1b4SNick Terrell * Return: Returns 0 iff a frame is completely decoded and fully flushed. 396cf30f6a5SNick Terrell * Otherwise returns a hint for the number of bytes to use as the 397cf30f6a5SNick Terrell * input for the next function call or an error, which can be checked 398cf30f6a5SNick Terrell * using zstd_is_error(). The size hint will never load more than the 399cf30f6a5SNick Terrell * frame. 40073f3d1b4SNick Terrell */ 401cf30f6a5SNick Terrell size_t zstd_decompress_stream(zstd_dstream *dstream, zstd_out_buffer *output, 402cf30f6a5SNick Terrell zstd_in_buffer *input); 403cf30f6a5SNick Terrell 404cf30f6a5SNick Terrell /* ====== Frame Inspection Functions ====== */ 40573f3d1b4SNick Terrell 40673f3d1b4SNick Terrell /** 407cf30f6a5SNick Terrell * zstd_find_frame_compressed_size() - returns the size of a compressed frame 408cf30f6a5SNick Terrell * @src: Source buffer. It should point to the start of a zstd encoded 409cf30f6a5SNick Terrell * frame or a skippable frame. 410cf30f6a5SNick Terrell * @src_size: The size of the source buffer. It must be at least as large as the 41173f3d1b4SNick Terrell * size of the frame. 41273f3d1b4SNick Terrell * 41373f3d1b4SNick Terrell * Return: The compressed size of the frame pointed to by `src` or an error, 414cf30f6a5SNick Terrell * which can be check with zstd_is_error(). 41573f3d1b4SNick Terrell * Suitable to pass to ZSTD_decompress() or similar functions. 41673f3d1b4SNick Terrell */ 417cf30f6a5SNick Terrell size_t zstd_find_frame_compressed_size(const void *src, size_t src_size); 41873f3d1b4SNick Terrell 41973f3d1b4SNick Terrell /** 420cf30f6a5SNick Terrell * struct zstd_frame_params - zstd frame parameters stored in the frame header 421*e0c1b49fSNick Terrell * @frameContentSize: The frame content size, or ZSTD_CONTENTSIZE_UNKNOWN if not 422*e0c1b49fSNick Terrell * present. 42373f3d1b4SNick Terrell * @windowSize: The window size, or 0 if the frame is a skippable frame. 424*e0c1b49fSNick Terrell * @blockSizeMax: The maximum block size. 425*e0c1b49fSNick Terrell * @frameType: The frame type (zstd or skippable) 426*e0c1b49fSNick Terrell * @headerSize: The size of the frame header. 42773f3d1b4SNick Terrell * @dictID: The dictionary id, or 0 if not present. 42873f3d1b4SNick Terrell * @checksumFlag: Whether a checksum was used. 429*e0c1b49fSNick Terrell * 430*e0c1b49fSNick Terrell * See zstd_lib.h. 43173f3d1b4SNick Terrell */ 432*e0c1b49fSNick Terrell typedef ZSTD_frameHeader zstd_frame_header; 43373f3d1b4SNick Terrell 43473f3d1b4SNick Terrell /** 435cf30f6a5SNick Terrell * zstd_get_frame_header() - extracts parameters from a zstd or skippable frame 436cf30f6a5SNick Terrell * @params: On success the frame parameters are written here. 43773f3d1b4SNick Terrell * @src: The source buffer. It must point to a zstd or skippable frame. 438cf30f6a5SNick Terrell * @src_size: The size of the source buffer. 43973f3d1b4SNick Terrell * 44073f3d1b4SNick Terrell * Return: 0 on success. If more data is required it returns how many bytes 44173f3d1b4SNick Terrell * must be provided to make forward progress. Otherwise it returns 442cf30f6a5SNick Terrell * an error, which can be checked using zstd_is_error(). 44373f3d1b4SNick Terrell */ 444cf30f6a5SNick Terrell size_t zstd_get_frame_header(zstd_frame_header *params, const void *src, 445cf30f6a5SNick Terrell size_t src_size); 44673f3d1b4SNick Terrell 447cf30f6a5SNick Terrell #endif /* LINUX_ZSTD_H */ 448