xref: /freebsd/contrib/xz/src/liblzma/common/common.h (revision 7ef62cebc2f965b0f640263e179276928885e33d)
1 ///////////////////////////////////////////////////////////////////////////////
2 //
3 /// \file       common.h
4 /// \brief      Definitions common to the whole liblzma library
5 //
6 //  Author:     Lasse Collin
7 //
8 //  This file has been put into the public domain.
9 //  You can do whatever you want with this file.
10 //
11 ///////////////////////////////////////////////////////////////////////////////
12 
13 #ifndef LZMA_COMMON_H
14 #define LZMA_COMMON_H
15 
16 #include "sysdefs.h"
17 #include "mythread.h"
18 #include "tuklib_integer.h"
19 
20 #if defined(_WIN32) || defined(__CYGWIN__)
21 #	ifdef DLL_EXPORT
22 #		define LZMA_API_EXPORT __declspec(dllexport)
23 #	else
24 #		define LZMA_API_EXPORT
25 #	endif
26 // Don't use ifdef or defined() below.
27 #elif HAVE_VISIBILITY
28 #	define LZMA_API_EXPORT __attribute__((__visibility__("default")))
29 #else
30 #	define LZMA_API_EXPORT
31 #endif
32 
33 #define LZMA_API(type) LZMA_API_EXPORT type LZMA_API_CALL
34 
35 #include "lzma.h"
36 
37 // This is for detecting modern GCC and Clang attributes
38 // like __symver__ in GCC >= 10.
39 #ifdef __has_attribute
40 #	define lzma_has_attribute(attr) __has_attribute(attr)
41 #else
42 #	define lzma_has_attribute(attr) 0
43 #endif
44 
45 // The extra symbol versioning in the C files may only be used when
46 // building a shared library. If HAVE_SYMBOL_VERSIONS_LINUX is defined
47 // to 2 then symbol versioning is done only if also PIC is defined.
48 // By default Libtool defines PIC when building a shared library and
49 // doesn't define it when building a static library but it can be
50 // overridden with --with-pic and --without-pic. configure let's rely
51 // on PIC if neither --with-pic or --without-pic was used.
52 #if defined(HAVE_SYMBOL_VERSIONS_LINUX) \
53 		&& (HAVE_SYMBOL_VERSIONS_LINUX == 2 && !defined(PIC))
54 #	undef HAVE_SYMBOL_VERSIONS_LINUX
55 #endif
56 
57 #ifdef HAVE_SYMBOL_VERSIONS_LINUX
58 // To keep link-time optimization (LTO, -flto) working with GCC,
59 // the __symver__ attribute must be used instead of __asm__(".symver ...").
60 // Otherwise the symbol versions may be lost, resulting in broken liblzma
61 // that has wrong default versions in the exported symbol list!
62 // The attribute was added in GCC 10; LTO with older GCC is not supported.
63 //
64 // To keep -Wmissing-prototypes happy, use LZMA_SYMVER_API only with function
65 // declarations (including those with __alias__ attribute) and LZMA_API with
66 // the function definitions. This means a little bit of silly copy-and-paste
67 // between declarations and definitions though.
68 //
69 // As of GCC 12.2, the __symver__ attribute supports only @ and @@ but the
70 // very convenient @@@ isn't supported (it's supported by GNU assembler
71 // since 2000). When using @@ instead of @@@, the internal name must not be
72 // the same as the external name to avoid problems in some situations. This
73 // is why "#define foo_52 foo" is needed for the default symbol versions.
74 //
75 // __has_attribute is supported before GCC 10 and it is supported in Clang 14
76 // too (which doesn't support __symver__) so use it to detect if __symver__
77 // is available. This should be far more reliable than looking at compiler
78 // version macros as nowadays especially __GNUC__ is defined by many compilers.
79 #	if lzma_has_attribute(__symver__)
80 #		define LZMA_SYMVER_API(extnamever, type, intname) \
81 			extern __attribute__((__symver__(extnamever))) \
82 					LZMA_API(type) intname
83 #	else
84 #		define LZMA_SYMVER_API(extnamever, type, intname) \
85 			__asm__(".symver " #intname "," extnamever); \
86 			extern LZMA_API(type) intname
87 #	endif
88 #endif
89 
90 // These allow helping the compiler in some often-executed branches, whose
91 // result is almost always the same.
92 #ifdef __GNUC__
93 #	define likely(expr) __builtin_expect(expr, true)
94 #	define unlikely(expr) __builtin_expect(expr, false)
95 #else
96 #	define likely(expr) (expr)
97 #	define unlikely(expr) (expr)
98 #endif
99 
100 
101 /// Size of temporary buffers needed in some filters
102 #define LZMA_BUFFER_SIZE 4096
103 
104 
105 /// Maximum number of worker threads within one multithreaded component.
106 /// The limit exists solely to make it simpler to prevent integer overflows
107 /// when allocating structures etc. This should be big enough for now...
108 /// the code won't scale anywhere close to this number anyway.
109 #define LZMA_THREADS_MAX 16384
110 
111 
112 /// Starting value for memory usage estimates. Instead of calculating size
113 /// of _every_ structure and taking into account malloc() overhead etc., we
114 /// add a base size to all memory usage estimates. It's not very accurate
115 /// but should be easily good enough.
116 #define LZMA_MEMUSAGE_BASE (UINT64_C(1) << 15)
117 
118 /// Start of internal Filter ID space. These IDs must never be used
119 /// in Streams.
120 #define LZMA_FILTER_RESERVED_START (LZMA_VLI_C(1) << 62)
121 
122 
123 /// Supported flags that can be passed to lzma_stream_decoder(),
124 /// lzma_auto_decoder(), or lzma_stream_decoder_mt().
125 #define LZMA_SUPPORTED_FLAGS \
126 	( LZMA_TELL_NO_CHECK \
127 	| LZMA_TELL_UNSUPPORTED_CHECK \
128 	| LZMA_TELL_ANY_CHECK \
129 	| LZMA_IGNORE_CHECK \
130 	| LZMA_CONCATENATED \
131 	| LZMA_FAIL_FAST )
132 
133 
134 /// Largest valid lzma_action value as unsigned integer.
135 #define LZMA_ACTION_MAX ((unsigned int)(LZMA_FULL_BARRIER))
136 
137 
138 /// Special return value (lzma_ret) to indicate that a timeout was reached
139 /// and lzma_code() must not return LZMA_BUF_ERROR. This is converted to
140 /// LZMA_OK in lzma_code().
141 #define LZMA_TIMED_OUT LZMA_RET_INTERNAL1
142 
143 /// Special return value (lzma_ret) for use in stream_decoder_mt.c to
144 /// indicate Index was detected instead of a Block Header.
145 #define LZMA_INDEX_DETECTED LZMA_RET_INTERNAL2
146 
147 
148 typedef struct lzma_next_coder_s lzma_next_coder;
149 
150 typedef struct lzma_filter_info_s lzma_filter_info;
151 
152 
153 /// Type of a function used to initialize a filter encoder or decoder
154 typedef lzma_ret (*lzma_init_function)(
155 		lzma_next_coder *next, const lzma_allocator *allocator,
156 		const lzma_filter_info *filters);
157 
158 /// Type of a function to do some kind of coding work (filters, Stream,
159 /// Block encoders/decoders etc.). Some special coders use don't use both
160 /// input and output buffers, but for simplicity they still use this same
161 /// function prototype.
162 typedef lzma_ret (*lzma_code_function)(
163 		void *coder, const lzma_allocator *allocator,
164 		const uint8_t *restrict in, size_t *restrict in_pos,
165 		size_t in_size, uint8_t *restrict out,
166 		size_t *restrict out_pos, size_t out_size,
167 		lzma_action action);
168 
169 /// Type of a function to free the memory allocated for the coder
170 typedef void (*lzma_end_function)(
171 		void *coder, const lzma_allocator *allocator);
172 
173 
174 /// Raw coder validates and converts an array of lzma_filter structures to
175 /// an array of lzma_filter_info structures. This array is used with
176 /// lzma_next_filter_init to initialize the filter chain.
177 struct lzma_filter_info_s {
178 	/// Filter ID. This can be used to share the same initiazation
179 	/// function *and* data structures with different Filter IDs
180 	/// (LZMA_FILTER_LZMA1EXT does it), and also by the encoder
181 	/// with lzma_filters_update() if filter chain is updated
182 	/// in the middle of a raw stream or Block (LZMA_SYNC_FLUSH).
183 	lzma_vli id;
184 
185 	/// Pointer to function used to initialize the filter.
186 	/// This is NULL to indicate end of array.
187 	lzma_init_function init;
188 
189 	/// Pointer to filter's options structure
190 	void *options;
191 };
192 
193 
194 /// Hold data and function pointers of the next filter in the chain.
195 struct lzma_next_coder_s {
196 	/// Pointer to coder-specific data
197 	void *coder;
198 
199 	/// Filter ID. This is LZMA_VLI_UNKNOWN when this structure doesn't
200 	/// point to a filter coder.
201 	lzma_vli id;
202 
203 	/// "Pointer" to init function. This is never called here.
204 	/// We need only to detect if we are initializing a coder
205 	/// that was allocated earlier. See lzma_next_coder_init and
206 	/// lzma_next_strm_init macros in this file.
207 	uintptr_t init;
208 
209 	/// Pointer to function to do the actual coding
210 	lzma_code_function code;
211 
212 	/// Pointer to function to free lzma_next_coder.coder. This can
213 	/// be NULL; in that case, lzma_free is called to free
214 	/// lzma_next_coder.coder.
215 	lzma_end_function end;
216 
217 	/// Pointer to a function to get progress information. If this is NULL,
218 	/// lzma_stream.total_in and .total_out are used instead.
219 	void (*get_progress)(void *coder,
220 			uint64_t *progress_in, uint64_t *progress_out);
221 
222 	/// Pointer to function to return the type of the integrity check.
223 	/// Most coders won't support this.
224 	lzma_check (*get_check)(const void *coder);
225 
226 	/// Pointer to function to get and/or change the memory usage limit.
227 	/// If new_memlimit == 0, the limit is not changed.
228 	lzma_ret (*memconfig)(void *coder, uint64_t *memusage,
229 			uint64_t *old_memlimit, uint64_t new_memlimit);
230 
231 	/// Update the filter-specific options or the whole filter chain
232 	/// in the encoder.
233 	lzma_ret (*update)(void *coder, const lzma_allocator *allocator,
234 			const lzma_filter *filters,
235 			const lzma_filter *reversed_filters);
236 
237 	/// Set how many bytes of output this coder may produce at maximum.
238 	/// On success LZMA_OK must be returned.
239 	/// If the filter chain as a whole cannot support this feature,
240 	/// this must return LZMA_OPTIONS_ERROR.
241 	/// If no input has been given to the coder and the requested limit
242 	/// is too small, this must return LZMA_BUF_ERROR. If input has been
243 	/// seen, LZMA_OK is allowed too.
244 	lzma_ret (*set_out_limit)(void *coder, uint64_t *uncomp_size,
245 			uint64_t out_limit);
246 };
247 
248 
249 /// Macro to initialize lzma_next_coder structure
250 #define LZMA_NEXT_CODER_INIT \
251 	(lzma_next_coder){ \
252 		.coder = NULL, \
253 		.init = (uintptr_t)(NULL), \
254 		.id = LZMA_VLI_UNKNOWN, \
255 		.code = NULL, \
256 		.end = NULL, \
257 		.get_progress = NULL, \
258 		.get_check = NULL, \
259 		.memconfig = NULL, \
260 		.update = NULL, \
261 		.set_out_limit = NULL, \
262 	}
263 
264 
265 /// Internal data for lzma_strm_init, lzma_code, and lzma_end. A pointer to
266 /// this is stored in lzma_stream.
267 struct lzma_internal_s {
268 	/// The actual coder that should do something useful
269 	lzma_next_coder next;
270 
271 	/// Track the state of the coder. This is used to validate arguments
272 	/// so that the actual coders can rely on e.g. that LZMA_SYNC_FLUSH
273 	/// is used on every call to lzma_code until next.code has returned
274 	/// LZMA_STREAM_END.
275 	enum {
276 		ISEQ_RUN,
277 		ISEQ_SYNC_FLUSH,
278 		ISEQ_FULL_FLUSH,
279 		ISEQ_FINISH,
280 		ISEQ_FULL_BARRIER,
281 		ISEQ_END,
282 		ISEQ_ERROR,
283 	} sequence;
284 
285 	/// A copy of lzma_stream avail_in. This is used to verify that the
286 	/// amount of input doesn't change once e.g. LZMA_FINISH has been
287 	/// used.
288 	size_t avail_in;
289 
290 	/// Indicates which lzma_action values are allowed by next.code.
291 	bool supported_actions[LZMA_ACTION_MAX + 1];
292 
293 	/// If true, lzma_code will return LZMA_BUF_ERROR if no progress was
294 	/// made (no input consumed and no output produced by next.code).
295 	bool allow_buf_error;
296 };
297 
298 
299 /// Allocates memory
300 extern void *lzma_alloc(size_t size, const lzma_allocator *allocator)
301 		lzma_attribute((__malloc__)) lzma_attr_alloc_size(1);
302 
303 /// Allocates memory and zeroes it (like calloc()). This can be faster
304 /// than lzma_alloc() + memzero() while being backward compatible with
305 /// custom allocators.
306 extern void * lzma_attribute((__malloc__)) lzma_attr_alloc_size(1)
307 		lzma_alloc_zero(size_t size, const lzma_allocator *allocator);
308 
309 /// Frees memory
310 extern void lzma_free(void *ptr, const lzma_allocator *allocator);
311 
312 
313 /// Allocates strm->internal if it is NULL, and initializes *strm and
314 /// strm->internal. This function is only called via lzma_next_strm_init macro.
315 extern lzma_ret lzma_strm_init(lzma_stream *strm);
316 
317 /// Initializes the next filter in the chain, if any. This takes care of
318 /// freeing the memory of previously initialized filter if it is different
319 /// than the filter being initialized now. This way the actual filter
320 /// initialization functions don't need to use lzma_next_coder_init macro.
321 extern lzma_ret lzma_next_filter_init(lzma_next_coder *next,
322 		const lzma_allocator *allocator,
323 		const lzma_filter_info *filters);
324 
325 /// Update the next filter in the chain, if any. This checks that
326 /// the application is not trying to change the Filter IDs.
327 extern lzma_ret lzma_next_filter_update(
328 		lzma_next_coder *next, const lzma_allocator *allocator,
329 		const lzma_filter *reversed_filters);
330 
331 /// Frees the memory allocated for next->coder either using next->end or,
332 /// if next->end is NULL, using lzma_free.
333 extern void lzma_next_end(lzma_next_coder *next,
334 		const lzma_allocator *allocator);
335 
336 
337 /// Copy as much data as possible from in[] to out[] and update *in_pos
338 /// and *out_pos accordingly. Returns the number of bytes copied.
339 extern size_t lzma_bufcpy(const uint8_t *restrict in, size_t *restrict in_pos,
340 		size_t in_size, uint8_t *restrict out,
341 		size_t *restrict out_pos, size_t out_size);
342 
343 
344 /// \brief      Return if expression doesn't evaluate to LZMA_OK
345 ///
346 /// There are several situations where we want to return immediately
347 /// with the value of expr if it isn't LZMA_OK. This macro shortens
348 /// the code a little.
349 #define return_if_error(expr) \
350 do { \
351 	const lzma_ret ret_ = (expr); \
352 	if (ret_ != LZMA_OK) \
353 		return ret_; \
354 } while (0)
355 
356 
357 /// If next isn't already initialized, free the previous coder. Then mark
358 /// that next is _possibly_ initialized for the coder using this macro.
359 /// "Possibly" means that if e.g. allocation of next->coder fails, the
360 /// structure isn't actually initialized for this coder, but leaving
361 /// next->init to func is still OK.
362 #define lzma_next_coder_init(func, next, allocator) \
363 do { \
364 	if ((uintptr_t)(func) != (next)->init) \
365 		lzma_next_end(next, allocator); \
366 	(next)->init = (uintptr_t)(func); \
367 } while (0)
368 
369 
370 /// Initializes lzma_strm and calls func() to initialize strm->internal->next.
371 /// (The function being called will use lzma_next_coder_init()). If
372 /// initialization fails, memory that wasn't freed by func() is freed
373 /// along strm->internal.
374 #define lzma_next_strm_init(func, strm, ...) \
375 do { \
376 	return_if_error(lzma_strm_init(strm)); \
377 	const lzma_ret ret_ = func(&(strm)->internal->next, \
378 			(strm)->allocator, __VA_ARGS__); \
379 	if (ret_ != LZMA_OK) { \
380 		lzma_end(strm); \
381 		return ret_; \
382 	} \
383 } while (0)
384 
385 #endif
386