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