include/linux/zstd.h

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