path: root/include/linux/zstd.h

/*
 * Copyright (c) 2016-present, Yann Collet, Facebook, Inc.
 * All rights reserved.
 *
 * This source code is licensed under the BSD-style license found in the
 * LICENSE file in the root directory of https://github.com/facebook/zstd.
 * An additional grant of patent rights can be found in the PATENTS file in the
 * same directory.
 *
 * This program is free software; you can redistribute it and/or modify it under
 * the terms of the GNU General Public License version 2 as published by the
 * Free Software Foundation. This program is dual-licensed; you may select
 * either version 2 of the GNU General Public License ("GPL") or BSD license
 * ("BSD").
 */

#ifndef ZSTD_H
#define ZSTD_H

/* ======   Dependency   ======*/
#include <linux/types.h>   /* size_t */


/*-*****************************************************************************
 * Introduction
 *
 * zstd, short for Zstandard, is a fast lossless compression algorithm,
 * targeting real-time compression scenarios at zlib-level and better
 * compression ratios. The zstd compression library provides in-memory
 * compression and decompression functions. The library supports compression
 * levels from 1 up to ZSTD_maxCLevel() which is 22. Levels >= 20, labeled
 * ultra, should be used with caution, as they require more memory.
 * Compression can be done in:
 *  - a single step, reusing a context (described as Explicit memory management)
 *  - unbounded multiple steps (described as Streaming compression)
 * The compression ratio achievable on small data can be highly improved using
 * compression with a dictionary in:
 *  - a single step (described as Simple dictionary API)
 *  - a single step, reusing a dictionary (described as Fast dictionary API)
 ******************************************************************************/

/*======  Helper functions  ======*/

/**
 * enum ZSTD_ErrorCode - zstd error codes
 *
 * Functions that return size_t can be checked for errors using ZSTD_isError()
 * and the ZSTD_ErrorCode can be extracted using ZSTD_getErrorCode().
 */
typedef enum {
	ZSTD_error_no_error,
	ZSTD_error_GENERIC,
	ZSTD_error_prefix_unknown,
	ZSTD_error_version_unsupported,
	ZSTD_error_parameter_unknown,
	ZSTD_error_frameParameter_unsupported,
	ZSTD_error_frameParameter_unsupportedBy32bits,
	ZSTD_error_frameParameter_windowTooLarge,
	ZSTD_error_compressionParameter_unsupported,
	ZSTD_error_init_missing,
	ZSTD_error_memory_allocation,
	ZSTD_error_stage_wrong,
	ZSTD_error_dstSize_tooSmall,
	ZSTD_error_srcSize_wrong,
	ZSTD_error_corruption_detected,
	ZSTD_error_checksum_wrong,
	ZSTD_error_tableLog_tooLarge,
	ZSTD_error_maxSymbolValue_tooLarge,
	ZSTD_error_maxSymbolValue_tooSmall,
	ZSTD_error_dictionary_corrupted,
	ZSTD_error_dictionary_wrong,
	ZSTD_error_dictionaryCreation_failed,
	ZSTD_error_maxCode
} ZSTD_ErrorCode;

/**
 * ZSTD_maxCLevel() - maximum compression level available
 *
 * Return: Maximum compression level available.
 */
int ZSTD_maxCLevel(void);
/**
 * ZSTD_compressBound() - maximum compressed size in worst case scenario
 * @srcSize: The size of the data to compress.
 *
 * Return:   The maximum compressed size in the worst case scenario.
 */
size_t ZSTD_compressBound(size_t srcSize);
/**
 * ZSTD_isError() - tells if a size_t function result is an error code
 * @code:  The function result to check for error.
 *
 * Return: Non-zero iff the code is an error.
 */
static __attribute__((unused)) unsigned int ZSTD_isError(size_t code)
{
	return code > (size_t)-ZSTD_error_maxCode;
}
/**
 * ZSTD_getErrorCode() - translates an error function result to a ZSTD_ErrorCode
 * @functionResult: The result of a function for which ZSTD_isError() is true.
 *
 * Return:          The ZSTD_ErrorCode corresponding to the functionResult or 0
 *                  if the functionResult isn't an error.
 */
static __attribute__((unused)) ZSTD_ErrorCode ZSTD_getErrorCode(
	size_t functionResult)
{
	if (!ZSTD_isError(functionResult))
		return (ZSTD_ErrorCode)0;
	return (ZSTD_ErrorCode)(0 - functionResult);
}

