@@@ fltfmt mess

[mLib] / test / tvec-bench.h

/* -*-c-*-
 *
 * Test-vector framework benchmark extension
 *
 * (c) 2024 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of the mLib utilities library.
 *
 * mLib is free software: you can redistribute it and/or modify it under
 * the terms of the GNU Library General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or (at
 * your option) any later version.
 *
 * mLib is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
 * License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with mLib.  If not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
 * USA.
 */

#ifndef MLIB_TVEC_BENCH_H
#define MLIB_TVEC_BENCH_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#ifndef MLIB_BENCH_H
#  include "bench.h"
#endif

#ifndef MLIB_CONTROL_H
#  include "control.h"
#endif

#ifndef MLIB_GPRINTF_H
#  include "gprintf.h"
#endif

#ifndef MLIB_TVEC_H
#  include "tvec.h"
#endif

#ifndef MLIB_TVEC_OUTPUT_H
#  include "tvec-output.h"
#endif

/*----- Test environment --------------------------------------------------*/

struct tvec_benchenv {
  /* Benchmark environment definition. */

  struct tvec_env _env;			/* benchmarking is an environment */
  struct bench_state **bst;		/* benchmark state anchor or null */
  unsigned long niter;			/* iterations done per unit */
  int riter, rbuf;			/* iterations and buffer registers */
  const struct tvec_env *env;		/* subordinate environment */
};

struct tvec_benchctx {
  /* Benchmark environment context; private. */

  const struct tvec_benchenv *be;	/* environment configuration */
  struct bench_state *bst;		/* benchmark state */
  double dflt_target;			/* default time in seconds */
  unsigned f;				/* flags */
#define TVBF_SETTRG 1u			/*   set `@target' */
#define TVBF_SETMASK (TVBF_SETTRG))	/*   mask of @TVBF_SET...@ */
  void *subctx;				/* subordinate environment context */
};

/* --- Environment implementation --- *
 *
 * The following special variables are supported.
 *
 *   * %|@target|% is the (approximate) number of seconds to run the
 *     benchmark.
 *
 * Unrecognized variables are passed to the subordinate environment, if there
 * is one.  Other events are passed through to the subordinate environment.
 */

extern tvec_envsetupfn tvec_benchsetup;
extern tvec_envfindvarfn tvec_benchfindvar;
extern tvec_envbeforefn tvec_benchbefore;
extern tvec_envrunfn tvec_benchrun;
extern tvec_envafterfn tvec_benchafter;
extern tvec_envteardownfn tvec_benchteardown;

#define TVEC_BENCHENV							\
  { sizeof(struct tvec_benchctx),					\
    tvec_benchsetup,							\
    tvec_benchfindvar,							\
    tvec_benchbefore,							\
    tvec_benchrun,							\
    tvec_benchafter,							\
    tvec_benchteardown }
#define TVEC_BENCHINIT TVEC_BENCHENV, &tvec_benchstate

/*----- Benchmark output extension ----------------------------------------*/

#define TVEC_BENCHOUTEXT "tvec-bench"

struct tvec_benchoutops {
  /* Output extension for benchmarking.  The name for this extension is
   * %|tvec-bench|%.
   */

  void (*bbench)(struct tvec_output */*o*/,
		 const char */*desc*/, unsigned /*unit*/);
    /* Begin a benchmark.  If the description @desc@ is null -- which it will
     * be unless we're doing adhoc testing, then the output driver should
     * label its benchmark output, e.g., by dumping the values of the input
     * registers marked @TVRF_ID@.  The @unit@ is one of the @BTU_...@
     * constants explaining what sort of thing is being measured.
     */

  void (*ebench)(struct tvec_output */*o*/,
		 const char */*desc*/, unsigned /*unit*/,
		 const struct bench_timing */*t*/);
    /* End a benchmark.  The @unit@ argument is as for @bbench@.  If @tm@ is
     * zero then the measurement failed; otherwise @tm->n@ counts total
     * number of things (operations or bytes, as indicated by @unit@)
     * processed in the indicated time.
     */
};

extern const struct tvec_benchoutops tvec_benchoutputfallback;
  /* Fallback operations for benchmark output.  The @o@ argument is a pointer
   * to a @struct tvec_fallbackoutput@.
   */

