1 /* SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause */ 2 /* 3 * Copyright (c) Yann Collet, Facebook, Inc. 4 * All rights reserved. 5 * 6 * This source code is licensed under both the BSD-style license (found in the 7 * LICENSE file in the root directory of https://github.com/facebook/zstd) and 8 * the GPLv2 (found in the COPYING file in the root directory of 9 * https://github.com/facebook/zstd). You may select, at your option, one of the 10 * above-listed licenses. 11 */ 12 13 #ifndef LINUX_ZSTD_H 14 #define LINUX_ZSTD_H 15 16 /** 17 * This is a kernel-style API that wraps the upstream zstd API, which cannot be 18 * used directly because the symbols aren't exported. It exposes the minimal 19 * functionality which is currently required by users of zstd in the kernel. 20 * Expose extra functions from lib/zstd/zstd.h as needed. 21 */ 22 23 /* ====== Dependency ====== */ 24 #include <linux/types.h> 25 #include <linux/zstd_errors.h> 26 #include <linux/zstd_lib.h> 27 28 /* ====== Helper Functions ====== */ 29 /** 30 * zstd_compress_bound() - maximum compressed size in worst case scenario 31 * @src_size: The size of the data to compress. 32 * 33 * Return: The maximum compressed size in the worst case scenario. 34 */ 35 size_t zstd_compress_bound(size_t src_size); 36 37 /** 38 * zstd_is_error() - tells if a size_t function result is an error code 39 * @code: The function result to check for error. 40 * 41 * Return: Non-zero iff the code is an error. 42 */ 43 unsigned int zstd_is_error(size_t code); 44 45 /** 46 * enum zstd_error_code - zstd error codes 47 */ 48 typedef ZSTD_ErrorCode zstd_error_code; 49 50 /** 51 * zstd_get_error_code() - translates an error function result to an error code 52 * @code: The function result for which zstd_is_error(code) is true. 53 * 54 * Return: A unique error code for this error. 55 */ 56 zstd_error_code zstd_get_error_code(size_t code); 57 58 /** 59 * zstd_get_error_name() - translates an error function result to a string 60 * @code: The function result for which zstd_is_error(code) is true. 61 * 62 * Return: An error string corresponding to the error code. 63 */ 64 const char *zstd_get_error_name(size_t code); 65 66 /** 67 * zstd_min_clevel() - minimum allowed compression level 68 * 69 * Return: The minimum allowed compression level. 70 */ 71 int zstd_min_clevel(void); 72 73 /** 74 * zstd_max_clevel() - maximum allowed compression level 75 * 76 * Return: The maximum allowed compression level. 77 */ 78 int zstd_max_clevel(void); 79 80 /* ====== Parameter Selection ====== */ 81 82 /** 83 * enum zstd_strategy - zstd compression search strategy 84 * 85 * From faster to stronger. See zstd_lib.h. 86 */ 87 typedef ZSTD_strategy zstd_strategy; 88 89 /** 90 * struct zstd_compression_parameters - zstd compression parameters 91 * @windowLog: Log of the largest match distance. Larger means more 92 * compression, and more memory needed during decompression. 93 * @chainLog: Fully searched segment. Larger means more compression, 94 * slower, and more memory (useless for fast). 95 * @hashLog: Dispatch table. Larger means more compression, 96 * slower, and more memory. 97 * @searchLog: Number of searches. Larger means more compression and slower. 98 * @searchLength: Match length searched. Larger means faster decompression, 99 * sometimes less compression. 100 * @targetLength: Acceptable match size for optimal parser (only). Larger means 101 * more compression, and slower. 102 * @strategy: The zstd compression strategy. 103 * 104 * See zstd_lib.h. 105 */ 106 typedef ZSTD_compressionParameters zstd_compression_parameters; 107 108 /** 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 115 * header when using dictionary compression. 116 * 117 * The default value is all fields set to 0. See zstd_lib.h. 118 */ 119 typedef ZSTD_frameParameters zstd_frame_parameters; 120 121 /** 122 * struct zstd_parameters - zstd parameters 123 * @cParams: The compression parameters. 124 * @fParams: The frame parameters. 125 */ 126 typedef ZSTD_parameters zstd_parameters; 127 128 /** 129 * zstd_get_params() - returns zstd_parameters for selected level 130 * @level: The compression level 131 * @estimated_src_size: The estimated source size to compress or 0 132 * if unknown. 133 * 134 * Return: The selected zstd_parameters. 135 */ 136 zstd_parameters zstd_get_params(int level, 137 unsigned long long estimated_src_size); 138 139 /* ====== Single-pass Compression ====== */ 140 141 typedef ZSTD_CCtx zstd_cctx; 142 143 /** 144 * zstd_cctx_workspace_bound() - max memory needed to initialize a zstd_cctx 145 * @parameters: The compression parameters to be used. 146 * 147 * If multiple compression parameters might be used, the caller must call 148 * zstd_cctx_workspace_bound() for each set of parameters and use the maximum 149 * size. 150 * 151 * Return: A lower bound on the size of the workspace that is passed to 152 * zstd_init_cctx(). 153 */ 154 size_t zstd_cctx_workspace_bound(const zstd_compression_parameters *parameters); 155 156 /** 157 * zstd_init_cctx() - initialize a zstd compression context 158 * @workspace: The workspace to emplace the context into. It must outlive 159 * the returned context. 160 * @workspace_size: The size of workspace. Use zstd_cctx_workspace_bound() to 161 * determine how large the workspace must be. 162 * 163 * Return: A zstd compression context or NULL on error. 164 */ 165 zstd_cctx *zstd_init_cctx(void *workspace, size_t workspace_size); 166 167 /** 168 * zstd_compress_cctx() - compress src into dst with the initialized parameters 169 * @cctx: The context. Must have been initialized with zstd_init_cctx(). 170 * @dst: The buffer to compress src into. 171 * @dst_capacity: The size of the destination buffer. May be any size, but 172 * ZSTD_compressBound(srcSize) is guaranteed to be large enough. 173 * @src: The data to compress. 174 * @src_size: The size of the data to compress. 175 * @parameters: The compression parameters to be used. 176 * 177 * Return: The compressed size or an error, which can be checked using 178 * zstd_is_error(). 179 */ 180 size_t zstd_compress_cctx(zstd_cctx *cctx, void *dst, size_t dst_capacity, 181 const void *src, size_t src_size, const zstd_parameters *parameters); 182 183 /* ====== Single-pass Decompression ====== */ 184 185 typedef ZSTD_DCtx zstd_dctx; 186 187 /** 188 * zstd_dctx_workspace_bound() - max memory needed to initialize a zstd_dctx 189 * 190 * Return: A lower bound on the size of the workspace that is passed to 191 * zstd_init_dctx(). 192 */ 193 size_t zstd_dctx_workspace_bound(void); 194 195 /** 196 * zstd_init_dctx() - initialize a zstd decompression context 197 * @workspace: The workspace to emplace the context into. It must outlive 198 * the returned context. 199 * @workspace_size: The size of workspace. Use zstd_dctx_workspace_bound() to 200 * determine how large the workspace must be. 201 * 202 * Return: A zstd decompression context or NULL on error. 203 */ 204 zstd_dctx *zstd_init_dctx(void *workspace, size_t workspace_size); 205 206 /** 207 * zstd_decompress_dctx() - decompress zstd compressed src into dst 208 * @dctx: The decompression context. 209 * @dst: The buffer to decompress src into. 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. 213 * @src: The zstd compressed data to decompress. Multiple concatenated 214 * frames and skippable frames are allowed. 215 * @src_size: The exact size of the data to decompress. 216 * 217 * Return: The decompressed size or an error, which can be checked using 218 * zstd_is_error(). 219 */ 220 size_t zstd_decompress_dctx(zstd_dctx *dctx, void *dst, size_t dst_capacity, 221 const void *src, size_t src_size); 222 223 /* ====== Streaming Buffers ====== */ 224 225 /** 226 * struct zstd_in_buffer - input buffer for streaming 227 * @src: Start of the input buffer. 228 * @size: Size of the input buffer. 229 * @pos: Position where reading stopped. Will be updated. 230 * Necessarily 0 <= pos <= size. 231 * 232 * See zstd_lib.h. 233 */ 234 typedef ZSTD_inBuffer zstd_in_buffer; 235 236 /** 237 * struct zstd_out_buffer - output buffer for streaming 238 * @dst: Start of the output buffer. 239 * @size: Size of the output buffer. 240 * @pos: Position where writing stopped. Will be updated. 241 * Necessarily 0 <= pos <= size. 242 * 243 * See zstd_lib.h. 244 */ 245 typedef ZSTD_outBuffer zstd_out_buffer; 246 247 /* ====== Streaming Compression ====== */ 248 249 typedef ZSTD_CStream zstd_cstream; 250 251 /** 252 * zstd_cstream_workspace_bound() - memory needed to initialize a zstd_cstream 253 * @cparams: The compression parameters to be used for compression. 254 * 255 * Return: A lower bound on the size of the workspace that is passed to 256 * zstd_init_cstream(). 257 */ 258 size_t zstd_cstream_workspace_bound(const zstd_compression_parameters *cparams); 259 260 /** 261 * zstd_init_cstream() - initialize a zstd streaming compression context 262 * @parameters The zstd parameters to use for compression. 263 * @pledged_src_size: If params.fParams.contentSizeFlag == 1 then the caller 264 * must pass the source size (zero means empty source). 265 * Otherwise, the caller may optionally pass the source 266 * size, or zero if unknown. 267 * @workspace: The workspace to emplace the context into. It must outlive 268 * the returned context. 269 * @workspace_size: The size of workspace. 270 * Use zstd_cstream_workspace_bound(params->cparams) to 271 * determine how large the workspace must be. 272 * 273 * Return: The zstd streaming compression context or NULL on error. 274 */ 275 zstd_cstream *zstd_init_cstream(const zstd_parameters *parameters, 276 unsigned long long pledged_src_size, void *workspace, size_t workspace_size); 277 278 /** 279 * zstd_reset_cstream() - reset the context using parameters from creation 280 * @cstream: The zstd streaming compression context to reset. 281 * @pledged_src_size: Optionally the source size, or zero if unknown. 282 * 283 * Resets the context using the parameters from creation. Skips dictionary 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. 286 * 287 * Return: Zero or an error, which can be checked using 288 * zstd_is_error(). 289 */ 290 size_t zstd_reset_cstream(zstd_cstream *cstream, 291 unsigned long long pledged_src_size); 292 293 /** 294 * zstd_compress_stream() - streaming compress some of input into output 295 * @cstream: The zstd streaming compression context. 296 * @output: Destination buffer. `output->pos` is updated to indicate how much 297 * compressed data was written. 298 * @input: Source buffer. `input->pos` is updated to indicate how much data 299 * was read. Note that it may not consume the entire input, in which 300 * case `input->pos < input->size`, and it's up to the caller to 301 * present remaining data again. 302 * 303 * The `input` and `output` buffers may be any size. Guaranteed to make some 304 * forward progress if `input` and `output` are not empty. 305 * 306 * Return: A hint for the number of bytes to use as the input for the next 307 * function call or an error, which can be checked using 308 * zstd_is_error(). 309 */ 310 size_t zstd_compress_stream(zstd_cstream *cstream, zstd_out_buffer *output, 311 zstd_in_buffer *input); 312 313 /** 314 * zstd_flush_stream() - flush internal buffers into output 315 * @cstream: The zstd streaming compression context. 316 * @output: Destination buffer. `output->pos` is updated to indicate how much 317 * compressed data was written. 318 * 319 * zstd_flush_stream() must be called until it returns 0, meaning all the data 320 * has been flushed. Since zstd_flush_stream() causes a block to be ended, 321 * calling it too often will degrade the compression ratio. 322 * 323 * Return: The number of bytes still present within internal buffers or an 324 * error, which can be checked using zstd_is_error(). 325 */ 326 size_t zstd_flush_stream(zstd_cstream *cstream, zstd_out_buffer *output); 327 328 /** 329 * zstd_end_stream() - flush internal buffers into output and end the frame 330 * @cstream: The zstd streaming compression context. 331 * @output: Destination buffer. `output->pos` is updated to indicate how much 332 * compressed data was written. 333 * 334 * zstd_end_stream() must be called until it returns 0, meaning all the data has 335 * been flushed and the frame epilogue has been written. 336 * 337 * Return: The number of bytes still present within internal buffers or an 338 * error, which can be checked using zstd_is_error(). 339 */ 340 size_t zstd_end_stream(zstd_cstream *cstream, zstd_out_buffer *output); 341 342 /* ====== Streaming Decompression ====== */ 343 344 typedef ZSTD_DStream zstd_dstream; 345 346 /** 347 * zstd_dstream_workspace_bound() - memory needed to initialize a zstd_dstream 348 * @max_window_size: The maximum window size allowed for compressed frames. 349 * 350 * Return: A lower bound on the size of the workspace that is passed 351 * to zstd_init_dstream(). 352 */ 353 size_t zstd_dstream_workspace_bound(size_t max_window_size); 354 355 /** 356 * zstd_init_dstream() - initialize a zstd streaming decompression context 357 * @max_window_size: The maximum window size allowed for compressed frames. 358 * @workspace: The workspace to emplace the context into. It must outlive 359 * the returned context. 360 * @workspaceSize: The size of workspace. 361 * Use zstd_dstream_workspace_bound(max_window_size) to 362 * determine how large the workspace must be. 363 * 364 * Return: The zstd streaming decompression context. 365 */ 366 zstd_dstream *zstd_init_dstream(size_t max_window_size, void *workspace, 367 size_t workspace_size); 368 369 /** 370 * zstd_reset_dstream() - reset the context using parameters from creation 371 * @dstream: The zstd streaming decompression context to reset. 372 * 373 * Resets the context using the parameters from creation. Skips dictionary 374 * loading, since it can be reused. 375 * 376 * Return: Zero or an error, which can be checked using zstd_is_error(). 377 */ 378 size_t zstd_reset_dstream(zstd_dstream *dstream); 379 380 /** 381 * zstd_decompress_stream() - streaming decompress some of input into output 382 * @dstream: The zstd streaming decompression context. 383 * @output: Destination buffer. `output.pos` is updated to indicate how much 384 * decompressed data was written. 385 * @input: Source buffer. `input.pos` is updated to indicate how much data was 386 * read. Note that it may not consume the entire input, in which case 387 * `input.pos < input.size`, and it's up to the caller to present 388 * remaining data again. 389 * 390 * The `input` and `output` buffers may be any size. Guaranteed to make some 391 * forward progress if `input` and `output` are not empty. 392 * zstd_decompress_stream() will not consume the last byte of the frame until 393 * the entire frame is flushed. 394 * 395 * Return: Returns 0 iff a frame is completely decoded and fully flushed. 396 * Otherwise returns a hint for the number of bytes to use as the 397 * input for the next function call or an error, which can be checked 398 * using zstd_is_error(). The size hint will never load more than the 399 * frame. 400 */ 401 size_t zstd_decompress_stream(zstd_dstream *dstream, zstd_out_buffer *output, 402 zstd_in_buffer *input); 403 404 /* ====== Frame Inspection Functions ====== */ 405 406 /** 407 * zstd_find_frame_compressed_size() - returns the size of a compressed frame 408 * @src: Source buffer. It should point to the start of a zstd encoded 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. 412 * 413 * Return: The compressed size of the frame pointed to by `src` or an error, 414 * which can be check with zstd_is_error(). 415 * Suitable to pass to ZSTD_decompress() or similar functions. 416 */ 417 size_t zstd_find_frame_compressed_size(const void *src, size_t src_size); 418 419 /** 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 422 * present. 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. 427 * @dictID: The dictionary id, or 0 if not present. 428 * @checksumFlag: Whether a checksum was used. 429 * 430 * See zstd_lib.h. 431 */ 432 typedef ZSTD_frameHeader zstd_frame_header; 433 434 /** 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. 439 * 440 * Return: 0 on success. If more data is required it returns how many bytes 441 * must be provided to make forward progress. Otherwise it returns 442 * an error, which can be checked using zstd_is_error(). 443 */ 444 size_t zstd_get_frame_header(zstd_frame_header *params, const void *src, 445 size_t src_size); 446 447 #endif /* LINUX_ZSTD_H */ 448