/**
 * enum ZSTD_strategy - zstd compression search strategy
 *
 * From faster to stronger.
 */
typedef enum {
	ZSTD_fast,
	ZSTD_dfast,
	ZSTD_greedy,
	ZSTD_lazy,
	ZSTD_lazy2,
	ZSTD_btlazy2,
	ZSTD_btopt,
	ZSTD_btopt2
} ZSTD_strategy;

/**
 * struct ZSTD_compressionParameters - zstd compression parameters
 * @windowLog:    Log of the largest match distance. Larger means more
 *                compression, and more memory needed during decompression.
 * @chainLog:     Fully searched segment. Larger means more compression, slower,
 *                and more memory (useless for fast).
 * @hashLog:      Dispatch table. Larger means more compression,
 *                slower, and more memory.
 * @searchLog:    Number of searches. Larger means more compression and slower.
 * @searchLength: Match length searched. Larger means faster decompression,
 *                sometimes less compression.
 * @targetLength: Acceptable match size for optimal parser (only). Larger means
 *                more compression, and slower.
 * @strategy:     The zstd compression strategy.
 */
typedef struct {
	unsigned int windowLog;
	unsigned int chainLog;
	unsigned int hashLog;
	unsigned int searchLog;
	unsigned int searchLength;
	unsigned int targetLength;
	ZSTD_strategy strategy;
} ZSTD_compressionParameters;

/**
 * struct ZSTD_frameParameters - zstd frame parameters
 * @contentSizeFlag: Controls whether content size will be present in the frame
 *                   header (when known).
 * @checksumFlag:    Controls whether a 32-bit checksum is generated at the end
 *                   of the frame for error detection.
 * @noDictIDFlag:    Controls whether dictID will be saved into the frame header
 *                   when using dictionary compression.
 *
 * The default value is all fields set to 0.
 */
typedef struct {
	unsigned int contentSizeFlag;
	unsigned int checksumFlag;
	unsigned int noDictIDFlag;
} ZSTD_frameParameters;

/**
 * struct ZSTD_parameters - zstd parameters
 * @cParams: The compression parameters.
 * @fParams: The frame parameters.
 */
typedef struct {
	ZSTD_compressionParameters cParams;
	ZSTD_frameParameters fParams;
} ZSTD_parameters;

/**
 * ZSTD_getCParams() - returns ZSTD_compressionParameters for selected level
 * @compressionLevel: The compression level from 1 to ZSTD_maxCLevel().
 * @estimatedSrcSize: The estimated source size to compress or 0 if unknown.
 * @dictSize:         The dictionary size or 0 if a dictionary isn't being used.
 *
 * Return:            The selected ZSTD_compressionParameters.
 */
ZSTD_compressionParameters ZSTD_getCParams(int compressionLevel,
	unsigned long long estimatedSrcSize, size_t dictSize);

/**
 * ZSTD_getParams() - returns ZSTD_parameters for selected level
 * @compressionLevel: The compression level from 1 to ZSTD_maxCLevel().
 * @estimatedSrcSize: The estimated source size to compress or 0 if unknown.
 * @dictSize:         The dictionary size or 0 if a dictionary isn't being used.
 *
 * The same as ZSTD_getCParams() except also selects the default frame
 * parameters (all zero).
 *
 * Return:            The selected ZSTD_parameters.
 */
ZSTD_parameters ZSTD_getParams(int compressionLevel,
	unsigned long long estimatedSrcSize, size_t dictSize);

/*-*************************************
 * Explicit memory management
 **************************************/

/**
 * ZSTD_CCtxWorkspaceBound() - amount of memory needed to initialize a ZSTD_CCtx
 * @cParams: The compression parameters to be used for compression.
 *
 * If multiple compression parameters might be used, the caller must call
 * ZSTD_CCtxWorkspaceBound() for each set of parameters and use the maximum
 * size.
 *
 * Return:   A lower bound on the size of the workspace that is passed to
 *           ZSTD_initCCtx().
 */
size_t ZSTD_CCtxWorkspaceBound(ZSTD_compressionParameters cParams);

/**
 * struct ZSTD_CCtx - the zstd compression context
 *
 * When compressing many times it is recommended to allocate a context just once
 * and reuse it for each successive compression operation.
 */
