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