1/* SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause */
2/*
3 * Copyright (c) Yann Collet, Facebook, Inc.
4 * All rights reserved.
5 *
6 * This source code is licensed under both the BSD-style license (found in the
7 * LICENSE file in the root directory of https://github.com/facebook/zstd) and
8 * the GPLv2 (found in the COPYING file in the root directory of
9 * https://github.com/facebook/zstd). You may select, at your option, one of the
10 * above-listed licenses.
11 */
12
13#ifndef LINUX_ZSTD_H
14#define LINUX_ZSTD_H
15
16/**
17 * This is a kernel-style API that wraps the upstream zstd API, which cannot be
18 * used directly because the symbols aren't exported. It exposes the minimal
19 * functionality which is currently required by users of zstd in the kernel.
20 * Expose extra functions from lib/zstd/zstd.h as needed.
21 */
22
23/* ====== Dependency ====== */
24#include <linux/types.h>
25#include <linux/zstd_errors.h>
26#include <linux/zstd_lib.h>
27
28/* ====== Helper Functions ====== */
29/**
30 * zstd_compress_bound() - maximum compressed size in worst case scenario
31 * @src_size: The size of the data to compress.
32 *
33 * Return: The maximum compressed size in the worst case scenario.
34 */
35size_t zstd_compress_bound(size_t src_size);
36
37/**
38 * zstd_is_error() - tells if a size_t function result is an error code
39 * @code: The function result to check for error.
40 *
41 * Return: Non-zero iff the code is an error.
42 */
43unsigned int zstd_is_error(size_t code);
44
45/**
46 * enum zstd_error_code - zstd error codes
47 */
48typedef ZSTD_ErrorCode zstd_error_code;
49
50/**
51 * zstd_get_error_code() - translates an error function result to an error code
52 * @code: The function result for which zstd_is_error(code) is true.
53 *
54 * Return: A unique error code for this error.
55 */
56zstd_error_code zstd_get_error_code(size_t code);
57
58/**
59 * zstd_get_error_name() - translates an error function result to a string
60 * @code: The function result for which zstd_is_error(code) is true.
61 *
62 * Return: An error string corresponding to the error code.
63 */
64const char *zstd_get_error_name(size_t code);
65
66/**
67 * zstd_min_clevel() - minimum allowed compression level
68 *
69 * Return: The minimum allowed compression level.
70 */
71int zstd_min_clevel(void);
72
73/**
74 * zstd_max_clevel() - maximum allowed compression level
75 *
76 * Return: The maximum allowed compression level.
77 */
78int zstd_max_clevel(void);
79
80/* ====== Parameter Selection ====== */
81
82/**
83 * enum zstd_strategy - zstd compression search strategy
84 *
85 * From faster to stronger. See zstd_lib.h.
86 */
87typedef ZSTD_strategy zstd_strategy;
88
89/**
90 * struct zstd_compression_parameters - zstd compression parameters
91 * @windowLog: Log of the largest match distance. Larger means more
92 * compression, and more memory needed during decompression.
93 * @chainLog: Fully searched segment. Larger means more compression,
94 * slower, and more memory (useless for fast).
95 * @hashLog: Dispatch table. Larger means more compression,
96 * slower, and more memory.
97 * @searchLog: Number of searches. Larger means more compression and slower.
98 * @searchLength: Match length searched. Larger means faster decompression,
99 * sometimes less compression.
100 * @targetLength: Acceptable match size for optimal parser (only). Larger means
101 * more compression, and slower.
102 * @strategy: The zstd compression strategy.
103 *
104 * See zstd_lib.h.
105 */
106typedef ZSTD_compressionParameters zstd_compression_parameters;
107
108/**
109 * struct zstd_frame_parameters - zstd frame parameters
110 * @contentSizeFlag: Controls whether content size will be present in the
111 * frame header (when known).
112 * @checksumFlag: Controls whether a 32-bit checksum is generated at the
113 * end of the frame for error detection.
114 * @noDictIDFlag: Controls whether dictID will be saved into the frame
115 * header when using dictionary compression.
116 *
117 * The default value is all fields set to 0. See zstd_lib.h.
118 */
119typedef ZSTD_frameParameters zstd_frame_parameters;
120
121/**
122 * struct zstd_parameters - zstd parameters
123 * @cParams: The compression parameters.
124 * @fParams: The frame parameters.
125 */
126typedef ZSTD_parameters zstd_parameters;
127
128/**
129 * zstd_get_params() - returns zstd_parameters for selected level
130 * @level: The compression level
131 * @estimated_src_size: The estimated source size to compress or 0
132 * if unknown.
133 *
134 * Return: The selected zstd_parameters.
135 */
136zstd_parameters zstd_get_params(int level,
137 unsigned long long estimated_src_size);
138
139/* ====== Single-pass Compression ====== */
140
141typedef ZSTD_CCtx zstd_cctx;
142
143/**
144 * zstd_cctx_workspace_bound() - max memory needed to initialize a zstd_cctx
145 * @parameters: The compression parameters to be used.
146 *
147 * If multiple compression parameters might be used, the caller must call
148 * zstd_cctx_workspace_bound() for each set of parameters and use the maximum
149 * size.
150 *
151 * Return: A lower bound on the size of the workspace that is passed to
152 * zstd_init_cctx().
153 */
154size_t zstd_cctx_workspace_bound(const zstd_compression_parameters *parameters);
155
156/**
157 * zstd_init_cctx() - initialize a zstd compression context
158 * @workspace: The workspace to emplace the context into. It must outlive
159 * the returned context.
160 * @workspace_size: The size of workspace. Use zstd_cctx_workspace_bound() to
161 * determine how large the workspace must be.
162 *
163 * Return: A zstd compression context or NULL on error.
164 */
165zstd_cctx *zstd_init_cctx(void *workspace, size_t workspace_size);
166
167/**
168 * zstd_compress_cctx() - compress src into dst with the initialized parameters
169 * @cctx: The context. Must have been initialized with zstd_init_cctx().
170 * @dst: The buffer to compress src into.
171 * @dst_capacity: The size of the destination buffer. May be any size, but
172 * ZSTD_compressBound(srcSize) is guaranteed to be large enough.
173 * @src: The data to compress.
174 * @src_size: The size of the data to compress.
175 * @parameters: The compression parameters to be used.
176 *
177 * Return: The compressed size or an error, which can be checked using
178 * zstd_is_error().
179 */
180size_t zstd_compress_cctx(zstd_cctx *cctx, void *dst, size_t dst_capacity,
181 const void *src, size_t src_size, const zstd_parameters *parameters);
182
183/* ====== Single-pass Decompression ====== */
184
185typedef ZSTD_DCtx zstd_dctx;
186
187/**
188 * zstd_dctx_workspace_bound() - max memory needed to initialize a zstd_dctx
189 *
190 * Return: A lower bound on the size of the workspace that is passed to
191 * zstd_init_dctx().
192 */
193size_t zstd_dctx_workspace_bound(void);
194
195/**
196 * zstd_init_dctx() - initialize a zstd decompression context
197 * @workspace: The workspace to emplace the context into. It must outlive
198 * the returned context.
199 * @workspace_size: The size of workspace. Use zstd_dctx_workspace_bound() to
200 * determine how large the workspace must be.
201 *
202 * Return: A zstd decompression context or NULL on error.
203 */
204zstd_dctx *zstd_init_dctx(void *workspace, size_t workspace_size);
205
206/**
207 * zstd_decompress_dctx() - decompress zstd compressed src into dst
208 * @dctx: The decompression context.
209 * @dst: The buffer to decompress src into.
210 * @dst_capacity: The size of the destination buffer. Must be at least as large
211 * as the decompressed size. If the caller cannot upper bound the
212 * decompressed size, then it's better to use the streaming API.
213 * @src: The zstd compressed data to decompress. Multiple concatenated
214 * frames and skippable frames are allowed.
215 * @src_size: The exact size of the data to decompress.
216 *
217 * Return: The decompressed size or an error, which can be checked using
218 * zstd_is_error().
219 */
220size_t zstd_decompress_dctx(zstd_dctx *dctx, void *dst, size_t dst_capacity,
221 const void *src, size_t src_size);
222
223/* ====== Streaming Buffers ====== */
224
225/**
226 * struct zstd_in_buffer - input buffer for streaming
227 * @src: Start of the input buffer.
228 * @size: Size of the input buffer.
229 * @pos: Position where reading stopped. Will be updated.
230 * Necessarily 0 <= pos <= size.
231 *
232 * See zstd_lib.h.
233 */
234typedef ZSTD_inBuffer zstd_in_buffer;
235
236/**
237 * struct zstd_out_buffer - output buffer for streaming
238 * @dst: Start of the output buffer.
239 * @size: Size of the output buffer.
240 * @pos: Position where writing stopped. Will be updated.
241 * Necessarily 0 <= pos <= size.
242 *
243 * See zstd_lib.h.
244 */
245typedef ZSTD_outBuffer zstd_out_buffer;
246
247/* ====== Streaming Compression ====== */
248
249typedef ZSTD_CStream zstd_cstream;
250
251/**
252 * zstd_cstream_workspace_bound() - memory needed to initialize a zstd_cstream
253 * @cparams: The compression parameters to be used for compression.
254 *
255 * Return: A lower bound on the size of the workspace that is passed to
256 * zstd_init_cstream().
257 */
258size_t zstd_cstream_workspace_bound(const zstd_compression_parameters *cparams);
259
260/**
261 * zstd_init_cstream() - initialize a zstd streaming compression context
262 * @parameters The zstd parameters to use for compression.
263 * @pledged_src_size: If params.fParams.contentSizeFlag == 1 then the caller
264 * must pass the source size (zero means empty source).
265 * Otherwise, the caller may optionally pass the source
266 * size, or zero if unknown.
267 * @workspace: The workspace to emplace the context into. It must outlive
268 * the returned context.
269 * @workspace_size: The size of workspace.
270 * Use zstd_cstream_workspace_bound(params->cparams) to
271 * determine how large the workspace must be.
272 *
273 * Return: The zstd streaming compression context or NULL on error.
274 */
275zstd_cstream *zstd_init_cstream(const zstd_parameters *parameters,
276 unsigned long long pledged_src_size, void *workspace, size_t workspace_size);
277
278/**
279 * zstd_reset_cstream() - reset the context using parameters from creation
280 * @cstream: The zstd streaming compression context to reset.
281 * @pledged_src_size: Optionally the source size, or zero if unknown.
282 *
283 * Resets the context using the parameters from creation. Skips dictionary
284 * loading, since it can be reused. If `pledged_src_size` is non-zero the frame
285 * content size is always written into the frame header.
286 *
287 * Return: Zero or an error, which can be checked using
288 * zstd_is_error().
289 */
290size_t zstd_reset_cstream(zstd_cstream *cstream,
291 unsigned long long pledged_src_size);
292
293/**
294 * zstd_compress_stream() - streaming compress some of input into output
295 * @cstream: The zstd streaming compression context.
296 * @output: Destination buffer. `output->pos` is updated to indicate how much
297 * compressed data was written.
298 * @input: Source buffer. `input->pos` is updated to indicate how much data
299 * was read. Note that it may not consume the entire input, in which
300 * case `input->pos < input->size`, and it's up to the caller to
301 * present remaining data again.
302 *
303 * The `input` and `output` buffers may be any size. Guaranteed to make some
304 * forward progress if `input` and `output` are not empty.
305 *
306 * Return: A hint for the number of bytes to use as the input for the next
307 * function call or an error, which can be checked using
308 * zstd_is_error().
309 */
310size_t zstd_compress_stream(zstd_cstream *cstream, zstd_out_buffer *output,
311 zstd_in_buffer *input);
312
313/**
314 * zstd_flush_stream() - flush internal buffers into output
315 * @cstream: The zstd streaming compression context.
316 * @output: Destination buffer. `output->pos` is updated to indicate how much
317 * compressed data was written.
318 *
319 * zstd_flush_stream() must be called until it returns 0, meaning all the data
320 * has been flushed. Since zstd_flush_stream() causes a block to be ended,
321 * calling it too often will degrade the compression ratio.
322 *
323 * Return: The number of bytes still present within internal buffers or an
324 * error, which can be checked using zstd_is_error().
325 */
326size_t zstd_flush_stream(zstd_cstream *cstream, zstd_out_buffer *output);
327
328/**
329 * zstd_end_stream() - flush internal buffers into output and end the frame
330 * @cstream: The zstd streaming compression context.
331 * @output: Destination buffer. `output->pos` is updated to indicate how much
332 * compressed data was written.
333 *
334 * zstd_end_stream() must be called until it returns 0, meaning all the data has
335 * been flushed and the frame epilogue has been written.
336 *
337 * Return: The number of bytes still present within internal buffers or an
338 * error, which can be checked using zstd_is_error().
339 */
340size_t zstd_end_stream(zstd_cstream *cstream, zstd_out_buffer *output);
341
342/* ====== Streaming Decompression ====== */
343
344typedef ZSTD_DStream zstd_dstream;
345
346/**
347 * zstd_dstream_workspace_bound() - memory needed to initialize a zstd_dstream
348 * @max_window_size: The maximum window size allowed for compressed frames.
349 *
350 * Return: A lower bound on the size of the workspace that is passed
351 * to zstd_init_dstream().
352 */
353size_t zstd_dstream_workspace_bound(size_t max_window_size);
354
355/**
356 * zstd_init_dstream() - initialize a zstd streaming decompression context
357 * @max_window_size: The maximum window size allowed for compressed frames.
358 * @workspace: The workspace to emplace the context into. It must outlive
359 * the returned context.
360 * @workspaceSize: The size of workspace.
361 * Use zstd_dstream_workspace_bound(max_window_size) to
362 * determine how large the workspace must be.
363 *
364 * Return: The zstd streaming decompression context.
365 */
366zstd_dstream *zstd_init_dstream(size_t max_window_size, void *workspace,
367 size_t workspace_size);
368
369/**
370 * zstd_reset_dstream() - reset the context using parameters from creation
371 * @dstream: The zstd streaming decompression context to reset.
372 *
373 * Resets the context using the parameters from creation. Skips dictionary
374 * loading, since it can be reused.
375 *
376 * Return: Zero or an error, which can be checked using zstd_is_error().
377 */
378size_t zstd_reset_dstream(zstd_dstream *dstream);
379
380/**
381 * zstd_decompress_stream() - streaming decompress some of input into output
382 * @dstream: The zstd streaming decompression context.
383 * @output: Destination buffer. `output.pos` is updated to indicate how much
384 * decompressed data was written.
385 * @input: Source buffer. `input.pos` is updated to indicate how much data was
386 * read. Note that it may not consume the entire input, in which case
387 * `input.pos < input.size`, and it's up to the caller to present
388 * remaining data again.
389 *
390 * The `input` and `output` buffers may be any size. Guaranteed to make some
391 * forward progress if `input` and `output` are not empty.
392 * zstd_decompress_stream() will not consume the last byte of the frame until
393 * the entire frame is flushed.
394 *
395 * Return: Returns 0 iff a frame is completely decoded and fully flushed.
396 * Otherwise returns a hint for the number of bytes to use as the
397 * input for the next function call or an error, which can be checked
398 * using zstd_is_error(). The size hint will never load more than the
399 * frame.
400 */
401size_t zstd_decompress_stream(zstd_dstream *dstream, zstd_out_buffer *output,
402 zstd_in_buffer *input);
403
404/* ====== Frame Inspection Functions ====== */
405
406/**
407 * zstd_find_frame_compressed_size() - returns the size of a compressed frame
408 * @src: Source buffer. It should point to the start of a zstd encoded
409 * frame or a skippable frame.
410 * @src_size: The size of the source buffer. It must be at least as large as the
411 * size of the frame.
412 *
413 * Return: The compressed size of the frame pointed to by `src` or an error,
414 * which can be check with zstd_is_error().
415 * Suitable to pass to ZSTD_decompress() or similar functions.
416 */
417size_t zstd_find_frame_compressed_size(const void *src, size_t src_size);
418
419/**
420 * struct zstd_frame_params - zstd frame parameters stored in the frame header
421 * @frameContentSize: The frame content size, or ZSTD_CONTENTSIZE_UNKNOWN if not
422 * present.
423 * @windowSize: The window size, or 0 if the frame is a skippable frame.
424 * @blockSizeMax: The maximum block size.
425 * @frameType: The frame type (zstd or skippable)
426 * @headerSize: The size of the frame header.
427 * @dictID: The dictionary id, or 0 if not present.
428 * @checksumFlag: Whether a checksum was used.
429 *
430 * See zstd_lib.h.
431 */
432typedef ZSTD_frameHeader zstd_frame_header;
433
434/**
435 * zstd_get_frame_header() - extracts parameters from a zstd or skippable frame
436 * @params: On success the frame parameters are written here.
437 * @src: The source buffer. It must point to a zstd or skippable frame.
438 * @src_size: The size of the source buffer.
439 *
440 * Return: 0 on success. If more data is required it returns how many bytes
441 * must be provided to make forward progress. Otherwise it returns
442 * an error, which can be checked using zstd_is_error().
443 */
444size_t zstd_get_frame_header(zstd_frame_header *params, const void *src,
445 size_t src_size);
446
447#endif /* LINUX_ZSTD_H */
448

source code of linux/include/linux/zstd.h