typedef struct ZSTD_CCtx_s ZSTD_CCtx;
/**
 * ZSTD_initCCtx() - initialize a zstd compression context
 * @workspace:     The workspace to emplace the context into. It must outlive
 *                 the returned context.
 * @workspaceSize: The size of workspace. Use ZSTD_CCtxWorkspaceBound() to
 *                 determine how large the workspace must be.
 *
 * Return:         A compression context emplaced into workspace.
 */
ZSTD_CCtx *ZSTD_initCCtx(void *workspace, size_t workspaceSize);

/**
 * ZSTD_compressCCtx() - compress src into dst
 * @ctx:         The context. Must have been initialized with a workspace at
 *               least as large as ZSTD_CCtxWorkspaceBound(params.cParams).
 * @dst:         The buffer to compress src into.
 * @dstCapacity: The size of the destination buffer. May be any size, but
 *               ZSTD_compressBound(srcSize) is guaranteed to be large enough.
 * @src:         The data to compress.
 * @srcSize:     The size of the data to compress.
 * @params:      The parameters to use for compression. See ZSTD_getParams().
 *
 * Return:       The compressed size or an error, which can be checked using
 *               ZSTD_isError().
 */
size_t ZSTD_compressCCtx(ZSTD_CCtx *ctx, void *dst, size_t dstCapacity,
	const void *src, size_t srcSize, ZSTD_parameters params);

/**
 * ZSTD_DCtxWorkspaceBound() - amount of memory needed to initialize a ZSTD_DCtx
 *
 * Return: A lower bound on the size of the workspace that is passed to
 *         ZSTD_initDCtx().
 */
size_t ZSTD_DCtxWorkspaceBound(void);

/**
 * struct ZSTD_DCtx - the zstd decompression context
 *
 * When decompressing many times it is recommended to allocate a context just
 * once and reuse it for each successive decompression operation.
 */
typedef struct ZSTD_DCtx_s ZSTD_DCtx;
/**
 * ZSTD_initDCtx() - initialize a zstd decompression context
 * @workspace:     The workspace to emplace the context into. It must outlive
 *                 the returned context.
 * @workspaceSize: The size of workspace. Use ZSTD_DCtxWorkspaceBound() to
 *                 determine how large the workspace must be.
 *
 * Return:         A decompression context emplaced into workspace.
 */
ZSTD_DCtx *ZSTD_initDCtx(void *workspace, size_t workspaceSize);

/**
 * ZSTD_decompressDCtx() - decompress zstd compressed src into dst
 * @ctx:         The decompression context.
 * @dst:         The buffer to decompress src into.
 * @dstCapacity: The size of the destination buffer. Must be at least as large
 *               as the decompressed size. If the caller cannot upper bound the
 *               decompressed size, then it's better to use the streaming API.
 * @src:         The zstd compressed data to decompress. Multiple concatenated
 *               frames and skippable frames are allowed.
 * @srcSize:     The exact size of the data to decompress.
 *
 * Return:       The decompressed size or an error, which can be checked using
 *               ZSTD_isError().
 */
size_t ZSTD_decompressDCtx(ZSTD_DCtx *ctx, void *dst, size_t dstCapacity,
	const void *src, size_t srcSize);

/*-************************
 * Simple dictionary API
 **************************/

/**
 * ZSTD_compress_usingDict() - compress src into dst using a dictionary
 * @ctx:         The context. Must have been initialized with a workspace at
 *               least as large as ZSTD_CCtxWorkspaceBound(params.cParams).
 * @dst:         The buffer to compress src into.
 * @dstCapacity: The size of the destination buffer. May be any size, but
 *               ZSTD_compressBound(srcSize) is guaranteed to be large enough.
 * @src:         The data to compress.
 * @srcSize:     The size of the data to compress.
 * @dict:        The dictionary to use for compression.
 * @dictSize:    The size of the dictionary.
 * @params:      The parameters to use for compression. See ZSTD_getParams().
 *
 * Compression using a predefined dictionary. The same dictionary must be used
 * during decompression.
 *
 * Return:       The compressed size or an error, which can be checked using
 *               ZSTD_isError().
 */
size_t ZSTD_compress_usingDict(ZSTD_CCtx *ctx, void *dst, size_t dstCapacity,
	const void *src, size_t srcSize, const void *dict, size_t dictSize,
	ZSTD_parameters params);