/*----- Global variables --------------------------------------------------*/

extern struct bench_state *tvec_benchstate; /* default benchmark state */

/*----- Functions provided ------------------------------------------------*/

/* --- @TVEC_BENCHMARK@, @TVEC_BENCHMARK_TAG@ --- *
 *
 * Arguments:	@const char *desc@ = a description of the benchmark
 *		@struct bench_state **bst_inout@ = benchmark state (updated)
 *		@unsigned unit@ = unit being measured (@BTU_...@ code)
 *		@double base@ = number of units per external iteration
 *
 * Returns:	---
 *
 * Use:
 */

#define TVEC_BENCHMARK_DECLS						\
  struct tvec_state *_tvbench_tv;					\
  struct tvec_fallbackoutput _tvbench_fo;				\
  const struct tvec_benchoutops *_tvbench_bo;				\
  struct tvec_output *_tvbench_o;					\
  const char *_tvbench_desc;						\
  unsigned _tvbench_unit;						\
  struct bench_timing _tvbench_tm;					\
  int _tvbench_rc;							\
  BENCH_MEASURE_DECLS

#define TVEC_BENCHMARK_TAG(tag, desc, tv, bst, unit, base)		\
  MC_BEFORE(tag##__tvbench_setup, {					\
    _tvbench_tv = (tv);							\
    _tvbench_bo = tvec_outputext(_tvbench_tv, &_tvbench_o, &_tvbench_fo, \
				 TVEC_BENCHOUTEXT,			\
				 &tvec_benchoutputfallback);		\
    _tvbench_desc = (desc); _tvbench_unit = (unit);			\
    TVEC_BEGINTEST(_tvbench_tv);					\
    _tvbench_bo->bbench(_tvbench_o, _tvbench_desc, _tvbench_unit);	\
  })									\
  MC_AFTER(tag##__tvbench_report, {					\
    _tvbench_bo->ebench(_tvbench_o, _tvbench_desc, _tvbench_unit,	\
			_tvbench_rc ? 0 : &_tvbench_tm);		\
    tvec_endtest(_tvbench_tv);						\
  })									\
  BENCH_MEASURE_TAG(tag##__tvbench_measure, (bst),			\
		    _tvbench_rc, &_tvbench_tm, (base))

#define TVEC_BENCHMARK(desc, tv, bst, unit, base)			\
  TVEC_BENCHMARK_TAG(tvec_bench, desc, tv, bst, unit, base)

/* --- @tvec_benchprep@ --- *
 *
 * Arguments:	@struct tvec_state *tv@ = test vector state
 *		@struct bench_state **bst_inout@ = benchmark state (updated)
 *		@unsigned f@ = calibration flags
 *
 * Returns:	Zero on success, %$-1$% on failure.
 *
 * Use:		If @*bst_inout@ is null then allocate and initialize a fresh
 *		benchmark state with a default timer, and @*bst_inout@ is
 *		updated to point to the fresh state.  The storage for the
 *		state was allocated using the test vector state's arena.
 *
 *		If the benchmark state hasn't been calibrated, then this is
 *		done, passing @f@ to @bench_calibrate@.
 *
 *		On failure, the test group is skipped, reporting a suitable
 *		message, and %$-1$% is returned.  If a fresh benchmark state
 *		was allocated, but calibration failed, the state is
 *		%%\emph{not}%% released.
 */

extern int tvec_benchprep(struct tvec_state */*tv*/,
			  struct bench_state **/*bst_inout*/,
			  unsigned /*f*/);

/* --- @tvec_benchreport@ --- *
 *
 * Arguments:	@const struct gprintf_ops *gops@ = print operations
 *		@void *go@ = print destination
 *		@unsigned unit@ = the unit being measured (@BTU_...@)
 *		@unsigned style@ = output style (@TVSF_...@)
 *		@const struct bench_timing *t@ = the benchmark result
 *
 * Returns:	---
 *
 * Use:		Formats a report about the benchmark performance.  This
 *		function is intended to be called on by an output @ebench@
 *		function.
 */

extern void tvec_benchreport
  (const struct gprintf_ops */*gops*/, void */*go*/,
   unsigned /*unit*/, unsigned /*style*/, const struct bench_timing */*tm*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif