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