1 /*
2  * Copyright (c) 2016-present, Yann Collet, Facebook, Inc.
3  * All rights reserved.
4  *
5  * This source code is licensed under both the BSD-style license (found in the
6  * LICENSE file in the root directory of this source tree) and the GPLv2 (found
7  * in the COPYING file in the root directory of this source tree).
8  */
9 
10 #ifndef ZSTD_LDM_H
11 #define ZSTD_LDM_H
12 
13 #if defined (__cplusplus)
14 extern "C" {
15 #endif
16 
17 #include "zstd_compress_internal.h"   /* ldmParams_t, U32 */
18 #include "zstd.h"   /* ZSTD_CCtx, size_t */
19 
20 /*-*************************************
21 *  Long distance matching
22 ***************************************/
23 
24 #define ZSTD_LDM_DEFAULT_WINDOW_LOG ZSTD_WINDOWLOG_DEFAULTMAX
25 
26 /**
27  * ZSTD_ldm_generateSequences():
28  *
29  * Generates the sequences using the long distance match finder.
30  * Generates long range matching sequences in `sequences`, which parse a prefix
31  * of the source. `sequences` must be large enough to store every sequence,
32  * which can be checked with `ZSTD_ldm_getMaxNbSeq()`.
33  * @returns 0 or an error code.
34  *
35  * NOTE: The user must have called ZSTD_window_update() for all of the input
36  * they have, even if they pass it to ZSTD_ldm_generateSequences() in chunks.
37  * NOTE: This function returns an error if it runs out of space to store
38  *       sequences.
39  */
40 size_t ZSTD_ldm_generateSequences(
41             ldmState_t* ldms, rawSeqStore_t* sequences,
42             ldmParams_t const* params, void const* src, size_t srcSize);
43 
44 /**
45  * ZSTD_ldm_blockCompress():
46  *
47  * Compresses a block using the predefined sequences, along with a secondary
48  * block compressor. The literals section of every sequence is passed to the
49  * secondary block compressor, and those sequences are interspersed with the
50  * predefined sequences. Returns the length of the last literals.
51  * Updates `rawSeqStore.pos` to indicate how many sequences have been consumed.
52  * `rawSeqStore.seq` may also be updated to split the last sequence between two
53  * blocks.
54  * @return The length of the last literals.
55  *
56  * NOTE: The source must be at most the maximum block size, but the predefined
57  * sequences can be any size, and may be longer than the block. In the case that
58  * they are longer than the block, the last sequences may need to be split into
59  * two. We handle that case correctly, and update `rawSeqStore` appropriately.
60  * NOTE: This function does not return any errors.
61  */
62 size_t ZSTD_ldm_blockCompress(rawSeqStore_t* rawSeqStore,
63             ZSTD_matchState_t* ms, seqStore_t* seqStore, U32 rep[ZSTD_REP_NUM],
64             void const* src, size_t srcSize);
65 
66 /**
67  * ZSTD_ldm_skipSequences():
68  *
69  * Skip past `srcSize` bytes worth of sequences in `rawSeqStore`.
70  * Avoids emitting matches less than `minMatch` bytes.
71  * Must be called for data with is not passed to ZSTD_ldm_blockCompress().
72  */
73 void ZSTD_ldm_skipSequences(rawSeqStore_t* rawSeqStore, size_t srcSize,
74     U32 const minMatch);
75 
76 
77 /** ZSTD_ldm_getTableSize() :
78  *  Estimate the space needed for long distance matching tables or 0 if LDM is
79  *  disabled.
80  */
81 size_t ZSTD_ldm_getTableSize(ldmParams_t params);
82 
83 /** ZSTD_ldm_getSeqSpace() :
84  *  Return an upper bound on the number of sequences that can be produced by
85  *  the long distance matcher, or 0 if LDM is disabled.
86  */
87 size_t ZSTD_ldm_getMaxNbSeq(ldmParams_t params, size_t maxChunkSize);
88 
89 /** ZSTD_ldm_getTableSize() :
90  *  Return prime8bytes^(minMatchLength-1) */
91 U64 ZSTD_ldm_getHashPower(U32 minMatchLength);
92 
93 /** ZSTD_ldm_adjustParameters() :
94  *  If the params->hashEveryLog is not set, set it to its default value based on
95  *  windowLog and params->hashLog.
96  *
97  *  Ensures that params->bucketSizeLog is <= params->hashLog (setting it to
98  *  params->hashLog if it is not).
99  *
100  *  Ensures that the minMatchLength >= targetLength during optimal parsing.
101  */
102 void ZSTD_ldm_adjustParameters(ldmParams_t* params,
103                                ZSTD_compressionParameters const* cParams);
104 
105 #if defined (__cplusplus)
106 }
107 #endif
108 
109 #endif /* ZSTD_FAST_H */
110