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