| 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) |
| 15 | extern "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 | |
| 50 | struct ZSTD_CCtx_s; |
| 51 | struct ZSTD_DCtx_s; |
| 52 | struct ZSTD_CCtx_params_s; |
| 53 | |
| 54 | typedef 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 | */ |
| 117 | typedef 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 | */ |
| 126 | ZSTD_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 | */ |
| 134 | ZSTD_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 | */ |
| 145 | ZSTD_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 | */ |
| 153 | ZSTD_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 */ |