1 /* SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause */ 2 /* 3 * Copyright (c) Meta Platforms, Inc. and affiliates. 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 typedef ZSTD_CCtx zstd_cctx; 140 typedef ZSTD_cParameter zstd_cparameter; 141 142 /** 143 * zstd_cctx_set_param() - sets a compression parameter 144 * @cctx: The context. Must have been initialized with zstd_init_cctx(). 145 * @param: The parameter to set. 146 * @value: The value to set the parameter to. 147 * 148 * Return: Zero or an error, which can be checked using zstd_is_error(). 149 */ 150 size_t zstd_cctx_set_param(zstd_cctx *cctx, zstd_cparameter param, int value); 151 152 /* ====== Single-pass Compression ====== */ 153 154 /** 155 * zstd_cctx_workspace_bound() - max memory needed to initialize a zstd_cctx 156 * @parameters: The compression parameters to be used. 157 * 158 * If multiple compression parameters might be used, the caller must call 159 * zstd_cctx_workspace_bound() for each set of parameters and use the maximum 160 * size. 161 * 162 * Return: A lower bound on the size of the workspace that is passed to 163 * zstd_init_cctx(). 164 */ 165 size_t zstd_cctx_workspace_bound(const zstd_compression_parameters *parameters); 166 167 /** 168 * zstd_cctx_workspace_bound_with_ext_seq_prod() - max memory needed to 169 * initialize a zstd_cctx when using the block-level external sequence 170 * producer API. 171 * @parameters: The compression parameters to be used. 172 * 173 * If multiple compression parameters might be used, the caller must call 174 * this function for each set of parameters and use the maximum size. 175 * 176 * Return: A lower bound on the size of the workspace that is passed to 177 * zstd_init_cctx(). 178 */ 179 size_t zstd_cctx_workspace_bound_with_ext_seq_prod(const zstd_compression_parameters *parameters); 180 181 /** 182 * zstd_init_cctx() - initialize a zstd compression context 183 * @workspace: The workspace to emplace the context into. It must outlive 184 * the returned context. 185 * @workspace_size: The size of workspace. Use zstd_cctx_workspace_bound() to 186 * determine how large the workspace must be. 187 * 188 * Return: A zstd compression context or NULL on error. 189 */ 190 zstd_cctx *zstd_init_cctx(void *workspace, size_t workspace_size); 191 192 /** 193 * zstd_compress_cctx() - compress src into dst with the initialized parameters 194 * @cctx: The context. Must have been initialized with zstd_init_cctx(). 195 * @dst: The buffer to compress src into. 196 * @dst_capacity: The size of the destination buffer. May be any size, but 197 * ZSTD_compressBound(srcSize) is guaranteed to be large enough. 198 * @src: The data to compress. 199 * @src_size: The size of the data to compress. 200 * @parameters: The compression parameters to be used. 201 * 202 * Return: The compressed size or an error, which can be checked using 203 * zstd_is_error(). 204 */ 205 size_t zstd_compress_cctx(zstd_cctx *cctx, void *dst, size_t dst_capacity, 206 const void *src, size_t src_size, const zstd_parameters *parameters); 207 208 /* ====== Single-pass Decompression ====== */ 209 210 typedef ZSTD_DCtx zstd_dctx; 211 212 /** 213 * zstd_dctx_workspace_bound() - max memory needed to initialize a zstd_dctx 214 * 215 * Return: A lower bound on the size of the workspace that is passed to 216 * zstd_init_dctx(). 217 */ 218 size_t zstd_dctx_workspace_bound(void); 219 220 /** 221 * zstd_init_dctx() - initialize a zstd decompression context 222 * @workspace: The workspace to emplace the context into. It must outlive 223 * the returned context. 224 * @workspace_size: The size of workspace. Use zstd_dctx_workspace_bound() to 225 * determine how large the workspace must be. 226 * 227 * Return: A zstd decompression context or NULL on error. 228 */ 229 zstd_dctx *zstd_init_dctx(void *workspace, size_t workspace_size); 230 231 /** 232 * zstd_decompress_dctx() - decompress zstd compressed src into dst 233 * @dctx: The decompression context. 234 * @dst: The buffer to decompress src into. 235 * @dst_capacity: The size of the destination buffer. Must be at least as large 236 * as the decompressed size. If the caller cannot upper bound the 237 * decompressed size, then it's better to use the streaming API. 238 * @src: The zstd compressed data to decompress. Multiple concatenated 239 * frames and skippable frames are allowed. 240 * @src_size: The exact size of the data to decompress. 241 * 242 * Return: The decompressed size or an error, which can be checked using 243 * zstd_is_error(). 244 */ 245 size_t zstd_decompress_dctx(zstd_dctx *dctx, void *dst, size_t dst_capacity, 246 const void *src, size_t src_size); 247 248 /* ====== Streaming Buffers ====== */ 249 250 /** 251 * struct zstd_in_buffer - input buffer for streaming 252 * @src: Start of the input buffer. 253 * @size: Size of the input buffer. 254 * @pos: Position where reading stopped. Will be updated. 255 * Necessarily 0 <= pos <= size. 256 * 257 * See zstd_lib.h. 258 */ 259 typedef ZSTD_inBuffer zstd_in_buffer; 260 261 /** 262 * struct zstd_out_buffer - output buffer for streaming 263 * @dst: Start of the output buffer. 264 * @size: Size of the output buffer. 265 * @pos: Position where writing stopped. Will be updated. 266 * Necessarily 0 <= pos <= size. 267 * 268 * See zstd_lib.h. 269 */ 270 typedef ZSTD_outBuffer zstd_out_buffer; 271 272 /* ====== Streaming Compression ====== */ 273 274 typedef ZSTD_CStream zstd_cstream; 275 276 /** 277 * zstd_cstream_workspace_bound() - memory needed to initialize a zstd_cstream 278 * @cparams: The compression parameters to be used for compression. 279 * 280 * Return: A lower bound on the size of the workspace that is passed to 281 * zstd_init_cstream(). 282 */ 283 size_t zstd_cstream_workspace_bound(const zstd_compression_parameters *cparams); 284 285 /** 286 * zstd_cstream_workspace_bound_with_ext_seq_prod() - memory needed to initialize 287 * a zstd_cstream when using the block-level external sequence producer API. 288 * @cparams: The compression parameters to be used for compression. 289 * 290 * Return: A lower bound on the size of the workspace that is passed to 291 * zstd_init_cstream(). 292 */ 293 size_t zstd_cstream_workspace_bound_with_ext_seq_prod(const zstd_compression_parameters *cparams); 294 295 /** 296 * zstd_init_cstream() - initialize a zstd streaming compression context 297 * @parameters The zstd parameters to use for compression. 298 * @pledged_src_size: If params.fParams.contentSizeFlag == 1 then the caller 299 * must pass the source size (zero means empty source). 300 * Otherwise, the caller may optionally pass the source 301 * size, or zero if unknown. 302 * @workspace: The workspace to emplace the context into. It must outlive 303 * the returned context. 304 * @workspace_size: The size of workspace. 305 * Use zstd_cstream_workspace_bound(params->cparams) to 306 * determine how large the workspace must be. 307 * 308 * Return: The zstd streaming compression context or NULL on error. 309 */ 310 zstd_cstream *zstd_init_cstream(const zstd_parameters *parameters, 311 unsigned long long pledged_src_size, void *workspace, size_t workspace_size); 312 313 /** 314 * zstd_reset_cstream() - reset the context using parameters from creation 315 * @cstream: The zstd streaming compression context to reset. 316 * @pledged_src_size: Optionally the source size, or zero if unknown. 317 * 318 * Resets the context using the parameters from creation. Skips dictionary 319 * loading, since it can be reused. If `pledged_src_size` is non-zero the frame 320 * content size is always written into the frame header. 321 * 322 * Return: Zero or an error, which can be checked using 323 * zstd_is_error(). 324 */ 325 size_t zstd_reset_cstream(zstd_cstream *cstream, 326 unsigned long long pledged_src_size); 327 328 /** 329 * zstd_compress_stream() - streaming compress some of input into output 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 * @input: Source buffer. `input->pos` is updated to indicate how much data 334 * was read. Note that it may not consume the entire input, in which 335 * case `input->pos < input->size`, and it's up to the caller to 336 * present remaining data again. 337 * 338 * The `input` and `output` buffers may be any size. Guaranteed to make some 339 * forward progress if `input` and `output` are not empty. 340 * 341 * Return: A hint for the number of bytes to use as the input for the next 342 * function call or an error, which can be checked using 343 * zstd_is_error(). 344 */ 345 size_t zstd_compress_stream(zstd_cstream *cstream, zstd_out_buffer *output, 346 zstd_in_buffer *input); 347 348 /** 349 * zstd_flush_stream() - flush internal buffers into output 350 * @cstream: The zstd streaming compression context. 351 * @output: Destination buffer. `output->pos` is updated to indicate how much 352 * compressed data was written. 353 * 354 * zstd_flush_stream() must be called until it returns 0, meaning all the data 355 * has been flushed. Since zstd_flush_stream() causes a block to be ended, 356 * calling it too often will degrade the compression ratio. 357 * 358 * Return: The number of bytes still present within internal buffers or an 359 * error, which can be checked using zstd_is_error(). 360 */ 361 size_t zstd_flush_stream(zstd_cstream *cstream, zstd_out_buffer *output); 362 363 /** 364 * zstd_end_stream() - flush internal buffers into output and end the frame 365 * @cstream: The zstd streaming compression context. 366 * @output: Destination buffer. `output->pos` is updated to indicate how much 367 * compressed data was written. 368 * 369 * zstd_end_stream() must be called until it returns 0, meaning all the data has 370 * been flushed and the frame epilogue has been written. 371 * 372 * Return: The number of bytes still present within internal buffers or an 373 * error, which can be checked using zstd_is_error(). 374 */ 375 size_t zstd_end_stream(zstd_cstream *cstream, zstd_out_buffer *output); 376 377 /* ====== Streaming Decompression ====== */ 378 379 typedef ZSTD_DStream zstd_dstream; 380 381 /** 382 * zstd_dstream_workspace_bound() - memory needed to initialize a zstd_dstream 383 * @max_window_size: The maximum window size allowed for compressed frames. 384 * 385 * Return: A lower bound on the size of the workspace that is passed 386 * to zstd_init_dstream(). 387 */ 388 size_t zstd_dstream_workspace_bound(size_t max_window_size); 389 390 /** 391 * zstd_init_dstream() - initialize a zstd streaming decompression context 392 * @max_window_size: The maximum window size allowed for compressed frames. 393 * @workspace: The workspace to emplace the context into. It must outlive 394 * the returned context. 395 * @workspaceSize: The size of workspace. 396 * Use zstd_dstream_workspace_bound(max_window_size) to 397 * determine how large the workspace must be. 398 * 399 * Return: The zstd streaming decompression context. 400 */ 401 zstd_dstream *zstd_init_dstream(size_t max_window_size, void *workspace, 402 size_t workspace_size); 403 404 /** 405 * zstd_reset_dstream() - reset the context using parameters from creation 406 * @dstream: The zstd streaming decompression context to reset. 407 * 408 * Resets the context using the parameters from creation. Skips dictionary 409 * loading, since it can be reused. 410 * 411 * Return: Zero or an error, which can be checked using zstd_is_error(). 412 */ 413 size_t zstd_reset_dstream(zstd_dstream *dstream); 414 415 /** 416 * zstd_decompress_stream() - streaming decompress some of input into output 417 * @dstream: The zstd streaming decompression context. 418 * @output: Destination buffer. `output.pos` is updated to indicate how much 419 * decompressed data was written. 420 * @input: Source buffer. `input.pos` is updated to indicate how much data was 421 * read. Note that it may not consume the entire input, in which case 422 * `input.pos < input.size`, and it's up to the caller to present 423 * remaining data again. 424 * 425 * The `input` and `output` buffers may be any size. Guaranteed to make some 426 * forward progress if `input` and `output` are not empty. 427 * zstd_decompress_stream() will not consume the last byte of the frame until 428 * the entire frame is flushed. 429 * 430 * Return: Returns 0 iff a frame is completely decoded and fully flushed. 431 * Otherwise returns a hint for the number of bytes to use as the 432 * input for the next function call or an error, which can be checked 433 * using zstd_is_error(). The size hint will never load more than the 434 * frame. 435 */ 436 size_t zstd_decompress_stream(zstd_dstream *dstream, zstd_out_buffer *output, 437 zstd_in_buffer *input); 438 439 /* ====== Frame Inspection Functions ====== */ 440 441 /** 442 * zstd_find_frame_compressed_size() - returns the size of a compressed frame 443 * @src: Source buffer. It should point to the start of a zstd encoded 444 * frame or a skippable frame. 445 * @src_size: The size of the source buffer. It must be at least as large as the 446 * size of the frame. 447 * 448 * Return: The compressed size of the frame pointed to by `src` or an error, 449 * which can be check with zstd_is_error(). 450 * Suitable to pass to ZSTD_decompress() or similar functions. 451 */ 452 size_t zstd_find_frame_compressed_size(const void *src, size_t src_size); 453 454 /** 455 * zstd_register_sequence_producer() - exposes the zstd library function 456 * ZSTD_registerSequenceProducer(). This is used for the block-level external 457 * sequence producer API. See upstream zstd.h for detailed documentation. 458 */ 459 typedef ZSTD_sequenceProducer_F zstd_sequence_producer_f; 460 void zstd_register_sequence_producer( 461 zstd_cctx *cctx, 462 void* sequence_producer_state, 463 zstd_sequence_producer_f sequence_producer 464 ); 465 466 /** 467 * struct zstd_frame_params - zstd frame parameters stored in the frame header 468 * @frameContentSize: The frame content size, or ZSTD_CONTENTSIZE_UNKNOWN if not 469 * present. 470 * @windowSize: The window size, or 0 if the frame is a skippable frame. 471 * @blockSizeMax: The maximum block size. 472 * @frameType: The frame type (zstd or skippable) 473 * @headerSize: The size of the frame header. 474 * @dictID: The dictionary id, or 0 if not present. 475 * @checksumFlag: Whether a checksum was used. 476 * 477 * See zstd_lib.h. 478 */ 479 typedef ZSTD_FrameHeader zstd_frame_header; 480 481 /** 482 * zstd_get_frame_header() - extracts parameters from a zstd or skippable frame 483 * @params: On success the frame parameters are written here. 484 * @src: The source buffer. It must point to a zstd or skippable frame. 485 * @src_size: The size of the source buffer. 486 * 487 * Return: 0 on success. If more data is required it returns how many bytes 488 * must be provided to make forward progress. Otherwise it returns 489 * an error, which can be checked using zstd_is_error(). 490 */ 491 size_t zstd_get_frame_header(zstd_frame_header *params, const void *src, 492 size_t src_size); 493 494 /** 495 * struct zstd_sequence - a sequence of literals or a match 496 * 497 * @offset: The offset of the match 498 * @litLength: The literal length of the sequence 499 * @matchLength: The match length of the sequence 500 * @rep: Represents which repeat offset is used 501 */ 502 typedef ZSTD_Sequence zstd_sequence; 503 504 /** 505 * zstd_compress_sequences_and_literals() - compress an array of zstd_sequence and literals 506 * 507 * @cctx: The zstd compression context. 508 * @dst: The buffer to compress the data into. 509 * @dst_capacity: The size of the destination buffer. 510 * @in_seqs: The array of zstd_sequence to compress. 511 * @in_seqs_size: The number of sequences in in_seqs. 512 * @literals: The literals associated to the sequences to be compressed. 513 * @lit_size: The size of the literals in the literals buffer. 514 * @lit_capacity: The size of the literals buffer. 515 * @decompressed_size: The size of the input data 516 * 517 * Return: The compressed size or an error, which can be checked using 518 * zstd_is_error(). 519 */ 520 size_t zstd_compress_sequences_and_literals(zstd_cctx *cctx, void* dst, size_t dst_capacity, 521 const zstd_sequence *in_seqs, size_t in_seqs_size, 522 const void* literals, size_t lit_size, size_t lit_capacity, 523 size_t decompressed_size); 524 525 #endif /* LINUX_ZSTD_H */ 526