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