/**
 * ZSTD_decompress_usingDict() - decompress src into dst using a dictionary
 * @ctx:         The decompression context.
 * @dst:         The buffer to decompress src into.
 * @dstCapacity: The size of the destination buffer. Must be at least as large
 *               as the decompressed size. If the caller cannot upper bound the
 *               decompressed size, then it's better to use the streaming API.
 * @src:         The zstd compressed data to decompress. Multiple concatenated
 *               frames and skippable frames are allowed.
 * @srcSize:     The exact size of the data to decompress.
 * @dict:        The dictionary to use for decompression. The same dictionary
 *               must've been used to compress the data.
 * @dictSize:    The size of the dictionary.
 *
 * Return:       The decompressed size or an error, which can be checked using
 *               ZSTD_isError().
 */
size_t ZSTD_decompress_usingDict(ZSTD_DCtx *ctx, void *dst, size_t dstCapacity,
	const void *src, size_t srcSize, const void *dict, size_t dictSize);

/*-**************************
 * Fast dictionary API
 ***************************/

/**
 * ZSTD_CDictWorkspaceBound() - memory needed to initialize a ZSTD_CDict
 * @cParams: The compression parameters to be used for compression.
 *
 * Return:   A lower bound on the size of the workspace that is passed to
 *           ZSTD_initCDict().
 */
size_t ZSTD_CDictWorkspaceBound(ZSTD_compressionParameters cParams);

/**
 * struct ZSTD_CDict - a digested dictionary to be used for compression
 */
typedef struct ZSTD_CDict_s ZSTD_CDict;

/**
 * ZSTD_initCDict() - initialize a digested dictionary for compression
 * @dictBuffer:    The dictionary to digest. The buffer is referenced by the
 *                 ZSTD_CDict so it must outlive the returned ZSTD_CDict.
 * @dictSize:      The size of the dictionary.
 * @params:        The parameters to use for compression. See ZSTD_getParams().
 * @workspace:     The workspace. It must outlive the returned ZSTD_CDict.
 * @workspaceSize: The workspace size. Must be at least
 *                 ZSTD_CDictWorkspaceBound(params.cParams).
 *
 * When compressing multiple messages / blocks with the same dictionary it is
 * recommended to load it just once. The ZSTD_CDict merely references the
 * dictBuffer, so it must outlive the returned ZSTD_CDict.
 *
 * Return:         The digested dictionary emplaced into workspace.
 */
ZSTD_CDict *ZSTD_initCDict(const void *dictBuffer, size_t dictSize,
	ZSTD_parameters params, void *workspace, size_t workspaceSize);

/**
 * ZSTD_compress_usingCDict() - compress src into dst using a ZSTD_CDict
 * @ctx:         The context. Must have been initialized with a workspace at
 *               least as large as ZSTD_CCtxWorkspaceBound(cParams) where
 *               cParams are the compression parameters used to initialize the
 *               cdict.
 * @dst:         The buffer to compress src into.
 * @dstCapacity: The size of the destination buffer. May be any size, but
 *               ZSTD_compressBound(srcSize) is guaranteed to be large enough.
 * @src:         The data to compress.
 * @srcSize:     The size of the data to compress.
 * @cdict:       The digested dictionary to use for compression.
 * @params:      The parameters to use for compression. See ZSTD_getParams().
 *
 * Compression using a digested dictionary. The same dictionary must be used
 * during decompression.
 *
 * Return:       The compressed size or an error, which can be checked using
 *               ZSTD_isError().
 */
size_t ZSTD_compress_usingCDict(ZSTD_CCtx *cctx, void *dst, size_t dstCapacity,
	const void *src, size_t srcSize, const ZSTD_CDict *cdict);


/**
 * ZSTD_DDictWorkspaceBound() - memory needed to initialize a ZSTD_DDict
 *
 * Return:  A lower bound on the size of the workspace that is passed to
 *          ZSTD_initDDict().
 */
size_t ZSTD_DDictWorkspaceBound(void);

/**
 * struct ZSTD_DDict - a digested dictionary to be used for decompression
 */
typedef struct ZSTD_DDict_s ZSTD_DDict;

