Sven Schmidt | 4e1a33b | 2017-02-24 15:01:12 -0800 | [diff] [blame] | 1 | /* LZ4 Kernel Interface |
Kyungsik Lee | cffb78b | 2013-07-08 16:01:45 -0700 | [diff] [blame] | 2 | * |
| 3 | * Copyright (C) 2013, LG Electronics, Kyungsik Lee <kyungsik.lee@lge.com> |
Sven Schmidt | 4e1a33b | 2017-02-24 15:01:12 -0800 | [diff] [blame] | 4 | * Copyright (C) 2016, Sven Schmidt <4sschmid@informatik.uni-hamburg.de> |
Kyungsik Lee | cffb78b | 2013-07-08 16:01:45 -0700 | [diff] [blame] | 5 | * |
| 6 | * This program is free software; you can redistribute it and/or modify |
| 7 | * it under the terms of the GNU General Public License version 2 as |
| 8 | * published by the Free Software Foundation. |
Sven Schmidt | 4e1a33b | 2017-02-24 15:01:12 -0800 | [diff] [blame] | 9 | * |
| 10 | * This file is based on the original header file |
| 11 | * for LZ4 - Fast LZ compression algorithm. |
| 12 | * |
| 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) |
| 16 | * Redistribution and use in source and binary forms, with or without |
| 17 | * modification, are permitted provided that the following conditions are |
| 18 | * met: |
| 19 | * * Redistributions of source code must retain the above copyright |
| 20 | * notice, this list of conditions and the following disclaimer. |
| 21 | * * Redistributions in binary form must reproduce the above |
| 22 | * copyright notice, this list of conditions and the following disclaimer |
| 23 | * in the documentation and/or other materials provided with the |
| 24 | * distribution. |
| 25 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 26 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 27 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| 28 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
| 29 | * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| 30 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| 31 | * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| 32 | * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| 33 | * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| 34 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
| 35 | * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 36 | * You can contact the author at : |
| 37 | * - LZ4 homepage : http://www.lz4.org |
| 38 | * - LZ4 source repository : https://github.com/lz4/lz4 |
Kyungsik Lee | cffb78b | 2013-07-08 16:01:45 -0700 | [diff] [blame] | 39 | */ |
Sven Schmidt | 4e1a33b | 2017-02-24 15:01:12 -0800 | [diff] [blame] | 40 | |
| 41 | #ifndef __LZ4_H__ |
| 42 | #define __LZ4_H__ |
| 43 | |
| 44 | #include <linux/types.h> |
| 45 | #include <linux/string.h> /* memset, memcpy */ |
| 46 | |
| 47 | /*-************************************************************************ |
| 48 | * CONSTANTS |
| 49 | **************************************************************************/ |
| 50 | /* |
| 51 | * LZ4_MEMORY_USAGE : |
| 52 | * Memory usage formula : N->2^N Bytes |
| 53 | * (examples : 10 -> 1KB; 12 -> 4KB ; 16 -> 64KB; 20 -> 1MB; etc.) |
| 54 | * Increasing memory usage improves compression ratio |
| 55 | * Reduced memory usage can improve speed, due to cache effect |
| 56 | * Default value is 14, for 16KB, which nicely fits into Intel x86 L1 cache |
| 57 | */ |
| 58 | #define LZ4_MEMORY_USAGE 14 |
| 59 | |
| 60 | #define LZ4_MAX_INPUT_SIZE 0x7E000000 /* 2 113 929 216 bytes */ |
| 61 | #define LZ4_COMPRESSBOUND(isize) (\ |
| 62 | (unsigned int)(isize) > (unsigned int)LZ4_MAX_INPUT_SIZE \ |
| 63 | ? 0 \ |
| 64 | : (isize) + ((isize)/255) + 16) |
| 65 | |
| 66 | #define LZ4_ACCELERATION_DEFAULT 1 |
| 67 | #define LZ4_HASHLOG (LZ4_MEMORY_USAGE-2) |
| 68 | #define LZ4_HASHTABLESIZE (1 << LZ4_MEMORY_USAGE) |
| 69 | #define LZ4_HASH_SIZE_U32 (1 << LZ4_HASHLOG) |
| 70 | |
| 71 | #define LZ4HC_MIN_CLEVEL 3 |
| 72 | #define LZ4HC_DEFAULT_CLEVEL 9 |
| 73 | #define LZ4HC_MAX_CLEVEL 16 |
| 74 | |
| 75 | #define LZ4HC_DICTIONARY_LOGSIZE 16 |
| 76 | #define LZ4HC_MAXD (1<<LZ4HC_DICTIONARY_LOGSIZE) |
| 77 | #define LZ4HC_MAXD_MASK (LZ4HC_MAXD - 1) |
| 78 | #define LZ4HC_HASH_LOG (LZ4HC_DICTIONARY_LOGSIZE - 1) |
| 79 | #define LZ4HC_HASHTABLESIZE (1 << LZ4HC_HASH_LOG) |
| 80 | #define LZ4HC_HASH_MASK (LZ4HC_HASHTABLESIZE - 1) |
| 81 | |
| 82 | /*-************************************************************************ |
| 83 | * STREAMING CONSTANTS AND STRUCTURES |
| 84 | **************************************************************************/ |
| 85 | #define LZ4_STREAMSIZE_U64 ((1 << (LZ4_MEMORY_USAGE - 3)) + 4) |
| 86 | #define LZ4_STREAMSIZE (LZ4_STREAMSIZE_U64 * sizeof(unsigned long long)) |
| 87 | |
| 88 | #define LZ4_STREAMHCSIZE 262192 |
| 89 | #define LZ4_STREAMHCSIZE_SIZET (262192 / sizeof(size_t)) |
| 90 | |
| 91 | #define LZ4_STREAMDECODESIZE_U64 4 |
| 92 | #define LZ4_STREAMDECODESIZE (LZ4_STREAMDECODESIZE_U64 * \ |
| 93 | sizeof(unsigned long long)) |
Kyungsik Lee | cffb78b | 2013-07-08 16:01:45 -0700 | [diff] [blame] | 94 | |
| 95 | /* |
Sven Schmidt | 4e1a33b | 2017-02-24 15:01:12 -0800 | [diff] [blame] | 96 | * LZ4_stream_t - information structure to track an LZ4 stream. |
Kyungsik Lee | cffb78b | 2013-07-08 16:01:45 -0700 | [diff] [blame] | 97 | */ |
Sven Schmidt | 4e1a33b | 2017-02-24 15:01:12 -0800 | [diff] [blame] | 98 | typedef struct { |
| 99 | uint32_t hashTable[LZ4_HASH_SIZE_U32]; |
| 100 | uint32_t currentOffset; |
| 101 | uint32_t initCheck; |
| 102 | const uint8_t *dictionary; |
| 103 | uint8_t *bufferStart; |
| 104 | uint32_t dictSize; |
| 105 | } LZ4_stream_t_internal; |
| 106 | typedef union { |
| 107 | unsigned long long table[LZ4_STREAMSIZE_U64]; |
| 108 | LZ4_stream_t_internal internal_donotuse; |
| 109 | } LZ4_stream_t; |
| 110 | |
| 111 | /* |
| 112 | * LZ4_streamHC_t - information structure to track an LZ4HC stream. |
| 113 | */ |
| 114 | typedef struct { |
| 115 | unsigned int hashTable[LZ4HC_HASHTABLESIZE]; |
| 116 | unsigned short chainTable[LZ4HC_MAXD]; |
| 117 | /* next block to continue on current prefix */ |
| 118 | const unsigned char *end; |
| 119 | /* All index relative to this position */ |
| 120 | const unsigned char *base; |
| 121 | /* alternate base for extDict */ |
| 122 | const unsigned char *dictBase; |
| 123 | /* below that point, need extDict */ |
| 124 | unsigned int dictLimit; |
| 125 | /* below that point, no more dict */ |
| 126 | unsigned int lowLimit; |
| 127 | /* index from which to continue dict update */ |
| 128 | unsigned int nextToUpdate; |
| 129 | unsigned int compressionLevel; |
| 130 | } LZ4HC_CCtx_internal; |
| 131 | typedef union { |
| 132 | size_t table[LZ4_STREAMHCSIZE_SIZET]; |
| 133 | LZ4HC_CCtx_internal internal_donotuse; |
| 134 | } LZ4_streamHC_t; |
| 135 | |
| 136 | /* |
| 137 | * LZ4_streamDecode_t - information structure to track an |
| 138 | * LZ4 stream during decompression. |
| 139 | * |
| 140 | * init this structure using LZ4_setStreamDecode (or memset()) before first use |
| 141 | */ |
| 142 | typedef struct { |
| 143 | const uint8_t *externalDict; |
| 144 | size_t extDictSize; |
| 145 | const uint8_t *prefixEnd; |
| 146 | size_t prefixSize; |
| 147 | } LZ4_streamDecode_t_internal; |
| 148 | typedef union { |
| 149 | unsigned long long table[LZ4_STREAMDECODESIZE_U64]; |
| 150 | LZ4_streamDecode_t_internal internal_donotuse; |
| 151 | } LZ4_streamDecode_t; |
| 152 | |
| 153 | /*-************************************************************************ |
| 154 | * SIZE OF STATE |
| 155 | **************************************************************************/ |
| 156 | #define LZ4_MEM_COMPRESS LZ4_STREAMSIZE |
| 157 | #define LZ4HC_MEM_COMPRESS LZ4_STREAMHCSIZE |
| 158 | |
| 159 | /*-************************************************************************ |
| 160 | * Compression Functions |
| 161 | **************************************************************************/ |
| 162 | |
| 163 | /** |
| 164 | * LZ4_compressBound() - Max. output size in worst case szenarios |
| 165 | * @isize: Size of the input data |
| 166 | * |
| 167 | * Return: Max. size LZ4 may output in a "worst case" szenario |
| 168 | * (data not compressible) |
| 169 | */ |
| 170 | static inline int LZ4_compressBound(size_t isize) |
Kyungsik Lee | cffb78b | 2013-07-08 16:01:45 -0700 | [diff] [blame] | 171 | { |
Sven Schmidt | 4e1a33b | 2017-02-24 15:01:12 -0800 | [diff] [blame] | 172 | return LZ4_COMPRESSBOUND(isize); |
Kyungsik Lee | cffb78b | 2013-07-08 16:01:45 -0700 | [diff] [blame] | 173 | } |
| 174 | |
Sven Schmidt | 4e1a33b | 2017-02-24 15:01:12 -0800 | [diff] [blame] | 175 | /** |
Sven Schmidt | 4e1a33b | 2017-02-24 15:01:12 -0800 | [diff] [blame] | 176 | * LZ4_compress_default() - Compress data from source to dest |
| 177 | * @source: source address of the original data |
| 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' |
| 181 | * which must be already allocated |
| 182 | * @wrkmem: address of the working memory. |
| 183 | * This requires 'workmem' of LZ4_MEM_COMPRESS. |
| 184 | * |
| 185 | * Compresses 'sourceSize' bytes from buffer 'source' |
| 186 | * into already allocated 'dest' buffer of size 'maxOutputSize'. |
| 187 | * Compression is guaranteed to succeed if |
| 188 | * 'maxOutputSize' >= LZ4_compressBound(inputSize). |
| 189 | * It also runs faster, so it's a recommended setting. |
| 190 | * If the function cannot compress 'source' into a more limited 'dest' budget, |
| 191 | * compression stops *immediately*, and the function result is zero. |
| 192 | * As a consequence, 'dest' content is not valid. |
| 193 | * |
| 194 | * Return: Number of bytes written into buffer 'dest' |
| 195 | * (necessarily <= maxOutputSize) or 0 if compression fails |
Kyungsik Lee | cffb78b | 2013-07-08 16:01:45 -0700 | [diff] [blame] | 196 | */ |
Sven Schmidt | 4e1a33b | 2017-02-24 15:01:12 -0800 | [diff] [blame] | 197 | int LZ4_compress_default(const char *source, char *dest, int inputSize, |
| 198 | int maxOutputSize, void *wrkmem); |
| 199 | |
| 200 | /** |
| 201 | * LZ4_compress_fast() - As LZ4_compress_default providing an acceleration param |
| 202 | * @source: source address of the original data |
| 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' |
| 206 | * which must be already allocated |
| 207 | * @acceleration: acceleration factor |
| 208 | * @wrkmem: address of the working memory. |
| 209 | * This requires 'workmem' of LZ4_MEM_COMPRESS. |
| 210 | * |
| 211 | * Same as LZ4_compress_default(), but allows to select an "acceleration" |
| 212 | * factor. The larger the acceleration value, the faster the algorithm, |
| 213 | * but also the lesser the compression. It's a trade-off. It can be fine tuned, |
| 214 | * with each successive value providing roughly +~3% to speed. |
| 215 | * An acceleration value of "1" is the same as regular LZ4_compress_default() |
| 216 | * Values <= 0 will be replaced by LZ4_ACCELERATION_DEFAULT, which is 1. |
| 217 | * |
| 218 | * Return: Number of bytes written into buffer 'dest' |
| 219 | * (necessarily <= maxOutputSize) or 0 if compression fails |
| 220 | */ |
| 221 | int LZ4_compress_fast(const char *source, char *dest, int inputSize, |
| 222 | int maxOutputSize, int acceleration, void *wrkmem); |
| 223 | |
| 224 | /** |
| 225 | * LZ4_compress_destSize() - Compress as much data as possible |
| 226 | * from source to dest |
| 227 | * @source: source address of the original data |
| 228 | * @dest: output buffer address of the compressed data |
| 229 | * @sourceSizePtr: will be modified to indicate how many bytes where read |
| 230 | * from 'source' to fill 'dest'. New value is necessarily <= old value. |
| 231 | * @targetDestSize: Size of buffer 'dest' which must be already allocated |
| 232 | * @wrkmem: address of the working memory. |
| 233 | * This requires 'workmem' of LZ4_MEM_COMPRESS. |
| 234 | * |
| 235 | * Reverse the logic, by compressing as much data as possible |
| 236 | * from 'source' buffer into already allocated buffer 'dest' |
| 237 | * of size 'targetDestSize'. |
| 238 | * This function either compresses the entire 'source' content into 'dest' |
| 239 | * if it's large enough, or fill 'dest' buffer completely with as much data as |
| 240 | * possible from 'source'. |
| 241 | * |
| 242 | * Return: Number of bytes written into 'dest' (necessarily <= targetDestSize) |
| 243 | * or 0 if compression fails |
| 244 | */ |
| 245 | int LZ4_compress_destSize(const char *source, char *dest, int *sourceSizePtr, |
| 246 | int targetDestSize, void *wrkmem); |
Kyungsik Lee | cffb78b | 2013-07-08 16:01:45 -0700 | [diff] [blame] | 247 | |
Sven Schmidt | 4e1a33b | 2017-02-24 15:01:12 -0800 | [diff] [blame] | 248 | /*-************************************************************************ |
| 249 | * Decompression Functions |
| 250 | **************************************************************************/ |
| 251 | |
| 252 | /** |
| 253 | * LZ4_decompress_fast() - Decompresses data from 'source' into 'dest' |
| 254 | * @source: source address of the compressed data |
| 255 | * @dest: output buffer address of the uncompressed data |
| 256 | * which must be already allocated with 'originalSize' bytes |
| 257 | * @originalSize: is the original and therefore uncompressed size |
| 258 | * |
| 259 | * Decompresses data from 'source' into 'dest'. |
| 260 | * This function fully respect memory boundaries for properly formed |
| 261 | * compressed data. |
| 262 | * It is a bit faster than LZ4_decompress_safe(). |
| 263 | * However, it does not provide any protection against intentionally |
| 264 | * modified data stream (malicious input). |
| 265 | * Use this function in trusted environment only |
| 266 | * (data to decode comes from a trusted source). |
| 267 | * |
| 268 | * Return: number of bytes read from the source buffer |
| 269 | * or a negative result if decompression fails. |
| 270 | */ |
| 271 | int LZ4_decompress_fast(const char *source, char *dest, int originalSize); |
| 272 | |
| 273 | /** |
| 274 | * LZ4_decompress_safe() - Decompression protected against buffer overflow |
| 275 | * @source: source address of the compressed data |
| 276 | * @dest: output buffer address of the uncompressed data |
| 277 | * which must be already allocated |
| 278 | * @compressedSize: is the precise full size of the compressed block |
| 279 | * @maxDecompressedSize: is the size of 'dest' buffer |
| 280 | * |
| 281 | * Decompresses data fom 'source' into 'dest'. |
| 282 | * If the source stream is detected malformed, the function will |
| 283 | * stop decoding and return a negative result. |
| 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. |
| 287 | * |
| 288 | * Return: number of bytes decompressed into destination buffer |
| 289 | * (necessarily <= maxDecompressedSize) |
| 290 | * or a negative result in case of error |
| 291 | */ |
| 292 | int LZ4_decompress_safe(const char *source, char *dest, int compressedSize, |
| 293 | int maxDecompressedSize); |
| 294 | |
| 295 | /** |
| 296 | * LZ4_decompress_safe_partial() - Decompress a block of size 'compressedSize' |
| 297 | * at position 'source' into buffer 'dest' |
| 298 | * @source: source address of the compressed data |
| 299 | * @dest: output buffer address of the decompressed data which must be |
| 300 | * already allocated |
| 301 | * @compressedSize: is the precise full size of the compressed block. |
| 302 | * @targetOutputSize: the decompression operation will try |
| 303 | * to stop as soon as 'targetOutputSize' has been reached |
| 304 | * @maxDecompressedSize: is the size of destination buffer |
| 305 | * |
| 306 | * This function decompresses a compressed block of size 'compressedSize' |
| 307 | * at position 'source' into destination buffer 'dest' |
| 308 | * of size 'maxDecompressedSize'. |
| 309 | * The function tries to stop decompressing operation as soon as |
| 310 | * 'targetOutputSize' has been reached, reducing decompression time. |
| 311 | * This function never writes outside of output buffer, |
| 312 | * and never reads outside of input buffer. |
| 313 | * It is therefore protected against malicious data packets. |
| 314 | * |
| 315 | * Return: the number of bytes decoded in the destination buffer |
| 316 | * (necessarily <= maxDecompressedSize) |
| 317 | * or a negative result in case of error |
| 318 | * |
| 319 | */ |
| 320 | int LZ4_decompress_safe_partial(const char *source, char *dest, |
| 321 | int compressedSize, int targetOutputSize, int maxDecompressedSize); |
| 322 | |
Sven Schmidt | 4e1a33b | 2017-02-24 15:01:12 -0800 | [diff] [blame] | 323 | /*-************************************************************************ |
| 324 | * LZ4 HC Compression |
| 325 | **************************************************************************/ |
| 326 | |
| 327 | /** |
| 328 | * LZ4_compress_HC() - Compress data from `src` into `dst`, using HC algorithm |
| 329 | * @src: source address of the original data |
| 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', |
| 333 | * which must be already allocated |
| 334 | * @compressionLevel: Recommended values are between 4 and 9, although any |
| 335 | * value between 1 and LZ4HC_MAX_CLEVEL will work. |
| 336 | * Values >LZ4HC_MAX_CLEVEL behave the same as 16. |
| 337 | * @wrkmem: address of the working memory. |
| 338 | * This requires 'wrkmem' of size LZ4HC_MEM_COMPRESS. |
| 339 | * |
| 340 | * Compress data from 'src' into 'dst', using the more powerful |
| 341 | * but slower "HC" algorithm. Compression is guaranteed to succeed if |
| 342 | * `dstCapacity >= LZ4_compressBound(srcSize) |
| 343 | * |
| 344 | * Return : the number of bytes written into 'dst' or 0 if compression fails. |
| 345 | */ |
| 346 | int LZ4_compress_HC(const char *src, char *dst, int srcSize, int dstCapacity, |
| 347 | int compressionLevel, void *wrkmem); |
| 348 | |
| 349 | /** |
Sven Schmidt | 4e1a33b | 2017-02-24 15:01:12 -0800 | [diff] [blame] | 350 | * LZ4_resetStreamHC() - Init an allocated 'LZ4_streamHC_t' structure |
| 351 | * @streamHCPtr: pointer to the 'LZ4_streamHC_t' structure |
| 352 | * @compressionLevel: Recommended values are between 4 and 9, although any |
| 353 | * value between 1 and LZ4HC_MAX_CLEVEL will work. |
| 354 | * Values >LZ4HC_MAX_CLEVEL behave the same as 16. |
| 355 | * |
| 356 | * An LZ4_streamHC_t structure can be allocated once |
| 357 | * and re-used multiple times. |
| 358 | * Use this function to init an allocated `LZ4_streamHC_t` structure |
| 359 | * and start a new compression. |
| 360 | */ |
| 361 | void LZ4_resetStreamHC(LZ4_streamHC_t *streamHCPtr, int compressionLevel); |
| 362 | |
| 363 | /** |
| 364 | * LZ4_loadDictHC() - Load a static dictionary into LZ4_streamHC |
| 365 | * @streamHCPtr: pointer to the LZ4HC_stream_t |
| 366 | * @dictionary: dictionary to load |
| 367 | * @dictSize: size of dictionary |
| 368 | * |
| 369 | * Use this function to load a static dictionary into LZ4HC_stream. |
| 370 | * Any previous data will be forgotten, only 'dictionary' |
| 371 | * will remain in memory. |
| 372 | * Loading a size of 0 is allowed. |
| 373 | * |
| 374 | * Return : dictionary size, in bytes (necessarily <= 64 KB) |
| 375 | */ |
| 376 | int LZ4_loadDictHC(LZ4_streamHC_t *streamHCPtr, const char *dictionary, |
| 377 | int dictSize); |
| 378 | |
| 379 | /** |
| 380 | * LZ4_compress_HC_continue() - Compress 'src' using data from previously |
| 381 | * compressed blocks as a dictionary using the HC algorithm |
| 382 | * @streamHCPtr: Pointer to the previous 'LZ4_streamHC_t' structure |
| 383 | * @src: source address of the original data |
| 384 | * @dst: output buffer address of the compressed data, |
| 385 | * which must be already allocated |
| 386 | * @srcSize: size of the input data. Max supported value is LZ4_MAX_INPUT_SIZE |
| 387 | * @maxDstSize: full or partial size of buffer 'dest' |
| 388 | * which must be already allocated |
| 389 | * |
| 390 | * These functions compress data in successive blocks of any size, using |
| 391 | * previous blocks as dictionary. One key assumption is that previous |
| 392 | * blocks (up to 64 KB) remain read-accessible while |
| 393 | * compressing next blocks. There is an exception for ring buffers, |
| 394 | * which can be smaller than 64 KB. |
| 395 | * Ring buffers scenario is automatically detected and handled by |
| 396 | * LZ4_compress_HC_continue(). |
| 397 | * Before starting compression, state must be properly initialized, |
| 398 | * using LZ4_resetStreamHC(). |
| 399 | * A first "fictional block" can then be designated as |
| 400 | * initial dictionary, using LZ4_loadDictHC() (Optional). |
| 401 | * Then, use LZ4_compress_HC_continue() |
| 402 | * to compress each successive block. Previous memory blocks |
| 403 | * (including initial dictionary when present) must remain accessible |
| 404 | * and unmodified during compression. |
| 405 | * 'dst' buffer should be sized to handle worst case scenarios, using |
| 406 | * LZ4_compressBound(), to ensure operation success. |
| 407 | * If, for any reason, previous data blocks can't be preserved unmodified |
| 408 | * in memory during next compression block, |
| 409 | * you must save it to a safer memory space, using LZ4_saveDictHC(). |
| 410 | * Return value of LZ4_saveDictHC() is the size of dictionary |
| 411 | * effectively saved into 'safeBuffer'. |
| 412 | * |
| 413 | * Return: Number of bytes written into buffer 'dst' or 0 if compression fails |
| 414 | */ |
| 415 | int LZ4_compress_HC_continue(LZ4_streamHC_t *streamHCPtr, const char *src, |
| 416 | char *dst, int srcSize, int maxDstSize); |
| 417 | |
| 418 | /** |
| 419 | * LZ4_saveDictHC() - Save static dictionary from LZ4HC_stream |
| 420 | * @streamHCPtr: pointer to the 'LZ4HC_stream_t' structure |
| 421 | * @safeBuffer: buffer to save dictionary to, must be already allocated |
| 422 | * @maxDictSize: size of 'safeBuffer' |
| 423 | * |
| 424 | * If previously compressed data block is not guaranteed |
| 425 | * to remain available at its memory location, |
| 426 | * save it into a safer place (char *safeBuffer). |
| 427 | * Note : you don't need to call LZ4_loadDictHC() afterwards, |
| 428 | * dictionary is immediately usable, you can therefore call |
| 429 | * LZ4_compress_HC_continue(). |
| 430 | * |
| 431 | * Return : saved dictionary size in bytes (necessarily <= maxDictSize), |
| 432 | * or 0 if error. |
| 433 | */ |
| 434 | int LZ4_saveDictHC(LZ4_streamHC_t *streamHCPtr, char *safeBuffer, |
| 435 | int maxDictSize); |
| 436 | |
| 437 | /*-********************************************* |
| 438 | * Streaming Compression Functions |
| 439 | ***********************************************/ |
| 440 | |
| 441 | /** |
| 442 | * LZ4_resetStream() - Init an allocated 'LZ4_stream_t' structure |
| 443 | * @LZ4_stream: pointer to the 'LZ4_stream_t' structure |
| 444 | * |
| 445 | * An LZ4_stream_t structure can be allocated once |
| 446 | * and re-used multiple times. |
| 447 | * Use this function to init an allocated `LZ4_stream_t` structure |
| 448 | * and start a new compression. |
| 449 | */ |
| 450 | void LZ4_resetStream(LZ4_stream_t *LZ4_stream); |
| 451 | |
| 452 | /** |
| 453 | * LZ4_loadDict() - Load a static dictionary into LZ4_stream |
| 454 | * @streamPtr: pointer to the LZ4_stream_t |
| 455 | * @dictionary: dictionary to load |
| 456 | * @dictSize: size of dictionary |
| 457 | * |
| 458 | * Use this function to load a static dictionary into LZ4_stream. |
| 459 | * Any previous data will be forgotten, only 'dictionary' |
| 460 | * will remain in memory. |
| 461 | * Loading a size of 0 is allowed. |
| 462 | * |
| 463 | * Return : dictionary size, in bytes (necessarily <= 64 KB) |
| 464 | */ |
| 465 | int LZ4_loadDict(LZ4_stream_t *streamPtr, const char *dictionary, |
| 466 | int dictSize); |
| 467 | |
| 468 | /** |
| 469 | * LZ4_saveDict() - Save static dictionary from LZ4_stream |
| 470 | * @streamPtr: pointer to the 'LZ4_stream_t' structure |
| 471 | * @safeBuffer: buffer to save dictionary to, must be already allocated |
| 472 | * @dictSize: size of 'safeBuffer' |
| 473 | * |
| 474 | * If previously compressed data block is not guaranteed |
| 475 | * to remain available at its memory location, |
| 476 | * save it into a safer place (char *safeBuffer). |
| 477 | * Note : you don't need to call LZ4_loadDict() afterwards, |
| 478 | * dictionary is immediately usable, you can therefore call |
| 479 | * LZ4_compress_fast_continue(). |
| 480 | * |
| 481 | * Return : saved dictionary size in bytes (necessarily <= dictSize), |
| 482 | * or 0 if error. |
| 483 | */ |
| 484 | int LZ4_saveDict(LZ4_stream_t *streamPtr, char *safeBuffer, int dictSize); |
| 485 | |
| 486 | /** |
| 487 | * LZ4_compress_fast_continue() - Compress 'src' using data from previously |
| 488 | * compressed blocks as a dictionary |
| 489 | * @streamPtr: Pointer to the previous 'LZ4_stream_t' structure |
| 490 | * @src: source address of the original data |
| 491 | * @dst: output buffer address of the compressed data, |
| 492 | * which must be already allocated |
| 493 | * @srcSize: size of the input data. Max supported value is LZ4_MAX_INPUT_SIZE |
| 494 | * @maxDstSize: full or partial size of buffer 'dest' |
| 495 | * which must be already allocated |
| 496 | * @acceleration: acceleration factor |
| 497 | * |
| 498 | * Compress buffer content 'src', using data from previously compressed blocks |
| 499 | * as dictionary to improve compression ratio. |
| 500 | * Important : Previous data blocks are assumed to still |
| 501 | * be present and unmodified ! |
| 502 | * If maxDstSize >= LZ4_compressBound(srcSize), |
| 503 | * compression is guaranteed to succeed, and runs faster. |
| 504 | * |
| 505 | * Return: Number of bytes written into buffer 'dst' or 0 if compression fails |
| 506 | */ |
| 507 | int LZ4_compress_fast_continue(LZ4_stream_t *streamPtr, const char *src, |
| 508 | char *dst, int srcSize, int maxDstSize, int acceleration); |
| 509 | |
| 510 | /** |
| 511 | * LZ4_setStreamDecode() - Instruct where to find dictionary |
| 512 | * @LZ4_streamDecode: the 'LZ4_streamDecode_t' structure |
| 513 | * @dictionary: dictionary to use |
| 514 | * @dictSize: size of dictionary |
| 515 | * |
| 516 | * Use this function to instruct where to find the dictionary. |
| 517 | * Setting a size of 0 is allowed (same effect as reset). |
| 518 | * |
| 519 | * Return: 1 if OK, 0 if error |
| 520 | */ |
| 521 | int LZ4_setStreamDecode(LZ4_streamDecode_t *LZ4_streamDecode, |
| 522 | const char *dictionary, int dictSize); |
| 523 | |
| 524 | /** |
| 525 | * LZ4_decompress_fast_continue() - Decompress blocks in streaming mode |
| 526 | * @LZ4_streamDecode: the 'LZ4_streamDecode_t' structure |
| 527 | * @source: source address of the compressed data |
| 528 | * @dest: output buffer address of the uncompressed data |
| 529 | * which must be already allocated |
| 530 | * @compressedSize: is the precise full size of the compressed block |
| 531 | * @maxDecompressedSize: is the size of 'dest' buffer |
| 532 | * |
| 533 | * These decoding function allows decompression of multiple blocks |
| 534 | * in "streaming" mode. |
| 535 | * Previously decoded blocks *must* remain available at the memory position |
| 536 | * where they were decoded (up to 64 KB) |
| 537 | * In the case of a ring buffers, decoding buffer must be either : |
| 538 | * - Exactly same size as encoding buffer, with same update rule |
| 539 | * (block boundaries at same positions) In which case, |
| 540 | * the decoding & encoding ring buffer can have any size, |
| 541 | * including very small ones ( < 64 KB). |
| 542 | * - Larger than encoding buffer, by a minimum of maxBlockSize more bytes. |
| 543 | * maxBlockSize is implementation dependent. |
| 544 | * It's the maximum size you intend to compress into a single block. |
| 545 | * In which case, encoding and decoding buffers do not need |
| 546 | * to be synchronized, and encoding ring buffer can have any size, |
| 547 | * including small ones ( < 64 KB). |
| 548 | * - _At least_ 64 KB + 8 bytes + maxBlockSize. |
| 549 | * In which case, encoding and decoding buffers do not need to be |
| 550 | * synchronized, and encoding ring buffer can have any size, |
| 551 | * including larger than decoding buffer. W |
| 552 | * Whenever these conditions are not possible, save the last 64KB of decoded |
| 553 | * data into a safe buffer, and indicate where it is saved |
| 554 | * using LZ4_setStreamDecode() |
| 555 | * |
| 556 | * Return: number of bytes decompressed into destination buffer |
| 557 | * (necessarily <= maxDecompressedSize) |
| 558 | * or a negative result in case of error |
| 559 | */ |
| 560 | int LZ4_decompress_safe_continue(LZ4_streamDecode_t *LZ4_streamDecode, |
| 561 | const char *source, char *dest, int compressedSize, |
| 562 | int maxDecompressedSize); |
| 563 | |
| 564 | /** |
| 565 | * LZ4_decompress_fast_continue() - Decompress blocks in streaming mode |
| 566 | * @LZ4_streamDecode: the 'LZ4_streamDecode_t' structure |
| 567 | * @source: source address of the compressed data |
| 568 | * @dest: output buffer address of the uncompressed data |
| 569 | * which must be already allocated with 'originalSize' bytes |
| 570 | * @originalSize: is the original and therefore uncompressed size |
| 571 | * |
| 572 | * These decoding function allows decompression of multiple blocks |
| 573 | * in "streaming" mode. |
| 574 | * Previously decoded blocks *must* remain available at the memory position |
| 575 | * where they were decoded (up to 64 KB) |
| 576 | * In the case of a ring buffers, decoding buffer must be either : |
| 577 | * - Exactly same size as encoding buffer, with same update rule |
| 578 | * (block boundaries at same positions) In which case, |
| 579 | * the decoding & encoding ring buffer can have any size, |
| 580 | * including very small ones ( < 64 KB). |
| 581 | * - Larger than encoding buffer, by a minimum of maxBlockSize more bytes. |
| 582 | * maxBlockSize is implementation dependent. |
| 583 | * It's the maximum size you intend to compress into a single block. |
| 584 | * In which case, encoding and decoding buffers do not need |
| 585 | * to be synchronized, and encoding ring buffer can have any size, |
| 586 | * including small ones ( < 64 KB). |
| 587 | * - _At least_ 64 KB + 8 bytes + maxBlockSize. |
| 588 | * In which case, encoding and decoding buffers do not need to be |
| 589 | * synchronized, and encoding ring buffer can have any size, |
| 590 | * including larger than decoding buffer. W |
| 591 | * Whenever these conditions are not possible, save the last 64KB of decoded |
| 592 | * data into a safe buffer, and indicate where it is saved |
| 593 | * using LZ4_setStreamDecode() |
| 594 | * |
| 595 | * Return: number of bytes decompressed into destination buffer |
| 596 | * (necessarily <= maxDecompressedSize) |
| 597 | * or a negative result in case of error |
| 598 | */ |
| 599 | int LZ4_decompress_fast_continue(LZ4_streamDecode_t *LZ4_streamDecode, |
| 600 | const char *source, char *dest, int originalSize); |
| 601 | |
| 602 | /** |
| 603 | * LZ4_decompress_safe_usingDict() - Same as LZ4_setStreamDecode() |
| 604 | * followed by LZ4_decompress_safe_continue() |
| 605 | * @source: source address of the compressed data |
| 606 | * @dest: output buffer address of the uncompressed data |
| 607 | * which must be already allocated |
| 608 | * @compressedSize: is the precise full size of the compressed block |
| 609 | * @maxDecompressedSize: is the size of 'dest' buffer |
| 610 | * @dictStart: pointer to the start of the dictionary in memory |
| 611 | * @dictSize: size of dictionary |
| 612 | * |
| 613 | * These decoding function works the same as |
| 614 | * a combination of LZ4_setStreamDecode() followed by |
| 615 | * LZ4_decompress_safe_continue() |
| 616 | * It is stand-alone, and don'tn eed a LZ4_streamDecode_t structure. |
| 617 | * |
| 618 | * Return: number of bytes decompressed into destination buffer |
| 619 | * (necessarily <= maxDecompressedSize) |
| 620 | * or a negative result in case of error |
| 621 | */ |
| 622 | int LZ4_decompress_safe_usingDict(const char *source, char *dest, |
| 623 | int compressedSize, int maxDecompressedSize, const char *dictStart, |
| 624 | int dictSize); |
| 625 | |
| 626 | /** |
| 627 | * LZ4_decompress_fast_usingDict() - Same as LZ4_setStreamDecode() |
| 628 | * followed by LZ4_decompress_fast_continue() |
| 629 | * @source: source address of the compressed data |
| 630 | * @dest: output buffer address of the uncompressed data |
| 631 | * which must be already allocated with 'originalSize' bytes |
| 632 | * @originalSize: is the original and therefore uncompressed size |
| 633 | * @dictStart: pointer to the start of the dictionary in memory |
| 634 | * @dictSize: size of dictionary |
| 635 | * |
| 636 | * These decoding function works the same as |
| 637 | * a combination of LZ4_setStreamDecode() followed by |
| 638 | * LZ4_decompress_safe_continue() |
| 639 | * It is stand-alone, and don'tn eed a LZ4_streamDecode_t structure. |
| 640 | * |
| 641 | * Return: number of bytes decompressed into destination buffer |
| 642 | * (necessarily <= maxDecompressedSize) |
| 643 | * or a negative result in case of error |
| 644 | */ |
| 645 | int LZ4_decompress_fast_usingDict(const char *source, char *dest, |
| 646 | int originalSize, const char *dictStart, int dictSize); |
| 647 | |
Kyungsik Lee | cffb78b | 2013-07-08 16:01:45 -0700 | [diff] [blame] | 648 | #endif |