Interface

From BenchIT-Wiki

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.