/**
 * ZSTD_initDDict() - initialize a digested dictionary for decompression
 * @dictBuffer:    The dictionary to digest. The buffer is referenced by the
 *                 ZSTD_DDict so it must outlive the returned ZSTD_DDict.
 * @dictSize:      The size of the dictionary.
 * @workspace:     The workspace. It must outlive the returned ZSTD_DDict.
 * @workspaceSize: The workspace size. Must be at least
 *                 ZSTD_DDictWorkspaceBound().
 *
 * When decompressing multiple messages / blocks with the same dictionary it is
 * recommended to load it just once. The ZSTD_DDict merely references the
 * dictBuffer, so it must outlive the returned ZSTD_DDict.
 *
 * Return:         The digested dictionary emplaced into workspace.
 */
ZSTD_DDict *ZSTD_initDDict(const void *dictBuffer, size_t dictSize,
	void *workspace, size_t workspaceSize);

/**
 * ZSTD_decompress_usingDDict() - decompress src into dst using a ZSTD_DDict
 * @ctx:         The decompression context.
 * @dst:         The buffer to decompress src into.
 * @dstCapacity: The size of the destination buffer. Must be at least as large
 *               as the decompressed size. If the caller cannot upper bound the
 *               decompressed size, then it's better to use the streaming API.
 * @src:         The zstd compressed data to decompress. Multiple concatenated
 *               frames and skippable frames are allowed.
 * @srcSize:     The exact size of the data to decompress.
 * @ddict:       The digested dictionary to use for decompression. The same
 *               dictionary must've been used to compress the data.
 *
 * Return:       The decompressed size or an error, which can be checked using
 *               ZSTD_isError().
 */
size_t ZSTD_decompress_usingDDict(ZSTD_DCtx *dctx, void *dst,
	size_t dstCapacity, const void *src, size_t srcSize,
	const ZSTD_DDict *ddict);


/*-**************************
 * Streaming
 ***************************/

/**
 * struct ZSTD_inBuffer - input buffer for streaming
 * @src:  Start of the input buffer.
 * @size: Size of the input buffer.
 * @pos:  Position where reading stopped. Will be updated.
 *        Necessarily 0 <= pos <= size.
 */
typedef struct ZSTD_inBuffer_s {
	const void *src;
	size_t size;
	size_t pos;
} ZSTD_inBuffer;

/**
 * struct ZSTD_outBuffer - output buffer for streaming
 * @dst:  Start of the output buffer.
 * @size: Size of the output buffer.
 * @pos:  Position where writing stopped. Will be updated.
 *        Necessarily 0 <= pos <= size.
 */
typedef struct ZSTD_outBuffer_s {
	void *dst;
	size_t size;
	size_t pos;
} ZSTD_outBuffer;



/*-*****************************************************************************
 * Streaming compression - HowTo
 *
 * A ZSTD_CStream object is required to track streaming operation.
 * Use ZSTD_initCStream() to initialize a ZSTD_CStream object.
 * ZSTD_CStream objects can be reused multiple times on consecutive compression
 * operations. It is recommended to re-use ZSTD_CStream in situations where many
 * streaming operations will be achieved consecutively. Use one separate
 * ZSTD_CStream per thread for parallel execution.
 *
 * Use ZSTD_compressStream() repetitively to consume input stream.
 * The function will automatically update both `pos` fields.
 * Note that it may not consume the entire input, in which case `pos < size`,
 * and it's up to the caller to present again remaining data.
 * It returns a hint for the preferred number of bytes to use as an input for
 * the next function call.
 *
 * At any moment, it's possible to flush whatever data remains within internal
 * buffer, using ZSTD_flushStream(). `output->pos` will be updated. There might
 * still be some content left within the internal buffer if `output->size` is
 * too small. It returns the number of bytes left in the internal buffer and
 * must be called until it returns 0.
 *
 * ZSTD_endStream() instructs to finish a frame. It will perform a flush and
 * write frame epilogue. The epilogue is required for decoders to consider a
 * frame completed. Similar to ZSTD_flushStream(), it may not be able to flush
 * the full content if `output->size` is too small. In which case, call again
 * ZSTD_endStream() to complete the flush. It returns the number of bytes left
 * in the internal buffer and must be called until it returns 0.
 ******************************************************************************/

/**
 * ZSTD_CStreamWorkspaceBound() - memory needed to initialize a ZSTD_CStream
 * @cParams: The compression parameters to be used for compression.
 *
 * Retu