@@@ bench wip
[mLib] / test / tvec.h
index 5ea18ca..d16df58 100644 (file)
   extern "C" {
 #endif
 
+/* Here's the overall flow for a testing session.
+ *
+ * @tvec_begin@
+ *                     -> output @bsession@
+ * @tvec_read@
+ *                     -> output @bgroup@
+ *                     -> env @setup@
+ *   one or more tests
+ *                     -> type @init@ (input and output)
+ *                     -> type @parse@ (input)
+ *                     -> output @btest@
+ *                     -> env @before@
+ *                             -> @tvec_skipgroup@
+ *                                     -> output @skipgroup@
+ *                     -> env @run@
+ *                             -> @tvec_skip@
+ *                                     -> output @skip@
+ *                             -> test @fn@
+ *                             -> @tvec_checkregs@
+ *                                     -> type @eq@
+ *                             -> @tvec_fail@
+ *                                     -> output @fail@
+ *                             -> @tvec_mismatch@
+ *                                     -> output @dumpreg@
+ *                                             -> type @dump@
+ *                     -> output @etest@
+ *                     -> env @after@
+ *   finally
+ *                     -> output @egroup@
+ *                     -> env @teardown@
+ *
+ * @tvec_adhoc@
+ *   @tvec_begingroup@
+ *                     -> output @bgroup@
+ *                     -> env @setup@
+ *     @tvec_begintest@
+ *                     -> output @btest@
+ *     @tvec_skip@
+ *                     -> output @skip@
+ *     @tvec_claimeq@
+ *                     -> @tvec_fail@
+ *                             -> output @fail@
+ *                     -> @tvec_mismatch@
+ *                             -> output @dumpreg@
+ *                             -> type @dump@
+ *     @tvec_endtest@
+ *                     -> output @etest@
+ *     or @tvec_skipgroup@
+ *                     -> output @skipgroup@
+ * @tvec_endgroup@
+ *                     -> output @egroup@
+ *
+ * @tvec_end@
+ *                     -> output @esession@
+ *                     -> output @destroy@
+ *
+ * @tvec_benchrun@
+ *                     -> type @dump@ (compact style)
+ *                     -> output @bbench@
+ *                     -> subenv @run@
+ *                             -> test @fn@
+ *                     -> output @ebench@
+ *                             -> @tvec_benchreport@
+ *
+ * The output functions @error@ and @notice@ can be called at arbitrary
+ * times.
+ */
+
 /*----- Header files ------------------------------------------------------*/
 
 #include <stdarg.h>
 #  include "gprintf.h"
 #endif
 
+#ifndef MLIB_LBUF_H
+#  include "lbuf.h"
+#endif
+
 #ifndef MLIB_MACROS_H
 #  include "macros.h"
 #endif
@@ -105,47 +177,50 @@ enum {
  */
 
 union tvec_regval {
-       /* The actual register value.  This is what the type handler sees.
-        * Additional members can be added by setting `TVEC_REGSLOTS' before
-        * including this file.
-        *
-        * A register value can be /initialized/, which simply means that its
-        * contents represent a valid value according to its type -- the
-        * register can be compared, dumped, serialized, parsed into, etc.
-        * You can't do anything safely to an uninitialized register value
-        * other than initialize it.
-        */
+  /* The actual register value.  This is what the type handler sees.
+   * Additional members can be added by setting `TVEC_REGSLOTS' before
+   * including this file.
+   *
+   * A register value can be /initialized/, which simply means that its
+   * contents represent a valid value according to its type -- the register
+   * can be compared, dumped, serialized, parsed into, etc.  You can't do
+   * anything safely to an uninitialized register value other than initialize
+   * it.
+   */
 
   long i;                              /* signed integer */
   unsigned long u;                     /* unsigned integer */
   void *p;                             /* pointer */
   double f;                            /* floating point */
   struct { unsigned char *p; size_t sz; } bytes; /* binary string of bytes */
-  struct { char *p; size_t sz; } str;  /* text string */
+  struct { char *p; size_t sz; } text; /* text string */
+  struct {                             /* buffer */
+    unsigned char *p; size_t sz;       /* binary string */
+    size_t a, m;                       /* residue and modulus */
+    size_t off;                                /* offset into full buffer */
+  } buf;
 #ifdef TVEC_REGSLOTS
   TVEC_REGSLOTS
 #endif
 };
 
 struct tvec_reg {
-       /* A register.
-        *
-        * Note that all of the registers listed as being used by a
-        * particular test group are initialized at all times[1] while that
-        * test group is being processed.  (The other register slots don't
-        * even have types associated with them, so there's nothing useful we
-        * could do with them.)
-        *
-        * The `TVRF_LIVE' flag indicates that the register was assigned a
-        * value by the test vector file: it's the right thing to use to
-        * check whether an optional register is actually present.  Even
-        * `dead' registers are still initialized, though.
-        *
-        * [1] This isn't quite true.  Between individual tests, the
-        *     registers are released and reinitialized in order to reset
-        *     them to known values ready for the next test.  But you won't
-        *     see them at this point.
-        */
+  /* A register.
+   *
+   * Note that all of the registers listed as being used by a particular test
+   * group are initialized at all times[1] while that test group is being
+   * processed.  (The other register slots don't even have types associated
+   * with them, so there's nothing useful we could do with them.)
+   *
+   * The `TVRF_LIVE' flag indicates that the register was assigned a value by
+   * the test vector file: it's the right thing to use to check whether an
+   * optional register is actually present.  Even `dead' registers are still
+   * initialized, though.
+   *
+   * [1] This isn't quite true.  Between individual tests, the registers are
+   *    released and reinitialized in order to reset them to known values
+   *    ready for the next test.  But you won't see them at this point.
+   */
 
   unsigned f;                          /* flags */
 #define TVRF_LIVE 1u                   /*   used in current test  */
@@ -153,13 +228,12 @@ struct tvec_reg {
 };
 
 struct tvec_regdef {
-       /* A register definition.  Register definitions list the registers
-        * which are used by a particular test group (see `struct tvec_test'
-        * below).
-        *
-        * A vector of register definitions is terminated by a definition
-        * whose `name' slot is null.
-        */
+  /* A register definition.  Register definitions list the registers which
+   * are used by a particular test group (see `struct tvec_test' below).
+   *
+   * A vector of register definitions is terminated by a definition whose
+   * `name' slot is null.
+   */
 
   const char *name;                    /* register name (for input files) */
   unsigned i;                          /* register index */
@@ -186,6 +260,192 @@ struct tvec_regdef {
 #define TVEC_GREG(vec, i, regsz)                                       \
        ((struct tvec_reg *)((unsigned char *)(vec) + (i)*(regsz)))
 
+/*----- Register types ----------------------------------------------------*/
+
+struct tvec_state;                     /* forward declaration */
+
+struct tvec_regty {
+  /* A register type. */
+
+  void (*init)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/);
+    /* Initialize the value in @*rv@.  This will be called before any other
+     * function acting on the value, including @release@.
+     */
+
+  void (*release)(union tvec_regval */*rv*/,
+                 const struct tvec_regdef */*rd*/);
+    /* Release any resources associated with the value in @*rv@. */
+
+  int (*eq)(const union tvec_regval */*rv0*/,
+           const union tvec_regval */*rv1*/,
+           const struct tvec_regdef */*rd*/);
+    /* Return nonzero if @*rv0@ and @*rv1@ are equal values.  Asymmetric
+     * criteria are permitted: @tvec_checkregs@ calls @eq@ with the input
+     * register as @rv0@ and the output as @rv1@.
+     */
+
+  int (*tobuf)(buf */*b*/, const union tvec_regval */*rv*/,
+              const struct tvec_regdef */*rd*/);
+    /* Serialize the value @*rv@, writing the result to @b@.  Return zero on
+     * success, or %$-1$% on error.
+     */
+
+  int (*frombuf)(buf */*b*/, union tvec_regval */*rv*/,
+                const struct tvec_regdef */*rd*/);
+    /* Deserialize a value from @b@, storing it in @*rv@.  Return zero on
+     * success, or %$-1$% on error.
+     */
+
+  int (*parse)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/,
+              struct tvec_state */*tv*/);
+    /* Parse a value from @tv->fp@, storing it in @*rv@.  Return zero on
+     * success, or %$-1$% on error, having reported one or more errors via
+     * @tvec_error@ or @tvec_syntax@.  A successful return should leave the
+     * input position at the start of the next line; the caller will flush
+     * the remainder of the line itself.
+     */
+
+  void (*dump)(const union tvec_regval */*rv*/,
+              const struct tvec_regdef */*rd*/,
+              unsigned /*style*/,
+              const struct gprintf_ops */*gops*/, void */*go*/);
+#define TVSF_COMPACT 1u
+    /* Write a human-readable representation of the value @*rv@ using
+     * @gprintf@ on @gops@ and @go@.  The @style@ is a collection of flags:
+     * if @TVSF_COMPACT@ is set, then output should be minimal, and must fit
+     * on a single line; otherwise, output may consist of multiple lines and
+     * may contain redundant information if that is likely to be useful to a
+     * human reader.
+     */
+};
+
+/*----- Test descriptions -------------------------------------------------*/
+
+typedef void tvec_testfn(const struct tvec_reg */*in*/,
+                        struct tvec_reg */*out*/,
+                        void */*ctx*/);
+  /* A test function.  It should read inputs from @in@ and write outputs to
+   * @out@.  The @TVRF_LIVE@ is set on inputs which are actually present, and
+   * on outputs which are wanted to test.  A test function can set additional
+   * `gratuitous outputs' by setting @TVRF_LIVE@ on them; clearing
+   * @TVRF_LIVE@ on a wanted output causes a mismatch.
+   *
+   * A test function may be called zero or more times by the environment.  In
+   * particular, it may be called multiple times, though usually by prior
+   * arrangement with the environment.
+   *
+   * The @ctx@ is supplied by the environment's @run@ function (see below).
+   * The default environment calls the test function once, with a null
+   * @ctx@.  There is no expectation that the environment's context has
+   * anything to do with the test function's context.
+   */
+
+struct tvec_env;
+
+typedef int tvec_setvarfn(struct tvec_state */*tv*/, const char */*var*/,
+                         const union tvec_regval */*rv*/, void */*ctx*/);
+  /* Called after a variable is read.  Return zero on success or %$-1$% on
+   * error.  This function is never called if the test group is skipped.
+   */
+
+struct tvec_vardef {
+  size_t regsz;                                /* (minimum) register size */
+  tvec_setvarfn *setvar;               /* function to set variable */
+  struct tvec_regdef def;              /* register definition */
+};
+
+typedef void tvec_envsetupfn(struct tvec_state */*tv*/,
+                            const struct tvec_env */*env*/,
+                            void */*pctx*/, void */*ctx*/);
+  /* Initialize the context; called at the start of a test group; @pctx@ is
+   * null for environments called by the core, but may be non-null for
+   * subordinate environments.  If setup fails, the function should call
+   * @tvec_skipgroup@ with a suitable excuse.  The @set@, @after@, and
+   * @teardown@ entry points will still be called, but @before@ and @run@
+   * will not.
+   */
+
+typedef const struct tvec_vardef *tvec_envfindvarfn
+  (struct tvec_state */*tv*/, const char */*name*/,
+   void **/*ctx_out*/, void */*ctx*/);
+  /* Called when the parser finds a %|@var|%' special variable.  If a
+   * suitable variable was found, set @*ctx_out@ to a suitable context and
+   * return the variable definition; the context will be passed to the
+   * variable definition's @setvar@ function.  If no suitable variable was
+   * found, then return null.
+   */
+
+typedef void tvec_envbeforefn(struct tvec_state */*tv*/, void */*ctx*/);
+  /* Called prior to running a test.  This is the right place to act on any
+   * `%|@var|%' settings.  If preparation fails, the function should call
+   * @tvec_skip@ with a suitable excuse.  This function is never called if
+   * the test group is skipped.  It %%\emph{is}%% called if the test will be
+   * skipped due to erroneous test data.  It should check the @TVSF_ACTIVE@
+   * flag if necessary.
+   */
+
+typedef void tvec_envrunfn(struct tvec_state */*tv*/,
+                          tvec_testfn */*fn*/, void */*ctx*/);
+  /* Run the test.  It should either call @tvec_skip@, or run @fn@ one or
+   * more times.  In the latter case, it is responsible for checking the
+   * outputs, and calling @tvec_fail@ as necessary; @tvec_checkregs@ will
+   * check the register values against the supplied test vector, while
+   * @tvec_check@ does pretty much everything necessary.  This function is
+   * never called if the test group is skipped.
+   */
+
+typedef void tvec_envafterfn(struct tvec_state */*tv*/, void */*ctx*/);
+  /* Called after running or skipping a test.  Typical actions involve
+   * resetting whatever things were established by @set@.  This function
+   * %%\emph{is}%% called if the test group is skipped or the test data is
+   * erroneous, so that the test environment can reset variables set by the
+   * @set@ entry point.  It should check the @TVSF_SKIP@ flag if necessary.
+   */
+
+typedef void tvec_envteardownfn(struct tvec_state */*tv*/, void */*ctx*/);
+  /* Tear down the environment: called at the end of a test group. */
+
+
+struct tvec_env {
+  /* A test environment sets things up for and arranges to run the test.
+   *
+   * The caller is responsible for allocating storage for the environment's
+   * context, based on the @ctxsz@ slot, and freeing it later; this space is
+   * passed in as the @ctx@ parameter to the remaining functions; if @ctxsz@
+   * is zero then @ctx@ is null.
+   */
+
+  size_t ctxsz;                                /* environment context size */
+
+  tvec_envsetupfn *setup;              /* setup for group */
+  tvec_envfindvarfn *findvar;          /* find variable */
+  tvec_envbeforefn *before;            /* prepare for test */
+  tvec_envrunfn *run;                  /* run test function */
+  tvec_envafterfn *after;              /* clean up after test */
+  tvec_envteardownfn *teardown;                /* tear down after group */
+};
+
+struct tvec_test {
+  /* A test description. */
+
+  const char *name;                    /* name of the test */
+  const struct tvec_regdef *regs;      /* descriptions of the registers */
+  const struct tvec_env *env;          /* environment to run test in */
+  tvec_testfn *fn;                     /* test function */
+};
+#define TVEC_ENDTESTS { 0, 0, 0, 0 }
+
+enum {
+  /* Register output dispositions. */
+
+  TVRD_INPUT,                          /* input-only register */
+  TVRD_OUTPUT,                         /* output-only (input is dead) */
+  TVRD_MATCH,                          /* matching (equal) registers */
+  TVRD_FOUND,                          /* mismatching output register */
+  TVRD_EXPECT,                         /* mismatching input register */
+  TVRD_LIMIT                           /* (number of dispositions) */
+};
+
 /*----- Test state --------------------------------------------------------*/
 
 enum {
@@ -194,6 +454,7 @@ enum {
   TVOUT_LOSE,                          /* test failed */
   TVOUT_SKIP,                          /* test skipped */
   TVOUT_WIN,                           /* test passed */
+  TVOUT_XFAIL,                         /* test passed, but shouldn't have */
   TVOUT_LIMIT                          /* (number of possible outcomes) */
 };
 
@@ -201,12 +462,14 @@ struct tvec_state {
   /* The primary state structure for the test vector machinery. */
 
   unsigned f;                          /* flags */
-#define TVSF_SKIP 1u                   /*   skip this test group */
-#define TVSF_OPEN 2u                   /*   test is open */
-#define TVSF_ACTIVE 4u                 /*   test is active */
-#define TVSF_ERROR 8u                  /*   an error occurred */
-#define TVSF_OUTMASK 0xf0              /*   test outcome (@TVOUT_...@) */
+#define TVSF_SKIP 0x0001u              /*   skip this test group */
+#define TVSF_OPEN 0x0002u              /*   test is open */
+#define TVSF_ACTIVE 0x0004u            /*   test is active */
+#define TVSF_ERROR 0x0008u             /*   an error occurred */
+#define TVSF_OUTMASK 0x00f0u           /*   test outcome (@TVOUT_...@) */
 #define TVSF_OUTSHIFT 4                        /*   shift applied to outcome */
+#define TVSF_XFAIL 0x0100u             /*   test expected to fail */
+#define TVSF_MUFFLE 0x0200u            /*   muffle errors */
 
   /* Registers.  Available to execution environments. */
   unsigned nrout, nreg;                       /* number of output/total registers */
@@ -253,339 +516,123 @@ struct tvec_output {
 /* Benchmarking details. */
 enum {
   TVBU_OP,                            /* counting operations of some kind */
-  TVBU_BYTE                            /* counting bytes (@rbuf >= 0@) */
+  TVBU_BYTE,                           /* counting bytes (@rbuf >= 0@) */
+  TVBU_LIMIT                           /* (number of units) */
 };
-struct bench_timing;                   /* forward declaration */
+struct bench_timing;    /* include <mLib/bench.h> for the real definition */
 
 struct tvec_outops {
   /* Output operations. */
 
   void (*bsession)(struct tvec_output */*o*/, struct tvec_state */*tv*/);
-       /* Begin a test session.  The output driver will probably want to
-        * save @tv@, because this isn't provided to any other methods.
-        */
+    /* Begin a test session.  The output driver will probably want to
+     * save @tv@, because this isn't provided to any other methods.
+     */
 
   int (*esession)(struct tvec_output */*o*/);
-       /* End a session, and return the suggested exit code. */
+    /* End a session, and return the suggested exit code. */
 
   void (*bgroup)(struct tvec_output */*o*/);
-       /* Begin a test group.  The test group description is @tv->test@. */
+    /* Begin a test group.  The test group description is @tv->test@. */
 
   void (*skipgroup)(struct tvec_output */*o*/,
                    const char */*excuse*/, va_list */*ap*/);
-       /* The group is being skipped; @excuse@ may be null or a format
-        * string explaining why.  The @egroup@ method will not be called
-        * separately.
-        */
+    /* The group is being skipped; @excuse@ may be null or a format
+     * string explaining why.  The @egroup@ method will not be called
+     * separately.
+     */
 
   void (*egroup)(struct tvec_output */*o*/);
-       /* End a test group.  At least one test was attempted or @skipgroup@
-        * would have been called instead.  If @tv->curr[TVOUT_LOSE]@ is
-        * nonzero then the test group as a whole failed; otherwise it
-        * passed.
-        */
+    /* End a test group.  At least one test was attempted or @skipgroup@
+     * would have been called instead.  If @tv->curr[TVOUT_LOSE]@ is nonzero
+     * then the test group as a whole failed; otherwise it passed.
+     */
 
   void (*btest)(struct tvec_output */*o*/);
-       /* Begin a test case. */
+    /* Begin a test case. */
 
   void (*skip)(struct tvec_output */*o*/,
               const char */*excuse*/, va_list */*ap*/);
-       /* The test case is being skipped; @excuse@ may be null or a format
-        * string explaining why.  The @etest@ function will still be called
-        * (so this works differently from @skipgroup@ and @egroup@).  A test
-        * case can be skipped at most once, and, if skipped, it cannot fail.
-        */
+    /* The test case is being skipped; @excuse@ may be null or a format
+     * string explaining why.  The @etest@ function will still be called (so
+     * this works differently from @skipgroup@ and @egroup@).  A test case
+     * can be skipped at most once, and, if skipped, it cannot fail.
+     */
 
   void (*fail)(struct tvec_output */*o*/,
               const char */*detail*/, va_list */*ap*/);
-       /* The test case failed.
-        *
-        * The output driver should preferably report the filename (@infile@)
-        * and line number (@test_lno@, not @lno@) for the failing test.
-        *
-        * The @detail@ may be null or a format string describing detail
-        * about how the failing test was run which can't be determined from
-        * the registers; a @detail@ is usually provided when (and only when)
-        * the test environment potentially invokes the test function more
-        * than once.
-        *
-        * A single test case can fail multiple times!
-        */
+    /* The test case failed.
+     *
+     * The output driver should preferably report the filename (@infile@) and
+     * line number (@test_lno@, not @lno@) for the failing test.
+     *
+     * The @detail@ may be null or a format string describing detail about
+     * how the failing test was run which can't be determined from the
+     * registers; a @detail@ is usually provided when (and only when) the
+     * test environment potentially invokes the test function more than once.
+     *
+     * A single test case can fail multiple times!
+     */
 
   void (*dumpreg)(struct tvec_output */*o*/,
                  unsigned /*disp*/, const union tvec_regval */*rv*/,
                  const struct tvec_regdef */*rd*/);
-       /* Dump a register.  The `disposition' @disp@ explains what condition
-        * the register is in; see @tvec_dumpreg@ and the @TVRD_...@ codes.
-        * The register value is at @rv@, and its definition, including its
-        * type, at @rd@.  Note that this function may be called on virtual
-        * registers which aren't in either of the register vectors or
-        * mentioned by the test description.
-        */
+    /* Dump a register.  The `disposition' @disp@ explains what condition the
+     * register is in; see @tvec_dumpreg@ and the @TVRD_...@ codes.  The
+     * register value is at @rv@, and its definition, including its type, at
+     * @rd@.  Note that this function may be called on virtual registers
+     * which aren't in either of the register vectors or mentioned by the
+     * test description.  It may also be called with @rv@ null, indicating
+     * that the register is not live.
+     */
 
   void (*etest)(struct tvec_output */*o*/, unsigned /*outcome*/);
-       /* The test case concluded with the given @outcome@ (one of the
-        * @TVOUT_...@ codes.
-        */
+    /* The test case concluded with the given @outcome@ (one of the
+     * @TVOUT_...@ codes.
+     */
 
   void (*bbench)(struct tvec_output */*o*/,
                 const char */*ident*/, unsigned /*unit*/);
-       /* Begin a benchmark.  The @ident@ is a formatted string identifying
-        * the benchmark based on the values of the input registered marked
-        * @TVRF_ID@; the output driver is free to use this or come up with
-        * its own way to identify the test, e.g., by inspecting the register
-        * values for itself.  The @unit@ is one of the @TVBU_...@ constants
-        * explaining what sort of thing is being measured.
-        */
+    /* Begin a benchmark.  The @ident@ is a formatted string identifying the
+     * benchmark based on the values of the input registered marked
+     * @TVRF_ID@; the output driver is free to use this or come up with its
+     * own way to identify the test, e.g., by inspecting the register values
+     * for itself.  The @unit@ is one of the @TVBU_...@ constants explaining
+     * what sort of thing is being measured.
+     */
 
   void (*ebench)(struct tvec_output */*o*/,
                 const char */*ident*/, unsigned /*unit*/,
                 const struct bench_timing */*tm*/);
-       /* End a benchmark.  The @ident@ and @unit@ arguments are 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.
-        */
-
-  void (*error)(struct tvec_output */*o*/,
-               const char */*msg*/, va_list */*ap*/);
-       /* Report an error.  The driver should ideally report the filename
-        * (@infile@) and line number (@lno@) prompting the error.
-        */
-
-  void (*notice)(struct tvec_output */*o*/,
-                const char */*msg*/, va_list */*ap*/);
-       /* Report a miscellaneous message.  The driver should ideally report
-        * the filename (@infile@) and line number (@lno@) prompting the
-        * error.
-        */
-
-  void (*destroy)(struct tvec_output */*o*/);
-       /* Release any resources acquired by the driver. */
-};
-
-/*----- Test descriptions -------------------------------------------------*/
-
-typedef void tvec_testfn(const struct tvec_reg */*in*/,
-                        struct tvec_reg */*out*/,
-                        void */*ctx*/);
-  /* A test function.  It should read inputs from @in@ and write outputs to
-   * @out@.  The @TVRF_LIVE@ is set on inputs which are actually present, and
-   * on outputs which are wanted to test.  A test function can set additional
-   * `gratuitous outputs' by setting @TVRF_LIVE@ on them; clearing
-   * @TVRF_LIVE@ on a wanted output causes a mismatch.
-   *
-   * A test function may be called zero or more times by the environment.  In
-   * particular, it may be called multiple times, though usually by prior
-   * arrangement with the environment.
-   *
-   * The @ctx@ is supplied by the environment's @run@ function (see below).
-   * The default environment calls the test function once, with a null
-   * @ctx@.  There is no expectation that the environment's context has
-   * anything to do with the test function's context.
-   */
-
-struct tvec_env {
-  /* A test environment sets things up for and arranges to run the test.
-   *
-   * The caller is responsible for allocating storage for the environment's
-   * context, based on the @ctxsz@ slot, and freeing it later; this space is
-   * passed in as the @ctx@ parameter to the remaining functions; if @ctxsz@
-   * is zero then @ctx@ is null.
-   */
-
-  size_t ctxsz;                              /* environment context size */
-
-  int (*setup)(struct tvec_state */*tv*/, const struct tvec_env */*env*/,
-              void */*pctx*/, void */*ctx*/);
-    /* Initialize the context; called at the start of a test group; @pctx@ is
-     * null for environments called by the core, but may be non-null for
-     * subordinate environments.  Return zero on success, or @-1@ on failure.
-     * If setup fails, the context is freed, and the test group is skipped.
+    /* End a benchmark.  The @ident@ and @unit@ arguments are 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.
      */
 
-  int (*set)(struct tvec_state */*tv*/, const char */*var*/,
-            const struct tvec_env */*env*/, void */*ctx*/);
-    /* Called when the parser finds a %|@var|%' setting to parse and store
-     * the value.  If @setup@ failed, this is still called (so as to skip the
-     * value), but @ctx@ is null.
-     */
-
-  int (*before)(struct tvec_state */*tv*/, void */*ctx*/);
-    /* Called prior to running a test.  This is the right place to act on any
-     * `%|@var|%' settings.  Return zero on success or @-1@ on failure (which
-     * causes the test to be skipped).  This function is never called if the
-     * test group is skipped.
-     */
-
-  void (*run)(struct tvec_state */*tv*/, tvec_testfn */*fn*/, void */*ctx*/);
-    /* Run the test.  It should either call @tvec_skip@, or run @fn@ one or
-     * more times.  In the latter case, it is responsible for checking the
-     * outputs, and calling @tvec_fail@ as necessary; @tvec_checkregs@ will
-     * check the register values against the supplied test vector, while
-     * @tvec_check@ does pretty much everything necessary.  This function is
-     * never called if the test group is skipped.
-     */
-
-  void (*after)(struct tvec_state */*tv*/, void */*ctx*/);
-    /* Called after running or skipping a test.  Typical actions involve
-     * resetting whatever things were established by @set@.  This function is
-     * never called if the test group is skipped.
+  void (*report)(struct tvec_output */*o*/, unsigned /*level*/,
+                const char */*msg*/, va_list */*ap*/);
+    /* Report a message.  The driver should ideally report the filename
+     * (@infile@) and line number (@lno@) prompting the error.
      */
 
-  void (*teardown)(struct tvec_state */*tv*/, void */*ctx*/);
-    /* Tear down the environment: called at the end of a test group.  If the
-     * setup failed, then this function is still called, with a null @ctx@.
-     */
+  void (*destroy)(struct tvec_output */*o*/);
+    /* Release any resources acquired by the driver. */
 };
 
-struct tvec_test {
-  /* A test description. */
-
-  const char *name;                    /* name of the test */
-  const struct tvec_regdef *regs;      /* descriptions of the registers */
-  const struct tvec_env *env;          /* environment to run test in */
-  tvec_testfn *fn;                     /* test function */
-};
-#define TVEC_ENDTESTS { 0, 0, 0, 0 }
+#define TVEC_LEVELS(_)                                                 \
+       _(NOTE, "notice", 4)                                            \
+       _(ERR, "ERROR", 8)
 
 enum {
-  /* Register output dispositions. */
-
-  TVRD_INPUT,                          /* input-only register */
-  TVRD_OUTPUT,                         /* output-only (input is dead) */
-  TVRD_MATCH,                          /* matching (equal) registers */
-  TVRD_FOUND,                          /* mismatching output register */
-  TVRD_EXPECT                          /* mismatching input register */
-};
-
-/*----- Register types ----------------------------------------------------*/
-
-struct tvec_regty {
-  /* A register type. */
-
-  void (*init)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/);
-       /* Initialize the value in @*rv@.  This will be called before any
-        * other function acting on the value, including @release@.
-        */
-
-  void (*release)(union tvec_regval */*rv*/,
-                 const struct tvec_regdef */*rd*/);
-       /* Release any resources associated with the value in @*rv@. */
-
-  int (*eq)(const union tvec_regval */*rv0*/,
-           const union tvec_regval */*rv1*/,
-           const struct tvec_regdef */*rd*/);
-       /* Return nonzero if @*rv0@ and @*rv1@ are equal values.
-        * Asymmetric criteria are permitted: @tvec_checkregs@ calls @eq@
-        * with the input register as @rv0@ and the output as @rv1@.
-        */
-
-  int (*tobuf)(buf */*b*/, const union tvec_regval */*rv*/,
-              const struct tvec_regdef */*rd*/);
-       /* Serialize the value @*rv@, writing the result to @b@.  Return
-        * zero on success, or @-1@ on error.
-        */
-
-  int (*frombuf)(buf */*b*/, union tvec_regval */*rv*/,
-                const struct tvec_regdef */*rd*/);
-       /* Deserialize a value from @b@, storing it in @*rv@.  Return zero on
-        * success, or @-1@ on error.
-        */
-
-  int (*parse)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/,
-              struct tvec_state */*tv*/);
-       /* Parse a value from @tv->fp@, storing it in @*rv@.  Return zero on
-        * success, or @-1@ on error, having reported one or more errors via
-        * @tvec_error@ or @tvec_syntax@.  A successful return should leave
-        * the input position at the start of the next line; the caller will
-        * flush the remainder of the line itself.
-        */
-
-  void (*dump)(const union tvec_regval */*rv*/,
-              const struct tvec_regdef */*rd*/,
-              unsigned /*style*/,
-              const struct gprintf_ops */*gops*/, void */*go*/);
-#define TVSF_COMPACT 1u
-       /* Write a human-readable representation of the value @*rv@ using
-        * @gprintf@ on @gops@ and @go@.  The @style@ is a collection of
-        * flags: if @TVSF_COMPACT@ is set, then output should be minimal,
-        * and must fit on a single line; otherwise, output may consist of
-        * multiple lines and may contain redundant information if that is
-        * likely to be useful to a human reader.
-        */
+#define TVEC_DEFLEVEL(tag, name, val) TVLEV_##tag = val,
+  TVEC_LEVELS(TVEC_DEFLEVEL)
+#undef TVEC_DEFLEVEL
+  TVLEV_LIMIT
 };
 
 /*----- Session lifecycle -------------------------------------------------*/
 
-/* Here's the overall flow for a testing session.
- *
- * @tvec_begin@
- *                     -> output @bsession@
- * @tvec_read@
- *                     -> output @bgroup@
- *                     -> env @setup@
- *   one or more tests
- *                     -> type @init@ (input and output)
- *                     -> type @parse@ (input)
- *                     -> output @btest@
- *                     -> env @before@
- *                     -> env @run@
- *                             -> @tvec_skip@
- *                                     -> output @skip@
- *                             -> test @fn@
- *                             -> @tvec_checkregs@
- *                                     -> type @eq@
- *                             -> @tvec_fail@
- *                                     -> output @fail@
- *                             -> @tvec_mismatch@
- *                                     -> output @dumpreg@
- *                                             -> type @dump@
- *                     -> env @after@
- *                     -> output @etest@
- *   or
- *                     -> output @skipgroup@
- *   finally
- *                     -> output @egroup@
- *                     -> env @teardown@
- *
- * @tvec_adhoc@
- *   @tvec_begingroup@
- *                     -> output @bgroup@
- *                     -> env @setup@
- *     @tvec_begintest@
- *                     -> output @btest@
- *     @tvec_skip@
- *                     -> output @skip@
- *     @tvec_claimeq@
- *                     -> @tvec_fail@
- *                             -> output @fail@
- *                     -> @tvec_mismatch@
- *                             -> output @dumpreg@
- *                             -> type @dump@
- *     @tvec_endtest@
- *                     -> output @etest@
- *     or @tvec_skipgroup@
- *                     -> output @skipgroup@
- * @tvec_endgroup@
- *                     -> output @egroup@
- *
- * @tvec_end@
- *                     -> output @esession@
- *                     -> output @destroy@
- *
- * @tvec_benchrun@
- *                     -> type @dump@ (compact style)
- *                     -> output @bbench@
- *                     -> subenv @run@
- *                             -> test @fn@
- *                     -> output @ebench@
- *                             -> @tvec_benchreport@
- *
- * The output functions @error@ and @notice@ can be called at arbitrary
- * times.
- */
-
 /* --- @tvec_begin@ --- *
  *
  * Arguments:  @struct tvec_state *tv_out@ = state structure to fill in
@@ -620,7 +667,7 @@ extern int tvec_end(struct tvec_state */*tv*/);
  *             @const char *infile@ = the name of the input file
  *             @FILE *fp@ = stream to read from
  *
- * Returns:    Zero on success, @-1@ on error.
+ * Returns:    Zero on success, %$-1$% on error.
  *
  * Use:                Read test vector data from @fp@ and exercise test functions.
  *             THe return code doesn't indicate test failures: it's only
@@ -634,9 +681,9 @@ extern int tvec_read(struct tvec_state */*tv*/,
 /*----- Command-line interface --------------------------------------------*/
 
 extern const struct tvec_config tvec_adhocconfig;
-/* A special @struct tvec_config@ to use for programs which perform ad-hoc
- * testing.
- */
+  /* A special @struct tvec_config@ to use for programs which perform ad-hoc
  * testing.
  */
 
 /* --- @tvec_parseargs@ --- *
  *
@@ -664,7 +711,7 @@ extern void tvec_parseargs(int /*argc*/, char */*argv*/[],
  *             @const char *file@ = pathname of file to read
  *             @const char *arg@ = argument to interpret
  *
- * Returns:    Zero on success, @-1@ on error.
+ * Returns:    Zero on success, %$-1$% on error.
  *
  * Use:                Read test vector data from stdin or a named file.  The
  *             @tvec_readarg@ function reads from stdin if @arg@ is `%|-|%',
@@ -680,7 +727,7 @@ extern int tvec_readarg(struct tvec_state */*tv*/, const char */*arg*/);
  * Arguments:  @struct tvec_state *tv@ = test vector state
  *             @const char *dflt@ = defsault filename or null
  *
- * Returns:    Zero on success, @-1@ on error.
+ * Returns:    Zero on success, %$-1$% on error.
  *
  * Use:                Reads from the default test vector data.  If @file@ is null,
  *             then read from standard input, unless that's a terminal; if
@@ -699,7 +746,7 @@ extern int tvec_readdflt(struct tvec_state */*tv*/, const char */*file*/);
  *             @int *argpos_inout@ = current argument position (updated)
  *             @const char *dflt@ = default filename or null
  *
- * Returns:    Zero on success, @-1@ on error.
+ * Returns:    Zero on success, %$-1$% on error.
  *
  * Use:                Reads from the sources indicated by the command-line
  *             arguments, in order, interpreting each as for @tvec_readarg@;
@@ -740,63 +787,32 @@ extern int tvec_main(int /*argc*/, char */*argv*/[],
  * Returns:    ---
  *
  * Use:                Skip the current group.  This should only be called from a
- *             test environment @setup@ function; a similar effect occurs if
- *             the @setup@ function fails.
- */
-
-extern void PRINTF_LIKE(2, 3)
-  tvec_skipgroup(struct tvec_state */*tv*/, const char */*excuse*/, ...);
-extern void tvec_skipgroup_v(struct tvec_state */*tv*/,
-                            const char */*excuse*/, va_list */*ap*/);
-
-/* --- @tvec_skip@, @tvec_skip_v@ --- *
- *
- * Arguments:  @struct tvec_state *tv@ = test-vector state
- *             @const char *excuse@, @va_list *ap@ = reason why test skipped
- *
- * Returns:    ---
- *
- * Use:                Skip the current test.  This should only be called from a
- *             test environment @run@ function; a similar effect occurs if
- *             the @before@ function fails.
- */
-
-extern void PRINTF_LIKE(2, 3)
-  tvec_skip(struct tvec_state */*tv*/, const char */*excuse*/, ...);
-extern void tvec_skip_v(struct tvec_state */*tv*/,
-                       const char */*excuse*/, va_list */*ap*/);
-
-/* --- @tvec_resetoutputs@ --- *
- *
- * Arguments:  @struct tvec_state *tv@ = test-vector state
- *
- * Returns:    ---
- *
- * Use:                Reset (releases and reinitializes) the output registers in
- *             the test state.  This is mostly of use to test environment
- *             @run@ functions, between invocations of the test function.
+ *             test environment @setup@ function; a similar effect occurs if
+ *             the @setup@ function fails.
  */
 
-extern void tvec_resetoutputs(struct tvec_state */*tv*/);
+extern PRINTF_LIKE(2, 3)
+  void tvec_skipgroup(struct tvec_state */*tv*/,
+                     const char */*excuse*/, ...);
+extern void tvec_skipgroup_v(struct tvec_state */*tv*/,
+                            const char */*excuse*/, va_list */*ap*/);
 
-/* --- @tvec_checkregs@ --- *
+/* --- @tvec_skip@, @tvec_skip_v@ --- *
  *
  * Arguments:  @struct tvec_state *tv@ = test-vector state
+ *             @const char *excuse@, @va_list *ap@ = reason why test skipped
  *
- * Returns:    Zero on success, @-1@ on mismatch.
- *
- * Use:                Compare the active output registers (according to the current
- *             test group definition) with the corresponding input register
- *             values.  A mismatch occurs if the two values differ
- *             (according to the register type's @eq@ method), or if the
- *             input is live but the output is dead.
+ * Returns:    ---
  *
- *             This function only checks for a mismatch and returns the
- *             result; it takes no other action.  In particular, it doesn't
- *             report a failure, or dump register values.
+ * Use:                Skip the current test.  This should only be called from a
+ *             test environment @run@ function; a similar effect occurs if
+ *             the @before@ function fails.
  */
 
-extern int tvec_checkregs(struct tvec_state */*tv*/);
+extern PRINTF_LIKE(2, 3)
+  void tvec_skip(struct tvec_state */*tv*/, const char */*excuse*/, ...);
+extern void tvec_skip_v(struct tvec_state */*tv*/,
+                       const char */*excuse*/, va_list */*ap*/);
 
 /* --- @tvec_fail@, @tvec_fail_v@ --- *
  *
@@ -815,8 +831,8 @@ extern int tvec_checkregs(struct tvec_state */*tv*/);
  *             safely be left null if the test function is run only once.
  */
 
-extern void PRINTF_LIKE(2, 3)
-  tvec_fail(struct tvec_state */*tv*/, const char */*detail*/, ...);
+extern PRINTF_LIKE(2, 3)
+  void tvec_fail(struct tvec_state */*tv*/, const char */*detail*/, ...);
 extern void tvec_fail_v(struct tvec_state */*tv*/,
                        const char */*detail*/, va_list */*ap*/);
 
@@ -824,7 +840,7 @@ extern void tvec_fail_v(struct tvec_state */*tv*/,
  *
  * Arguments:  @struct tvec_state *tv@ = test-vector state
  *             @unsigned disp@ = the register disposition (@TVRD_...@)
- *             @const union tvec_regval *tv@ = register value
+ *             @const union tvec_regval *tv@ = register value, or null
  *             @const struct tvec_regdef *rd@ = register definition
  *
  * Returns:    ---
@@ -842,6 +858,55 @@ extern void tvec_dumpreg(struct tvec_state */*tv*/,
                         unsigned /*disp*/, const union tvec_regval */*rv*/,
                         const struct tvec_regdef */*rd*/);
 
+/* --- @tvec_initregs@, @tvec_releaseregs@ --- *
+ *
+ * Arguments:  @struct tvec_state *tv@ = test-vector state
+ *
+ * Returns:    ---
+ *
+ * Use:                Initialize or release, respectively, the registers required
+ *             by the current test.  All of the registers, both input and
+ *             output, are effected.  Initialized registers are not marked
+ *             live.
+ */
+
+extern void tvec_initregs(struct tvec_state */*tv*/);
+extern void tvec_releaseregs(struct tvec_state */*tv*/);
+
+/* --- @tvec_resetoutputs@ --- *
+ *
+ * Arguments:  @struct tvec_state *tv@ = test-vector state
+ *
+ * Returns:    ---
+ *
+ * Use:                Reset (releases and reinitializes) the output registers in
+ *             the test state.  This is mostly of use to test environment
+ *             @run@ functions, between invocations of the test function.
+ *             Output registers are marked live if and only if the
+ *             corresponding input register is live.
+ */
+
+extern void tvec_resetoutputs(struct tvec_state */*tv*/);
+
+/* --- @tvec_checkregs@ --- *
+ *
+ * Arguments:  @struct tvec_state *tv@ = test-vector state
+ *
+ * Returns:    Zero on success, %$-1$% on mismatch.
+ *
+ * Use:                Compare the active output registers (according to the current
+ *             test group definition) with the corresponding input register
+ *             values.  A mismatch occurs if the two values differ
+ *             (according to the register type's @eq@ method), or if the
+ *             input is live but the output is dead.
+ *
+ *             This function only checks for a mismatch and returns the
+ *             result; it takes no other action.  In particular, it doesn't
+ *             report a failure, or dump register values.
+ */
+
+extern int tvec_checkregs(struct tvec_state */*tv*/);
+
 /* --- @tvec_mismatch@ --- *
  *
  * Arguments:  @struct tvec_state *tv@ = test-vector state
@@ -873,8 +938,8 @@ extern void tvec_mismatch(struct tvec_state */*tv*/, unsigned /*f*/);
  *             obvious way.
  */
 
-extern void PRINTF_LIKE(2, 3)
-  tvec_check(struct tvec_state */*tv*/, const char */*detail*/, ...);
+extern PRINTF_LIKE(2, 3)
+  void tvec_check(struct tvec_state */*tv*/, const char */*detail*/, ...);
 extern void tvec_check_v(struct tvec_state */*tv*/,
                         const char */*detail*/, va_list */*ap*/);
 
@@ -971,13 +1036,13 @@ extern void tvec_begintest(struct tvec_state */*tv*/,
 #define TVEC_BEGINTEST(tv)                                             \
        do tvec_begintest(tv, __FILE__, __LINE__); while (0)
 
-/* --- *tvec_endtest@ --- *
+/* --- @tvec_endtest@ --- *
  *
  * Arguments:  @struct tvec_state *tv@ = test-vector state
  *
  * Returns:    ---
  *
- * Use:                End a ad-hoc test case,  The statistics are updated and the
+ * Use:                End an ad-hoc test case,  The statistics are updated and the
  *             outcome is reported to the output formatter.
  */
 
@@ -1030,10 +1095,10 @@ extern void tvec_endtest(struct tvec_state */*tv*/);
  *             the failure message.
  */
 
-extern int PRINTF_LIKE(5, 6)
-  tvec_claim(struct tvec_state */*tv*/, int /*ok*/,
-            const char */*file*/, unsigned /*lno*/,
-            const char */*msg*/, ...);
+extern PRINTF_LIKE(5, 6)
+  int tvec_claim(struct tvec_state */*tv*/, int /*ok*/,
+                const char */*file*/, unsigned /*lno*/,
+                const char */*msg*/, ...);
 extern int tvec_claim_v(struct tvec_state */*tv*/, int /*ok*/,
                        const char */*file*/, unsigned /*lno*/,
                        const char */*msg*/, va_list */*ap*/);
@@ -1071,185 +1136,350 @@ extern int tvec_claimeq(struct tvec_state */*tv*/,
 
 /*----- Benchmarking ------------------------------------------------------*/
 
-struct tvec_bench {
+struct tvec_benchenv {
   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 */
 };
-#define TVEC_BENCHENV                                                  \
-  { sizeof(struct tvec_benchctx),                                      \
-    tvec_benchsetup,                                                   \
-    tvec_benchset,                                                     \
-    tvec_benchbefore,                                                  \
-    tvec_benchrun,                                                     \
-    tvec_benchafter,                                                   \
-    tvec_benchteardown }
-#define TVEC_BENCHINIT TVEC_BENCHENV, &tvec_benchstate
 
 struct tvec_benchctx {
-  const struct tvec_bench *b;
-  struct bench_state *bst;
-  double dflt_target;
-  void *subctx;
+  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;                                /* subsidiary environment context */
 };
 
 extern struct bench_state *tvec_benchstate;
 
-/* --- @tvec_benchsetup@ --- *
- *
- * Arguments:  @struct tvec_state *tv@ = test vector state
- *             @const struct tvec_env *env@ = environment description
- *             @void *pctx@ = parent context (ignored)
- *             @void *ctx@ = context pointer to initialize
+/* --- Environment implementation --- *
  *
- * Returns:    Zero on success, @-1@ on failure.
+ * The following special variables are supported.
  *
- * Use:                Initialize a benchmarking environment context.
+ *   * %|@target|% is the (approximate) number of seconds to run the
+ *     benchmark.
  *
- *             The environment description must really be a @struct
- *             tvec_bench@.  If the @bst@ slot is null, then a temporary
- *             benchmark state is allocated for the current test group and
- *             released at the end.  Otherwise, it must be the address of a
- *             pointer to a benchmark state: if the pointer is null, then a
- *             fresh state is allocated and initialized and the pointer is
- *             updated; otherwise, the pointer is assumed to refer to an
- *             existing valid benchmark state.
+ * Unrecognized variables are passed to the subordinate environment, if there
+ * is one.  Other events are passed through to the subsidiary environment.
  */
 
-extern int tvec_benchsetup(struct tvec_state */*tv*/,
-                          const struct tvec_env */*env*/,
-                          void */*pctx*/, void */*ctx*/);
+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;
 
-/* --- @tvec_benchset@ --- *
- *
- * Arguments:  @struct tvec_state *tv@ = test vector state
- *             @const char *var@ = variable name to set
- *             @const struct tvec_env *env@ = environment description
- *             @void *ctx@ = context pointer
- *
- * Returns:    Zero on success, @-1@ on failure.
+#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
+
+/* --- @tvec_benchreport@ --- *
  *
- * Use:                Set a special variable.  The following special variables are
- *             supported.
+ * Arguments:  @const struct gprintf_ops *gops@ = print operations
+ *             @void *go@ = print destination
+ *             @unsigned unit@ = the unit being measured (~TVBU_...@)
+ *             @const struct bench_timing *tm@ = the benchmark result
  *
- *               * %|@target|% is the (approximate) number of seconds to run
- *                 the benchmark.
+ * Returns:    ---
  *
- *             Unrecognized variables are passed to the subordinate
- *             environment, if there is one.
+ * Use:                Formats a report about the benchmark performance.  This
+ *             function is intended to be called on by an output
+ *             @ebench@ function.
  */
 
-extern int tvec_benchset(struct tvec_state */*tv*/, const char */*var*/,
-                        const struct tvec_env */*env*/, void */*ctx*/);
+extern void tvec_benchreport
+  (const struct gprintf_ops */*gops*/, void */*go*/,
+   unsigned /*unit*/, const struct bench_timing */*tm*/);
 
-/* --- @tvec_benchbefore@ --- *
- *
- * Arguments:  @struct tvec_state *tv@ = test vector state
- *             @void *ctx@ = context pointer
- *
- * Returns:    Zero on success, @-1@ on failure.
- *
- * Use:                Invoke the subordinate environment's @before@ function to
- *             prepare for the benchmark.
- */
+/*----- Remote execution --------------------------------------------------*/
 
-extern int tvec_benchbefore(struct tvec_state */*tv*/, void */*ctx*/);
+struct tvec_remotecomms {
+  int infd, outfd;                     /* input and output descriptors */
+  dbuf bout;                           /* output buffer */
+  unsigned char *bin;                  /* input buffer */
+  size_t binoff, binlen, binsz;                /* input offset, length, and size */
+  size_t t;                            /* temporary offset */
+  unsigned f;                          /* flags */
+#define TVRF_BROKEN 0x0001u            /*   communications have failed */
+};
+#define TVEC_REMOTECOMMS_INIT { -1, -1, DBUF_INIT, 0, 0, 0, 0, 0, 0 }
+
+struct tvec_remotectx {
+  struct tvec_state *tv;               /* test vector state */
+  struct tvec_remotecomms rc;          /* communication state */
+  const struct tvec_remoteenv *re;     /* environment configuration */
+  void *subctx;                                /* subenvironment context */
+  struct tvec_vardef vd;               /* temporary variable definition */
+  unsigned ver;                                /* protocol version */
+  pid_t kid;                           /* child process id */
+  int errfd;                           /* child stderr descriptor */
+  lbuf errbuf;                         /* child stderr line buffer */
+  dstr prgwant, progress;              /* progress: wanted/reported */
+  unsigned exwant, exit;               /* exit status wanted/reported */
+#define TVRF_RCNMASK 0x0300u           /*   reconnection behaviour: */
+#define TVRCN_DEMAND 0x0000u           /*     connect on demand */
+#define TVRCN_SKIP 0x0100u             /*     skip unless connected */
+#define TVRCN_FORCE 0x0200u            /*     force reconnection */
+#define TVRF_MUFFLE 0x0400u            /*   muffle child stderr */
+#define TVRF_SETEXIT 0x0800u           /*   set `@exit' */
+#define TVRF_SETPRG 0x1000u            /*   set `@progress' */
+#define TVRF_SETRCN 0x2000u            /*   set `@reconnect' */
+#define TVRF_SETMASK (TVRF_SETEXIT | TVRF_SETPRG | TVRF_SETRCN)
+                                       /*   mask of @TVTF_SET...@ */
+};
 
-/* --- @tvec_benchrun@ --- *
- *
- * Arguments:  @struct tvec_state *tv@ = test vector state
- *             @tvec_testfn *fn@ = test function to run
- *             @void *ctx@ = context pointer for the test function
+typedef int tvec_connectfn(pid_t */*kid_out*/, int */*infd_out*/,
+                          int */*outfd_out*/, int */*errfd_out*/,
+                          struct tvec_state */*tv*/,
+                          const struct tvec_remoteenv */*env*/);
+  /* A connection function.  On entry, @tv@ holds the test-vector state, and
+   * @env@ is the test group's remote environment structure, which will
+   * typically really be some subclass of @struct tvec_remoteenv@ containing
+   * additional parameters for establishing the child process.
+   *
+   * On successful completion, the function stores input and output
+   * descriptors (which need not be distinct) in @*infd_out@ and
+   * @*outfd_out@, and returns zero; if it creates a child process, it should
+   * additionally store the child's process-id in @*kid_out@ and store in
+   * @*errfd_out@ a descriptor from which the child's error output can be
+   * read.  On error, the function should report an appropriate message via
+   * @tvec_error@ and return %$-1$%.
+   */
+
+struct tvec_remoteenv_slots {
+  tvec_connectfn *connect;             /* connection function */
+  const struct tvec_env *env;          /* subsidiary environment */
+  unsigned dflt_reconn;                        /* default reconnection */
+};
+
+struct tvec_remoteenv {
+  struct tvec_env _env;
+  struct tvec_remoteenv_slots r;
+};
+
+struct tvec_remotefork_slots {
+  const struct tvec_test *tests;       /* child tests (or null) */
+};
+
+struct tvec_remotefork {
+  struct tvec_env _env;
+  struct tvec_remoteenv_slots r;
+  struct tvec_remotefork_slots f;
+};
+
+struct tvec_remoteexec_slots {
+  const char *const *args;             /* command line to execute */
+};
+
+struct tvec_remoteexec {
+  struct tvec_env _env;
+  struct tvec_remoteenv_slots r;
+  struct tvec_remoteexec_slots x;
+};
+
+union tvec_remoteenv_subclass_kludge {
+  struct tvec_env _env;
+  struct tvec_remoteenv renv;
+  struct tvec_remotefork fork;
+  struct tvec_remoteexec exec;
+};
+
+/* Exit status.
+ *
+ * We don't use the conventional encoding returned by the @wait@(2) family of
+ * system calls because it's too hard for our flags type to decode.  Instead,
+ * we use our own encoding.
+ *
+ * The exit code or signal number ends up in the `value' field in the low 12
+ * bits; bit 12 is set if the value field holds a signal, and it if holds an
+ * exit code.  Bits 13--15 hold a code which describes the status of a child
+ * process or connection.
+ */
+#define TVXF_VALMASK 0x0fffu           /* value (exit code or signal) */
+#define TVXF_SIG 0x1000u               /* value is signal, not exit code */
+#define TVXF_CAUSEMASK 0xe000u         /* mask for cause bits */
+#define TVXST_RUN 0x0000u              /*   still running */
+#define TVXST_EXIT 0x2000u             /*   child exited */
+#define TVXST_KILL 0x4000u             /*   child killed by signal */
+#define TVXST_CONT 0x6000u             /*   child continued (?) */
+#define TVXST_STOP 0x8000u             /*   child stopped (?) */
+#define TVXST_DISCONN 0xa000u          /*   disconnected */
+#define TVXST_UNK 0xc000u              /*   unknown */
+#define TVXST_ERR 0xe000u            /*   local error prevented diagnosis */
+
+/* Remote environment. */
+extern tvec_envsetupfn tvec_remotesetup;
+extern tvec_envfindvarfn tvec_remotefindvar;
+extern tvec_envbeforefn tvec_remotebefore;
+extern tvec_envrunfn tvec_remoterun;
+extern tvec_envafterfn tvec_remoteafter;
+extern tvec_envteardownfn tvec_remoteteardown;
+#define TVEC_REMOTEENV                                                 \
+  { sizeof(struct tvec_remotectx),                                     \
+    tvec_remotesetup,                                                  \
+    tvec_remotefindvar,                                                        \
+    tvec_remotebefore,                                                 \
+    tvec_remoterun,                                                    \
+    tvec_remoteafter,                                                  \
+    tvec_remoteteardown }
+
+/* --- @tvec_setprogress@, @tvec_setprogress_v@ --- *
+ *
+ * Arguments:  @const char *status@ = progress status token format
+ *             @va_list ap@ = argument tail
  *
  * Returns:    ---
  *
- * Use:                Measures and reports the performance of a test function.
+ * Use:                Reports the progress of a test execution to the client.
  *
+ *             The framework makes use of tokens beginning with %|%|%:
  *
- */
-
-extern void tvec_benchrun(struct tvec_state */*tv*/,
-                         tvec_testfn */*fn*/, void */*ctx*/);
-
-/* --- @tvec_benchafter@ --- *
+ *               * %|%IDLE|%: during the top-level server code;
  *
- * Arguments:  @struct tvec_state *tv@ = test vector state
- *             @void *ctx@ = context pointer
+ *               * %|%SETUP|%: during the enclosing environment's @before@
+ *                 function;
  *
- * Returns:    ---
+ *               * %|%RUN|%: during the environment's @run@ function, or the
+ *                 test function; and
+ *
+ *               * %|%DONE|%: during the enclosing environment's @after@
+ *                 function.
  *
- * Use:                Invoke the subordinate environment's @after@ function to
- *             clean up after the benchmark.
+ *             The intent is that a test can use the progress token to check
+ *             that a function which is expected to crash does so at the
+ *             correct point, so it's expected that more complex test
+ *             functions and/or environments will set their own progress
+ *             tokens to reflect what's going on.
  */
 
-extern void tvec_benchafter(struct tvec_state */*tv*/, void */*ctx*/);
+extern PRINTF_LIKE(1, 2) int tvec_setprogress(const char */*status*/, ...);
+extern int tvec_setprogress_v(const char */*status*/, va_list */*ap*/);
 
-/* --- @tvec_benchteardown@ --- *
+/* --- @tvec_remoteserver@ --- *
  *
- * Arguments:  @struct tvec_state *tv@ = test vector state
- *             @void *ctx@ = context pointer
+ * Arguments:  @int infd@, @int outfd@ = input and output file descriptors
+ *             @const struct tvec_config *config@ = test configuration
  *
- * Returns:    ---
+ * Returns:    Suggested exit code.
+ *
+ * Use:                Run a test server, reading packets from @infd@ and writing
+ *             responses and notifications to @outfd@, and invoking tests as
+ *             described by @config@.
  *
- * Use:                Tear down the benchmark environment.
+ *             This function is not particularly general purpose.  It
+ *             expects to `take over' the process, and makes use of private
+ *             global variables.
  */
 
-extern void tvec_benchteardown(struct tvec_state */*tv*/, void */*ctx*/);
+extern int tvec_remoteserver(int /*infd*/, int /*outfd*/,
+                            const struct tvec_config */*config*/);
 
-/* --- @tvec_benchreport@ --- *
+extern tvec_connectfn tvec_fork, tvec_exec;
+
+#define TVEC_REMOTEFORK(subenv, tests)                                 \
+       TVEC_REMOTEENV, { tvec_fork, subenv }, { tests }
+
+#define TVEC_REMOTEEXEC(subenv, args)                                  \
+       TVEC_REMOTEENV, { tvec_exec, subenv }, { args }
+
+/*----- Timeouts ----------------------------------------------------------*/
+
+struct tvec_timeoutenv {
+  struct tvec_env _env;
+  int timer;                   /* the timer (@ITIMER_...@) */
+  double t;                            /* time to wait (in seconds) */
+  const struct tvec_env *env;          /* subsidiary environment */
+};
+
+struct tvec_timeoutctx {
+  const struct tvec_timeoutenv *te;    /* saved environment description */
+  int timer;                           /* timer code (as overridden) */
+  double t;                            /* time to wait (as overridden) */
+  unsigned f;                          /* flags */
+#define TVTF_SETTMO 1u                 /*   set `@timeout' */
+#define TVTF_SETTMR 2u                 /*   set `@timer' */
+#define TVTF_SETMASK (TVTF_SETTMO | TVTF_SETTMR)
+                                       /*   mask of @TVTF_SET...@ */
+  void *subctx;
+};
+
+extern tvec_envsetupfn tvec_timeoutsetup;
+extern tvec_envfindvarfn tvec_timeoutfindvar;
+extern tvec_envbeforefn tvec_timeoutbefore;
+extern tvec_envrunfn tvec_timeoutrun;
+extern tvec_envafterfn tvec_timeoutafter;
+extern tvec_envteardownfn tvec_timeoutteardown;
+#define TVEC_TIMEOUTENV                                                        \
+       { sizeof(struct tvec_timeoutctx),                               \
+         tvec_timeoutsetup,                                            \
+         tvec_timeoutfindvar,                                          \
+         tvec_timeoutbefore,                                           \
+         tvec_timeoutrun,                                              \
+         tvec_timeoutafter,                                            \
+         tvec_timeoutteardown }
+#define TVEC_TIMEOUTINIT(timer, t) TVEC_TIMEOUTENV, timer, t
+
+/*----- Output functions --------------------------------------------------*/
+
+/* --- @tvec_strlevel@ --- *
  *
- * Arguments:  @const struct gprintf_ops *gops@ = print operations
- *             @void *go@ = print destination
- *             @unsigned unit@ = the unit being measured (~TVBU_...@)
- *             @const struct bench_timing *tm@ = the benchmark result
+ * Arguments:  @unsigned level@ = level code
  *
- * Returns:    ---
+ * Returns:    A human-readable description.
  *
- * Use:                Formats a report about the benchmark performance.  This
- *             function is intended to be called on by an output
- *             @ebench@ function.
+ * Use:                Converts a level code into something that you can print in a
+ *             message.
  */
 
-extern void tvec_benchreport
-  (const struct gprintf_ops */*gops*/, void */*go*/,
-   unsigned /*unit*/, const struct bench_timing */*tm*/);
-
-/*----- Output functions --------------------------------------------------*/
+extern  const char *tvec_strlevel(unsigned /*level*/);
 
-/* --- @tvec_error@, @tvec_error_v@ --- *
+/* --- @tvec_report@, @tvec_report_v@ --- *
  *
  * Arguments:  @struct tvec_state *tv@ = test-vector state
  *             @const char *msg@, @va_list ap@ = error message
  *
- * Returns:    @-1@.
+ * Returns:    ---
  *
- * Use:                Report an error.  Errors are distinct from test failures,
- *             and indicate that a problem was encountered which compromised
- *             the activity of testing.
+ * Use:                Report an message with a given severity.  Messages with level
+ *             @TVLEV_ERR@ or higher force a nonzero exit code.
  */
 
-extern int PRINTF_LIKE(2, 3)
-  tvec_error(struct tvec_state */*tv*/, const char */*msg*/, ...);
-extern int tvec_error_v(struct tvec_state */*tv*/,
-                       const char */*msg*/, va_list */*ap*/);
+extern PRINTF_LIKE(3, 4)
+  void tvec_report(struct tvec_state */*tv*/, unsigned /*level*/,
+                  const char */*msg*/, ...);
+extern void tvec_report_v(struct tvec_state */*tv*/, unsigned /*level*/,
+                         const char */*msg*/, va_list */*ap*/);
 
-/* --- @tvec_notice@, @tvec_notice_v@ --- *
+/* --- @tvec_error@, @tvec_notice@ --- *
  *
  * Arguments:  @struct tvec_state *tv@ = test-vector state
- *             @const char *msg@, @va_list ap@ = message
+ *             @const char *msg@, @va_list ap@ = error message
  *
- * Returns:    ---
+ * Returns:    The @tvec_error@ function returns %$-1$% as a trivial
+ *             convenience; @tvec_notice@ does not return a value.
  *
- * Use:                Output a notice: essentially, some important information
- *             which doesn't fit into any of the existing categories.
+ * Use:                Report an error or a notice.  Errors are distinct from test
+ *             failures, and indicate that a problem was encountered which
+ *             compromised the activity of testing.  Notices are important
+ *             information which doesn't fit into any other obvious
+ *             category.
  */
 
-extern void PRINTF_LIKE(2, 3)
-  tvec_notice(struct tvec_state */*tv*/, const char */*msg*/, ...);
-extern void tvec_notice_v(struct tvec_state */*tv*/,
-                         const char */*msg*/, va_list */*ap*/);
+extern PRINTF_LIKE(2, 3)
+  int tvec_error(struct tvec_state */*tv*/, const char */*msg*/, ...);
+extern PRINTF_LIKE(2, 3)
+  void tvec_notice(struct tvec_state */*tv*/, const char */*msg*/, ...);
 
 /* --- @tvec_humanoutput@ --- *
  *
@@ -1277,16 +1507,16 @@ extern struct tvec_output *tvec_humanoutput(FILE */*fp*/);
  *             (`Test Anything Protocol') format.
  *
  *             TAP comes from the Perl community, but has spread rather
- *             further.  This driver produces TAP version 13.  The driver
- *             produces a TAP `test point' -- i.e., a result reported as
- *             `ok' or `not ok' -- for each input test group.  Failure
- *             reports and register dumps are produced as diagnostic
- *             messages before the final group result.  (TAP permits
- *             structuerd YAML data after the test-point result, which could
- *             be used to report details, but (a) postponing the details
- *             until after the report is inconvenient, and (b) there is no
- *             standardization for the YAML anyway, so in practice it's no
- *             more useful than the unstructured diagnostics.
+ *             further.  This driver produces TAP version 14, but pretends
+ *             to be version 13.  The driver produces a TAP `test point' --
+ *             i.e., a result reported as `ok' or `not ok' -- for each input
+ *             test group.  Failure reports and register dumps are produced
+ *             as diagnostic messages before the final group result.  (TAP
+ *             permits structuerd YAML data after the test-point result,
+ *             which could be used to report details, but (a) postponing the
+ *             details until after the report is inconvenient, and (b) there
+ *             is no standardization for the YAML anyway, so in practice
+ *             it's no more useful than the unstructured diagnostics.
  */
 
 extern struct tvec_output *tvec_tapoutput(FILE */*fp*/);
@@ -1308,6 +1538,23 @@ extern struct tvec_output *tvec_dfltout(FILE */*fp*/);
 
 /*------ Serialization utilities ------------------------------------------*/
 
+/* Serialization format.
+ *
+ * The `candidate register definitions' are those entries @r@ in the @regs@
+ * vector whose index @r.i@ is strictly less than @nr@.  The `selected
+ * register definitions' are those candidate register definitions @r@ for
+ * which the indicated register @rv[r.i]@ has the @TVRF_LIVE@ flag set.  The
+ * serialized output begins with a header bitmap: if there are %$n$%
+ * candidate register definitions then the header bitmap consists of %$\lceil
+ * n/8 \rceil$% bytes.  Bits are ordered starting from the least significant
+ * bit of the first byte, end ending at the most significant bit of the final
+ * byte.  The bit corresponding to a candidate register definition is set if
+ * and only if that register defintion is selected.  The header bitmap is
+ * then followed by the serializations of the selected registers -- i.e., for
+ * each selected register definition @r@, the serialized value of register
+ * @rv[r.i]@ -- simply concatenated together, with no padding or alignment.
+ */
+
 /* --- @tvec_serialize@ --- *
  *
  * Arguments:  @const struct tvec_reg *rv@ = vector of registers
@@ -1318,27 +1565,10 @@ extern struct tvec_output *tvec_dfltout(FILE */*fp*/);
  *             @unsigned nr@ = number of entries in the @rv@ vector
  *             @size_t regsz@ = true size of each element of @rv@
  *
- * Returns:    Zero on success, @-1@ on failure.
+ * Returns:    Zero on success, %$-1$% on failure.
  *
  * Use:                Serialize a collection of register values.
  *
- *             The `candidate register definitions' are those entries @r@ in
- *             the @regs@ vector whose index @r.i@ is strictly less than
- *             @nr@.  The `selected register definitions' are those
- *             candidate register definitions @r@ for which the indicated
- *             register @rv[r.i]@ has the @TVRF_LIVE@ flag set.  The
- *             serialized output begins with a header bitmap: if there are
- *             %$n$% candidate register definitions then the header bitmap
- *             consists of %$\lceil n/8 \rceil$% bytes.  Bits are ordered
- *             starting from the least significant bit of the first byte,
- *             end ending at the most significant bit of the final byte.
- *             The bit corresponding to a candidate register definition is
- *             set if and only if that register defintion is selected.  The
- *             header bitmap is then followed by the serializations of the
- *             selected registers -- i.e., for each selected register
- *             definition @r@, the serialized value of register @rv[r.i]@ --
- *             simply concatenated together, with no padding or alignment.
- *
  *             The serialized output is written to the buffer @b@.  Failure
  *             can be caused by running out of buffer space, or a failing
  *             type handler.
@@ -1358,7 +1588,7 @@ extern int tvec_serialize(const struct tvec_reg */*rv*/, buf */*b*/,
  *             @unsigned nr@ = number of entries in the @rv@ vector
  *             @size_t regsz@ = true size of each element of @rv@
  *
- * Returns:    Zero on success, @-1@ on failure.
+ * Returns:    Zero on success, %$-1$% on failure.
  *
  * Use:                Deserialize a collection of register values.
  *
@@ -1369,10 +1599,7 @@ extern int tvec_serialize(const struct tvec_reg */*rv*/, buf */*b*/,
  *             slot, and set the @TVRF_LIVE@ flag on the register.  See
  *             @tvec_serialize@ for a description of the format.
  *
- *             On successful completion, store the address of the first byte
- *             after the serialized data in @*end_out@ if @end_out@ is not
- *             null.  Failure results only from a failing register type
- *             handler.
+ *             Failure results only from a failing register type handler.
  */
 
 extern int tvec_deserialize(struct tvec_reg */*rv*/, buf */*b*/,
@@ -1396,26 +1623,13 @@ extern int tvec_deserialize(struct tvec_reg */*rv*/, buf */*b*/,
  *     current line number.
  */
 
-/* --- @tvec_skipspc@ --- *
- *
- * Arguments:  @struct tvec_state *tv@ = test-vector state
- *
- * Returns:    ---
- *
- * Use:                Advance over any whitespace characters other than newlines.
- *             This will stop at `;', end-of-file, or any other kind of
- *             non-whitespace; and it won't consume a newline.
- */
-
-extern void tvec_skipspc(struct tvec_state */*tv*/);
-
 /* --- @tvec_syntax@, @tvec_syntax_v@ --- *
  *
  * Arguments:  @struct tvec_state *tv@ = test-vector state
  *             @int ch@ = the character found (in @fgetc@ format)
  *             @const char *expect@, @va_list ap@ = what was expected
  *
- * Returns:    @-1@
+ * Returns:    %$-1$%.
  *
  * Use:                Report a syntax error quoting @ch@ and @expect@.  If @ch@ is
  *             a newline, then back up so that it can be read again (e.g.,
@@ -1423,18 +1637,57 @@ extern void tvec_skipspc(struct tvec_state */*tv*/);
  *             advance the line number).
  */
 
-extern int PRINTF_LIKE(3, 4)
-  tvec_syntax(struct tvec_state */*tv*/, int /*ch*/,
-             const char */*expect*/, ...);
+extern PRINTF_LIKE(3, 4)
+  int tvec_syntax(struct tvec_state */*tv*/, int /*ch*/,
+                 const char */*expect*/, ...);
 extern int tvec_syntax_v(struct tvec_state */*tv*/, int /*ch*/,
                         const char */*expect*/, va_list */*ap*/);
 
+/* --- @tvec_unkreg@ --- *
+ *
+ * Arguments:  @struct tvec_state *tv@ = test-vector state
+ *             @const char *name@ = register or pseudoregister name
+ *
+ * Returns:    %$-1$%.
+ *
+ * Use:                Reports an error that the register or pseudoregister is
+ *             unrecognized.
+ */
+
+extern int tvec_unkreg(struct tvec_state */*tv*/, const char */*name*/);
+
+/* --- @tvec_dupreg@ --- *
+ *
+ * Arguments:  @struct tvec_state *tv@ = test-vector state
+ *             @const char *name@ = register or pseudoregister name
+ *
+ * Returns:    %$-1$%.
+ *
+ * Use:                Reports an error that the register or pseudoregister has been
+ *             assigned already in the current test.
+ */
+
+extern int tvec_dupreg(struct tvec_state */*tv*/, const char */*name*/);
+
+/* --- @tvec_skipspc@ --- *
+ *
+ * Arguments:  @struct tvec_state *tv@ = test-vector state
+ *
+ * Returns:    ---
+ *
+ * Use:                Advance over any whitespace characters other than newlines.
+ *             This will stop at `;', end-of-file, or any other kind of
+ *             non-whitespace; and it won't consume a newline.
+ */
+
+extern void tvec_skipspc(struct tvec_state */*tv*/);
+
 /* --- @tvec_flushtoeol@ --- *
  *
  * Arguments:  @struct tvec_state *tv@ = test-vector state
  *             @unsigned f@ = flags (@TVFF_...@)
  *
- * Returns:    Zero on success, @-1@ on error.
+ * Returns:    Zero on success, %$-1$% on error.
  *
  * Use:                Advance to the start of the next line, consuming the
  *             preceding newline.
@@ -1454,7 +1707,7 @@ extern int tvec_flushtoeol(struct tvec_state */*tv*/, unsigned /*f*/);
  *
  * Arguments:  @struct tvec_state *tv@ = test-vector state
  *
- * Returns:    Zero if there is a next token which can be read; @-1@ if no
+ * Returns:    Zero if there is a next token which can be read; %$-1$% if no
  *             token is available.
  *
  * Use:                Advance to the next whitespace-separated token, which may be
@@ -1468,21 +1721,22 @@ extern int tvec_flushtoeol(struct tvec_state */*tv*/, unsigned /*f*/);
  *
  *             If this function returns zero, then the next character in the
  *             file begins a suitable token which can be read and
- *             processed.  If it returns @-1@ then there is no such token,
+ *             processed.  If it returns %$-1$% then there is no such token,
  *             and the file position is left correctly.  The line number
  *             count is updated appropriately.
  */
 
 extern int tvec_nexttoken(struct tvec_state */*tv*/);
 
-/* --- @tvec_readword@ --- *
+/* --- @tvec_readword@, @tvec_readword_v@ --- *
  *
  * Arguments:  @struct tvec_state *tv@ = test-vector state
  *             @dstr *d@ = string to append the word to
+ *             @const char **p_inout@ = pointer into string, updated
  *             @const char *delims@ = additional delimiters to stop at
  *             @const char *expect@, @va_list ap@ = what was expected
  *
- * Returns:    Zero on success, @-1@ on failure.
+ * Returns:    Zero on success, %$-1$% on failure.
  *
  * Use:                A `word' consists of characters other than whitespace, null
  *             characters, and other than those listed in @delims@;
@@ -1491,8 +1745,8 @@ extern int tvec_nexttoken(struct tvec_state */*tv*/);
  *             include `;' in @delims@.  This is a common behaviour.)
  *
  *             If there is no word beginning at the current file position,
- *             then return @-1@; furthermore, if @expect@ is not null, then
- *             report an appropriate error via @tvec_syntax@.
+ *             then return %$-1$%; furthermore, if @expect@ is not null,
+ *             then report an appropriate error via @tvec_syntax@.
  *
  *             Otherwise, the word is accumulated in @d@ and zero is
  *             returned; if @d@ was not empty at the start of the call, the
@@ -1501,14 +1755,23 @@ extern int tvec_nexttoken(struct tvec_state */*tv*/);
  *             word constituents, a null terminator is written to @d@, and
  *             it is safe to treat the string in @d@ as being null-
  *             terminated.
+ *
+ *             If @p_inout@ is not null, then @*p_inout@ must be a pointer
+ *             into @d->buf@, which will be adjusted so that it will
+ *             continue to point at the same position even if the buffer is
+ *             reallocated.  As a subtle tweak, if @*p_inout@ initially
+ *             points at the end of the buffer, then it will be adjusted to
+ *             point at the beginning of the next word, rather than at the
+ *             additional intervening space.
  */
 
-extern int PRINTF_LIKE(4, 5)
-  tvec_readword(struct tvec_state */*tv*/, dstr */*d*/,
-               const char */*delims*/, const char */*expect*/, ...);
+extern PRINTF_LIKE(5, 6)
+  int tvec_readword(struct tvec_state */*tv*/, dstr */*d*/,
+                   const char **/*p_inout*/, const char */*delims*/,
+                   const char */*expect*/, ...);
 extern int tvec_readword_v(struct tvec_state */*tv*/, dstr */*d*/,
-                          const char */*delims*/, const char */*expect*/,
-                          va_list */*ap*/);
+                          const char **/*p_inout*/, const char */*delims*/,
+                          const char */*expect*/, va_list */*ap*/);
 
 /*----- Integer types: signed and unsigned --------------------------------*/
 
@@ -1612,10 +1875,11 @@ extern int tvec_claimeq_uint(struct tvec_state */*tv*/,
 
 /*----- Floating-point type -----------------------------------------------*/
 
-/* Floating-point are either NaN (`#nan', if supported by the platform);
- * positive or negative infinity (`#inf', `+#inf', or, preferred, `#+inf',
- * and `-#inf' or, preferred, `#-inf', if supported by the platform), or a
- * number in strtod(3) syntax.
+/* Floating-point values are either NaN (%|#nan|%, if supported by the
+ * platform); positive or negative infinity (%|#inf|%, %|+#inf|%, or
+ * %|#+inf|% (preferring the last), and %|-#inf|% or %|#-inf|% (preferring
+ * the latter), if supported by the platform); or a number in strtod(3)
+ * syntax.
  *
  * The comparison rules for floating-point numbers are complex: see
  * @tvec_claimeqish_float@ for details.
@@ -1716,6 +1980,37 @@ extern int tvec_claimeq_float(struct tvec_state */*tv*/,
 #define TVEC_CLAIMEQ_FLOAT(tv, f0, f1)                                 \
        (tvec_claimeq_float(tv, f0, f1, __FILE__, __LINE__, #f0 " /= " #f1))
 
+extern const struct tvec_floatinfo tvflt_finite, tvflt_nonneg;
+
+/*----- Durations ---------------------------------------------------------*/
+
+/* A duration measures a time interval in seconds.  The input format consists
+ * of a nonnegative decimal floating-point number in @strtod@ format followed
+ * by an optional unit specification.
+ *
+ * No @tvec_claimeq_...@ function is provided for durations: use
+ * @tvec_claimeq_float@.
+ */
+
+extern const struct tvec_regty tvty_duration;
+
+/* --- @tvec_parsedurunit@ --- *
+ *
+ * Arguments:  @double *scale_out@ = where to leave the scale
+ *             @const char **p_inout@ = input unit string, updated
+ *
+ * Returns:    Zero on success, %$-1$% on error.
+ *
+ * Use:                If @*p_inout@ begins with a unit string followed by the end
+ *             of the string or some non-alphanumeric character, then store
+ *             the corresponding scale factor in @*scale_out@, advance
+ *             @*p_inout@ past the unit string, and return zero.  Otherwise,
+ *             return %$-1$%.
+ */
+
+extern int tvec_parsedurunit(double */*scale_out*/,
+                            const char **/*p_inout*/);
+
 /*----- Enumerated types --------------------------------------------------*/
 
 /* An enumeration describes a set of values of some underlying type, each of
@@ -1731,7 +2026,7 @@ extern int tvec_claimeq_float(struct tvec_state */*tv*/,
  * On input, an enumerated value may be given by name or as a literal value.
  * For enumerations based on numeric types, the literal values can be written
  * in the same syntax as the underlying values.  For enumerations based on
- * pointers, the only permitted literal is `#nil', which denotes a null
+ * pointers, the only permitted literal is %|#nil|%, which denotes a null
  * pointer.  On output, names are preferred (with the underlying value given
  * in a comment).
  */
@@ -1778,7 +2073,8 @@ TVEC_MISCSLOTS(DEFINFO)
 #undef DEFINFO
 
 /* Standard enumerations. */
-const struct tvec_ienuminfo tvenum_bool;
+extern const struct tvec_ienuminfo tvenum_bool;
+extern const struct tvec_ienuminfo tvenum_cmp;
 
 /* --- @tvec_claimeq_tenum@, @TVEC_CLAIMEQ_TENUM@ --- *
  *
@@ -1831,18 +2127,19 @@ TVEC_MISCSLOTS(DECLCLAIM)
  * fields; more precisely, each name is associated with a value and a
  * covering bitmask.
  *
- * The input syntax is a sequence of items separated by `|' signs.  Each item
- * may be the symbolic name of a field value, or a literal unsigned integer.
- * The masks associated with the given symbolic names must be disjoint.  The
- * resulting numerical value is simply the bitwise OR of the given values.
+ * The input syntax is a sequence of items separated by `%|||%' signs.  Each
+ * item may be the symbolic name of a field value, or a literal unsigned
+ * integer.  The masks associated with the given symbolic names must be
+ * disjoint.  The resulting numerical value is simply the bitwise OR of the
+ * given values.
  *
  * On output, the table of symbolic names and their associated values and
  * masks is repeatedly scanned, in order, to find disjoint matches -- i.e.,
  * entries whose value matches the target value in the bit positions
  * indicated by the mask, and whose mask doesn't overlap with any previously
- * found matches; the names are then output, separated by `|'.  Any remaining
- * nonzero bits not covered by any of the matching masks are output as a
- * single literal integer, in hex.
+ * found matches; the names are then output, separated by `%|||%'.  Any
+ * remaining nonzero bits not covered by any of the matching masks are output
+ * as a single literal integer, in hex.
  */
 
 extern const struct tvec_regty tvty_flags;
@@ -1905,8 +2202,9 @@ extern int tvec_claimeq_flags(struct tvec_state */*tv*/,
 /* A character value holds a character, as read by @fgetc@.  The special
  * @EOF@ value can also be represented.
  *
- * On input, a character value can be given by name, with a leading `%|#|%';
- * or a character or `%|\|%'-escape sequence, optionally in single quotes.
+ * On input, a character value can be given by symbolic name, with a leading
+ * `%|#|%'; or a character or `%|\|%'-escape sequence, optionally in single
+ * quotes.
  *
  * The following escape sequences and character names are recognized.
  *
@@ -2023,6 +2321,9 @@ extern int tvec_claimeq_char(struct tvec_state */*tv*/,
  *   * `%|!repeat|% %$n$% %|{|% %%\textit{string}%% %|}|%', which includes
  *     %$n$% copies of the (compound) string.
  *
+ * The only difference between text and binary strings is that the initial
+ * coding scheme is %|bare|% for text strings and %|hex|% for binary strings.
+ *
  * Either kind of string can contain internal nul characters.  A trailing nul
  * is appended -- beyond the stated input length -- to input strings as a
  * convenience to test functions.  Test functions may include such a nul
@@ -2032,9 +2333,9 @@ extern int tvec_claimeq_char(struct tvec_state */*tv*/,
  * string (in bytes) will be checked against the permitted range.
  */
 
-extern const struct tvec_regty tvty_string, tvty_bytes;
+extern const struct tvec_regty tvty_text, tvty_bytes;
 
-/* --- @tvec_claimeq_string@, @TVEC_CLAIMEQ_STRING@ --- *
+/* --- @tvec_claimeq_text@, @TVEC_CLAIMEQ_TEXT@ --- *
  *
  * Arguments:  @struct tvec_state *tv@ = test-vector state
  *             @const char *p0@, @size_t sz0@ = first string with length
@@ -2052,22 +2353,22 @@ extern const struct tvec_regty tvty_string, tvty_bytes;
  *             mismatched values are dumped: @p0@ is printed as the output
  *             value and @p1@ is printed as the input reference.
  *
- *             The @TVEC_CLAIM_STRING@ macro is similar, only it (a)
+ *             The @TVEC_CLAIM_TEXT@ macro is similar, only it (a)
  *             identifies the file and line number of the call site
  *             automatically, and (b) implicitly quotes the source text of
  *             the @ch0@ and @ch1@ arguments in the failure message.
  */
 
-extern int tvec_claimeq_string(struct tvec_state */*tv*/,
-                              const char */*p0*/, size_t /*sz0*/,
-                              const char */*p1*/, size_t /*sz1*/,
-                              const char */*file*/, unsigned /*lno*/,
-                              const char */*expr*/);
-#define TVEC_CLAIMEQ_STRING(tv, p0, sz0, p1, sz1)                      \
-       (tvec_claimeq_string(tv, p0, sz0, p1, sz1, __FILE__, __LINE__,  \
-                            #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
+extern int tvec_claimeq_text(struct tvec_state */*tv*/,
+                            const char */*p0*/, size_t /*sz0*/,
+                            const char */*p1*/, size_t /*sz1*/,
+                            const char */*file*/, unsigned /*lno*/,
+                            const char */*expr*/);
+#define TVEC_CLAIMEQ_TEXT(tv, p0, sz0, p1, sz1)                                \
+       (tvec_claimeq_text(tv, p0, sz0, p1, sz1, __FILE__, __LINE__,    \
+                          #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
 
-/* --- @tvec_claimeq_strz@, @TVEC_CLAIMEQ_STRZ@ --- *
+/* --- @tvec_claimeq_textz@, @TVEC_CLAIMEQ_TEXTZ@ --- *
  *
  * Arguments:  @struct tvec_state *tv@ = test-vector state
  *             @const char *p0, *p1@ = two strings to compare
@@ -2080,16 +2381,15 @@ extern int tvec_claimeq_string(struct tvec_state */*tv*/,
  * Use:                Check that strings at @p0@ and @p1@ are equal, as for
  *             @tvec_claimeq_string@, except that the strings are assumed
  *             null-terminated, so their lengths don't need to be supplied
- *             explicitly.  The macro is similarly like
- *             @TVEC_CLAIMEQ_STRING@.
+ *             explicitly.  The macro is similarly like @TVEC_CLAIMEQ_TEXT@.
  */
 
-extern int tvec_claimeq_strz(struct tvec_state */*tv*/,
-                            const char */*p0*/, const char */*p1*/,
-                            const char */*file*/, unsigned /*lno*/,
-                            const char */*expr*/);
-#define TVEC_CLAIMEQ_STRZ(tv, p0, p1)                                  \
-       (tvec_claimeq_strz(tv, p0, p1, __FILE__, __LINE__, #p0 " /= " #p1))
+extern int tvec_claimeq_textz(struct tvec_state */*tv*/,
+                             const char */*p0*/, const char */*p1*/,
+                             const char */*file*/, unsigned /*lno*/,
+                             const char */*expr*/);
+#define TVEC_CLAIMEQ_TEXTZ(tv, p0, p1)                                 \
+       (tvec_claimeq_textz(tv, p0, p1, __FILE__, __LINE__, #p0 " /= " #p1))
 
 /* --- @tvec_claimeq_bytes@, @TVEC_CLAIMEQ_BYTES@ --- *
  *
@@ -2124,7 +2424,7 @@ extern int tvec_claimeq_bytes(struct tvec_state */*tv*/,
        (tvec_claimeq(tv, p0, sz0, p1, sz1, __FILE__, __LINE__,         \
                      #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
 
-/* --- @tvec_allocstring@, @tvec_allocbytes@ --- *
+/* --- @tvec_alloctext@, @tvec_allocbytes@ --- *
  *
  * Arguments:  @union tvec_regval *rv@ = register value
  *             @size_t sz@ = required size
@@ -2140,28 +2440,69 @@ extern int tvec_claimeq_bytes(struct tvec_state */*tv*/,
  *             the old buffer contents are simply discarded if reallocation
  *             is necessary.  Instead, use a @dbuf@ or @dstr@.
  *
- *             The @tvec_allocstring@ function sneakily allocates an extra
+ *             The @tvec_alloctext@ function sneakily allocates an extra
  *             byte for a terminating zero.  The @tvec_allocbytes@ function
  *             doesn't do this.
  */
 
-extern void tvec_allocstring(union tvec_regval */*rv*/, size_t /*sz*/);
+extern void tvec_alloctext(union tvec_regval */*rv*/, size_t /*sz*/);
 extern void tvec_allocbytes(union tvec_regval */*rv*/, size_t /*sz*/);
 
 /*----- Buffer type -------------------------------------------------------*/
 
 /* Buffer registers are primarily used for benchmarking.  Only a buffer's
- * size is significant: its contents are ignored on comparison and output,
- * and unspecified on input.
+ * allocation parameters are significant: its contents are ignored on
+ * comparison and output, and unspecified on input.
+ *
+ * The input format gives the buffer's size, and an optional alignment
+ * specification, in the form %|SZ [`@' M [`+' A]]|%.  Each of %|SZ|%, %|M|%
+ * and %|A|% are sizes, as an integer, optionally suffixed with a unit `kB',
+ * `MB', `GB', `TB', `PB', `EB', `ZB', `YB' (with or without the `B')
+ * denoting a power of 1024.  The %|SZ|% gives the (effective) buffer size.
+ * %|M|% is the `alignment quantum' and %|A|% is the `alignment offset'; both
+ * default to zero, but if %|M|% is nonzero then the start of the buffer is
+ * aligned such that it is %|A|% more than a multiple of %|M|% bytes.  Note
+ * that %|M|% need not be a power of two, though this is common.
+ *
+ * Units other than `B' are used on output only when the size would be
+ * expressed exactly.
+ *
+ * Buffers are %%\emph{not}%% allocated by default.  In benchmarks, this is
+ * best done in a @before@ function.
  *
- * The input is simply the buffer size, as an integer, optionally suffixed
- * with a unit `kB', `MB', `GB', `TB', `PB', `EB', `ZB', `YB' (with or
- * without the `B') denoting a power of 1024.  Units are used on output only
- * when the size would be expressed exactly.
+ * No @claimeq@ functions or macros are provided for buffers because they
+ * don't seem very useful.
  */
 
 extern const struct tvec_regty tvty_buffer;
 
+/* --- @tvec_initbuffer@ --- *
+ *
+ * Arguments:  @union tvec_regval *rv@ = register value
+ *             @const union tvec_regval *src@ = source buffer
+ *             @size_t sz@ = size to allocate
+ *
+ * Returns:    ---
+ *
+ * Use:                Initialize the alignment parameters in @rv@ to match @src@,
+ *             and the size to @sz@.
+ */
+
+extern void tvec_initbuffer(union tvec_regval */*rv*/,
+                           const union tvec_regval */*src*/, size_t /*sz*/);
+
+/* --- @tvec_allocbuffer@ --- *
+ *
+ * Arguments:  @union tvec_regval *rv@ = register value
+ *
+ * Returns:    ---
+ *
+ * Use:                Allocate @sz@ bytes to the buffer and fill the space with a
+ *             distinctive pattern.
+ */
+
+extern void tvec_allocbuffer(union tvec_regval */*rv*/);
+
 /*----- That's all, folks -------------------------------------------------*/
 
 #ifdef __cplusplus