1*a0483764SConrad Meyer /* 2*a0483764SConrad Meyer * Copyright (c) 2016-present, Yann Collet, Facebook, Inc. 3*a0483764SConrad Meyer * All rights reserved. 4*a0483764SConrad Meyer * 5*a0483764SConrad Meyer * This source code is licensed under both the BSD-style license (found in the 6*a0483764SConrad Meyer * LICENSE file in the root directory of this source tree) and the GPLv2 (found 7*a0483764SConrad Meyer * in the COPYING file in the root directory of this source tree). 8*a0483764SConrad Meyer * You may select, at your option, one of the above-listed licenses. 9*a0483764SConrad Meyer */ 10*a0483764SConrad Meyer 11*a0483764SConrad Meyer /* benchzstd : 12*a0483764SConrad Meyer * benchmark Zstandard compression / decompression 13*a0483764SConrad Meyer * over a set of files or buffers 14*a0483764SConrad Meyer * and display progress result and final summary 15*a0483764SConrad Meyer */ 16*a0483764SConrad Meyer 17*a0483764SConrad Meyer #if defined (__cplusplus) 18*a0483764SConrad Meyer extern "C" { 19*a0483764SConrad Meyer #endif 20*a0483764SConrad Meyer 21*a0483764SConrad Meyer #ifndef BENCH_ZSTD_H_3242387 22*a0483764SConrad Meyer #define BENCH_ZSTD_H_3242387 23*a0483764SConrad Meyer 24*a0483764SConrad Meyer /* === Dependencies === */ 25*a0483764SConrad Meyer #include <stddef.h> /* size_t */ 26*a0483764SConrad Meyer #define ZSTD_STATIC_LINKING_ONLY /* ZSTD_compressionParameters */ 27*a0483764SConrad Meyer #include "zstd.h" /* ZSTD_compressionParameters */ 28*a0483764SConrad Meyer 29*a0483764SConrad Meyer 30*a0483764SConrad Meyer /* === Constants === */ 31*a0483764SConrad Meyer 32*a0483764SConrad Meyer #define MB_UNIT 1000000 33*a0483764SConrad Meyer 34*a0483764SConrad Meyer 35*a0483764SConrad Meyer /* === Benchmark functions === */ 36*a0483764SConrad Meyer 37*a0483764SConrad Meyer /* Creates a variant `typeName`, able to express "error or valid result". 38*a0483764SConrad Meyer * Functions with return type `typeName` 39*a0483764SConrad Meyer * must first check if result is valid, using BMK_isSuccessful_*(), 40*a0483764SConrad Meyer * and only then can extract `baseType`. 41*a0483764SConrad Meyer */ 42*a0483764SConrad Meyer #define VARIANT_ERROR_RESULT(baseType, variantName) \ 43*a0483764SConrad Meyer \ 44*a0483764SConrad Meyer typedef struct { \ 45*a0483764SConrad Meyer baseType internal_never_use_directly; \ 46*a0483764SConrad Meyer int tag; \ 47*a0483764SConrad Meyer } variantName 48*a0483764SConrad Meyer 49*a0483764SConrad Meyer 50*a0483764SConrad Meyer typedef struct { 51*a0483764SConrad Meyer size_t cSize; 52*a0483764SConrad Meyer unsigned long long cSpeed; /* bytes / sec */ 53*a0483764SConrad Meyer unsigned long long dSpeed; 54*a0483764SConrad Meyer size_t cMem; /* memory usage during compression */ 55*a0483764SConrad Meyer } BMK_benchResult_t; 56*a0483764SConrad Meyer 57*a0483764SConrad Meyer VARIANT_ERROR_RESULT(BMK_benchResult_t, BMK_benchOutcome_t); 58*a0483764SConrad Meyer 59*a0483764SConrad Meyer /* check first if the return structure represents an error or a valid result */ 60*a0483764SConrad Meyer int BMK_isSuccessful_benchOutcome(BMK_benchOutcome_t outcome); 61*a0483764SConrad Meyer 62*a0483764SConrad Meyer /* extract result from variant type. 63*a0483764SConrad Meyer * note : this function will abort() program execution if result is not valid 64*a0483764SConrad Meyer * check result validity first, by using BMK_isSuccessful_benchOutcome() 65*a0483764SConrad Meyer */ 66*a0483764SConrad Meyer BMK_benchResult_t BMK_extract_benchResult(BMK_benchOutcome_t outcome); 67*a0483764SConrad Meyer 68*a0483764SConrad Meyer 69*a0483764SConrad Meyer /*! BMK_benchFiles() -- called by zstdcli */ 70*a0483764SConrad Meyer /* Loads files from fileNamesTable into memory, 71*a0483764SConrad Meyer * and an optional dictionary from dictFileName (can be NULL), 72*a0483764SConrad Meyer * then uses benchMem(). 73*a0483764SConrad Meyer * fileNamesTable - name of files to benchmark. 74*a0483764SConrad Meyer * nbFiles - number of files (size of fileNamesTable), must be > 0. 75*a0483764SConrad Meyer * dictFileName - name of dictionary file to load. 76*a0483764SConrad Meyer * cLevel - compression level to benchmark, errors if invalid. 77*a0483764SConrad Meyer * compressionParams - advanced compression Parameters. 78*a0483764SConrad Meyer * displayLevel - what gets printed: 79*a0483764SConrad Meyer * 0 : no display; 80*a0483764SConrad Meyer * 1 : errors; 81*a0483764SConrad Meyer * 2 : + result + interaction + warnings; 82*a0483764SConrad Meyer * 3 : + information; 83*a0483764SConrad Meyer * 4 : + debug 84*a0483764SConrad Meyer * @return: 85*a0483764SConrad Meyer * a variant, which expresses either an error, or a valid result. 86*a0483764SConrad Meyer * Use BMK_isSuccessful_benchOutcome() to check if function was successful. 87*a0483764SConrad Meyer * If yes, extract the valid result with BMK_extract_benchResult(), 88*a0483764SConrad Meyer * it will contain : 89*a0483764SConrad Meyer * .cSpeed: compression speed in bytes per second, 90*a0483764SConrad Meyer * .dSpeed: decompression speed in bytes per second, 91*a0483764SConrad Meyer * .cSize : compressed size, in bytes 92*a0483764SConrad Meyer * .cMem : memory budget required for the compression context 93*a0483764SConrad Meyer */ 94*a0483764SConrad Meyer BMK_benchOutcome_t BMK_benchFiles( 95*a0483764SConrad Meyer const char* const * fileNamesTable, unsigned nbFiles, 96*a0483764SConrad Meyer const char* dictFileName, 97*a0483764SConrad Meyer int cLevel, const ZSTD_compressionParameters* compressionParams, 98*a0483764SConrad Meyer int displayLevel); 99*a0483764SConrad Meyer 100*a0483764SConrad Meyer 101*a0483764SConrad Meyer typedef enum { 102*a0483764SConrad Meyer BMK_both = 0, 103*a0483764SConrad Meyer BMK_decodeOnly = 1, 104*a0483764SConrad Meyer BMK_compressOnly = 2 105*a0483764SConrad Meyer } BMK_mode_t; 106*a0483764SConrad Meyer 107*a0483764SConrad Meyer typedef struct { 108*a0483764SConrad Meyer BMK_mode_t mode; /* 0: all, 1: compress only 2: decode only */ 109*a0483764SConrad Meyer unsigned nbSeconds; /* default timing is in nbSeconds */ 110*a0483764SConrad Meyer size_t blockSize; /* Maximum size of each block*/ 111*a0483764SConrad Meyer unsigned nbWorkers; /* multithreading */ 112*a0483764SConrad Meyer unsigned realTime; /* real time priority */ 113*a0483764SConrad Meyer int additionalParam; /* used by python speed benchmark */ 114*a0483764SConrad Meyer unsigned ldmFlag; /* enables long distance matching */ 115*a0483764SConrad Meyer unsigned ldmMinMatch; /* below: parameters for long distance matching, see zstd.1.md */ 116*a0483764SConrad Meyer unsigned ldmHashLog; 117*a0483764SConrad Meyer unsigned ldmBucketSizeLog; 118*a0483764SConrad Meyer unsigned ldmHashRateLog; 119*a0483764SConrad Meyer } BMK_advancedParams_t; 120*a0483764SConrad Meyer 121*a0483764SConrad Meyer /* returns default parameters used by nonAdvanced functions */ 122*a0483764SConrad Meyer BMK_advancedParams_t BMK_initAdvancedParams(void); 123*a0483764SConrad Meyer 124*a0483764SConrad Meyer /*! BMK_benchFilesAdvanced(): 125*a0483764SConrad Meyer * Same as BMK_benchFiles(), 126*a0483764SConrad Meyer * with more controls, provided through advancedParams_t structure */ 127*a0483764SConrad Meyer BMK_benchOutcome_t BMK_benchFilesAdvanced( 128*a0483764SConrad Meyer const char* const * fileNamesTable, unsigned nbFiles, 129*a0483764SConrad Meyer const char* dictFileName, 130*a0483764SConrad Meyer int cLevel, const ZSTD_compressionParameters* compressionParams, 131*a0483764SConrad Meyer int displayLevel, const BMK_advancedParams_t* adv); 132*a0483764SConrad Meyer 133*a0483764SConrad Meyer /*! BMK_syntheticTest() -- called from zstdcli */ 134*a0483764SConrad Meyer /* Generates a sample with datagen, using compressibility argument */ 135*a0483764SConrad Meyer /* cLevel - compression level to benchmark, errors if invalid 136*a0483764SConrad Meyer * compressibility - determines compressibility of sample 137*a0483764SConrad Meyer * compressionParams - basic compression Parameters 138*a0483764SConrad Meyer * displayLevel - see benchFiles 139*a0483764SConrad Meyer * adv - see advanced_Params_t 140*a0483764SConrad Meyer * @return: 141*a0483764SConrad Meyer * a variant, which expresses either an error, or a valid result. 142*a0483764SConrad Meyer * Use BMK_isSuccessful_benchOutcome() to check if function was successful. 143*a0483764SConrad Meyer * If yes, extract the valid result with BMK_extract_benchResult(), 144*a0483764SConrad Meyer * it will contain : 145*a0483764SConrad Meyer * .cSpeed: compression speed in bytes per second, 146*a0483764SConrad Meyer * .dSpeed: decompression speed in bytes per second, 147*a0483764SConrad Meyer * .cSize : compressed size, in bytes 148*a0483764SConrad Meyer * .cMem : memory budget required for the compression context 149*a0483764SConrad Meyer */ 150*a0483764SConrad Meyer BMK_benchOutcome_t BMK_syntheticTest( 151*a0483764SConrad Meyer int cLevel, double compressibility, 152*a0483764SConrad Meyer const ZSTD_compressionParameters* compressionParams, 153*a0483764SConrad Meyer int displayLevel, const BMK_advancedParams_t* adv); 154*a0483764SConrad Meyer 155*a0483764SConrad Meyer 156*a0483764SConrad Meyer 157*a0483764SConrad Meyer /* === Benchmark Zstandard in a memory-to-memory scenario === */ 158*a0483764SConrad Meyer 159*a0483764SConrad Meyer /** BMK_benchMem() -- core benchmarking function, called in paramgrill 160*a0483764SConrad Meyer * applies ZSTD_compress_generic() and ZSTD_decompress_generic() on data in srcBuffer 161*a0483764SConrad Meyer * with specific compression parameters provided by other arguments using benchFunction 162*a0483764SConrad Meyer * (cLevel, comprParams + adv in advanced Mode) */ 163*a0483764SConrad Meyer /* srcBuffer - data source, expected to be valid compressed data if in Decode Only Mode 164*a0483764SConrad Meyer * srcSize - size of data in srcBuffer 165*a0483764SConrad Meyer * fileSizes - srcBuffer is considered cut into 1+ segments, to compress separately. 166*a0483764SConrad Meyer * note : sum(fileSizes) must be == srcSize. (<== ensure it's properly checked) 167*a0483764SConrad Meyer * nbFiles - nb of segments 168*a0483764SConrad Meyer * cLevel - compression level 169*a0483764SConrad Meyer * comprParams - basic compression parameters 170*a0483764SConrad Meyer * dictBuffer - a dictionary if used, null otherwise 171*a0483764SConrad Meyer * dictBufferSize - size of dictBuffer, 0 otherwise 172*a0483764SConrad Meyer * diplayLevel - see BMK_benchFiles 173*a0483764SConrad Meyer * displayName - name used by display 174*a0483764SConrad Meyer * @return: 175*a0483764SConrad Meyer * a variant, which expresses either an error, or a valid result. 176*a0483764SConrad Meyer * Use BMK_isSuccessful_benchOutcome() to check if function was successful. 177*a0483764SConrad Meyer * If yes, extract the valid result with BMK_extract_benchResult(), 178*a0483764SConrad Meyer * it will contain : 179*a0483764SConrad Meyer * .cSpeed: compression speed in bytes per second, 180*a0483764SConrad Meyer * .dSpeed: decompression speed in bytes per second, 181*a0483764SConrad Meyer * .cSize : compressed size, in bytes 182*a0483764SConrad Meyer * .cMem : memory budget required for the compression context 183*a0483764SConrad Meyer */ 184*a0483764SConrad Meyer BMK_benchOutcome_t BMK_benchMem(const void* srcBuffer, size_t srcSize, 185*a0483764SConrad Meyer const size_t* fileSizes, unsigned nbFiles, 186*a0483764SConrad Meyer int cLevel, const ZSTD_compressionParameters* comprParams, 187*a0483764SConrad Meyer const void* dictBuffer, size_t dictBufferSize, 188*a0483764SConrad Meyer int displayLevel, const char* displayName); 189*a0483764SConrad Meyer 190*a0483764SConrad Meyer 191*a0483764SConrad Meyer /* BMK_benchMemAdvanced() : same as BMK_benchMem() 192*a0483764SConrad Meyer * with following additional options : 193*a0483764SConrad Meyer * dstBuffer - destination buffer to write compressed output in, NULL if none provided. 194*a0483764SConrad Meyer * dstCapacity - capacity of destination buffer, give 0 if dstBuffer = NULL 195*a0483764SConrad Meyer * adv = see advancedParams_t 196*a0483764SConrad Meyer */ 197*a0483764SConrad Meyer BMK_benchOutcome_t BMK_benchMemAdvanced(const void* srcBuffer, size_t srcSize, 198*a0483764SConrad Meyer void* dstBuffer, size_t dstCapacity, 199*a0483764SConrad Meyer const size_t* fileSizes, unsigned nbFiles, 200*a0483764SConrad Meyer int cLevel, const ZSTD_compressionParameters* comprParams, 201*a0483764SConrad Meyer const void* dictBuffer, size_t dictBufferSize, 202*a0483764SConrad Meyer int displayLevel, const char* displayName, 203*a0483764SConrad Meyer const BMK_advancedParams_t* adv); 204*a0483764SConrad Meyer 205*a0483764SConrad Meyer 206*a0483764SConrad Meyer 207*a0483764SConrad Meyer 208*a0483764SConrad Meyer #endif /* BENCH_ZSTD_H_3242387 */ 209*a0483764SConrad Meyer 210*a0483764SConrad Meyer #if defined (__cplusplus) 211*a0483764SConrad Meyer } 212*a0483764SConrad Meyer #endif 213