include/linux/zstd.h

   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 */