include/linux/lz4.h

4  * Copyright (C) 2016, Sven Schmidt <4sschmid@informatik.uni-hamburg.de>
11  * for LZ4 - Fast LZ compression algorithm.
13  * LZ4 - Fast LZ compression algorithm
14  * Copyright (C) 2011-2016, Yann Collet.
15  * BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
37  *	- LZ4 homepage : http://www.lz4.org
38  *	- LZ4 source repository : https://github.com/lz4/lz4
47 /*-************************************************************************
52  * Memory usage formula : N->2^N Bytes
53  * (examples : 10 -> 1KB; 12 -> 4KB ; 16 -> 64KB; 20 -> 1MB; etc.)
67 #define LZ4_HASHLOG	 (LZ4_MEMORY_USAGE-2)
77 #define LZ4HC_MAXD_MASK (LZ4HC_MAXD - 1)
78 #define LZ4HC_HASH_LOG (LZ4HC_DICTIONARY_LOGSIZE - 1)
80 #define LZ4HC_HASH_MASK (LZ4HC_HASHTABLESIZE - 1)
82 /*-************************************************************************
85 #define LZ4_STREAMSIZE_U64 ((1 << (LZ4_MEMORY_USAGE - 3)) + 4)
96  * LZ4_stream_t - information structure to track an LZ4 stream.
112  * LZ4_streamHC_t - information structure to track an LZ4HC stream.
137  * LZ4_streamDecode_t - information structure to track an
153 /*-************************************************************************
154  *	SIZE OF STATE
159 /*-************************************************************************
164  * LZ4_compressBound() - Max. output size in worst case szenarios
165  * @isize: Size of the input data
167  * Return: Max. size LZ4 may output in a "worst case" szenario
176  * LZ4_compress_default() - Compress data from source to dest
178  * @dest: output buffer address of the compressed data
179  * @inputSize: size of the input data. Max supported value is LZ4_MAX_INPUT_SIZE
180  * @maxOutputSize: full or partial size of buffer 'dest'
185  * Compresses 'sourceSize' bytes from buffer 'source'
186  * into already allocated 'dest' buffer of size 'maxOutputSize'.
194  * Return: Number of bytes written into buffer 'dest'
201  * LZ4_compress_fast() - As LZ4_compress_default providing an acceleration param
203  * @dest: output buffer address of the compressed data
204  * @inputSize: size of the input data. Max supported value is LZ4_MAX_INPUT_SIZE
205  * @maxOutputSize: full or partial size of buffer 'dest'
213  * but also the lesser the compression. It's a trade-off. It can be fine tuned,
218  * Return: Number of bytes written into buffer 'dest'
225  * LZ4_compress_destSize() - Compress as much data as possible
228  * @dest: output buffer address of the compressed data
231  * @targetDestSize: Size of buffer 'dest' which must be already allocated
236  * from 'source' buffer into already allocated buffer 'dest'
237  * of size 'targetDestSize'.
239  * if it's large enough, or fill 'dest' buffer completely with as much data as
248 /*-************************************************************************
253  * LZ4_decompress_fast() - Decompresses data from 'source' into 'dest'
255  * @dest: output buffer address of the uncompressed data
257  * @originalSize: is the original and therefore uncompressed size
268  * Return: number of bytes read from the source buffer
274  * LZ4_decompress_safe() - Decompression protected against buffer overflow
276  * @dest: output buffer address of the uncompressed data
278  * @compressedSize: is the precise full size of the compressed block
279  * @maxDecompressedSize: is the size of 'dest' buffer
284  * This function is protected against buffer overflow exploits,
285  * including malicious data packets. It never writes outside output buffer,
286  * nor reads outside input buffer.
288  * Return: number of bytes decompressed into destination buffer
296  * LZ4_decompress_safe_partial() - Decompress a block of size 'compressedSize'
297  *	at position 'source' into buffer 'dest'
299  * @dest: output buffer address of the decompressed data which must be
301  * @compressedSize: is the precise full size of the compressed block.
304  * @maxDecompressedSize: is the size of destination buffer
306  * This function decompresses a compressed block of size 'compressedSize'
307  * at position 'source' into destination buffer 'dest'
308  * of size 'maxDecompressedSize'.
311  * This function never writes outside of output buffer,
312  * and never reads outside of input buffer.
315  * Return: the number of bytes decoded in the destination buffer
323 /*-************************************************************************
328  * LZ4_compress_HC() - Compress data from `src` into `dst`, using HC algorithm
330  * @dst: output buffer address of the compressed data
331  * @srcSize: size of the input data. Max supported value is LZ4_MAX_INPUT_SIZE
332  * @dstCapacity: full or partial size of buffer 'dst',
338  *	This requires 'wrkmem' of size LZ4HC_MEM_COMPRESS.
350  * LZ4_resetStreamHC() - Init an allocated 'LZ4_streamHC_t' structure
357  * and re-used multiple times.
364  * LZ4_loadDictHC() - Load a static dictionary into LZ4_streamHC
367  * @dictSize: size of dictionary
372  * Loading a size of 0 is allowed.
374  * Return : dictionary size, in bytes (necessarily <= 64 KB)
380  * LZ4_compress_HC_continue() - Compress 'src' using data from previously
384  * @dst: output buffer address of the compressed data,
386  * @srcSize: size of the input data. Max supported value is LZ4_MAX_INPUT_SIZE
387  * @maxDstSize: full or partial size of buffer 'dest'
390  * These functions compress data in successive blocks of any size, using
392  * blocks (up to 64 KB) remain read-accessible while
405  * 'dst' buffer should be sized to handle worst case scenarios, using
410  * Return value of LZ4_saveDictHC() is the size of dictionary
413  * Return: Number of bytes written into buffer 'dst'  or 0 if compression fails
419  * LZ4_saveDictHC() - Save static dictionary from LZ4HC_stream
421  * @safeBuffer: buffer to save dictionary to, must be already allocated
422  * @maxDictSize: size of 'safeBuffer'
431  * Return : saved dictionary size in bytes (necessarily <= maxDictSize),
437 /*-*********************************************
442  * LZ4_resetStream() - Init an allocated 'LZ4_stream_t' structure
446  * and re-used multiple times.
453  * LZ4_loadDict() - Load a static dictionary into LZ4_stream
456  * @dictSize: size of dictionary
461  * Loading a size of 0 is allowed.
463  * Return : dictionary size, in bytes (necessarily <= 64 KB)
469  * LZ4_saveDict() - Save static dictionary from LZ4_stream
471  * @safeBuffer: buffer to save dictionary to, must be already allocated
472  * @dictSize: size of 'safeBuffer'
481  * Return : saved dictionary size in bytes (necessarily <= dictSize),
487  * LZ4_compress_fast_continue() - Compress 'src' using data from previously
491  * @dst: output buffer address of the compressed data,
493  * @srcSize: size of the input data. Max supported value is LZ4_MAX_INPUT_SIZE
494  * @maxDstSize: full or partial size of buffer 'dest'
498  * Compress buffer content 'src', using data from previously compressed blocks
505  * Return: Number of bytes written into buffer 'dst'  or 0 if compression fails
511  * LZ4_setStreamDecode() - Instruct where to find dictionary
514  * @dictSize: size of dictionary
517  *	Setting a size of 0 is allowed (same effect as reset).
525  * LZ4_decompress_safe_continue() - Decompress blocks in streaming mode
528  * @dest: output buffer address of the uncompressed data
530  * @compressedSize: is the precise full size of the compressed block
531  * @maxDecompressedSize: is the size of 'dest' buffer
537  * In the case of a ring buffers, decoding buffer must be either :
538  *    - Exactly same size as encoding buffer, with same update rule
540  *      the decoding & encoding ring buffer can have any size,
542  *    - Larger than encoding buffer, by a minimum of maxBlockSize more bytes.
544  *      It's the maximum size you intend to compress into a single block.
546  *      to be synchronized, and encoding ring buffer can have any size,
548  *    - _At least_ 64 KB + 8 bytes + maxBlockSize.
550  *      synchronized, and encoding ring buffer can have any size,
551  *      including larger than decoding buffer. W
553  * data into a safe buffer, and indicate where it is saved
556  * Return: number of bytes decompressed into destination buffer
565  * LZ4_decompress_fast_continue() - Decompress blocks in streaming mode
568  * @dest: output buffer address of the uncompressed data
570  * @originalSize: is the original and therefore uncompressed size
576  * In the case of a ring buffers, decoding buffer must be either :
577  *    - Exactly same size as encoding buffer, with same update rule
579  *      the decoding & encoding ring buffer can have any size,
581  *    - Larger than encoding buffer, by a minimum of maxBlockSize more bytes.
583  *      It's the maximum size you intend to compress into a single block.
585  *      to be synchronized, and encoding ring buffer can have any size,
587  *    - _At least_ 64 KB + 8 bytes + maxBlockSize.
589  *      synchronized, and encoding ring buffer can have any size,
590  *      including larger than decoding buffer. W
592  * data into a safe buffer, and indicate where it is saved
595  * Return: number of bytes decompressed into destination buffer
603  * LZ4_decompress_safe_usingDict() - Same as LZ4_setStreamDecode()
606  * @dest: output buffer address of the uncompressed data
608  * @compressedSize: is the precise full size of the compressed block
609  * @maxDecompressedSize: is the size of 'dest' buffer
611  * @dictSize: size of dictionary
616  * It is stand-alone, and doesn't need an LZ4_streamDecode_t structure.
618  * Return: number of bytes decompressed into destination buffer
627  * LZ4_decompress_fast_usingDict() - Same as LZ4_setStreamDecode()
630  * @dest: output buffer address of the uncompressed data
632  * @originalSize: is the original and therefore uncompressed size
634  * @dictSize: size of dictionary
639  * It is stand-alone, and doesn't need an LZ4_streamDecode_t structure.
641  * Return: number of bytes decompressed into destination buffer