BenchIT uses a small interface for the interaction of the BenchIT-Core-System and the BenchIT-Kernels. The interface is defined in the file "interface.h".
- The first part defines constants, macros and data structures.
- INVALID_MEASUREMENT
Value to mark a measurement as invalid, e.g. due to insufficient timer resolution.
- IDL(X,Y)
Macro for executing the command Y if DEBUGLEVEL is equal to or larger than X.
- BI_GET_CALL_OVERHEAD_FUNC(X,Y)
Template for custom overhead measuring function. It constructs the function bi_get_call_overhead with arguments specified through X and the function to be called for measuring the overhead must be supplied in Y.
- If you want to measure the overhead of your function compute(), you would use BI_GET_CALL_OVERHEAD_FUNC( (), compute() );
- If your function has arguments which you would like to pass, e.g. compute( double size ), you would use it like that: BI_GET_CALL_OVERHEAD_FUNC( (double arg_size), compute(arg_size) );. The name of the argument is irrelevant, but must be the same in the two definitions.
- struct bi_info
Structure used by kernels to store information about the kernel and the measurement.
- char *codesequence;
Short piece of code showing the function of the kernel.
- char *kerneldescription;
Description of the function of the kernel.
- char *xaxistext;
Description of the x-axis.
- char **yaxistexts;
Descriptions of the y-axes.
- char **legendtexts;
Legend(s) for the measurement(s).
- int num_processes;
Actual number of processes the kernel has used.
- int num_threads_per_process;
Actual number of threads per process the kernel has used.
- int num_measurements;
The number of measurements that will be performed.
- int numfunctions;
Number of different functions this kernel measures.
- int *outlier_direction_upwards;
Boolean value indicating whether outliers are above(1) or below(0) the average
- int kernel_execs_mpi1;
Boolean value indicating whether this kernel uses MPI version 1.
- int kernel_execs_mpi2;
Boolean value indicating whether this kernel uses MPI version 2.
- int kernel_execs_pvm;
Boolean value indicating whether this kernel uses PVM.
- int kernel_execs_omp;
Boolean value indicating whether this kernel uses OpenMP.
- int kernel_execs_pthreads;
Boolean value indicating whether this kernel uses PThreads.
- double base_xaxis;
indicating whether xaxis is linear or logarithmic
- double base_yaxis;
indicating whether xaxis is linear or logarithmic
- char *gnuplot_options;
Custom options for gnuplot.
- char *additional_information;
additional information the kernel can specify.
This is suposed to be a comma seperated list of key=value settings
the key=value pairs will be put separately into the result file
some values may be used by the BenchIT-GUI and the Webpage
a list of accepted strings can be found here
int is3d;
Boolean value indicating whether the kernel produces 3-dimensional output
The second part defines the functions and variables provided by BenchIT, they are implemented in the file "benchit.c" and can be used by the kernels.
- extern char* bi_strdup(const char* str);
Returns a copy of the string 'str'.
- extern char* bi_getenv(const char *env, int exitOnNull );
Returns the content of the environment variable with the name supplied in env.
- exitOnNull defines the behaviour in case of an error. If the requested variable is not found and:
- exitOnNull == 0 - Null will be returned
- exitOnNull == 1 - BenchIT will exit with an error message
- exitOnNull >= 1 - BenchIT will exit with an error message and additionally dump the environment
- extern long int bi_int_getenv(const char *env, int exitOnNull );
Reads environment variable with the name supplied in env and converts it to a long int.
- exitOnNull does the same as in bi_getenv(...) described above.
- extern float bi_cpu_freq(void);
Returns the clockrate of the CPU in GHz.
- extern double (*bi_gettime)();
This function has to be used by the kernels to measure time.
If multiple timers are awailable BenchIT chooses the timer with the best granularity.
- extern int bi_confuseCache(int nCacheSize);
Tries to flush the Cache by filling nCacheSize bytes with data and calculating with it. Only the Data Cache is affected. Seperate instruction caches will not be cleared.
- extern double dTimerGranularity;
Granularity of bi_gettime() in seconds.
- extern double dTimerOverhead;
Overhead of one call to bi_gettime() in seconds.
- extern void bi_abort(int err);
Abort function that should be used by the kernels in case of an error instead of doing an exit(err); writes existing results if any.
- extern void bi_random_init(unsigned long long start,unsigned long long max);
Initalizes the random number generator.
- 'start' defines the initial state of the random number generator.
- 'max' is the upper bound for the return values of 'bi_random32()' and 'bi_random48()'. If 'max' is 0 there is no limitation.
- extern unsigned int bi_random32(void);
Returns a 32-Bit pseudo random number. 0 <= return value < 'max'(see bi_random_init(...)). MUST NOT BE USED BEFORE THE INITIALISATION of the random number generator!
- extern unsigned long long bi_random48(void);
Returns a 48-Bit pseudo random number. 0 <= return value < 'max'(see bi_random_init(...)). MUST NOT BE USED BEFORE THE INITIALISATION of the random number generator!
The third part defines the functions needed by BenchIT to do the measurements, these functions have to be implemented by the kernels.
- extern void bi_getinfo( bi_info* infostruct );
Provides an empty bi_info struct which has to be filled by the kernel.
- extern void *bi_init( int problemsizemax );
Initialize the kernel.
- extern int bi_entry( void *mcb, int problemsize, double *results );
Start a measurement with the specified problem size.
- extern void bi_cleanup( void *mcb );
This function is called at the end of the measurements.
