X-Git-Url: https://git.distorted.org.uk/~mdw/mLib/blobdiff_plain/67b5031ec6d160b5cae425466a34d1be3b211dd4..0335afec2c33fefcd6d3cb2c39d014ab2519b2c2:/test/tvec.h diff --git a/test/tvec.h b/test/tvec.h index 5ea18ca..b2ae674 100644 --- a/test/tvec.h +++ b/test/tvec.h @@ -32,6 +32,74 @@ 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 @@ -55,6 +123,10 @@ # 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 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@; @@ -732,71 +779,40 @@ extern int tvec_main(int /*argc*/, char */*argv*/[], /*----- Test processing ---------------------------------------------------*/ -/* --- @tvec_skipgroup@, @tvec_skipgroup_v@ --- * - * - * Arguments: @struct tvec_state *tv@ = test-vector state - * @const char *excuse@, @va_list *ap@ = reason why skipped - * - * 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@ --- * +/* --- @tvec_skipgroup@, @tvec_skipgroup_v@ --- * * * Arguments: @struct tvec_state *tv@ = test-vector state + * @const char *excuse@, @va_list *ap@ = reason why skipped * * 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. + * 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 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*/); + +/*----- Remote execution --------------------------------------------------*/ -/* --- @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. - */ +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...@ */ +}; + +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$%. + */ -extern int tvec_benchbefore(struct tvec_state */*tv*/, void */*ctx*/); +struct tvec_remoteenv_slots { + tvec_connectfn *connect; /* connection function */ + const struct tvec_env *env; /* subsidiary environment */ + unsigned dflt_reconn; /* default reconnection */ +}; -/* --- @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 +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,20 @@ 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; + /*----- Enumerated types --------------------------------------------------*/ /* An enumeration describes a set of values of some underlying type, each of @@ -1731,7 +2009,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 +2056,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 +2110,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 +2185,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 +2304,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 +2316,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 +2336,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 +2364,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 +2407,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 +2423,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