X-Git-Url: https://git.distorted.org.uk/~mdw/mLib/blobdiff_plain/b64eb60f6c1fdb12f3922e04913e137199838807..ce896b0b69481d8ec941e1601fddd2df5143b259:/test/tvec.h diff --git a/test/tvec.h b/test/tvec.h index f6cbcc8..123743e 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@ + * -> env @after@ + * -> output @etest@ + * 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 @@ -51,6 +119,14 @@ # include "dstr.h" #endif +#ifndef MLIB_GPRINTF_H +# include "gprintf.h" +#endif + +#ifndef MLIB_LBUF_H +# include "lbuf.h" +#endif + #ifndef MLIB_MACROS_H # include "macros.h" #endif @@ -64,7 +140,8 @@ #define TVEC_MISCSLOTS(_) \ _(PTR, const void *, p) /* arbitrary pointer */ \ _(INT, long, i) /* signed integer */ \ - _(UINT, unsigned long, u) /* signed integer */ + _(UINT, unsigned long, u) /* signed integer */ \ + _(FLT, double, f) /* floating point */ union tvec_misc { #define TVEC_DEFSLOT(tag, ty, slot) ty slot; @@ -114,6 +191,7 @@ union tvec_regval { 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 */ #ifdef TVEC_REGSLOTS @@ -163,365 +241,1696 @@ struct tvec_regdef { #define TVRF_ID 2u /* part of test identity */ union tvec_misc arg; /* extra detail for the type */ }; +#define TVEC_ENDREGS { 0, 0, 0, 0, { 0 } } -extern int tvec_serialize(const struct tvec_reg */*rv*/, - const struct tvec_regdef */*regs*/, - unsigned /*nr*/, size_t /*regsz*/, - void **/*p_out*/, size_t */*sz_out*/); +/* @TVEC_GREG(vec, i, regsz)@ + * + * If @vec@ is a data pointer which happens to contain the address of a + * vector of @struct tvec_reg@ objects, @i@ is an integer, and @regsz@ is the + * size of a @struct tvec_reg@, then this evaluates to the address of the + * @i@th element of the vector. + * + * This is the general tool you need for accessing register vectors when you + * don't have absolute knowledge of the size of a @union tvec_regval@. + * Usually you want to access one of the register vectors in a @struct + * tvec_state@, and @TVEC_REG@ will be more convenient. + */ +#define TVEC_GREG(vec, i, regsz) \ + ((struct tvec_reg *)((unsigned char *)(vec) + (i)*(regsz))) -extern int tvec_deserialize(struct tvec_reg */*rv*/, - const struct tvec_regdef */*regs*/, - unsigned /*nr*/, size_t /*regsz*/, - const void */*p*/, size_t /*sz*/); +/*----- Register types ----------------------------------------------------*/ -/*----- Test state --------------------------------------------------------*/ +struct tvec_state; /* forward declaration */ -enum { TVOUT_LOSE, TVOUT_SKIP, TVOUT_WIN, TVOUT_LIMIT }; +struct tvec_regty { + /* A register type. */ -struct tvec_state { - 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_OUTMASK 0xf0 /* test outcome */ -#define TVSF_OUTSHIFT 4 - unsigned nrout, nreg; /* number of output/total registers */ - size_t regsz; /* size of register entry */ - struct tvec_reg *in, *out; /* register vectors */ - char expst, st; /* progress status codes */ - const struct tvec_test *tests, *test; /* all tests and current test */ - unsigned curr[TVOUT_LIMIT], all[TVOUT_LIMIT], grps[TVOUT_LIMIT]; - struct tvec_output *output; /* output formatter */ - const char *infile; unsigned lno, test_lno; /* input file name, line */ - FILE *fp; /* input file stream */ -}; + 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@. + */ -#define TVEC_GREG(vec, i, regsz) \ - ((struct tvec_reg *)((unsigned char *)(vec) + (i)*(regsz))) -#define TVEC_REG(tv, vec, i) TVEC_GREG((tv)->vec, (i), (tv)->regsz) + 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_hookfn(struct tvec_state */*tv*/); 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 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@ and @teardown@ entry + * points will still be called, but @before@, @run@, and @after@ will not. + */ + +typedef int tvec_envsetfn(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. + */ + +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. + */ + +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 is + * never called if the test group is skipped. + */ + +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_envsetfn *set; /* set 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 */ - tvec_hookfn *preflight; /* check before starting */ - tvec_hookfn *run; /* test runner */ + const struct tvec_env *env; /* environment to run test in */ tvec_testfn *fn; /* test function */ - union tvec_misc arg; /* additional parameter to `run' */ }; +#define TVEC_ENDTESTS { 0, 0, 0, 0 } -extern void PRINTF_LIKE(2, 3) - tvec_check(struct tvec_state */*tv*/, const char */*detail*/, ...); -extern void tvec_check_v(struct tvec_state */*tv*/, - const char */*detail*/, va_list */*ap*/); - -extern void tvec_runtest(struct tvec_state */*tv*/); - -/*----- Input utilities ---------------------------------------------------*/ - -extern void tvec_skipspc(struct tvec_state */*tv*/); - -#define TVFF_ALLOWANY 1u -extern void tvec_flushtoeol(struct tvec_state */*tv*/, unsigned /*f*/); - -extern int PRINTF_LIKE(4, 5) - tvec_readword(struct tvec_state */*tv*/, dstr */*d*/, - 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*/); - -extern int tvec_nexttoken(struct tvec_state */*tv*/); - -/*----- Session lifecycle -------------------------------------------------*/ - -struct tvec_info { - const struct tvec_test *tests; - unsigned nrout, nreg; - size_t regsz; +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) */ }; -extern void tvec_begin(struct tvec_state */*tv_out*/, - const struct tvec_info */*info*/, - struct tvec_output */*o*/); -extern int tvec_end(struct tvec_state */*tv*/); - -extern void tvec_read(struct tvec_state */*tv*/, - const char */*infile*/, FILE */*fp*/); - +/*----- Test state --------------------------------------------------------*/ -/*----- Benchmarking ------------------------------------------------------*/ +enum { + /* Possible test outcomes. */ -struct tvec_bench { - unsigned long niter; /* iterations done per unit */ - int riter, rbuf; /* iterations and buffer registers */ - size_t ctxsz; /* size of context */ - int (*setup)(const struct tvec_reg */*in*/, struct tvec_reg */*out*/, - const union tvec_misc */*arg*/, void */*ctx*/); /* setup fn */ - void (*teardown)(void */*ctx*/); /* teardown function, or null */ - struct bench_state **b; /* benchmark state anchor or null */ - union tvec_misc arg; /* argument to setup */ + 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) */ }; -extern struct bench_state *tvec_benchstate; - -extern int tvec_ensurebench(struct tvec_state */*tv*/, - struct bench_state **/*b_out*/); -extern void tvec_bench(struct tvec_state */*tv*/); - -/*----- Ad-hoc testing ----------------------------------------------------*/ - -extern void tvec_adhoc(struct tvec_state */*tv*/, struct tvec_test */*t*/); - -extern void tvec_begingroup(struct tvec_state */*tv*/, const char */*name*/, - const char */*file*/, unsigned /*lno*/); -extern void tvec_reportgroup(struct tvec_state */*tv*/); -extern void tvec_endgroup(struct tvec_state */*tv*/); - -#define TVEC_BEGINGROUP(tv, name) \ - do tvec_begingroup(tv, name, __FILE__, __LINE__); while (0) - -#define TVEC_TESTGROUP(tag, tv, name) \ - MC_WRAP(tag##__around, \ - { TVEC_BEGINGROUP(tv, name); }, \ - { tvec_endgroup(tv); }, \ - { if (!((tv)->f&TVSF_SKIP)) tvec_skipgroup(tv, 0); \ - tvec_endgroup(tv); }) - -extern void tvec_begintest(struct tvec_state */*tv*/, - const char */*file*/, unsigned /*lno*/); -extern void tvec_endtest(struct tvec_state */*tv*/); - -#define TVEC_BEGINTEST(tv) \ - do tvec_begintest(tv, __FILE__, __LINE__); while (0) - -#define TVEC_TEST(tag, tv) \ - MC_WRAP(tag##__around, \ - { TVEC_BEGINTEST(tv); }, \ - { tvec_endtest(tv); }, \ - { if ((tv)->f&TVSF_ACTIVE) tvec_skipgroup((tv), 0); \ - tvec_endtest(tv); }) - -extern int PRINTF_LIKE(5, 6) - tvec_claim(struct tvec_state */*tv*/, int /*ok*/, - const char */*file*/, unsigned /*lno*/, - const char */*expr*/, ...); +struct tvec_state { + /* The primary state structure for the test vector machinery. */ -#define TVEC_CLAIM(tv, cond) \ - (tvec_claim(tv, !!(cond), __FILE__, __LINE__, #cond " untrue")) + unsigned f; /* flags */ +#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 */ + + /* Registers. Available to execution environments. */ + unsigned nrout, nreg; /* number of output/total registers */ + size_t regsz; /* size of register entry */ + struct tvec_reg *in, *out; /* register vectors */ -extern int tvec_claimeq(struct tvec_state */*tv*/, - const struct tvec_regty */*ty*/, - const union tvec_misc */*arg*/, - const char */*file*/, unsigned /*lno*/, - const char */*expr*/); + /* Test groups state. Available to output formatters. */ + const struct tvec_test *tests, *test; /* all tests and current test */ -/*----- Command-line interface --------------------------------------------*/ + /* Test scoreboard. Available to output formatters. */ + unsigned curr[TVOUT_LIMIT], all[TVOUT_LIMIT], grps[TVOUT_LIMIT]; -extern const struct tvec_info tvec_adhocinfo; + /* Output machinery. */ + struct tvec_output *output; /* output formatter */ -extern void tvec_parseargs(int /*argc*/, char */*argv*/[], - struct tvec_state */*tv_out*/, - int */*argpos_out*/, - const struct tvec_info */*info*/); + /* Input machinery. Available to type parsers. */ + const char *infile; unsigned lno, test_lno; /* input file name, line */ + FILE *fp; /* input file stream */ +}; -extern void tvec_readstdin(struct tvec_state */*tv*/); -extern void tvec_readfile(struct tvec_state */*tv*/, const char */*file*/); -extern void tvec_readdflt(struct tvec_state */*tv*/, const char */*file*/); -extern void tvec_readarg(struct tvec_state */*tv*/, const char */*arg*/); +/* @TVEC_REG(tv, vec, i)@ + * + * If @tv@ is a pointer to a @struct tvec_state@, @vec@ is either @in@ or + * @out@, and @i@ is an integer, then this evaluates to the address of the + * @i@th register in the selected vector. + */ +#define TVEC_REG(tv, vec, i) TVEC_GREG((tv)->vec, (i), (tv)->regsz) -extern void tvec_readargs(int /*argc*/, char */*argv*/[], - struct tvec_state */*tv*/, - int */*argpos_inout*/, const char */*dflt*/); +struct tvec_config { + /* An overall test configuration. */ -extern int tvec_main(int /*argc*/, char */*argv*/[], - const struct tvec_info */*info*/, - const char */*dflt*/); + const struct tvec_test *tests; /* the tests to be performed */ + unsigned nrout, nreg; /* number of output/total regs */ + size_t regsz; /* size of a register */ +}; /*----- Output formatting -------------------------------------------------*/ struct tvec_output { - const struct tvec_outops *ops; - struct tvec_state *tv; + /* An output formatter. */ + const struct tvec_outops *ops; /* pointer to operations */ }; -struct bench_timing; +/* Benchmarking details. */ +enum { + TVBU_OP, /* counting operations of some kind */ + TVBU_BYTE, /* counting bytes (@rbuf >= 0@) */ + TVBU_LIMIT /* (number of units) */ +}; +struct bench_timing; /* forward declaration */ struct tvec_outops { - void (*error)(struct tvec_output */*o*/, - const char */*msg*/, va_list */*ap*/); - void (*notice)(struct tvec_output */*o*/, - const char */*msg*/, va_list */*ap*/); - void (*write)(struct tvec_output */*o*/, const char */*p*/, size_t /*sz*/); + /* 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. + */ - void (*bsession)(struct tvec_output */*o*/); int (*esession)(struct tvec_output */*o*/); + /* End a session, and return the suggested exit code. */ void (*bgroup)(struct tvec_output */*o*/); - void (*egroup)(struct tvec_output */*o*/, unsigned /*outcome*/); + /* 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. + */ + + 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. + */ void (*btest)(struct tvec_output */*o*/); + /* 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. + */ + void (*fail)(struct tvec_output */*o*/, const char */*detail*/, va_list */*ap*/); - void (*mismatch)(struct tvec_output */*o*/); + /* 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. 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. + */ + + 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. + */ - void (*bbench)(struct tvec_output */*o*/); 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 (*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 (*destroy)(struct tvec_output */*o*/); + /* Release any resources acquired by the driver. */ }; -extern void PRINTF_LIKE(2, 3) NORETURN - tvec_error(struct tvec_state */*tv*/, const char */*msg*/, ...); -extern void NORETURN tvec_error_v(struct tvec_state */*tv*/, - const char */*msg*/, va_list */*ap*/); +enum { + TVLEV_NOTE = 4, /* notice */ + TVLEV_ERR = 8 /* error */ +}; -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*/); +/*----- Session lifecycle -------------------------------------------------*/ -extern void PRINTF_LIKE(3, 4) NORETURN - tvec_syntax(struct tvec_state */*tv*/, int /*ch*/, - const char */*expect*/, ...); -extern void NORETURN tvec_syntax_v(struct tvec_state */*tv*/, int /*ch*/, - const char */*expect*/, va_list */*ap*/); +/* --- @tvec_begin@ --- * + * + * Arguments: @struct tvec_state *tv_out@ = state structure to fill in + * @const struct tvec_config *config@ = test configuration + * @struct tvec_output *o@ = output driver + * + * Returns: --- + * + * Use: Initialize a state structure ready to do some testing. + */ -extern void PRINTF_LIKE(2, 3) - tvec_skipgroup(struct tvec_state */*tv*/, const char */*note*/, ...); -extern void tvec_skipgroup_v(struct tvec_state */*tv*/, - const char */*note*/, va_list */*ap*/); +extern void tvec_begin(struct tvec_state */*tv_out*/, + const struct tvec_config */*config*/, + struct tvec_output */*o*/); -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_end@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * + * Returns: A proposed exit code. + * + * Use: Conclude testing and suggests an exit code to be returned to + * the calling program. (The exit code comes from the output + * driver's @esession@ method.) + */ -extern void PRINTF_LIKE(2, 3) - tvec_fail(struct tvec_state */*tv*/, const char */*detail*/, ...); -extern void tvec_fail_v(struct tvec_state */*tv*/, - const char */*detail*/, va_list */*ap*/); +extern int tvec_end(struct tvec_state */*tv*/); -extern void tvec_mismatch(struct tvec_state */*tv*/); +/* --- @tvec_read@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @const char *infile@ = the name of the input file + * @FILE *fp@ = stream to read from + * + * 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 + * concerned with whether there were problems with the input + * file or with actually running the tests. + */ -extern void PRINTF_LIKE(2, 3) - tvec_write(struct tvec_state */*tv*/, const char */*p*/, ...); -extern void tvec_write_v(struct tvec_state */*tv*/, - const char */*p*/, va_list */*ap*/); +extern int tvec_read(struct tvec_state */*tv*/, + const char */*infile*/, FILE */*fp*/); -extern struct tvec_output *tvec_humanoutput(FILE */*fp*/); -extern struct tvec_output *tvec_tapoutput(FILE */*fp*/); -extern struct tvec_output *tvec_dfltout(FILE */*fp*/); +/*----- Command-line interface --------------------------------------------*/ -/*----- Register types ----------------------------------------------------*/ +extern const struct tvec_config tvec_adhocconfig; + /* A special @struct tvec_config@ to use for programs which perform ad-hoc + * testing. + */ -struct tvec_regty { - void (*init)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/); - void (*release)(union tvec_regval */*rv*/, - const struct tvec_regdef */*rd*/); - int (*eq)(const union tvec_regval */*rv0*/, - const union tvec_regval */*rv1*/, - const struct tvec_regdef */*rd*/); - size_t (*measure)(const union tvec_regval */*rv*/, - const struct tvec_regdef */*rd*/); - int (*tobuf)(buf */*b*/, const union tvec_regval */*rv*/, - const struct tvec_regdef */*rd*/); - int (*frombuf)(buf */*b*/, union tvec_regval */*rv*/, - const struct tvec_regdef */*rd*/); - void (*parse)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/, - struct tvec_state */*tv*/); - void (*dump)(const union tvec_regval */*rv*/, - const struct tvec_regdef */*rd*/, - struct tvec_state */*tv*/, unsigned /*style*/); -#define TVSF_COMPACT 1u -}; +/* --- @tvec_parseargs@ --- * + * + * Arguments: @int argc@ = number of command-line arguments + * @char *argv[]@ = vector of argument strings + * @struct tvec_state *tv_out@ = test vector state to initialize + * @int *argpos_out@ = where to leave unread argument index + * @const struct tvec_config *cofig@ = test vector configuration + * + * Returns: --- + * + * Use: Parse arguments and set up the test vector state @*tv_out@. + * If errors occur, print messages to standard error and exit + * with status 2. + */ -extern const struct tvec_regty tvty_int, tvty_uint; -struct tvec_irange { long min, max; }; -struct tvec_urange { unsigned long min, max; }; +extern void tvec_parseargs(int /*argc*/, char */*argv*/[], + struct tvec_state */*tv_out*/, + int */*argpos_out*/, + const struct tvec_config */*config*/); -extern const struct tvec_irange - tvrange_schar, tvrange_short, tvrange_int, tvrange_long, - tvrange_sbyte, tvrange_i16, tvrange_i32; -extern const struct tvec_urange - tvrange_uchar, tvrange_ushort, tvrange_uint, tvrange_ulong, tvrange_size, - tvrange_byte, tvrange_u16, tvrange_u32; +/* --- @tvec_readstdin@, @tvec_readfile@, @tvec_readarg@ --- * + * + * Arguments: @struct tvec_state *tv@ = test vector state + * @const char *file@ = pathname of file to read + * @const char *arg@ = argument to interpret + * + * 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 `%|-|%', + * and from the named file otherwise. + */ + +extern int tvec_readstdin(struct tvec_state */*tv*/); +extern int tvec_readfile(struct tvec_state */*tv*/, const char */*file*/); +extern int tvec_readarg(struct tvec_state */*tv*/, const char */*arg*/); + +/* --- @tvec_readdflt@ --- * + * + * Arguments: @struct tvec_state *tv@ = test vector state + * @const char *dflt@ = defsault filename or null + * + * 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 + * @file@ is not null, then read the named file, looking in the + * directory named by the `%|srcdir|%' environment variable if + * that's set, or otherwise in the current directory. + */ + +extern int tvec_readdflt(struct tvec_state */*tv*/, const char */*file*/); + +/* --- @tvec_readargs@ --- * + * + * Arguments: @int argc@ = number of command-line arguments + * @char *argv[]@ = vector of argument strings + * @struct tvec_state *tv@ = test vector state + * @int *argpos_inout@ = current argument position (updated) + * @const char *dflt@ = default filename or null + * + * 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@; + * if no arguments are given then read from @dflt@ as for + * @tvec_readdflt@. + */ + +extern int tvec_readargs(int /*argc*/, char */*argv*/[], + struct tvec_state */*tv*/, + int */*argpos_inout*/, const char */*dflt*/); + +/* --- @tvec_main@ --- * + * + * Arguments: @int argc@ = number of command-line arguments + * @char *argv[]@ = vector of argument strings + * @const struct tvec_config *cofig@ = test vector configuration + * @const char *dflt@ = default filename or null + * + * Returns: Exit code. + * + * Use: All-in-one test vector front-end. Parse options from the + * command-line as for @tvec_parseargs@, and then process the + * remaining positional arguments as for @tvec_readargs@. The + * function constructs and disposes of a test vector state. + */ + +extern int tvec_main(int /*argc*/, char */*argv*/[], + const struct tvec_config */*config*/, + const char */*dflt*/); + +/*----- 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@ --- * + * + * 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. + */ + +extern void tvec_resetoutputs(struct tvec_state */*tv*/); + +extern void tvec_initregs(struct tvec_state */*tv*/); +extern void tvec_releaseregs(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_fail@, @tvec_fail_v@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @const char *detail@, @va_list *ap@ = description of test + * + * Returns: --- + * + * Use: Report the current test as a failure. This function can be + * called multiple times for a single test, e.g., if the test + * environment's @run@ function invokes the test function + * repeatedly; but a single test that fails repeatedly still + * only counts as a single failure in the statistics. The + * @detail@ string and its format parameters can be used to + * distinguish which of several invocations failed; it can + * 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 void tvec_fail_v(struct tvec_state */*tv*/, + const char */*detail*/, va_list */*ap*/); + +/* --- @tvec_dumpreg@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @unsigned disp@ = the register disposition (@TVRD_...@) + * @const union tvec_regval *tv@ = register value, or null + * @const struct tvec_regdef *rd@ = register definition + * + * Returns: --- + * + * Use: Dump a register value to the output. This is the lowest- + * level function for dumping registers, and calls the output + * formatter directly. + * + * Usually @tvec_mismatch@ is much more convenient. Low-level + * access is required for reporting `virtual' registers + * corresponding to test environment settings. + */ + +extern void tvec_dumpreg(struct tvec_state */*tv*/, + unsigned /*disp*/, const union tvec_regval */*rv*/, + const struct tvec_regdef */*rd*/); + +/* --- @tvec_mismatch@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @unsigned f@ = flags (@TVMF_...@) + * + * Returns: --- + * + * Use: Dumps registers suitably to report a mismatch. The flag bits + * @TVMF_IN@ and @TVF_OUT@ select input-only and output + * registers. If both are reset then nothing happens. + * Suppressing the output registers may be useful, e.g., if the + * test function crashed rather than returning outputs. + */ + +#define TVMF_IN 1u +#define TVMF_OUT 2u +extern void tvec_mismatch(struct tvec_state */*tv*/, unsigned /*f*/); + +/* --- @tvec_check@, @tvec_check_v@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @const char *detail@, @va_list *ap@ = description of test + * + * Returns: --- + * + * Use: Check the register values, reporting a failure and dumping + * the registers in the event of a mismatch. This just wraps up + * @tvec_checkregs@, @tvec_fail@ and @tvec_mismatch@ in the + * obvious way. + */ + +extern void PRINTF_LIKE(2, 3) + tvec_check(struct tvec_state */*tv*/, const char */*detail*/, ...); +extern void tvec_check_v(struct tvec_state */*tv*/, + const char */*detail*/, va_list */*ap*/); + +/*----- Ad-hoc testing ----------------------------------------------------*/ + +/* --- @tvec_adhoc@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @struct tvec_test *t@ = space for a test definition + * + * Returns: --- + * + * Use: Begin ad-hoc testing, i.e., without reading a file of + * test-vector data. + * + * The structure at @t@ will be used to record information about + * the tests underway, which would normally come from a static + * test definition. The other functions in this section assume + * that @tvec_adhoc@ has been called. + */ + +extern void tvec_adhoc(struct tvec_state */*tv*/, struct tvec_test */*t*/); + +/* --- @tvec_begingroup@, @TVEC_BEGINGROUP@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @const char *name@ = name for this test group + * @const char *file@, @unsigned @lno@ = calling file and line + * + * Returns: --- + * + * Use: Begin an ad-hoc test group with the given name. The @file@ + * and @lno@ can be anything, but it's usually best if they + * refer to the source code performing the test: the macro + * @TVEC_BEGINGROUP@ does this automatically. + */ + +extern void tvec_begingroup(struct tvec_state */*tv*/, const char */*name*/, + const char */*file*/, unsigned /*lno*/); +#define TVEC_BEGINGROUP(tv, name) \ + do tvec_begingroup(tv, name, __FILE__, __LINE__); while (0) + +/* --- @tvec_endgroup@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * + * Returns: --- + * + * Use: End an ad-hoc test group. The statistics are updated and the + * outcome is reported to the output formatter. + */ + +extern void tvec_endgroup(struct tvec_state */*tv*/); + +/* --- @TVEC_TESTGROUP@, @TVEC_TESTGROUP_TAG@ --- * + * + * Arguments: @tag@ = label-disambiguation tag + * @const struct tvec_state *tv = test-vector state + * @const char *name@ = test-group name + * + * Returns: --- + * + * Use: Control-structure macro: @TVEC_TESTGROUP(tv, name) stmt@ + * establishes a test group with the given @name@ (attributing + * it to the source file and lie number), executes @stmt@, and + * ends the test group. If @stmt@ invokes @break@ then the test + * group is skipped. @TVEC_TESTGROUP_TAG@ is the same, with an + * additional @tag@ argument for use in higher-level macros. + */ + +#define TVEC_TESTGROUP_TAG(tag, tv, name) \ + MC_WRAP(tag##__around, \ + { TVEC_BEGINGROUP(tv, name); }, \ + { tvec_endgroup(tv); }, \ + { if (!((tv)->f&TVSF_SKIP)) tvec_skipgroup(tv, 0); \ + tvec_endgroup(tv); }) +#define TVEC_TESTGROUP(tv, name) TVEC_TESTGROUP_TAG(grp, tv, name) + +/* --- @tvec_begintest@, @TVEC_BEGINTEST@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @const char *file@, @unsigned @lno@ = calling file and line + * + * Returns: --- + * + * Use: Begin an ad-hoc test case. The @file@ and @lno@ can be + * anything, but it's usually best if they refer to the source + * code performing the test: the macro @TVEC_BEGINGROUP@ does + * this automatically. + */ + +extern void tvec_begintest(struct tvec_state */*tv*/, + const char */*file*/, unsigned /*lno*/); +#define TVEC_BEGINTEST(tv) \ + do tvec_begintest(tv, __FILE__, __LINE__); while (0) + +/* --- *tvec_endtest@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * + * Returns: --- + * + * Use: End a ad-hoc test case, The statistics are updated and the + * outcome is reported to the output formatter. + */ + +extern void tvec_endtest(struct tvec_state */*tv*/); + +/* --- @TVEC_TEST@, @TVEC_TEST_TAG@ --- * + * + * Arguments: @tag@ = label-disambiguation tag + * @struct tvec_test *t@ = space for a test definition + * + * Returns: --- + * + * Use: Control-structure macro: @TVEC_TEST(tv) stmt@ begins a test + * case, executes @stmt@, and ends the test case. If @stmt@ + * invokes @break@ then the test case is skipped. + * @TVEC_TEST_TAG@ is the same, with an additional @tag@ argumet + * for use in higher-level macros. + */ + +#define TVEC_TEST_TAG(tag, tv) \ + MC_WRAP(tag##__around, \ + { TVEC_BEGINTEST(tv); }, \ + { tvec_endtest(tv); }, \ + { if ((tv)->f&TVSF_ACTIVE) tvec_skip((tv), 0); \ + tvec_endtest(tv); }) +#define TVEC_TEST(tv) TVEC_TEST_TAG(test, tv) + +/* --- @tvec_claim@, @tvec_claim_v@, @TVEC_CLAIM@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @int ok@ = a flag + * @const char *file@, @unsigned @lno@ = calling file and line + * @const char *msg@, @va_list *ap@ = message to report on + * failure + * + * Returns: The value @ok@. + * + * Use: Check that a claimed condition holds, as (part of) a test. + * If no test case is underway (i.e., if @TVSF_OPEN@ is reset in + * @tv->f@), then a new test case is begun and ended. The + * @file@ and @lno@ are passed to the output formatter to be + * reported in case of a failure. If @ok@ is nonzero, then + * nothing else happens; so, in particular, if @tvec_claim@ + * established a new test case, then the test case succeeds. If + * @ok@ is zero, then a failure is reported, quoting @msg@. + * + * The @TVEC_CLAIM@ 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 @ok@ condition in + * 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 int tvec_claim_v(struct tvec_state */*tv*/, int /*ok*/, + const char */*file*/, unsigned /*lno*/, + const char */*msg*/, va_list */*ap*/); +#define TVEC_CLAIM(tv, cond) \ + (tvec_claim(tv, !!(cond), __FILE__, __LINE__, "%s untrue", #cond)) + +/* --- @tvec_claimeq@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @const struct tvec_regty *ty@ = register type + * @const union tvec_misc *arg@ = register type argument + * @const char *file@, @unsigned @lno@ = calling file and line + * @const char *expr@ = the expression to quote on failure + * + * Returns: Nonzero if the input and output values of register 0 are + * equal, zero if they differ. + * + * Use: Check that the input and output values of register 0 are + * equal (according to the register type @ty@). As for + * @tvec_claim@ above, a test case is automatically begun and + * ended if none is already underway. If the values are + * unequal, then @tvec_fail@ is called, quoting @expr@, and the + * mismatched values are dumped. + * + * This function is not expected to be called directly, but + * through type-specific wrapper functions or macros such as + * @TVEC_CLAIMEQ_INT@. + */ + +extern int tvec_claimeq(struct tvec_state */*tv*/, + const struct tvec_regty */*ty*/, + const union tvec_misc */*arg*/, + const char */*file*/, unsigned /*lno*/, + const char */*expr*/); + +/*----- Benchmarking ------------------------------------------------------*/ + +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 */ +}; + +struct tvec_benchctx { + const struct tvec_benchenv *be; /* environment configuration */ + struct bench_state *bst; /* benchmark state */ + double dflt_target; /* default time in seconds */ + void *subctx; /* subsidiary environment context */ +}; + +extern struct bench_state *tvec_benchstate; + +/* --- Environment implementation --- * + * + * The following special variables are supported. + * + * * %|@target|% is the (approximate) number of seconds to run the + * benchmark. + * + * Unrecognized variables are passed to the subordinate environment, if there + * is one. Other events are passed through to the subsidiary environment. + */ + +extern tvec_envsetupfn tvec_benchsetup; +extern tvec_envsetfn tvec_benchset; +extern tvec_envbeforefn tvec_benchbefore; +extern tvec_envrunfn tvec_benchrun; +extern tvec_envafterfn tvec_benchafter; +extern tvec_envteardownfn tvec_benchteardown; + +#define TVEC_BENCHENV \ + { sizeof(struct tvec_benchctx), \ + tvec_benchsetup, \ + tvec_benchset, \ + tvec_benchbefore, \ + tvec_benchrun, \ + tvec_benchafter, \ + tvec_benchteardown } +#define TVEC_BENCHINIT TVEC_BENCHENV, &tvec_benchstate + +/* --- @tvec_benchreport@ --- * + * + * 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 + * + * Returns: --- + * + * Use: Formats a report about the benchmark performance. This + * function is intended to be called on by an output + * @ebench@ function. + */ + +extern void tvec_benchreport + (const struct gprintf_ops */*gops*/, void */*go*/, + unsigned /*unit*/, const struct bench_timing */*tm*/); + +/*----- Remote execution --------------------------------------------------*/ + +struct tvec_remotecomms { + int infd, outfd; /* input and output descriptors */ + dbuf bin, bout; /* input and output buffers */ + unsigned f; /* flags */ +#define TVRF_BROKEN 0x0001u /* communications have failed */ + /* bits 8--15 for upper layer */ +}; +#define TVEC_REMOTECOMMS_INIT { -1, -1, DBUF_INIT, DBUF_INIT, 0 } + +struct tvec_remotectx { + struct tvec_state *tv; /* test vector state */ + struct tvec_remotecomms rc; /* communication state */ + const struct tvec_remoteenv *re; /* environment configuration */ + 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_SKIP 0x0000u /* skip unless connected */ +#define TVRCN_DEMAND 0x0100u /* connect on demand */ +#define TVRCN_FORCE 0x0200u /* force reconnection */ +#define TVRF_MUFFLE 0x0400u /* muffle child stderr */ +}; + +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*/); + +struct tvec_remoteenv_slots { + tvec_connectfn *connect; /* connection function */ + const struct tvec_env *env; /* subsidiary environment */ +}; + +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; +}; + +extern tvec_envsetupfn tvec_remotesetup; +extern tvec_envsetfn tvec_remoteset; +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_remoteset, \ + 0, \ + tvec_remoterun, \ + tvec_remoteafter, \ + tvec_remoteteardown } + +extern int tvec_setprogress(const char */*status*/); + +extern int tvec_remoteserver(int /*infd*/, int /*outfd*/, + const struct tvec_config */*config*/); + +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 } + +/*----- Output functions --------------------------------------------------*/ + +/* --- @tvec_report@, @tvec_report_v@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @const char *msg@, @va_list ap@ = error message + * + * Returns: --- + * + * Use: Report an message with a given severity. Messages with level + * @TVLEV_ERR@ or higher force a nonzero exit code. + */ + +extern void PRINTF_LIKE(3, 4) + 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_error@, @tvec_notice@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @const char *msg@, @va_list ap@ = error message + * + * Returns: The @tvec_error@ function returns @-1@ as a trivial + * convenience; @tvec_notice@ does not return a value. + * + * 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 int PRINTF_LIKE(2, 3) + tvec_error(struct tvec_state */*tv*/, const char */*msg*/, ...); +extern void PRINTF_LIKE(2, 3) + tvec_notice(struct tvec_state */*tv*/, const char */*msg*/, ...); + +/* --- @tvec_humanoutput@ --- * + * + * Arguments: @FILE *fp@ = output file to write on + * + * Returns: An output formatter. + * + * Use: Return an output formatter which writes on @fp@ with the + * expectation that a human will be watching and interpreting + * the output. If @fp@ denotes a terminal, the display shows a + * `scoreboard' indicating the outcome of each test case + * attempted, and may in addition use colour and other + * highlighting. + */ + +extern struct tvec_output *tvec_humanoutput(FILE */*fp*/); + +/* --- @tvec_tapoutput@ --- * + * + * Arguments: @FILE *fp@ = output file to write on + * + * Returns: An output formatter. + * + * Use: Return an output formatter which writes on @fp@ in `TAP' + * (`Test Anything Protocol') format. + * + * TAP comes from the Perl community, but has spread rather + * 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*/); + +/* --- @tvec_dfltoutput@ --- * + * + * Arguments: @FILE *fp@ = output file to write on + * + * Returns: An output formatter. + * + * Use: Selects and instantiates an output formatter suitable for + * writing on @fp@. The policy is subject to change, but + * currently the `human' output format is selected if @fp@ is + * interactive (i.e., if @isatty(fileno(fp))@ is true), and + * otherwise the `tap' format is used. + */ + +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 + * @buf *b@ = buffer to write on + * @const struct tvec_regdef *regs@ = vector of register + * descriptions, terminated by an entry with a null + * @name@ slot + * @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. + * + * Use: Serialize a collection of register values. + * + * The serialized output is written to the buffer @b@. Failure + * can be caused by running out of buffer space, or a failing + * type handler. + */ + +extern int tvec_serialize(const struct tvec_reg */*rv*/, buf */*b*/, + const struct tvec_regdef */*regs*/, + unsigned /*nr*/, size_t /*regsz*/); + +/* --- @tvec_deserialize@ --- * + * + * Arguments: @struct tvec_reg *rv@ = vector of registers + * @buf *b@ = buffer to write on + * @const struct tvec_regdef *regs@ = vector of register + * descriptions, terminated by an entry with a null + * @name@ slot + * @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. + * + * Use: Deserialize a collection of register values. + * + * The size of the register vector @nr@ and the register + * definitions @regs@ must match those used when producing the + * serialization. For each serialized register value, + * deserialize and store the value into the appropriate register + * slot, and set the @TVRF_LIVE@ flag on the register. See + * @tvec_serialize@ for a description of the format. + * + * Failure results only from a failing register type handler. + */ + +extern int tvec_deserialize(struct tvec_reg */*rv*/, buf */*b*/, + const struct tvec_regdef */*regs*/, + unsigned /*nr*/, size_t /*regsz*/); + +/*----- Input utilities ---------------------------------------------------*/ + +/* These are provided by the core for the benefit of type @parse@ methods, + * and test-environment @set@ functions, which get to read from the test + * input file. The latter are usually best implemented by calling on the + * former. + * + * The two main rules are as follows. + * + * * Leave the file position at the beginning of the line following + * whatever it was that you read. + * + * * When you read and consume a newline (which you do at least once, by + * the previous rule), then increment @tv->lno@ to keep track of the + * 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@ + * + * 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., + * by @tvec_flushtoeol@ or @tvec_nexttoken@, which will also + * advance the line number). + */ + +extern int PRINTF_LIKE(3, 4) + 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_flushtoeol@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @unsigned f@ = flags (@TVFF_...@) + * + * Returns: Zero on success, @-1@ on error. + * + * Use: Advance to the start of the next line, consuming the + * preceding newline. + * + * A syntax error is reported if no newline character is found, + * i.e., the file ends in mid-line. A syntax error is also + * reported if material other than whitespace or a comment is + * found before the end of the line end, and @TVFF_ALLOWANY@ is + * not set in @f@. The line number count is updated + * appropriately. + */ + +#define TVFF_ALLOWANY 1u +extern int tvec_flushtoeol(struct tvec_state */*tv*/, unsigned /*f*/); + +/* --- @tvec_nexttoken@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * + * 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 + * on the next line. + * + * Tokens are separated by non-newline whitespace, comments, and + * newlines followed by whitespace; a newline /not/ followed by + * whitespace instead begins the next assignment, and two + * newlines separated only by whitespace terminate the data for + * a test. + * + * 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, + * and the file position is left correctly. The line number + * count is updated appropriately. + */ + +extern int tvec_nexttoken(struct tvec_state */*tv*/); + +/* --- @tvec_readword@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @dstr *d@ = string to append the word to + * @const char *delims@ = additional delimiters to stop at + * @const char *expect@, @va_list ap@ = what was expected + * + * 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@; + * furthermore, a word does not begin with a `;'. (If you want + * reading to stop at comments not preceded by whitespace, then + * 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@. + * + * Otherwise, the word is accumulated in @d@ and zero is + * returned; if @d@ was not empty at the start of the call, the + * newly read word is separated from the existing material by a + * single space character. Since null bytes are never valid + * word constituents, a null terminator is written to @d@, and + * it is safe to treat the string in @d@ as being null- + * terminated. + */ + +extern int PRINTF_LIKE(4, 5) + tvec_readword(struct tvec_state */*tv*/, dstr */*d*/, + 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*/); + +/*----- Integer types: signed and unsigned --------------------------------*/ + +/* Integers may be input in decimal, hex, binary, or octal, following + * approximately usual conventions. + * + * * Signed integers may be preceded with a `+' or `-' sign. + * + * * Decimal integers are just a sequence of decimal digits `0' ... `9'. + * + * * Octal integers are a sequence of digits `0' ... `7', preceded by `0o' + * or `0O'. + * + * * Hexadecimal integers are a sequence of digits `0' ... `9', `a' + * ... `f', or `A' ... `F', preceded by `0x' or `0X'. + * + * * Radix-B integers are a sequence of digits `0' ... `9', `a' ... `f', or + * `A' ... `F', each with value less than B, preceded by `Br' or `BR', + * where 0 < B < 36 is expressed in decimal without any leading `0' or + * internal underscores `_'. + * + * * A digit sequence may contain internal underscore `_' separators, but + * not before or after all of the digits; and two consecutive `_' + * characters are not permitted. + */ + +extern const struct tvec_regty tvty_int, tvty_uint; + +/* The @arg.p@ slot may be null or a pointer to @struct tvec_irange@ or + * @struct tvec_urange@ as appropriate. The bounds are inclusive; use, e.g., + * @LONG_MAX@ explicitly if one or the other bound is logically inapplicable. + */ +struct tvec_irange { long min, max; }; +struct tvec_urange { unsigned long min, max; }; + +/* Bounds corresponding to common integer types. */ +extern const struct tvec_irange + tvrange_schar, tvrange_short, tvrange_int, tvrange_long, + tvrange_sbyte, tvrange_i16, tvrange_i32; +extern const struct tvec_urange + tvrange_uchar, tvrange_ushort, tvrange_uint, tvrange_ulong, tvrange_size, + tvrange_byte, tvrange_u16, tvrange_u32; + +/* --- @tvec_claimeq_int@, @TVEC_CLAIMEQ_INT@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @long i0, i1@ = two signed integers + * @const char *file@, @unsigned @lno@ = calling file and line + * @const char *expr@ = the expression to quote on failure + * + * Returns: Nonzero if @i0@ and @i1@ are equal, otherwise zero. + * + * Use: Check that values of @i0@ and @i1@ are equal. As for + * @tvec_claim@ above, a test case is automatically begun and + * ended if none is already underway. If the values are + * unequal, then @tvec_fail@ is called, quoting @expr@, and the + * mismatched values are dumped: @i0@ is printed as the output + * value and @i1@ is printed as the input reference. + * + * The @TVEC_CLAIM_INT@ 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 @i0@ and @i1@ + * arguments in the failure message. + */ extern int tvec_claimeq_int(struct tvec_state */*tv*/, long /*i0*/, long /*i1*/, const char */*file*/, unsigned /*lno*/, const char */*expr*/); +#define TVEC_CLAIMEQ_INT(tv, i0, i1) \ + (tvec_claimeq_int(tv, i0, i1, __FILE__, __LINE__, #i0 " /= " #i1)) + +/* --- @tvec_claimeq_uint@, @TVEC_CLAIMEQ_UINT@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @unsigned long u0, u1@ = two unsigned integers + * @const char *file@, @unsigned @lno@ = calling file and line + * @const char *expr@ = the expression to quote on failure + * + * Returns: Nonzero if @u0@ and @u1@ are equal, otherwise zero. + * + * Use: Check that values of @u0@ and @u1@ are equal. As for + * @tvec_claim@ above, a test case is automatically begun and + * ended if none is already underway. If the values are + * unequal, then @tvec_fail@ is called, quoting @expr@, and the + * mismatched values are dumped: @u0@ is printed as the output + * value and @u1@ is printed as the input reference. + * + * The @TVEC_CLAIM_UINT@ 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 @u0@ and @u1@ arguments in the failure message. + */ + extern int tvec_claimeq_uint(struct tvec_state */*tv*/, unsigned long /*u0*/, unsigned long /*u1*/, const char */*file*/, unsigned /*lno*/, const char */*expr*/); -#define TVEC_CLAIMEQ_INT(tv, i0, i1) \ - (tvec_claimeq_int(tv, i0, i1, __FILE__, __LINE__, #i0 " /= " #i1)) #define TVEC_CLAIMEQ_UINT(tv, u0, u1) \ (tvec_claimeq_uint(tv, u0, u1, __FILE__, __LINE__, #u0 " /= " #u1)) -extern const struct tvec_regty tvty_enum; +/*----- 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. + * + * The comparison rules for floating-point numbers are complex: see + * @tvec_claimeqish_float@ for details. + */ + +extern const struct tvec_regty tvty_float; + +struct tvec_floatinfo { + /* Details about acceptable floating-point values. */ + + unsigned f; /* flags (@TVFF_...@ bits) */ +#define TVFF_NOMIN 1u /* ignore @min@ (allow -inf) */ +#define TVFF_NOMAX 2u /* ignore @max@ (allow +inf) */ +#define TVFF_NANOK 4u /* permit NaN */ +#define TVFF_EQMASK 0xf0 /* how to compare */ +#define TVFF_EXACT 0x00 /* must equal exactly */ +#define TVFF_ABSDELTA 0x10 /* must be within @delta@ */ +#define TVFF_RELDELTA 0x20 /* diff < @delta@ fraction */ + double min, max; /* smallest/largest value allowed */ + double delta; /* maximum tolerable difference */ +}; + +/* --- @tvec_claimeqish_float@, @TVEC_CLAIMEQISH_FLOAT@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @double f0, f1@ = two floating-point numbers + * @unsigned f@ = flags (@TVFF_...@) + * @double delta@ = maximum tolerable difference + * @const char *file@, @unsigned @lno@ = calling file and line + * @const char *expr@ = the expression to quote on failure + * + * Returns: Nonzero if @f0@ and @u1@ are sufficiently close, otherwise + * zero. + * + * Use: Check that values of @f0@ and @f1@ are sufficiently close. + * As for @tvec_claim@ above, a test case is automatically begun + * and ended if none is already underway. If the values are + * too far apart, then @tvec_fail@ is called, quoting @expr@, + * and the mismatched values are dumped: @f0@ is printed as the + * output value and @f1@ is printed as the input reference. + * + * The details for the comparison are as follows. + * + * * A NaN value matches any other NaN, and nothing else. + * + * * An infinity matches another infinity of the same sign, + * and nothing else. + * + * * If @f&TVFF_EQMASK@ is @TVFF_EXACT@, then any + * representable number matches only itself: in particular, + * positive and negative zero are considered distinct. + * (This allows tests to check that they land on the correct + * side of branch cuts, for example.) + * + * * If @f&TVFF_EQMASK@ is @TVFF_ABSDELTA@, then %$x$% matches + * %$y$% when %$|x - y| < \delta$%. + * + * * If @f&TVFF_EQMASK@ is @TVFF_RELDELTA@, then %$x$% matches + * %$y$% when %$|1 - y/x| < \delta$%. (Note that this + * criterion is asymmetric FIXME + * + * The @TVEC_CLAIM_FLOAT@ 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 @f0@ and @f1@ arguments (and @delta@) in the failure + * message. + */ + +extern int tvec_claimeqish_float(struct tvec_state */*tv*/, + double /*f0*/, double /*f1*/, + unsigned /*f*/, double /*delta*/, + const char */*file*/, unsigned /*lno*/, + const char */*expr*/); +#define TVEC_CLAIMEQISH_FLOAT(tv, f0, f1, f, delta) \ + (tvec_claimeqish_float(tv, f0, f1, f, delta, , __FILE__, __LINE__, \ + #f0 " /= " #f1 " (+/- " #delta ")")) + +/* --- @tvec_claimeq_float@, @TVEC_CLAIMEQ_FLOAT@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @double f0, f1@ = two floating-point numbers + * @const char *file@, @unsigned @lno@ = calling file and line + * @const char *expr@ = the expression to quote on failure + * + * Returns: Nonzero if @f0@ and @u1@ are identical, otherwise zero. + * + * Use: Check that values of @f0@ and @f1@ are identical. The + * function is exactly equivalent to @tvec_claimeqish_float@ + * with @f == TVFF_EXACT@; the macro is similarly like + * @TVEC_CLAIMEQISH_FLOAT@ with @f == TVFF_EXACT@, except that + * it doesn't bother to quote a delta. + */ + +extern int tvec_claimeq_float(struct tvec_state */*tv*/, + double /*f0*/, double /*f1*/, + const char */*file*/, unsigned /*lno*/, + const char */*expr*/); +#define TVEC_CLAIMEQ_FLOAT(tv, f0, f1) \ + (tvec_claimeq_float(tv, f0, f1, __FILE__, __LINE__, #f0 " /= " #f1)) + +/*----- Enumerated types --------------------------------------------------*/ +/* An enumeration describes a set of values of some underlying type, each of + * which has a symbolic name. Values outside of the defined set can occur -- + * on output, because of bugs in the tested code, or on input to test + * handling of unexpected values. + * + * There is a distinct enumerated type for each of the branches of + * @tvec_misc@. In the following, we write @t@ for the type code, which is + * @i@ for signed integer, @u@ for unsigned integer, @f@ for floating-point, + * and @p@ for pointer. + * + * 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 + * pointer. On output, names are preferred (with the underlying value given + * in a comment). + */ + +#define DEFENUMTY(tag, ty, slot) \ + extern const struct tvec_regty tvty_##slot##enum; +TVEC_MISCSLOTS(DEFENUMTY) +#undef DEFENUMTY + +/* A @struct tvec_tassoc@ associates a string tag with a value. */ #define DEFASSOC(tag_, ty, slot) \ struct tvec_##slot##assoc { const char *tag; ty slot; }; TVEC_MISCSLOTS(DEFASSOC) #undef DEFASSOC -struct tvec_enuminfo { - const char *name; unsigned mv; - union { -#define DEFENUMINFO(tag, ty, slot) struct { \ - const struct tvec_##slot##assoc *av; \ - RANGESLOT_##tag \ - } slot; -#define RANGESLOT_INT const struct tvec_irange *ir; -#define RANGESLOT_UINT const struct tvec_urange *ur; -#define RANGESLOT_PTR - TVEC_MISCSLOTS(DEFENUMINFO) -#undef DEFENUMINFO -#undef RANGESLOT_INT -#undef RANGESLOT_UINT -#undef RANGESLOT_PTR - } u; -}; +#define TVEC_ENDENUM { 0, 0 } + +/* Information about an enumerated type. */ +#define DEFINFO(tag, ty, slot) \ + struct tvec_##slot##enuminfo { \ + const char *name; /* type name for diagnostics */ \ + const struct tvec_##slot##assoc *av; /* name/value mappings */ \ + EXTRA_##tag##_INFOSLOTS /* type-specific extra info */ \ + }; + +#define EXTRA_INT_INFOSLOTS \ + const struct tvec_irange *ir; /* allowed range of raw values */ + +#define EXTRA_UINT_INFOSLOTS \ + const struct tvec_urange *ur; /* allowed range of raw values */ + +#define EXTRA_FLT_INFOSLOTS \ + const struct tvec_floatinfo *fi; /* range and matching policy */ + +#define EXTRA_PTR_INFOSLOTS /* (nothing) */ + +TVEC_MISCSLOTS(DEFINFO) + +#undef EXTRA_INT_INFOSLOTS +#undef EXTRA_UINT_INFOSLOTS +#undef EXTRA_FLT_INFOSLOTS +#undef EXTRA_PTR_INFOSLOTS + +#undef DEFINFO + +/* Standard enumerations. */ +extern const struct tvec_ienuminfo tvenum_bool; +extern const struct tvec_ienuminfo tvenum_cmp; + +/* --- @tvec_claimeq_tenum@, @TVEC_CLAIMEQ_TENUM@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @const struct tvec_typeenuminfo *ei@ = enumeration type info + * @ty t0, t1@ = two values + * @const char *file@, @unsigned @lno@ = calling file and line + * @const char *expr@ = the expression to quote on failure + * + * Returns: Nonzero if @t0@ and @t1@ are equal, otherwise zero. + * + * Use: Check that values of @t0@ and @t1@ are equal. As for + * @tvec_claim@ above, a test case is automatically begun and + * ended if none is already underway. If the values are + * unequal, then @tvec_fail@ is called, quoting @expr@, and the + * mismatched values are dumped: @t0@ is printed as the output + * value and @t1@ is printed as the input reference. + * + * The @TVEC_CLAIM_TENUM@ 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 @t0@ and @t1@ arguments in the failure message. + */ #define DECLCLAIM(tag, ty, slot) \ extern int tvec_claimeq_##slot##enum \ (struct tvec_state */*tv*/, \ - const struct tvec_enuminfo */*ei*/, ty /*e0*/, ty /*e1*/, \ + const struct tvec_##slot##enuminfo */*ei*/, \ + ty /*t0*/, ty /*t1*/, \ const char */*file*/, unsigned /*lno*/, const char */*expr*/); TVEC_MISCSLOTS(DECLCLAIM) #undef DECLCLAIM -#define TVEC_CLAIMEQ_IENUM(tv, ei, e0, e1) \ - (tvec_claimeq_ienum(tv, ei, e0, e1, \ - __FILE__, __LINE__, #e0 " /= " #e1)) -#define TVEC_CLAIMEQ_UENUM(tv, ei, e0, e1) \ - (tvec_claimeq_uenum(tv, ei, e0, e1, \ - __FILE__, __LINE__, #e0 " /= " #e1)) -#define TVEC_CLAIMEQ_PENUM(tv, ei, e0, e1) \ - (tvec_claimeq_penum(tv, ei, e0, e1, \ - __FILE__, __LINE__, #e0 " /= " #e1)) +#define TVEC_CLAIMEQ_IENUM(tv, ei, i0, i1) \ + (tvec_claimeq_ienum(tv, ei, i0, i1, \ + __FILE__, __LINE__, #i0 " /= " #i1)) +#define TVEC_CLAIMEQ_UENUM(tv, ei, u0, u1) \ + (tvec_claimeq_uenum(tv, ei, u0, u1, \ + __FILE__, __LINE__, #u0 " /= " #u1)) +#define TVEC_CLAIMEQ_FENUM(tv, ei, f0, f1) \ + (tvec_claimeq_fenum(tv, ei, f0, f1, \ + __FILE__, __LINE__, #f0 " /= " #f1)) +#define TVEC_CLAIMEQ_PENUM(tv, ei, p0, p1) \ + (tvec_claimeq_penum(tv, ei, p0, p1, \ + __FILE__, __LINE__, #p0 " /= " #p1)) + +/*----- Flags type --------------------------------------------------------*/ + +/* A flags value packs a number of fields into a single nonnegative integer. + * Symbolic names are associated with the possible values of the various + * 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. + * + * 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. + */ extern const struct tvec_regty tvty_flags; -struct tvec_flag { const char *tag; unsigned long m, v; }; + +struct tvec_flag { + /* Definition of a single flag or bitfield value. + * + * Each named setting comes with a value @v@ and a mask @m@; the mask + * should cover all of the value bits, i.e., @(v&~m) == 0@. + */ + + const char *tag; /* name */ + unsigned long m, v; /* mask and value */ +}; + +#define TVEC_ENDFLAGS { 0, 0, 0 } + struct tvec_flaginfo { - const char *name; - const struct tvec_flag *fv; - const struct tvec_urange *range; + /* Information about a flags type. */ + + const char *name; /* type name for diagnostics */ + const struct tvec_flag *fv; /* name/mask/value mappings */ + const struct tvec_urange *range; /* permitted range for literals */ }; +/* --- @tvec_claimeq_flags@, @TVEC_CLAIMEQ_FLAGS@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @const struct tvec_flaginfo *fi@ = flags type info + * @unsigned long f0, f1@ = two values + * @const char *file@, @unsigned @lno@ = calling file and line + * @const char *expr@ = the expression to quote on failure + * + * Returns: Nonzero if @f0@ and @f1@ are equal, otherwise zero. + * + * Use: Check that values of @f0@ and @f1@ are equal. As for + * @tvec_claim@ above, a test case is automatically begun and + * ended if none is already underway. If the values are + * unequal, then @tvec_fail@ is called, quoting @expr@, and the + * mismatched values are dumped: @f0@ is printed as the output + * value and @f1@ is printed as the input reference. + * + * The @TVEC_CLAIM_FLAGS@ 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 @f0@ and @f1@ arguments in the failure message. + */ + extern int tvec_claimeq_flags(struct tvec_state */*tv*/, const struct tvec_flaginfo */*fi*/, unsigned long /*f0*/, unsigned long /*f1*/, @@ -531,37 +1940,268 @@ extern int tvec_claimeq_flags(struct tvec_state */*tv*/, (tvec_claimeq_flags(tv, fi, f0, f1, \ __FILE__, __LINE__, #f0 " /= " #f1)) +/*----- Character type ----------------------------------------------------*/ + +/* 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. + * + * The following escape sequences and character names are recognized. + * + * * `%|#eof|%' is the special end-of-file marker. + * + * * `%|#nul|%' is the NUL character, sometimes used to terminate strings. + * + * * `%|bell|%', `%|bel|%', `%|ding|%', or `%|\a|%' is the BEL character + * used to ring the terminal bell (or do some other thing to attract the + * user's attention). + * + * * %|#backspace|%, %|#bs|%, or %|\b|% is the backspace character, used to + * move the cursor backwords by one cell. + * + * * %|#escape|% %|#esc|%, or%|\e|% is the escape character, used to + * introduce special terminal commands. + * + * * %|#formfeed|%, %|#ff|%, or %|\f|% is the formfeed character, used to + * separate pages of text. + * + * * %|#newline|%, %|#linefeed|%, %|#lf|%, %|#nl|%, or %|\n|% is the + * newline character, used to terminate lines of text or advance the + * cursor to the next line (perhaps without returning it to the start of + * the line). + * + * * %|#return|%, %|#carriage-return|%, %|#cr|%, or %|\r|% is the + * carriage-return character, used to return the cursor to the start of + * the line. + * + * * %|#tab|%, %|#horizontal-tab|%, %|#ht|%, or %|\t|% is the tab + * character, used to advance the cursor to the next tab stop on the + * current line. + * + * * %|#vertical-tab|%, %|#vt|%, %|\v|% is the vertical tab character. + * + * * %|#space|%, %|#spc|% is the space character. + * + * * %|#delete|%, %|#del|% is the delete character, used to erase the most + * recent character. + * + * * %|\'|% is the single-quote character. + * + * * %|\\|% is the backslash character. + * + * * %|\"|% is the double-quote character. + * + * * %|\NNN|% or %|\{NNN}|% is the character with code NNN in octal. The + * NNN may be up to three digits long. + * + * * %|\xNN|% or %|\x{NN}|% is the character with code NNN in hexadecimal. + */ + +extern const struct tvec_regty tvty_char; + +/* --- @tvec_claimeq_char@, @TVEC_CLAIMEQ_CHAR@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @int ch0, ch1@ = two character codes + * @const char *file@, @unsigned @lno@ = calling file and line + * @const char *expr@ = the expression to quote on failure + * + * Returns: Nonzero if @ch0@ and @ch1@ are equal, otherwise zero. + * + * Use: Check that values of @ch0@ and @ch1@ are equal. As for + * @tvec_claim@ above, a test case is automatically begun and + * ended if none is already underway. If the values are + * unequal, then @tvec_fail@ is called, quoting @expr@, and the + * mismatched values are dumped: @ch0@ is printed as the output + * value and @ch1@ is printed as the input reference. + * + * The @TVEC_CLAIM_CHAR@ 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_char(struct tvec_state */*tv*/, + int /*ch0*/, int /*ch1*/, + const char */*file*/, unsigned /*lno*/, + const char */*expr*/); +#define TVEC_CLAIMEQ_CHAR(tv, c0, c1) \ + (tvec_claimeq_char(tv, c0, c1, __FILE__, __LINE__, #c0 " /= " #c1)) + +/*----- Text and binary string types --------------------------------------*/ + +/* A string is a sequence of octets. Text and binary strings differ + * primarily in presentation: text strings are shown as raw characters where + * possible; binary strings are shown as hex dumps with an auxiliary text + * display. + * + * The input format for both kinds of strings is basically the same: a + * `compound string', consisting of + * + * * single-quoted strings, which are interpreted entirely literally, but + * can't contain single quotes or newlines; + * + * * double-quoted strings, in which `%|\|%'-escapes are interpreted as for + * characters; + * + * * character names, marked by an initial `%|#|%' sign; + * + * * special tokens marked by an initial `%|!|%' sign; or + * + * * barewords interpreted according to the current coding scheme. + * + * The special tokens are + * + * * `%|!bare|%', which causes subsequent sequences of barewords to be + * treated as plain text; + * + * * `%|!hex|%', `%|!base32|%', `%|!base64|%', which cause subsequent + * barewords to be decoded in the requested manner. + * + * * `%|!repeat|% %$n$% %|{|% %%\textit{string}%% %|}|%', which includes + * %$n$% copies of the (compound) string. + * + * 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 + * character on output but this is not checked by the equality test. + * + * A @struct tvec_urange@ may be supplied as an argument: the length of the + * string (in bytes) will be checked against the permitted range. + */ + extern const struct tvec_regty tvty_string, tvty_bytes; +/* --- @tvec_claimeq_string@, @TVEC_CLAIMEQ_STRING@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @const char *p0@, @size_t sz0@ = first string with length + * @const char *p1@, @size_t sz1@ = second string with length + * @const char *file@, @unsigned @lno@ = calling file and line + * @const char *expr@ = the expression to quote on failure + * + * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise + * zero. + * + * Use: Check that strings at @p0@ and @p1@ are equal. As for + * @tvec_claim@ above, a test case is automatically begun and + * ended if none is already underway. If the values are + * unequal, then @tvec_fail@ is called, quoting @expr@, and the + * 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) + * 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 "]")) + +/* --- @tvec_claimeq_strz@, @TVEC_CLAIMEQ_STRZ@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @const char *p0, *p1@ = two strings to compare + * @const char *file@, @unsigned @lno@ = calling file and line + * @const char *expr@ = the expression to quote on failure + * + * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise + * zero. + * + * 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@. + */ + 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)) + +/* --- @tvec_claimeq_bytes@, @TVEC_CLAIMEQ_BYTES@ --- * + * + * Arguments: @struct tvec_state *tv@ = test-vector state + * @const void *p0@, @size_t sz0@ = first string with length + * @const void *p1@, @size_t sz1@ = second string with length + * @const char *file@, @unsigned @lno@ = calling file and line + * @const char *expr@ = the expression to quote on failure + * + * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise + * zero. + * + * Use: Check that binary strings at @p0@ and @p1@ are equal. As for + * @tvec_claim@ above, a test case is automatically begun and + * ended if none is already underway. If the values are + * unequal, then @tvec_fail@ is called, quoting @expr@, and the + * 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) + * 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_bytes(struct tvec_state */*tv*/, const void */*p0*/, size_t /*sz0*/, const void */*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 "]")) -#define TVEC_CLAIMEQ_STRZ(tv, p0, p1) \ - (tvec_claimeq_strz(tv, p0, p1, __FILE__, __LINE__, #p0 " /= " #p1)) #define TVEC_CLAIMEQ_BYTES(tv, p0, sz0, p1, sz1) \ (tvec_claimeq(tv, p0, sz0, p1, sz1, __FILE__, __LINE__, \ #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]")) -extern const struct tvec_regty tvty_buffer; +/* --- @tvec_allocstring@, @tvec_allocbytes@ --- * + * + * Arguments: @union tvec_regval *rv@ = register value + * @size_t sz@ = required size + * + * Returns: --- + * + * Use: Allocated space in a text or binary string register. If the + * current register size is sufficient, its buffer is left + * alone; otherwise, the old buffer, if any, is freed and a + * fresh buffer allocated. These functions are not intended to + * be used to adjust a buffer repeatedly, e.g., while building + * output incrementally: (a) they will perform badly, and (b) + * 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 + * 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_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. + * + * 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. + */ + +extern const struct tvec_regty tvty_buffer; + /*----- That's all, folks -------------------------------------------------*/ #ifdef __cplusplus