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_TRACE_H
12#define ZSTD_TRACE_H
13
14#if defined (__cplusplus)
15extern "C" {
16#endif
17
18#include <stddef.h>
19
20/* weak symbol support
21 * For now, enable conservatively:
22 * - Only GNUC
23 * - Only ELF
24 * - Only x86-64, i386 and aarch64
25 * Also, explicitly disable on platforms known not to work so they aren't
26 * forgotten in the future.
27 */
28#if !defined(ZSTD_HAVE_WEAK_SYMBOLS) && \
29 defined(__GNUC__) && defined(__ELF__) && \
30 (defined(__x86_64__) || defined(_M_X64) || defined(__i386__) || defined(_M_IX86) || defined(__aarch64__)) && \
31 !defined(__APPLE__) && !defined(_WIN32) && !defined(__MINGW32__) && \
32 !defined(__CYGWIN__) && !defined(_AIX)
33# define ZSTD_HAVE_WEAK_SYMBOLS 1
34#else
35# define ZSTD_HAVE_WEAK_SYMBOLS 0
36#endif
37#if ZSTD_HAVE_WEAK_SYMBOLS
38# define ZSTD_WEAK_ATTR __attribute__((__weak__))
39#else
40# define ZSTD_WEAK_ATTR
41#endif
42
43/* Only enable tracing when weak symbols are available. */
44#ifndef ZSTD_TRACE
45# define ZSTD_TRACE ZSTD_HAVE_WEAK_SYMBOLS
46#endif
47
48#if ZSTD_TRACE
49
50struct ZSTD_CCtx_s;
51struct ZSTD_DCtx_s;
52struct ZSTD_CCtx_params_s;
53
54typedef struct {
55 /**
56 * ZSTD_VERSION_NUMBER
57 *
58 * This is guaranteed to be the first member of ZSTD_trace.
59 * Otherwise, this struct is not stable between versions. If
60 * the version number does not match your expectation, you
61 * should not interpret the rest of the struct.
62 */
63 unsigned version;
64 /**
65 * Non-zero if streaming (de)compression is used.
66 */
67 unsigned streaming;
68 /**
69 * The dictionary ID.
70 */
71 unsigned dictionaryID;
72 /**
73 * Is the dictionary cold?
74 * Only set on decompression.
75 */
76 unsigned dictionaryIsCold;
77 /**
78 * The dictionary size or zero if no dictionary.
79 */
80 size_t dictionarySize;
81 /**
82 * The uncompressed size of the data.
83 */
84 size_t uncompressedSize;
85 /**
86 * The compressed size of the data.
87 */
88 size_t compressedSize;
89 /**
90 * The fully resolved CCtx parameters (NULL on decompression).
91 */
92 struct ZSTD_CCtx_params_s const* params;
93 /**
94 * The ZSTD_CCtx pointer (NULL on decompression).
95 */
96 struct ZSTD_CCtx_s const* cctx;
97 /**
98 * The ZSTD_DCtx pointer (NULL on compression).
99 */
100 struct ZSTD_DCtx_s const* dctx;
101} ZSTD_Trace;
102
103/**
104 * A tracing context. It must be 0 when tracing is disabled.
105 * Otherwise, any non-zero value returned by a tracing begin()
106 * function is presented to any subsequent calls to end().
107 *
108 * Any non-zero value is treated as tracing is enabled and not
109 * interpreted by the library.
110 *
111 * Two possible uses are:
112 * * A timestamp for when the begin() function was called.
113 * * A unique key identifying the (de)compression, like the
114 * address of the [dc]ctx pointer if you need to track
115 * more information than just a timestamp.
116 */
117typedef unsigned long long ZSTD_TraceCtx;
118
119/**
120 * Trace the beginning of a compression call.
121 * @param cctx The dctx pointer for the compression.
122 * It can be used as a key to map begin() to end().
123 * @returns Non-zero if tracing is enabled. The return value is
124 * passed to ZSTD_trace_compress_end().
125 */
126ZSTD_WEAK_ATTR ZSTD_TraceCtx ZSTD_trace_compress_begin(
127 struct ZSTD_CCtx_s const* cctx);
128
129/**
130 * Trace the end of a compression call.
131 * @param ctx The return value of ZSTD_trace_compress_begin().
132 * @param trace The zstd tracing info.
133 */
134ZSTD_WEAK_ATTR void ZSTD_trace_compress_end(
135 ZSTD_TraceCtx ctx,
136 ZSTD_Trace const* trace);
137
138/**
139 * Trace the beginning of a decompression call.
140 * @param dctx The dctx pointer for the decompression.
141 * It can be used as a key to map begin() to end().
142 * @returns Non-zero if tracing is enabled. The return value is
143 * passed to ZSTD_trace_compress_end().
144 */
145ZSTD_WEAK_ATTR ZSTD_TraceCtx ZSTD_trace_decompress_begin(
146 struct ZSTD_DCtx_s const* dctx);
147
148/**
149 * Trace the end of a decompression call.
150 * @param ctx The return value of ZSTD_trace_decompress_begin().
151 * @param trace The zstd tracing info.
152 */
153ZSTD_WEAK_ATTR void ZSTD_trace_decompress_end(
154 ZSTD_TraceCtx ctx,
155 ZSTD_Trace const* trace);
156
157#endif /* ZSTD_TRACE */
158
159#if defined (__cplusplus)
160}
161#endif
162
163#endif /* ZSTD_TRACE_H */
164