3 * Test vector processing framework
5 * (c) 2023 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of the mLib utilities library.
12 * mLib is free software: you can redistribute it and/or modify it under
13 * the terms of the GNU Library General Public License as published by
14 * the Free Software Foundation; either version 2 of the License, or (at
15 * your option) any later version.
17 * mLib is distributed in the hope that it will be useful, but WITHOUT
18 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
20 * License for more details.
22 * You should have received a copy of the GNU Library General Public
23 * License along with mLib. If not, write to the Free Software
24 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
35 /* Here's the overall flow for a testing session.
38 * -> output @bsession@
43 * -> type @init@ (input and output)
44 * -> type @parse@ (input)
48 * -> output @skipgroup@
83 * -> output @skipgroup@
88 * -> output @esession@
92 * -> type @dump@ (compact style)
97 * -> @tvec_benchreport@
99 * The output functions @error@ and @notice@ can be called at arbitrary
103 /*----- Header files ------------------------------------------------------*/
114 #ifndef MLIB_CONTROL_H
115 # include "control.h"
122 #ifndef MLIB_GPRINTF_H
123 # include "gprintf.h"
130 #ifndef MLIB_MACROS_H
134 /*----- Miscellaneous values ----------------------------------------------*/
136 /* These are attached to structures which represent extension points, as a
137 * way to pass an opaque parameter to whatever things are hooked onto them.
140 #define TVEC_MISCSLOTS(_) \
141 _(PTR, const void *, p) /* arbitrary pointer */ \
142 _(INT, long, i) /* signed integer */ \
143 _(UINT, unsigned long, u) /* signed integer */ \
144 _(FLT, double, f) /* floating point */
147 #define TVEC_DEFSLOT(tag, ty, slot) ty slot;
148 TVEC_MISCSLOTS(TVEC_DEFSLOT)
152 #define TVEC_DEFCONST(tag, ty, slot) TVMISC_##tag,
153 TVEC_MISCSLOTS(TVEC_DEFCONST)
157 /*----- Register values ---------------------------------------------------*/
159 /* The framework doesn't have a preconceived idea about what's in a register
160 * value: it just allocates them and accesses them through the register type
161 * functions. It doesn't even have a baked-in idea of how big a register
162 * value is: instead, it gets that via the `regsz' slot in `struct
163 * tvec_testinfo'. So, as far as the framework is concerned, it's safe to
164 * add new slots to this union, even if they make the overall union larger.
165 * This can be done by defining the preprocessor macro `TVEC_REGSLOTS' to be
166 * a `union' fragment defining any additional union members.
168 * This creates a distinction between code which does and doesn't know the
169 * size of a register value. Code which does, which typically means the test
170 * functions, benchmarking setup and teardown functions, and tightly-bound
171 * runner functions, is free to index the register vectors directly. Code
172 * which doesn't, which means the framework core itself and output formatting
173 * machinery, must use the `TVEC_REG' macro (or its more general `TVEC_GREG'
174 * companion) for indexing register vectors. (In principle, register type
175 * handlers also fit into this category, but they have no business peering
176 * into register values other than the one's they're given.)
180 /* The actual register value. This is what the type handler sees.
181 * Additional members can be added by setting `TVEC_REGSLOTS' before
182 * including this file.
184 * A register value can be /initialized/, which simply means that its
185 * contents represent a valid value according to its type -- the register
186 * can be compared, dumped, serialized, parsed into, etc. You can't do
187 * anything safely to an uninitialized register value other than initialize
191 long i; /* signed integer */
192 unsigned long u; /* unsigned integer */
193 void *p; /* pointer */
194 double f; /* floating point */
195 struct { char *p; size_t sz; } text; /* text string */
196 struct { unsigned char *p; size_t sz; } bytes; /* binary string of bytes */
197 struct { /* buffer */
198 unsigned char *p; size_t sz; /* binary string */
199 size_t a, m; /* residue and modulus */
200 size_t off; /* offset into full buffer */
210 * Note that all of the registers listed as being used by a particular test
211 * group are initialized at all times[1] while that test group is being
212 * processed. (The other register slots don't even have types associated
213 * with them, so there's nothing useful we could do with them.)
215 * The `TVRF_LIVE' flag indicates that the register was assigned a value by
216 * the test vector file: it's the right thing to use to check whether an
217 * optional register is actually present. Even `dead' registers are still
218 * initialized, though.
220 * [1] This isn't quite true. Between individual tests, the registers are
221 * released and reinitialized in order to reset them to known values
222 * ready for the next test. But you won't see them at this point.
225 unsigned f; /* flags */
226 #define TVRF_SEEN 1u /* assignment seen in file */
227 #define TVRF_LIVE 2u /* used in current test */
228 union tvec_regval v; /* register value */
232 /* A register definition. Register definitions list the registers which
233 * are used by a particular test group (see `struct tvec_test' below).
235 * A vector of register definitions is terminated by a definition whose
236 * `name' slot is null.
239 const char *name; /* register name (for input files) */
240 const struct tvec_regty *ty; /* register type descriptor */
241 unsigned i; /* register index */
242 unsigned f; /* flags */
243 #define TVRF_UNSET 1u /* register may be marked unset */
244 #define TVRF_OPT 2u /* register need not be assigned */
245 #define TVRF_ID 4u /* part of test identity */
246 union tvec_misc arg; /* extra detail for the type */
248 #define TVEC_ENDREGS { 0, 0, 0, 0, { 0 } }
250 /* @TVEC_GREG(vec, i, regsz)@
252 * If @vec@ is a data pointer which happens to contain the address of a
253 * vector of @struct tvec_reg@ objects, @i@ is an integer, and @regsz@ is the
254 * size of a @struct tvec_reg@, then this evaluates to the address of the
255 * @i@th element of the vector.
257 * This is the general tool you need for accessing register vectors when you
258 * don't have absolute knowledge of the size of a @union tvec_regval@.
259 * Usually you want to access one of the register vectors in a @struct
260 * tvec_state@, and @TVEC_REG@ will be more convenient.
262 #define TVEC_GREG(vec, i, regsz) \
263 ((struct tvec_reg *)((unsigned char *)(vec) + (i)*(regsz)))
265 /*----- Register types ----------------------------------------------------*/
267 struct tvec_state; /* forward declaration */
270 /* A register type. */
272 void (*init)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/);
273 /* Initialize the value in @*rv@. This will be called before any other
274 * function acting on the value, including @release@. Following @init@,
275 * the register value must be valid to use for all other type entry
279 void (*release)(union tvec_regval */*rv*/,
280 const struct tvec_regdef */*rd*/);
281 /* Release any resources associated with the value in @*rv@. The
282 * register value may be left in an invalid state.
285 int (*eq)(const union tvec_regval */*rv0*/,
286 const union tvec_regval */*rv1*/,
287 const struct tvec_regdef */*rd*/);
288 /* Return nonzero if @*rv0@ and @*rv1@ are equal values. Asymmetric
289 * criteria are permitted: @tvec_checkregs@ calls @eq@ with the input
290 * register as @rv0@ and the output as @rv1@.
293 int (*tobuf)(buf */*b*/, const union tvec_regval */*rv*/,
294 const struct tvec_regdef */*rd*/);
295 /* Serialize the value @*rv@, writing the result to @b@. Return zero on
296 * success, or %$-1$% on error.
299 int (*frombuf)(buf */*b*/, union tvec_regval */*rv*/,
300 const struct tvec_regdef */*rd*/);
301 /* Deserialize a value from @b@, storing it in @*rv@. Return zero on
302 * success, or %$-1$% on error.
305 int (*parse)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/,
306 struct tvec_state */*tv*/);
307 /* Parse a value from @tv->fp@, storing it in @*rv@. Return zero on
308 * success, or %$-1$% on error, having reported one or more errors via
309 * @tvec_error@ or @tvec_syntax@. A successful return should leave the
310 * input position at the start of the next line; the caller will flush
311 * the remainder of the line itself.
314 void (*dump)(const union tvec_regval */*rv*/,
315 const struct tvec_regdef */*rd*/,
317 const struct gprintf_ops */*gops*/, void */*go*/);
318 #define TVSF_COMPACT 1u
320 /* Write a human-readable representation of the value @*rv@ using
321 * @gprintf@ on @gops@ and @go@. The @style@ is a collection of flags:
322 * if @TVSF_COMPACT@ is set, then output should be minimal, and must fit
323 * on a single line; otherwise, output may consist of multiple lines and
324 * may contain redundant information if that is likely to be useful to a
325 * human reader. If @TVSF_RAW@ is set, then output should prefer
326 * machine-readability over human-readability.
330 /*----- Test descriptions -------------------------------------------------*/
334 typedef void tvec_testfn(const struct tvec_reg */*in*/,
335 struct tvec_reg */*out*/,
337 /* A test function. It should read inputs from @in@ and write outputs to
338 * @out@. The @TVRF_LIVE@ is set on inputs which are actually present, and
339 * on outputs which are wanted to test. A test function can set additional
340 * `gratuitous outputs' by setting @TVRF_LIVE@ on them; clearing
341 * @TVRF_LIVE@ on a wanted output causes a mismatch.
343 * A test function may be called zero or more times by the environment. In
344 * particular, it may be called multiple times, though usually by prior
345 * arrangement with the environment.
347 * The @ctx@ is supplied by the environment's @run@ function (see below).
348 * The default environment calls the test function once, with a null
349 * @ctx@. There is no expectation that the environment's context has
350 * anything to do with the test function's context.
353 typedef int tvec_setvarfn(struct tvec_state */*tv*/, const char */*var*/,
354 const union tvec_regval */*rv*/, void */*ctx*/);
355 /* Called after a variable is read. Return zero on success or %$-1$% on
356 * error. This function is never called if the test group is skipped.
360 size_t regsz; /* (minimum) register size */
361 tvec_setvarfn *setvar; /* function to set variable */
362 struct tvec_regdef def; /* register definition */
365 typedef void tvec_envsetupfn(struct tvec_state */*tv*/,
366 const struct tvec_env */*env*/,
367 void */*pctx*/, void */*ctx*/);
368 /* Initialize the context; called at the start of a test group; @pctx@ is
369 * null for environments called by the core, but may be non-null for
370 * subordinate environments. If setup fails, the function should call
371 * @tvec_skipgroup@ with a suitable excuse. The @set@, @after@, and
372 * @teardown@ entry points will still be called, but @before@ and @run@
376 typedef const struct tvec_vardef *tvec_envfindvarfn
377 (struct tvec_state */*tv*/, const char */*name*/,
378 void **/*ctx_out*/, void */*ctx*/);
379 /* Called when the parser finds a %|@var|%' special variable. If a
380 * suitable variable was found, set @*ctx_out@ to a suitable context and
381 * return the variable definition; the context will be passed to the
382 * variable definition's @setvar@ function. If no suitable variable was
383 * found, then return null.
386 typedef void tvec_envbeforefn(struct tvec_state */*tv*/, void */*ctx*/);
387 /* Called prior to running a test. This is the right place to act on any
388 * `%|@var|%' settings. If preparation fails, the function should call
389 * @tvec_skip@ with a suitable excuse. This function is never called if
390 * the test group is skipped. It %%\emph{is}%% called if the test will be
391 * skipped due to erroneous test data. It should check the @TVSF_ACTIVE@
395 typedef void tvec_envrunfn(struct tvec_state */*tv*/,
396 tvec_testfn */*fn*/, void */*ctx*/);
397 /* Run the test. It should either call @tvec_skip@, or run @fn@ one or
398 * more times. In the latter case, it is responsible for checking the
399 * outputs, and calling @tvec_fail@ as necessary; @tvec_checkregs@ will
400 * check the register values against the supplied test vector, while
401 * @tvec_check@ does pretty much everything necessary. This function is
402 * never called if the test group is skipped.
405 typedef void tvec_envafterfn(struct tvec_state */*tv*/, void */*ctx*/);
406 /* Called after running or skipping a test. Typical actions involve
407 * resetting whatever things were established by @set@. This function
408 * %%\emph{is}%% called if the test group is skipped or the test data is
409 * erroneous, so that the test environment can reset variables set by the
410 * @set@ entry point. It should check the @TVSF_SKIP@ flag if necessary.
413 typedef void tvec_envteardownfn(struct tvec_state */*tv*/, void */*ctx*/);
414 /* Tear down the environment: called at the end of a test group. */
418 /* A test environment sets things up for and arranges to run the test.
420 * The caller is responsible for allocating storage for the environment's
421 * context, based on the @ctxsz@ slot, and freeing it later; this space is
422 * passed in as the @ctx@ parameter to the remaining functions; if @ctxsz@
423 * is zero then @ctx@ is null.
426 size_t ctxsz; /* environment context size */
428 tvec_envsetupfn *setup; /* setup for group */
429 tvec_envfindvarfn *findvar; /* find variable */
430 tvec_envbeforefn *before; /* prepare for test */
431 tvec_envrunfn *run; /* run test function */
432 tvec_envafterfn *after; /* clean up after test */
433 tvec_envteardownfn *teardown; /* tear down after group */
437 /* A test description. */
439 const char *name; /* name of the test */
440 const struct tvec_regdef *regs; /* descriptions of the registers */
441 const struct tvec_env *env; /* environment to run test in */
442 tvec_testfn *fn; /* test function */
444 #define TVEC_ENDTESTS { 0, 0, 0, 0 }
446 /*----- Test state --------------------------------------------------------*/
449 /* Possible test outcomes. */
451 TVOUT_LOSE, /* test failed */
452 TVOUT_SKIP, /* test skipped */
453 TVOUT_XFAIL, /* test passed, but shouldn't have */
454 TVOUT_WIN, /* test passed */
455 TVOUT_LIMIT /* (number of possible outcomes) */
459 /* An overall test configuration. */
461 const struct tvec_test *tests; /* the tests to be performed */
462 unsigned nrout, nreg; /* number of output/total regs */
463 size_t regsz; /* size of a register */
467 /* The primary state structure for the test vector machinery. */
469 /* Flags. Read-only for all callers. */
470 unsigned f; /* flags */
471 #define TVSF_SKIP 0x0001u /* skip this test group */
472 #define TVSF_OPEN 0x0002u /* test is open */
473 #define TVSF_ACTIVE 0x0004u /* test is active */
474 #define TVSF_ERROR 0x0008u /* an error occurred */
475 #define TVSF_OUTMASK 0x00f0u /* test outcome (@TVOUT_...@) */
476 #define TVSF_OUTSHIFT 4 /* shift applied to outcome */
477 #define TVSF_XFAIL 0x0100u /* test expected to fail */
478 #define TVSF_MUFFLE 0x0200u /* muffle errors */
480 /* Test configuration. Read-only for all callers. */
481 struct tvec_config cfg; /* test configuration */
483 /* Registers. Available to execution environments, which may modify the
484 * contents of the active registers, as defined by the current test group,
485 * but not the vector pointers themselves or inactive registers.
487 struct tvec_reg *in, *out; /* register vectors */
489 /* Test group state. Read-only for all callers. */
490 const struct tvec_test *test; /* current test */
492 /* Test scoreboard. Available to output formatters. */
493 unsigned curr[TVOUT_LIMIT], all[TVOUT_LIMIT], grps[TVOUT_LIMIT];
495 /* Output machinery. */
496 struct tvec_output *output; /* output formatter */
498 /* Input machinery. Available to type parsers. */
499 const char *infile; unsigned lno, test_lno; /* input file name, line */
500 FILE *fp; /* input file stream */
503 /* @TVEC_REG(tv, vec, i)@
505 * If @tv@ is a pointer to a @struct tvec_state@, @vec@ is either @in@ or
506 * @out@, and @i@ is an integer, then this evaluates to the address of the
507 * @i@th register in the selected vector.
509 #define TVEC_REG(tv, vec, i) TVEC_GREG((tv)->vec, (i), (tv)->cfg.regsz)
511 /*----- Output formatting -------------------------------------------------*/
514 /* An output formatter. */
515 const struct tvec_outops *ops; /* pointer to operations */
519 /* Register output dispositions. */
521 TVRD_INPUT, /* input-only register */
522 TVRD_OUTPUT, /* output-only (input is dead) */
523 TVRD_MATCH, /* matching (equal) registers */
524 TVRD_FOUND, /* mismatching output register */
525 TVRD_EXPECT, /* mismatching input register */
526 TVRD_LIMIT /* (number of dispositions) */
529 #define TVEC_LEVELS(_) \
530 _(NOTE, "notice", 4) \
533 #define TVEC_DEFLEVEL(tag, name, val) TVLEV_##tag = val,
534 TVEC_LEVELS(TVEC_DEFLEVEL)
539 /* Benchmarking details. */
541 TVBU_OP, /* counting operations of some kind */
542 TVBU_BYTE, /* counting bytes (@rbuf >= 0@) */
543 TVBU_LIMIT /* (number of units) */
545 struct bench_timing; /* include <mLib/bench.h> for the real definition */
548 /* Output operations. */
550 void (*bsession)(struct tvec_output */*o*/, struct tvec_state */*tv*/);
551 /* Begin a test session. The output driver will probably want to
552 * save @tv@, because this isn't provided to any other methods.
555 int (*esession)(struct tvec_output */*o*/);
556 /* End a session, and return the suggested exit code. */
558 void (*bgroup)(struct tvec_output */*o*/);
559 /* Begin a test group. The test group description is @tv->test@. */
561 void (*skipgroup)(struct tvec_output */*o*/,
562 const char */*excuse*/, va_list */*ap*/);
563 /* The group is being skipped; @excuse@ may be null or a format
564 * string explaining why. The @egroup@ method will not be called
568 void (*egroup)(struct tvec_output */*o*/);
569 /* End a test group. At least one test was attempted or @skipgroup@
570 * would have been called instead. If @tv->curr[TVOUT_LOSE]@ is nonzero
571 * then the test group as a whole failed; otherwise it passed.
574 void (*btest)(struct tvec_output */*o*/);
575 /* Begin a test case. */
577 void (*skip)(struct tvec_output */*o*/,
578 const char */*excuse*/, va_list */*ap*/);
579 /* The test case is being skipped; @excuse@ may be null or a format
580 * string explaining why. The @etest@ function will still be called (so
581 * this works differently from @skipgroup@ and @egroup@). A test case
582 * can be skipped at most once, and, if skipped, it cannot fail.
585 void (*fail)(struct tvec_output */*o*/,
586 const char */*detail*/, va_list */*ap*/);
587 /* The test case failed.
589 * The output driver should preferably report the filename (@infile@) and
590 * line number (@test_lno@, not @lno@) for the failing test.
592 * The @detail@ may be null or a format string describing detail about
593 * how the failing test was run which can't be determined from the
594 * registers; a @detail@ is usually provided when (and only when) the
595 * test environment potentially invokes the test function more than once.
597 * A single test case can fail multiple times!
600 void (*dumpreg)(struct tvec_output */*o*/,
601 unsigned /*disp*/, const union tvec_regval */*rv*/,
602 const struct tvec_regdef */*rd*/);
603 /* Dump a register. The `disposition' @disp@ explains what condition the
604 * register is in; see @tvec_dumpreg@ and the @TVRD_...@ codes. The
605 * register value is at @rv@, and its definition, including its type, at
606 * @rd@. Note that this function may be called on virtual registers
607 * which aren't in either of the register vectors or mentioned by the
608 * test description. It may also be called with @rv@ null, indicating
609 * that the register is not live.
612 void (*etest)(struct tvec_output */*o*/, unsigned /*outcome*/);
613 /* The test case concluded with the given @outcome@ (one of the
617 void (*bbench)(struct tvec_output */*o*/,
618 const char */*ident*/, unsigned /*unit*/);
619 /* Begin a benchmark. The @ident@ is a formatted string identifying the
620 * benchmark based on the values of the input registered marked
621 * @TVRF_ID@; the output driver is free to use this or come up with its
622 * own way to identify the test, e.g., by inspecting the register values
623 * for itself. The @unit@ is one of the @TVBU_...@ constants explaining
624 * what sort of thing is being measured.
627 void (*ebench)(struct tvec_output */*o*/,
628 const char */*ident*/, unsigned /*unit*/,
629 const struct bench_timing */*tm*/);
630 /* End a benchmark. The @ident@ and @unit@ arguments are as for
631 * @bbench@. If @tm@ is zero then the measurement failed; otherwise
632 * @tm->n@ counts total number of things (operations or bytes, as
633 * indicated by @unit@) processed in the indicated time.
636 void (*report)(struct tvec_output */*o*/, unsigned /*level*/,
637 const char */*msg*/, va_list */*ap*/);
638 /* Report a message. The driver should ideally report the filename
639 * (@infile@) and line number (@lno@) prompting the error.
642 void (*destroy)(struct tvec_output */*o*/);
643 /* Release any resources acquired by the driver. */
646 /*----- Session lifecycle -------------------------------------------------*/
648 /* --- @tvec_begin@ --- *
650 * Arguments: @struct tvec_state *tv_out@ = state structure to fill in
651 * @const struct tvec_config *config@ = test configuration
652 * @struct tvec_output *o@ = output driver
656 * Use: Initialize a state structure ready to do some testing.
659 extern void tvec_begin(struct tvec_state */*tv_out*/,
660 const struct tvec_config */*config*/,
661 struct tvec_output */*o*/);
663 /* --- @tvec_end@ --- *
665 * Arguments: @struct tvec_state *tv@ = test-vector state
667 * Returns: A proposed exit code.
669 * Use: Conclude testing and suggests an exit code to be returned to
670 * the calling program. (The exit code comes from the output
671 * driver's @esession@ method.)
674 extern int tvec_end(struct tvec_state */*tv*/);
676 /* --- @tvec_read@ --- *
678 * Arguments: @struct tvec_state *tv@ = test-vector state
679 * @const char *infile@ = the name of the input file
680 * @FILE *fp@ = stream to read from
682 * Returns: Zero on success, %$-1$% on error.
684 * Use: Read test vector data from @fp@ and exercise test functions.
685 * THe return code doesn't indicate test failures: it's only
686 * concerned with whether there were problems with the input
687 * file or with actually running the tests.
690 extern int tvec_read(struct tvec_state */*tv*/,
691 const char */*infile*/, FILE */*fp*/);
693 /*----- Command-line interface --------------------------------------------*/
695 extern const struct tvec_config tvec_adhocconfig;
696 /* A special @struct tvec_config@ to use for programs which perform ad-hoc
700 /* --- @tvec_parseargs@ --- *
702 * Arguments: @int argc@ = number of command-line arguments
703 * @char *argv[]@ = vector of argument strings
704 * @struct tvec_state *tv_out@ = test vector state to initialize
705 * @int *argpos_out@ = where to leave unread argument index
706 * @const struct tvec_config *cofig@ = test vector configuration
710 * Use: Parse arguments and set up the test vector state @*tv_out@.
711 * If errors occur, print messages to standard error and exit
715 extern void tvec_parseargs(int /*argc*/, char */*argv*/[],
716 struct tvec_state */*tv_out*/,
718 const struct tvec_config */*config*/);
720 /* --- @tvec_readstdin@, @tvec_readfile@, @tvec_readarg@ --- *
722 * Arguments: @struct tvec_state *tv@ = test vector state
723 * @const char *file@ = pathname of file to read
724 * @const char *arg@ = argument to interpret
726 * Returns: Zero on success, %$-1$% on error.
728 * Use: Read test vector data from stdin or a named file. The
729 * @tvec_readarg@ function reads from stdin if @arg@ is `%|-|%',
730 * and from the named file otherwise.
733 extern int tvec_readstdin(struct tvec_state */*tv*/);
734 extern int tvec_readfile(struct tvec_state */*tv*/, const char */*file*/);
735 extern int tvec_readarg(struct tvec_state */*tv*/, const char */*arg*/);
737 /* --- @tvec_readdflt@ --- *
739 * Arguments: @struct tvec_state *tv@ = test vector state
740 * @const char *dflt@ = defsault filename or null
742 * Returns: Zero on success, %$-1$% on error.
744 * Use: Reads from the default test vector data. If @file@ is null,
745 * then read from standard input, unless that's a terminal; if
746 * @file@ is not null, then read the named file, looking in the
747 * directory named by the `%|srcdir|%' environment variable if
748 * that's set, or otherwise in the current directory.
751 extern int tvec_readdflt(struct tvec_state */*tv*/, const char */*file*/);
753 /* --- @tvec_readargs@ --- *
755 * Arguments: @int argc@ = number of command-line arguments
756 * @char *argv[]@ = vector of argument strings
757 * @struct tvec_state *tv@ = test vector state
758 * @int *argpos_inout@ = current argument position (updated)
759 * @const char *dflt@ = default filename or null
761 * Returns: Zero on success, %$-1$% on error.
763 * Use: Reads from the sources indicated by the command-line
764 * arguments, in order, interpreting each as for @tvec_readarg@;
765 * if no arguments are given then read from @dflt@ as for
769 extern int tvec_readargs(int /*argc*/, char */*argv*/[],
770 struct tvec_state */*tv*/,
771 int */*argpos_inout*/, const char */*dflt*/);
773 /* --- @tvec_main@ --- *
775 * Arguments: @int argc@ = number of command-line arguments
776 * @char *argv[]@ = vector of argument strings
777 * @const struct tvec_config *cofig@ = test vector configuration
778 * @const char *dflt@ = default filename or null
780 * Returns: Exit code.
782 * Use: All-in-one test vector front-end. Parse options from the
783 * command-line as for @tvec_parseargs@, and then process the
784 * remaining positional arguments as for @tvec_readargs@. The
785 * function constructs and disposes of a test vector state.
788 extern int tvec_main(int /*argc*/, char */*argv*/[],
789 const struct tvec_config */*config*/,
790 const char */*dflt*/);
792 /*----- Test processing ---------------------------------------------------*/
794 /* --- @tvec_skipgroup@, @tvec_skipgroup_v@ --- *
796 * Arguments: @struct tvec_state *tv@ = test-vector state
797 * @const char *excuse@, @va_list *ap@ = reason why skipped
801 * Use: Skip the current group. This should only be called from a
802 * test environment @setup@ function; a similar effect occurs if
803 * the @setup@ function fails.
806 extern PRINTF_LIKE(2, 3)
807 void tvec_skipgroup(struct tvec_state */*tv*/,
808 const char */*excuse*/, ...);
809 extern void tvec_skipgroup_v(struct tvec_state */*tv*/,
810 const char */*excuse*/, va_list */*ap*/);
812 /* --- @tvec_skip@, @tvec_skip_v@ --- *
814 * Arguments: @struct tvec_state *tv@ = test-vector state
815 * @const char *excuse@, @va_list *ap@ = reason why test skipped
819 * Use: Skip the current test. This should only be called from a
820 * test environment @run@ function; a similar effect occurs if
821 * the @before@ function fails.
824 extern PRINTF_LIKE(2, 3)
825 void tvec_skip(struct tvec_state */*tv*/, const char */*excuse*/, ...);
826 extern void tvec_skip_v(struct tvec_state */*tv*/,
827 const char */*excuse*/, va_list */*ap*/);
829 /* --- @tvec_fail@, @tvec_fail_v@ --- *
831 * Arguments: @struct tvec_state *tv@ = test-vector state
832 * @const char *detail@, @va_list *ap@ = description of test
836 * Use: Report the current test as a failure. This function can be
837 * called multiple times for a single test, e.g., if the test
838 * environment's @run@ function invokes the test function
839 * repeatedly; but a single test that fails repeatedly still
840 * only counts as a single failure in the statistics. The
841 * @detail@ string and its format parameters can be used to
842 * distinguish which of several invocations failed; it can
843 * safely be left null if the test function is run only once.
846 extern PRINTF_LIKE(2, 3)
847 void tvec_fail(struct tvec_state */*tv*/, const char */*detail*/, ...);
848 extern void tvec_fail_v(struct tvec_state */*tv*/,
849 const char */*detail*/, va_list */*ap*/);
851 /* --- @tvec_dumpreg@ --- *
853 * Arguments: @struct tvec_state *tv@ = test-vector state
854 * @unsigned disp@ = the register disposition (@TVRD_...@)
855 * @const union tvec_regval *tv@ = register value, or null
856 * @const struct tvec_regdef *rd@ = register definition
860 * Use: Dump a register value to the output. This is the lowest-
861 * level function for dumping registers, and calls the output
862 * formatter directly.
864 * Usually @tvec_mismatch@ is much more convenient. Low-level
865 * access is required for reporting `virtual' registers
866 * corresponding to test environment settings.
869 extern void tvec_dumpreg(struct tvec_state */*tv*/,
870 unsigned /*disp*/, const union tvec_regval */*rv*/,
871 const struct tvec_regdef */*rd*/);
873 /* --- @tvec_initregs@, @tvec_releaseregs@ --- *
875 * Arguments: @struct tvec_state *tv@ = test-vector state
879 * Use: Initialize or release, respectively, the registers required
880 * by the current test. All of the registers, both input and
881 * output, are effected. Initialized registers are not marked
885 extern void tvec_initregs(struct tvec_state */*tv*/);
886 extern void tvec_releaseregs(struct tvec_state */*tv*/);
888 /* --- @tvec_resetoutputs@ --- *
890 * Arguments: @struct tvec_state *tv@ = test-vector state
894 * Use: Reset (releases and reinitializes) the output registers in
895 * the test state. This is mostly of use to test environment
896 * @run@ functions, between invocations of the test function.
897 * Output registers are marked live if and only if the
898 * corresponding input register is live.
901 extern void tvec_resetoutputs(struct tvec_state */*tv*/);
903 /* --- @tvec_checkregs@ --- *
905 * Arguments: @struct tvec_state *tv@ = test-vector state
907 * Returns: Zero on success, %$-1$% on mismatch.
909 * Use: Compare the active output registers (according to the current
910 * test group definition) with the corresponding input register
911 * values. A mismatch occurs if the two values differ
912 * (according to the register type's @eq@ method), or if the
913 * input is live but the output is dead.
915 * This function only checks for a mismatch and returns the
916 * result; it takes no other action. In particular, it doesn't
917 * report a failure, or dump register values.
920 extern int tvec_checkregs(struct tvec_state */*tv*/);
922 /* --- @tvec_mismatch@ --- *
924 * Arguments: @struct tvec_state *tv@ = test-vector state
925 * @unsigned f@ = flags (@TVMF_...@)
929 * Use: Dumps registers suitably to report a mismatch. The flag bits
930 * @TVMF_IN@ and @TVF_OUT@ select input-only and output
931 * registers. If both are reset then nothing happens.
932 * Suppressing the output registers may be useful, e.g., if the
933 * test function crashed rather than returning outputs.
938 extern void tvec_mismatch(struct tvec_state */*tv*/, unsigned /*f*/);
940 /* --- @tvec_check@, @tvec_check_v@ --- *
942 * Arguments: @struct tvec_state *tv@ = test-vector state
943 * @const char *detail@, @va_list *ap@ = description of test
947 * Use: Check the register values, reporting a failure and dumping
948 * the registers in the event of a mismatch. This just wraps up
949 * @tvec_checkregs@, @tvec_fail@ and @tvec_mismatch@ in the
953 extern PRINTF_LIKE(2, 3)
954 void tvec_check(struct tvec_state */*tv*/, const char */*detail*/, ...);
955 extern void tvec_check_v(struct tvec_state */*tv*/,
956 const char */*detail*/, va_list */*ap*/);
958 /*----- Ad-hoc testing ----------------------------------------------------*/
960 /* --- @tvec_adhoc@ --- *
962 * Arguments: @struct tvec_state *tv@ = test-vector state
963 * @struct tvec_test *t@ = space for a test definition
967 * Use: Begin ad-hoc testing, i.e., without reading a file of
970 * The structure at @t@ will be used to record information about
971 * the tests underway, which would normally come from a static
972 * test definition. The other functions in this section assume
973 * that @tvec_adhoc@ has been called.
976 extern void tvec_adhoc(struct tvec_state */*tv*/, struct tvec_test */*t*/);
978 /* --- @tvec_begingroup@, @TVEC_BEGINGROUP@ --- *
980 * Arguments: @struct tvec_state *tv@ = test-vector state
981 * @const char *name@ = name for this test group
982 * @const char *file@, @unsigned @lno@ = calling file and line
986 * Use: Begin an ad-hoc test group with the given name. The @file@
987 * and @lno@ can be anything, but it's usually best if they
988 * refer to the source code performing the test: the macro
989 * @TVEC_BEGINGROUP@ does this automatically.
992 extern void tvec_begingroup(struct tvec_state */*tv*/, const char */*name*/,
993 const char */*file*/, unsigned /*lno*/);
994 #define TVEC_BEGINGROUP(tv, name) \
995 do tvec_begingroup(tv, name, __FILE__, __LINE__); while (0)
997 /* --- @tvec_endgroup@ --- *
999 * Arguments: @struct tvec_state *tv@ = test-vector state
1003 * Use: End an ad-hoc test group. The statistics are updated and the
1004 * outcome is reported to the output formatter.
1007 extern void tvec_endgroup(struct tvec_state */*tv*/);
1009 /* --- @TVEC_TESTGROUP@, @TVEC_TESTGROUP_TAG@ --- *
1011 * Arguments: @tag@ = label-disambiguation tag
1012 * @const struct tvec_state *tv = test-vector state
1013 * @const char *name@ = test-group name
1017 * Use: Control-structure macro: @TVEC_TESTGROUP(tv, name) stmt@
1018 * establishes a test group with the given @name@ (attributing
1019 * it to the source file and lie number), executes @stmt@, and
1020 * ends the test group. If @stmt@ invokes @break@ then the test
1021 * group is skipped. @TVEC_TESTGROUP_TAG@ is the same, with an
1022 * additional @tag@ argument for use in higher-level macros.
1025 #define TVEC_TESTGROUP_TAG(tag, tv, name) \
1026 MC_WRAP(tag##__around, \
1027 { TVEC_BEGINGROUP(tv, name); }, \
1028 { tvec_endgroup(tv); }, \
1029 { if (!((tv)->f&TVSF_SKIP)) tvec_skipgroup(tv, 0); \
1030 tvec_endgroup(tv); })
1031 #define TVEC_TESTGROUP(tv, name) TVEC_TESTGROUP_TAG(grp, tv, name)
1033 /* --- @tvec_begintest@, @TVEC_BEGINTEST@ --- *
1035 * Arguments: @struct tvec_state *tv@ = test-vector state
1036 * @const char *file@, @unsigned @lno@ = calling file and line
1040 * Use: Begin an ad-hoc test case. The @file@ and @lno@ can be
1041 * anything, but it's usually best if they refer to the source
1042 * code performing the test: the macro @TVEC_BEGINGROUP@ does
1043 * this automatically.
1046 extern void tvec_begintest(struct tvec_state */*tv*/,
1047 const char */*file*/, unsigned /*lno*/);
1048 #define TVEC_BEGINTEST(tv) \
1049 do tvec_begintest(tv, __FILE__, __LINE__); while (0)
1051 /* --- @tvec_endtest@ --- *
1053 * Arguments: @struct tvec_state *tv@ = test-vector state
1057 * Use: End an ad-hoc test case, The statistics are updated and the
1058 * outcome is reported to the output formatter.
1061 extern void tvec_endtest(struct tvec_state */*tv*/);
1063 /* --- @TVEC_TEST@, @TVEC_TEST_TAG@ --- *
1065 * Arguments: @tag@ = label-disambiguation tag
1066 * @struct tvec_test *t@ = space for a test definition
1070 * Use: Control-structure macro: @TVEC_TEST(tv) stmt@ begins a test
1071 * case, executes @stmt@, and ends the test case. If @stmt@
1072 * invokes @break@ then the test case is skipped.
1073 * @TVEC_TEST_TAG@ is the same, with an additional @tag@ argumet
1074 * for use in higher-level macros.
1077 #define TVEC_TEST_TAG(tag, tv) \
1078 MC_WRAP(tag##__around, \
1079 { TVEC_BEGINTEST(tv); }, \
1080 { tvec_endtest(tv); }, \
1081 { if ((tv)->f&TVSF_ACTIVE) tvec_skip((tv), 0); \
1082 tvec_endtest(tv); })
1083 #define TVEC_TEST(tv) TVEC_TEST_TAG(test, tv)
1085 /* --- @tvec_claim@, @tvec_claim_v@, @TVEC_CLAIM@ --- *
1087 * Arguments: @struct tvec_state *tv@ = test-vector state
1089 * @const char *file@, @unsigned @lno@ = calling file and line
1090 * @const char *msg@, @va_list *ap@ = message to report on
1093 * Returns: The value @ok@.
1095 * Use: Check that a claimed condition holds, as (part of) a test.
1096 * If no test case is underway (i.e., if @TVSF_OPEN@ is reset in
1097 * @tv->f@), then a new test case is begun and ended. The
1098 * @file@ and @lno@ are passed to the output formatter to be
1099 * reported in case of a failure. If @ok@ is nonzero, then
1100 * nothing else happens; so, in particular, if @tvec_claim@
1101 * established a new test case, then the test case succeeds. If
1102 * @ok@ is zero, then a failure is reported, quoting @msg@.
1104 * The @TVEC_CLAIM@ macro is similar, only it (a) identifies the
1105 * file and line number of the call site automatically, and (b)
1106 * implicitly quotes the source text of the @ok@ condition in
1107 * the failure message.
1110 extern PRINTF_LIKE(5, 6)
1111 int tvec_claim(struct tvec_state */*tv*/, int /*ok*/,
1112 const char */*file*/, unsigned /*lno*/,
1113 const char */*msg*/, ...);
1114 extern int tvec_claim_v(struct tvec_state */*tv*/, int /*ok*/,
1115 const char */*file*/, unsigned /*lno*/,
1116 const char */*msg*/, va_list */*ap*/);
1117 #define TVEC_CLAIM(tv, cond) \
1118 (tvec_claim(tv, !!(cond), __FILE__, __LINE__, "%s untrue", #cond))
1120 /* --- @tvec_claimeq@ --- *
1122 * Arguments: @struct tvec_state *tv@ = test-vector state
1123 * @const struct tvec_regty *ty@ = register type
1124 * @const union tvec_misc *arg@ = register type argument
1125 * @const char *file@, @unsigned @lno@ = calling file and line
1126 * @const char *expr@ = the expression to quote on failure
1128 * Returns: Nonzero if the input and output values of register 0 are
1129 * equal, zero if they differ.
1131 * Use: Check that the input and output values of register 0 are
1132 * equal (according to the register type @ty@). As for
1133 * @tvec_claim@ above, a test case is automatically begun and
1134 * ended if none is already underway. If the values are
1135 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
1136 * mismatched values are dumped.
1138 * This function is not expected to be called directly, but
1139 * through type-specific wrapper functions or macros such as
1140 * @TVEC_CLAIMEQ_INT@.
1143 extern int tvec_claimeq(struct tvec_state */*tv*/,
1144 const struct tvec_regty */*ty*/,
1145 const union tvec_misc */*arg*/,
1146 const char */*file*/, unsigned /*lno*/,
1147 const char */*expr*/);
1149 /*----- Benchmarking ------------------------------------------------------*/
1151 struct tvec_benchenv {
1152 struct tvec_env _env; /* benchmarking is an environment */
1153 struct bench_state **bst; /* benchmark state anchor or null */
1154 unsigned long niter; /* iterations done per unit */
1155 int riter, rbuf; /* iterations and buffer registers */
1156 const struct tvec_env *env; /* subordinate environment */
1159 struct tvec_benchctx {
1160 const struct tvec_benchenv *be; /* environment configuration */
1161 struct bench_state *bst; /* benchmark state */
1162 double dflt_target; /* default time in seconds */
1163 unsigned f; /* flags */
1164 #define TVBF_SETTRG 1u /* set `@target' */
1165 #define TVBF_SETMASK (TVBF_SETTRG)) /* mask of @TVBF_SET...@ */
1166 void *subctx; /* subsidiary environment context */
1169 extern struct bench_state *tvec_benchstate;
1171 /* --- Environment implementation --- *
1173 * The following special variables are supported.
1175 * * %|@target|% is the (approximate) number of seconds to run the
1178 * Unrecognized variables are passed to the subordinate environment, if there
1179 * is one. Other events are passed through to the subsidiary environment.
1182 extern tvec_envsetupfn tvec_benchsetup;
1183 extern tvec_envfindvarfn tvec_benchfindvar;
1184 extern tvec_envbeforefn tvec_benchbefore;
1185 extern tvec_envrunfn tvec_benchrun;
1186 extern tvec_envafterfn tvec_benchafter;
1187 extern tvec_envteardownfn tvec_benchteardown;
1189 #define TVEC_BENCHENV \
1190 { sizeof(struct tvec_benchctx), \
1192 tvec_benchfindvar, \
1196 tvec_benchteardown }
1197 #define TVEC_BENCHINIT TVEC_BENCHENV, &tvec_benchstate
1199 /* --- @tvec_benchreport@ --- *
1201 * Arguments: @const struct gprintf_ops *gops@ = print operations
1202 * @void *go@ = print destination
1203 * @unsigned unit@ = the unit being measured (~TVBU_...@)
1204 * @unsigned style@ = output style (@TVSF_...@)
1205 * @const struct bench_timing *tm@ = the benchmark result
1209 * Use: Formats a report about the benchmark performance. This
1210 * function is intended to be called on by an output @ebench@
1214 extern void tvec_benchreport
1215 (const struct gprintf_ops */*gops*/, void */*go*/,
1216 unsigned /*unit*/, unsigned /*style*/, const struct bench_timing */*tm*/);
1218 /*----- Remote execution --------------------------------------------------*/
1220 struct tvec_remoteenv;
1222 struct tvec_remotecomms {
1223 int infd, outfd; /* input and output descriptors */
1224 dbuf bout; /* output buffer */
1225 unsigned char *bin; /* input buffer */
1226 size_t binoff, binlen, binsz; /* input offset, length, and size */
1227 size_t t; /* temporary offset */
1228 unsigned f; /* flags */
1229 #define TVRF_BROKEN 0x0001u /* communications have failed */
1231 #define TVEC_REMOTECOMMS_INIT { -1, -1, DBUF_INIT, 0, 0, 0, 0, 0, 0 }
1233 struct tvec_remotectx {
1234 struct tvec_state *tv; /* test vector state */
1235 struct tvec_remotecomms rc; /* communication state */
1236 const struct tvec_remoteenv *re; /* environment configuration */
1237 void *subctx; /* subenvironment context */
1238 struct tvec_vardef vd; /* temporary variable definition */
1239 unsigned ver; /* protocol version */
1240 pid_t kid; /* child process id */
1241 int errfd; /* child stderr descriptor */
1242 lbuf errbuf; /* child stderr line buffer */
1243 dstr prgwant, progress; /* progress: wanted/reported */
1244 unsigned exwant, exit; /* exit status wanted/reported */
1245 #define TVRF_RCNMASK 0x0300u /* reconnection behaviour: */
1246 #define TVRCN_DEMAND 0x0000u /* connect on demand */
1247 #define TVRCN_SKIP 0x0100u /* skip unless connected */
1248 #define TVRCN_FORCE 0x0200u /* force reconnection */
1249 #define TVRF_MUFFLE 0x0400u /* muffle child stderr */
1250 #define TVRF_SETEXIT 0x0800u /* set `@exit' */
1251 #define TVRF_SETPRG 0x1000u /* set `@progress' */
1252 #define TVRF_SETRCN 0x2000u /* set `@reconnect' */
1253 #define TVRF_SETMASK (TVRF_SETEXIT | TVRF_SETPRG | TVRF_SETRCN)
1254 /* mask of @TVTF_SET...@ */
1257 typedef int tvec_connectfn(pid_t */*kid_out*/, int */*infd_out*/,
1258 int */*outfd_out*/, int */*errfd_out*/,
1259 struct tvec_state */*tv*/,
1260 const struct tvec_remoteenv */*env*/);
1261 /* A connection function. On entry, @tv@ holds the test-vector state, and
1262 * @env@ is the test group's remote environment structure, which will
1263 * typically really be some subclass of @struct tvec_remoteenv@ containing
1264 * additional parameters for establishing the child process.
1266 * On successful completion, the function stores input and output
1267 * descriptors (which need not be distinct) in @*infd_out@ and
1268 * @*outfd_out@, and returns zero; if it creates a child process, it should
1269 * additionally store the child's process-id in @*kid_out@ and store in
1270 * @*errfd_out@ a descriptor from which the child's error output can be
1271 * read. On error, the function should report an appropriate message via
1272 * @tvec_error@ and return %$-1$%.
1275 struct tvec_remoteenv_slots {
1276 tvec_connectfn *connect; /* connection function */
1277 const struct tvec_env *env; /* subsidiary environment */
1278 unsigned dflt_reconn; /* default reconnection */
1281 struct tvec_remoteenv {
1282 struct tvec_env _env;
1283 struct tvec_remoteenv_slots r;
1286 struct tvec_remotefork_slots {
1287 const struct tvec_test *tests; /* child tests (or null) */
1290 struct tvec_remotefork {
1291 struct tvec_env _env;
1292 struct tvec_remoteenv_slots r;
1293 struct tvec_remotefork_slots f;
1296 struct tvec_remoteexec_slots {
1297 const char *const *args; /* command line to execute */
1300 struct tvec_remoteexec {
1301 struct tvec_env _env;
1302 struct tvec_remoteenv_slots r;
1303 struct tvec_remoteexec_slots x;
1306 union tvec_remoteenv_subclass_kludge {
1307 struct tvec_env _env;
1308 struct tvec_remoteenv renv;
1309 struct tvec_remotefork fork;
1310 struct tvec_remoteexec exec;
1315 * We don't use the conventional encoding returned by the @wait@(2) family of
1316 * system calls because it's too hard for our flags type to decode. Instead,
1317 * we use our own encoding.
1319 * The exit code or signal number ends up in the `value' field in the low 12
1320 * bits; bit 12 is set if the value field holds a signal, and it if holds an
1321 * exit code. Bits 13--15 hold a code which describes the status of a child
1322 * process or connection.
1324 #define TVXF_VALMASK 0x0fffu /* value (exit code or signal) */
1325 #define TVXF_SIG 0x1000u /* value is signal, not exit code */
1326 #define TVXF_CAUSEMASK 0xe000u /* mask for cause bits */
1327 #define TVXST_RUN 0x0000u /* still running */
1328 #define TVXST_EXIT 0x2000u /* child exited */
1329 #define TVXST_KILL 0x4000u /* child killed by signal */
1330 #define TVXST_CONT 0x6000u /* child continued (?) */
1331 #define TVXST_STOP 0x8000u /* child stopped (?) */
1332 #define TVXST_DISCONN 0xa000u /* disconnected */
1333 #define TVXST_UNK 0xc000u /* unknown */
1334 #define TVXST_ERR 0xe000u /* local error prevented diagnosis */
1336 /* Remote environment. */
1337 extern tvec_envsetupfn tvec_remotesetup;
1338 extern tvec_envfindvarfn tvec_remotefindvar;
1339 extern tvec_envbeforefn tvec_remotebefore;
1340 extern tvec_envrunfn tvec_remoterun;
1341 extern tvec_envafterfn tvec_remoteafter;
1342 extern tvec_envteardownfn tvec_remoteteardown;
1343 #define TVEC_REMOTEENV \
1344 { sizeof(struct tvec_remotectx), \
1346 tvec_remotefindvar, \
1347 tvec_remotebefore, \
1350 tvec_remoteteardown }
1352 /* --- @tvec_setprogress@, @tvec_setprogress_v@ --- *
1354 * Arguments: @const char *status@ = progress status token format
1355 * @va_list ap@ = argument tail
1359 * Use: Reports the progress of a test execution to the client.
1361 * The framework makes use of tokens beginning with %|%|%:
1363 * * %|%IDLE|%: during the top-level server code;
1365 * * %|%SETUP|%: during the enclosing environment's @before@
1368 * * %|%RUN|%: during the environment's @run@ function, or the
1369 * test function; and
1371 * * %|%DONE|%: during the enclosing environment's @after@
1374 * The intent is that a test can use the progress token to check
1375 * that a function which is expected to crash does so at the
1376 * correct point, so it's expected that more complex test
1377 * functions and/or environments will set their own progress
1378 * tokens to reflect what's going on.
1381 extern PRINTF_LIKE(1, 2) int tvec_setprogress(const char */*status*/, ...);
1382 extern int tvec_setprogress_v(const char */*status*/, va_list */*ap*/);
1384 /* --- @tvec_remoteserver@ --- *
1386 * Arguments: @int infd@, @int outfd@ = input and output file descriptors
1387 * @const struct tvec_config *config@ = test configuration
1389 * Returns: Suggested exit code.
1391 * Use: Run a test server, reading packets from @infd@ and writing
1392 * responses and notifications to @outfd@, and invoking tests as
1393 * described by @config@.
1395 * This function is not particularly general purpose. It
1396 * expects to `take over' the process, and makes use of private
1400 extern int tvec_remoteserver(int /*infd*/, int /*outfd*/,
1401 const struct tvec_config */*config*/);
1403 extern tvec_connectfn tvec_fork, tvec_exec;
1405 #define TVEC_REMOTEFORK(subenv, tests) \
1406 TVEC_REMOTEENV, { tvec_fork, subenv }, { tests }
1408 #define TVEC_REMOTEEXEC(subenv, args) \
1409 TVEC_REMOTEENV, { tvec_exec, subenv }, { args }
1411 /*----- Timeouts ----------------------------------------------------------*/
1413 struct tvec_timeoutenv {
1414 struct tvec_env _env;
1415 int timer; /* the timer (@ITIMER_...@) */
1416 double t; /* time to wait (in seconds) */
1417 const struct tvec_env *env; /* subsidiary environment */
1420 struct tvec_timeoutctx {
1421 const struct tvec_timeoutenv *te; /* saved environment description */
1422 int timer; /* timer code (as overridden) */
1423 double t; /* time to wait (as overridden) */
1424 unsigned f; /* flags */
1425 #define TVTF_SETTMO 1u /* set `@timeout' */
1426 #define TVTF_SETTMR 2u /* set `@timer' */
1427 #define TVTF_SETMASK (TVTF_SETTMO | TVTF_SETTMR)
1428 /* mask of @TVTF_SET...@ */
1432 extern tvec_envsetupfn tvec_timeoutsetup;
1433 extern tvec_envfindvarfn tvec_timeoutfindvar;
1434 extern tvec_envbeforefn tvec_timeoutbefore;
1435 extern tvec_envrunfn tvec_timeoutrun;
1436 extern tvec_envafterfn tvec_timeoutafter;
1437 extern tvec_envteardownfn tvec_timeoutteardown;
1438 #define TVEC_TIMEOUTENV \
1439 { sizeof(struct tvec_timeoutctx), \
1440 tvec_timeoutsetup, \
1441 tvec_timeoutfindvar, \
1442 tvec_timeoutbefore, \
1444 tvec_timeoutafter, \
1445 tvec_timeoutteardown }
1446 #define TVEC_TIMEOUTINIT(timer, t) TVEC_TIMEOUTENV, timer, t
1448 /*----- Output functions --------------------------------------------------*/
1450 /* --- @tvec_strlevel@ --- *
1452 * Arguments: @unsigned level@ = level code
1454 * Returns: A human-readable description.
1456 * Use: Converts a level code into something that you can print in a
1460 extern const char *tvec_strlevel(unsigned /*level*/);
1462 /* --- @tvec_report@, @tvec_report_v@ --- *
1464 * Arguments: @struct tvec_state *tv@ = test-vector state
1465 * @const char *msg@, @va_list ap@ = error message
1469 * Use: Report an message with a given severity. Messages with level
1470 * @TVLEV_ERR@ or higher force a nonzero exit code.
1473 extern PRINTF_LIKE(3, 4)
1474 void tvec_report(struct tvec_state */*tv*/, unsigned /*level*/,
1475 const char */*msg*/, ...);
1476 extern void tvec_report_v(struct tvec_state */*tv*/, unsigned /*level*/,
1477 const char */*msg*/, va_list */*ap*/);
1479 /* --- @tvec_error@, @tvec_notice@ --- *
1481 * Arguments: @struct tvec_state *tv@ = test-vector state
1482 * @const char *msg@, @va_list ap@ = error message
1484 * Returns: The @tvec_error@ function returns %$-1$% as a trivial
1485 * convenience; @tvec_notice@ does not return a value.
1487 * Use: Report an error or a notice. Errors are distinct from test
1488 * failures, and indicate that a problem was encountered which
1489 * compromised the activity of testing. Notices are important
1490 * information which doesn't fit into any other obvious
1494 extern PRINTF_LIKE(2, 3)
1495 int tvec_error(struct tvec_state */*tv*/, const char */*msg*/, ...);
1496 extern PRINTF_LIKE(2, 3)
1497 void tvec_notice(struct tvec_state */*tv*/, const char */*msg*/, ...);
1499 /* --- @tvec_unkregerr@ --- *
1501 * Arguments: @struct tvec_state *tv@ = test-vector state
1502 * @const char *name@ = register or pseudoregister name
1506 * Use: Reports an error that the register or pseudoregister is
1510 extern int tvec_unkregerr(struct tvec_state */*tv*/, const char */*name*/);
1512 /* --- @tvec_dupregerr@ --- *
1514 * Arguments: @struct tvec_state *tv@ = test-vector state
1515 * @const char *name@ = register or pseudoregister name
1519 * Use: Reports an error that the register or pseudoregister has been
1520 * assigned already in the current test.
1523 extern int tvec_dupregerr(struct tvec_state */*tv*/, const char */*name*/);
1525 /* --- @tvec_humanoutput@ --- *
1527 * Arguments: @FILE *fp@ = output file to write on
1528 * @unsigned style@ = output style (@TVSF_...@)
1530 * Returns: An output formatter.
1532 * Use: Return an output formatter which writes on @fp@ with the
1533 * expectation that a human will be watching and interpreting
1534 * the output. If @fp@ denotes a terminal, the display shows a
1535 * `scoreboard' indicating the outcome of each test case
1536 * attempted, and may in addition use colour and other
1540 extern struct tvec_output *tvec_humanoutput(FILE */*fp*/);
1542 /* --- @tvec_machineoutput@ --- *
1544 * Arguments: @FILE *fp@ = output file to write on
1546 * Returns: An output formatter.
1548 * Use: Return an output formatter which writes on @fp@ in a
1549 * moderately simple machine-readable format.
1552 struct tvec_output *tvec_machineoutput(FILE *fp);
1554 /* --- @tvec_tapoutput@ --- *
1556 * Arguments: @FILE *fp@ = output file to write on
1557 * @unsigned style@ = output style (@TVSF_...@)
1559 * Returns: An output formatter.
1561 * Use: Return an output formatter which writes on @fp@ in `TAP'
1562 * (`Test Anything Protocol') format.
1564 * TAP comes from the Perl community, but has spread rather
1565 * further. This driver currently produces TAP version 14, but
1566 * pretends to be version 13. The driver produces a TAP `test
1567 * point' -- i.e., a result reported as `ok' or `not ok' -- for
1568 * each input test group. Failure reports and register dumps
1569 * are produced as diagnostic messages before the final group
1570 * result. (TAP permits structuerd YAML data after the
1571 * test-point result, which could be used to report details, but
1572 * (a) postponing the details until after the report is
1573 * inconvenient, and (b) there is no standardization for the
1574 * YAML anyway, so in practice it's no more useful than the
1575 * unstructured diagnostics.
1578 extern struct tvec_output *tvec_tapoutput(FILE */*fp*/);
1580 /* --- @tvec_dfltoutput@ --- *
1582 * Arguments: @FILE *fp@ = output file to write on
1584 * Returns: An output formatter.
1586 * Use: Selects and instantiates an output formatter suitable for
1587 * writing on @fp@. The policy is subject to change, but
1588 * currently the `human' output format is selected if @fp@ is
1589 * interactive (i.e., if @isatty(fileno(fp))@ is true), and
1590 * otherwise the `tap' format is used.
1593 extern struct tvec_output *tvec_dfltout(FILE */*fp*/);
1595 /*------ Serialization utilities ------------------------------------------*/
1597 /* Serialization format.
1599 * The `candidate register definitions' are those entries @r@ in the @regs@
1600 * vector whose index @r.i@ is strictly less than @nr@. The `selected
1601 * register definitions' are those candidate register definitions @r@ for
1602 * which the indicated register @rv[r.i]@ has the @TVRF_LIVE@ flag set. The
1603 * serialized output begins with a header bitmap: if there are %$n$%
1604 * candidate register definitions then the header bitmap consists of %$\lceil
1605 * n/8 \rceil$% bytes. Bits are ordered starting from the least significant
1606 * bit of the first byte, end ending at the most significant bit of the final
1607 * byte. The bit corresponding to a candidate register definition is set if
1608 * and only if that register defintion is selected. The header bitmap is
1609 * then followed by the serializations of the selected registers -- i.e., for
1610 * each selected register definition @r@, the serialized value of register
1611 * @rv[r.i]@ -- simply concatenated together, with no padding or alignment.
1614 /* --- @tvec_serialize@ --- *
1616 * Arguments: @const struct tvec_reg *rv@ = vector of registers
1617 * @buf *b@ = buffer to write on
1618 * @const struct tvec_regdef *regs@ = vector of register
1619 * descriptions, terminated by an entry with a null
1621 * @unsigned nr@ = number of entries in the @rv@ vector
1622 * @size_t regsz@ = true size of each element of @rv@
1624 * Returns: Zero on success, %$-1$% on failure.
1626 * Use: Serialize a collection of register values.
1628 * The serialized output is written to the buffer @b@. Failure
1629 * can be caused by running out of buffer space, or a failing
1633 extern int tvec_serialize(const struct tvec_reg */*rv*/, buf */*b*/,
1634 const struct tvec_regdef */*regs*/,
1635 unsigned /*nr*/, size_t /*regsz*/);
1637 /* --- @tvec_deserialize@ --- *
1639 * Arguments: @struct tvec_reg *rv@ = vector of registers
1640 * @buf *b@ = buffer to write on
1641 * @const struct tvec_regdef *regs@ = vector of register
1642 * descriptions, terminated by an entry with a null
1644 * @unsigned nr@ = number of entries in the @rv@ vector
1645 * @size_t regsz@ = true size of each element of @rv@
1647 * Returns: Zero on success, %$-1$% on failure.
1649 * Use: Deserialize a collection of register values.
1651 * The size of the register vector @nr@ and the register
1652 * definitions @regs@ must match those used when producing the
1653 * serialization. For each serialized register value,
1654 * deserialize and store the value into the appropriate register
1655 * slot, and set the @TVRF_LIVE@ flag on the register. See
1656 * @tvec_serialize@ for a description of the format.
1658 * Failure results only from a failing register type handler.
1661 extern int tvec_deserialize(struct tvec_reg */*rv*/, buf */*b*/,
1662 const struct tvec_regdef */*regs*/,
1663 unsigned /*nr*/, size_t /*regsz*/);
1665 /*----- Input utilities ---------------------------------------------------*/
1667 /* These are provided by the core for the benefit of type @parse@ methods,
1668 * and test-environment @set@ functions, which get to read from the test
1669 * input file. The latter are usually best implemented by calling on the
1672 * The two main rules are as follows.
1674 * * Leave the file position at the beginning of the line following
1675 * whatever it was that you read.
1677 * * When you read and consume a newline (which you do at least once, by
1678 * the previous rule), then increment @tv->lno@ to keep track of the
1679 * current line number.
1682 /* --- @tvec_syntax@, @tvec_syntax_v@ --- *
1684 * Arguments: @struct tvec_state *tv@ = test-vector state
1685 * @int ch@ = the character found (in @fgetc@ format)
1686 * @const char *expect@, @va_list ap@ = what was expected
1690 * Use: Report a syntax error quoting @ch@ and @expect@. If @ch@ is
1691 * a newline, then back up so that it can be read again (e.g.,
1692 * by @tvec_flushtoeol@ or @tvec_nexttoken@, which will also
1693 * advance the line number).
1696 extern PRINTF_LIKE(3, 4)
1697 int tvec_syntax(struct tvec_state */*tv*/, int /*ch*/,
1698 const char */*expect*/, ...);
1699 extern int tvec_syntax_v(struct tvec_state */*tv*/, int /*ch*/,
1700 const char */*expect*/, va_list */*ap*/);
1702 /* --- @tvec_skipspc@ --- *
1704 * Arguments: @struct tvec_state *tv@ = test-vector state
1708 * Use: Advance over any whitespace characters other than newlines.
1709 * This will stop at `;', end-of-file, or any other kind of
1710 * non-whitespace; and it won't consume a newline.
1713 extern void tvec_skipspc(struct tvec_state */*tv*/);
1715 /* --- @tvec_flushtoeol@ --- *
1717 * Arguments: @struct tvec_state *tv@ = test-vector state
1718 * @unsigned f@ = flags (@TVFF_...@)
1720 * Returns: Zero on success, %$-1$% on error.
1722 * Use: Advance to the start of the next line, consuming the
1723 * preceding newline.
1725 * A syntax error is reported if no newline character is found,
1726 * i.e., the file ends in mid-line. A syntax error is also
1727 * reported if material other than whitespace or a comment is
1728 * found before the end of the line end, and @TVFF_ALLOWANY@ is
1729 * not set in @f@. The line number count is updated
1733 #define TVFF_ALLOWANY 1u
1734 extern int tvec_flushtoeol(struct tvec_state */*tv*/, unsigned /*f*/);
1736 /* --- @tvec_nexttoken@ --- *
1738 * Arguments: @struct tvec_state *tv@ = test-vector state
1740 * Returns: Zero if there is a next token which can be read; %$-1$% if no
1741 * token is available.
1743 * Use: Advance to the next whitespace-separated token, which may be
1746 * Tokens are separated by non-newline whitespace, comments, and
1747 * newlines followed by whitespace; a newline /not/ followed by
1748 * whitespace instead begins the next assignment, and two
1749 * newlines separated only by whitespace terminate the data for
1752 * If this function returns zero, then the next character in the
1753 * file begins a suitable token which can be read and
1754 * processed. If it returns %$-1$% then there is no such token,
1755 * and the file position is left correctly. The line number
1756 * count is updated appropriately.
1759 extern int tvec_nexttoken(struct tvec_state */*tv*/);
1761 /* --- @tvec_readword@, @tvec_readword_v@ --- *
1763 * Arguments: @struct tvec_state *tv@ = test-vector state
1764 * @dstr *d@ = string to append the word to
1765 * @const char **p_inout@ = pointer into string, updated
1766 * @const char *delims@ = additional delimiters to stop at
1767 * @const char *expect@, @va_list ap@ = what was expected
1769 * Returns: Zero on success, %$-1$% on failure.
1771 * Use: A `word' consists of characters other than whitespace, null
1772 * characters, and other than those listed in @delims@;
1773 * furthermore, a word does not begin with a `;'. (If you want
1774 * reading to stop at comments not preceded by whitespace, then
1775 * include `;' in @delims@. This is a common behaviour.)
1777 * If there is no word beginning at the current file position,
1778 * then return %$-1$%; furthermore, if @expect@ is not null,
1779 * then report an appropriate error via @tvec_syntax@.
1781 * Otherwise, the word is accumulated in @d@ and zero is
1782 * returned; if @d@ was not empty at the start of the call, the
1783 * newly read word is separated from the existing material by a
1784 * single space character. Since null bytes are never valid
1785 * word constituents, a null terminator is written to @d@, and
1786 * it is safe to treat the string in @d@ as being null-
1789 * If @p_inout@ is not null, then @*p_inout@ must be a pointer
1790 * into @d->buf@, which will be adjusted so that it will
1791 * continue to point at the same position even if the buffer is
1792 * reallocated. As a subtle tweak, if @*p_inout@ initially
1793 * points at the end of the buffer, then it will be adjusted to
1794 * point at the beginning of the next word, rather than at the
1795 * additional intervening space.
1798 extern PRINTF_LIKE(5, 6)
1799 int tvec_readword(struct tvec_state */*tv*/, dstr */*d*/,
1800 const char **/*p_inout*/, const char */*delims*/,
1801 const char */*expect*/, ...);
1802 extern int tvec_readword_v(struct tvec_state */*tv*/, dstr */*d*/,
1803 const char **/*p_inout*/, const char */*delims*/,
1804 const char */*expect*/, va_list */*ap*/);
1806 /*----- Integer types: signed and unsigned --------------------------------*/
1808 /* Integers may be input in decimal, hex, binary, or octal, following
1809 * approximately usual conventions.
1811 * * Signed integers may be preceded with a `+' or `-' sign.
1813 * * Decimal integers are just a sequence of decimal digits `0' ... `9'.
1815 * * Octal integers are a sequence of digits `0' ... `7', preceded by `0o'
1818 * * Hexadecimal integers are a sequence of digits `0' ... `9', `a'
1819 * ... `f', or `A' ... `F', preceded by `0x' or `0X'.
1821 * * Radix-B integers are a sequence of digits `0' ... `9', `a' ... `f', or
1822 * `A' ... `F', each with value less than B, preceded by `Br' or `BR',
1823 * where 0 < B < 36 is expressed in decimal without any leading `0' or
1824 * internal underscores `_'.
1826 * * A digit sequence may contain internal underscore `_' separators, but
1827 * not before or after all of the digits; and two consecutive `_'
1828 * characters are not permitted.
1831 extern const struct tvec_regty tvty_int, tvty_uint;
1833 /* The @arg.p@ slot may be null or a pointer to @struct tvec_irange@ or
1834 * @struct tvec_urange@ as appropriate. The bounds are inclusive; use, e.g.,
1835 * @LONG_MAX@ explicitly if one or the other bound is logically inapplicable.
1837 struct tvec_irange { long min, max; };
1838 struct tvec_urange { unsigned long min, max; };
1840 /* Bounds corresponding to common integer types. */
1841 extern const struct tvec_irange
1842 tvrange_schar, tvrange_short, tvrange_int, tvrange_long,
1843 tvrange_sbyte, tvrange_i16, tvrange_i32;
1844 extern const struct tvec_urange
1845 tvrange_uchar, tvrange_ushort, tvrange_uint, tvrange_ulong, tvrange_size,
1846 tvrange_byte, tvrange_u16, tvrange_u32;
1848 /* --- @tvec_claimeq_int@, @TVEC_CLAIMEQ_INT@ --- *
1850 * Arguments: @struct tvec_state *tv@ = test-vector state
1851 * @long i0, i1@ = two signed integers
1852 * @const char *file@, @unsigned @lno@ = calling file and line
1853 * @const char *expr@ = the expression to quote on failure
1855 * Returns: Nonzero if @i0@ and @i1@ are equal, otherwise zero.
1857 * Use: Check that values of @i0@ and @i1@ are equal. As for
1858 * @tvec_claim@ above, a test case is automatically begun and
1859 * ended if none is already underway. If the values are
1860 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
1861 * mismatched values are dumped: @i0@ is printed as the output
1862 * value and @i1@ is printed as the input reference.
1864 * The @TVEC_CLAIM_INT@ macro is similar, only it (a) identifies
1865 * the file and line number of the call site automatically, and
1866 * (b) implicitly quotes the source text of the @i0@ and @i1@
1867 * arguments in the failure message.
1870 extern int tvec_claimeq_int(struct tvec_state */*tv*/,
1871 long /*i0*/, long /*i1*/,
1872 const char */*file*/, unsigned /*lno*/,
1873 const char */*expr*/);
1874 #define TVEC_CLAIMEQ_INT(tv, i0, i1) \
1875 (tvec_claimeq_int(tv, i0, i1, __FILE__, __LINE__, #i0 " /= " #i1))
1877 /* --- @tvec_claimeq_uint@, @TVEC_CLAIMEQ_UINT@ --- *
1879 * Arguments: @struct tvec_state *tv@ = test-vector state
1880 * @unsigned long u0, u1@ = two unsigned integers
1881 * @const char *file@, @unsigned @lno@ = calling file and line
1882 * @const char *expr@ = the expression to quote on failure
1884 * Returns: Nonzero if @u0@ and @u1@ are equal, otherwise zero.
1886 * Use: Check that values of @u0@ and @u1@ are equal. As for
1887 * @tvec_claim@ above, a test case is automatically begun and
1888 * ended if none is already underway. If the values are
1889 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
1890 * mismatched values are dumped: @u0@ is printed as the output
1891 * value and @u1@ is printed as the input reference.
1893 * The @TVEC_CLAIM_UINT@ macro is similar, only it (a)
1894 * identifies the file and line number of the call site
1895 * automatically, and (b) implicitly quotes the source text of
1896 * the @u0@ and @u1@ arguments in the failure message.
1899 extern int tvec_claimeq_uint(struct tvec_state */*tv*/,
1900 unsigned long /*u0*/, unsigned long /*u1*/,
1901 const char */*file*/, unsigned /*lno*/,
1902 const char */*expr*/);
1903 #define TVEC_CLAIMEQ_UINT(tv, u0, u1) \
1904 (tvec_claimeq_uint(tv, u0, u1, __FILE__, __LINE__, #u0 " /= " #u1))
1906 /*----- Size type ---------------------------------------------------------*/
1908 /* A size is an unsigned integer followed by an optional unit specifier
1909 * consisting of an SI unit prefix and (optionally) the letter `B'.
1912 extern const struct tvec_regty tvty_size;
1914 /* --- @tvec_claimeq_size@ --- *
1916 * Arguments: @struct tvec_state *tv@ = test-vector state
1917 * @unsigned long sz0, sz1@ = two sizes
1918 * @const char *file@, @unsigned @lno@ = calling file and line
1919 * @const char *expr@ = the expression to quote on failure
1921 * Returns: Nonzero if @sz0@ and @sz1@ are equal, otherwise zero.
1923 * Use: Check that values of @u0@ and @u1@ are equal. As for
1924 * @tvec_claim@ above, a test case is automatically begun and
1925 * ended if none is already underway. If the values are
1926 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
1927 * mismatched values are dumped: @u0@ is printed as the output
1928 * value and @u1@ is printed as the input reference.
1930 * The @TVEC_CLAIM_SIZE@ macro is similar, only it (a)
1931 * identifies the file and line number of the call site
1932 * automatically, and (b) implicitly quotes the source text of
1933 * the @u0@ and @u1@ arguments in the failure message.
1936 int tvec_claimeq_size(struct tvec_state *tv,
1937 unsigned long sz0, unsigned long sz1,
1938 const char *file, unsigned lno, const char *expr);
1939 #define TVEC_CLAIMEQ_UINT(tv, u0, u1) \
1940 (tvec_claimeq_uint(tv, u0, u1, __FILE__, __LINE__, #u0 " /= " #u1))
1942 /*----- Floating-point type -----------------------------------------------*/
1944 /* Floating-point values are either NaN (%|#nan|%, if supported by the
1945 * platform); positive or negative infinity (%|#inf|%, %|+#inf|%, or
1946 * %|#+inf|% (preferring the last), and %|-#inf|% or %|#-inf|% (preferring
1947 * the latter), if supported by the platform); or a number in strtod(3)
1950 * The comparison rules for floating-point numbers are complex: see
1951 * @tvec_claimeqish_float@ for details.
1954 extern const struct tvec_regty tvty_float;
1956 struct tvec_floatinfo {
1957 /* Details about acceptable floating-point values. */
1959 unsigned f; /* flags (@TVFF_...@ bits) */
1960 #define TVFF_NOMIN 1u /* ignore @min@ (allow -inf) */
1961 #define TVFF_NOMAX 2u /* ignore @max@ (allow +inf) */
1962 #define TVFF_NANOK 4u /* permit NaN */
1963 #define TVFF_EQMASK 0xf0 /* how to compare */
1964 #define TVFF_EXACT 0x00 /* must equal exactly */
1965 #define TVFF_ABSDELTA 0x10 /* must be within @delta@ */
1966 #define TVFF_RELDELTA 0x20 /* diff < @delta@ fraction */
1967 double min, max; /* smallest/largest value allowed */
1968 double delta; /* maximum tolerable difference */
1971 extern const struct tvec_floatinfo tvflt_finite, tvflt_nonneg;
1973 /* --- @tvec_claimeqish_float@, @TVEC_CLAIMEQISH_FLOAT@ --- *
1975 * Arguments: @struct tvec_state *tv@ = test-vector state
1976 * @double f0, f1@ = two floating-point numbers
1977 * @unsigned f@ = flags (@TVFF_...@)
1978 * @double delta@ = maximum tolerable difference
1979 * @const char *file@, @unsigned @lno@ = calling file and line
1980 * @const char *expr@ = the expression to quote on failure
1982 * Returns: Nonzero if @f0@ and @f1@ are sufficiently close, otherwise
1985 * Use: Check that values of @f0@ and @f1@ are sufficiently close.
1986 * As for @tvec_claim@ above, a test case is automatically begun
1987 * and ended if none is already underway. If the values are
1988 * too far apart, then @tvec_fail@ is called, quoting @expr@,
1989 * and the mismatched values are dumped: @f0@ is printed as the
1990 * output value and @f1@ is printed as the input reference.
1992 * The details for the comparison are as follows.
1994 * * A NaN value matches any other NaN, and nothing else.
1996 * * An infinity matches another infinity of the same sign,
1999 * * If @f&TVFF_EQMASK@ is @TVFF_EXACT@, then any
2000 * representable number matches only itself: in particular,
2001 * positive and negative zero are considered distinct.
2002 * (This allows tests to check that they land on the correct
2003 * side of branch cuts, for example.)
2005 * * If @f&TVFF_EQMASK@ is @TVFF_ABSDELTA@, then %$x$% matches
2006 * %$y$% when %$|x - y| < \delta$%.
2008 * * If @f&TVFF_EQMASK@ is @TVFF_RELDELTA@, then %$x$% matches
2009 * %$y$% when %$|1 - x/y| < \delta$%. (Note that this
2010 * criterion is asymmetric. Write %$x \approx_\delta y$%
2011 * if and only if %$|1 - x/y < \delta$%. Then, for example,
2012 * if %$y/(1 + \delta) < x < y (1 - \delta)$%, then
2013 * %$x \approx_\delta y$%, but %$y \not\approx_\delta x$%.)
2015 * The @TVEC_CLAIM_FLOAT@ macro is similar, only it (a)
2016 * identifies the file and line number of the call site
2017 * automatically, and (b) implicitly quotes the source text of
2018 * the @f0@ and @f1@ arguments (and @delta@) in the failure
2022 extern int tvec_claimeqish_float(struct tvec_state */*tv*/,
2023 double /*f0*/, double /*f1*/,
2024 unsigned /*f*/, double /*delta*/,
2025 const char */*file*/, unsigned /*lno*/,
2026 const char */*expr*/);
2027 #define TVEC_CLAIMEQISH_FLOAT(tv, f0, f1, f, delta) \
2028 (tvec_claimeqish_float(tv, f0, f1, f, delta, __FILE__, __LINE__, \
2029 #f0 " /= " #f1 " (+/- " #delta ")"))
2031 /* --- @tvec_claimeq_float@, @TVEC_CLAIMEQ_FLOAT@ --- *
2033 * Arguments: @struct tvec_state *tv@ = test-vector state
2034 * @double f0, f1@ = two floating-point numbers
2035 * @const char *file@, @unsigned @lno@ = calling file and line
2036 * @const char *expr@ = the expression to quote on failure
2038 * Returns: Nonzero if @f0@ and @u1@ are identical, otherwise zero.
2040 * Use: Check that values of @f0@ and @f1@ are identical. The
2041 * function is exactly equivalent to @tvec_claimeqish_float@
2042 * with @f == TVFF_EXACT@; the macro is similarly like
2043 * @TVEC_CLAIMEQISH_FLOAT@ with @f == TVFF_EXACT@, except that
2044 * it doesn't bother to quote a delta.
2047 extern int tvec_claimeq_float(struct tvec_state */*tv*/,
2048 double /*f0*/, double /*f1*/,
2049 const char */*file*/, unsigned /*lno*/,
2050 const char */*expr*/);
2051 #define TVEC_CLAIMEQ_FLOAT(tv, f0, f1) \
2052 (tvec_claimeq_float(tv, f0, f1, __FILE__, __LINE__, #f0 " /= " #f1))
2054 /*----- Durations ---------------------------------------------------------*/
2056 /* A duration measures a time interval in seconds. The input format consists
2057 * of a nonnegative decimal floating-point number in @strtod@ format followed
2058 * by an optional unit specification.
2061 extern const struct tvec_regty tvty_duration;
2063 /* --- @tvec_parsedurunit@ --- *
2065 * Arguments: @double *scale_out@ = where to leave the scale
2066 * @const char **p_inout@ = input unit string, updated
2068 * Returns: Zero on success, %$-1$% on error.
2070 * Use: If @*p_inout@ begins with a unit string followed by the end
2071 * of the string or some non-alphanumeric character, then store
2072 * the corresponding scale factor in @*scale_out@, advance
2073 * @*p_inout@ past the unit string, and return zero. Otherwise,
2077 extern int tvec_parsedurunit(double */*scale_out*/,
2078 const char **/*p_inout*/);
2080 /* --- @tvec_claimeqish_duration@, @TVEC_CLAIMEQISH_DURATION@ --- *
2082 * Arguments: @struct tvec_state *tv@ = test-vector state
2083 * @double to, t1@ = two durations
2084 * @unsigned f@ = flags (@TVFF_...@)
2085 * @double delta@ = maximum tolerable difference
2086 * @const char *file@, @unsigned @lno@ = calling file and line
2087 * @const char *expr@ = the expression to quote on failure
2089 * Returns: Nonzero if @t0@ and @t1@ are sufficiently close, otherwise
2092 * Use: Check that values of @t0@ and @t1@ are sufficiently close.
2093 * This is essentially the same as @tvec_claimeqish_float@, only
2094 * it dumps the values as durations on a mismatch.
2096 * The @TVEC_CLAIM_FLOAT@ macro is similar, only it (a)
2097 * identifies the file and line number of the call site
2098 * automatically, and (b) implicitly quotes the source text of
2099 * the @t0@ and @t1@ arguments (and @delta@) in the failure
2103 extern int tvec_claimeqish_duration(struct tvec_state */*tv*/,
2104 double /*t0*/, double /*t1*/,
2105 unsigned /*f*/, double /*delta*/,
2106 const char */*file*/, unsigned /*lno*/,
2107 const char */*expr*/);
2108 #define TVEC_CLAIMEQISH_DURATION(tv, t0, t1, f, delta) \
2109 (tvec_claimeqish_duration(tv, t0, t1, f, delta, __FILE__, __LINE__, \
2110 #t0 " /= " #t1 " (+/- " #delta ")"))
2112 /* --- @tvec_claimeq_duration@, @TVEC_CLAIMEQ_DURATION@ --- *
2114 * Arguments: @struct tvec_state *tv@ = test-vector state
2115 * @double t0, t1@ = two durations
2116 * @const char *file@, @unsigned @lno@ = calling file and line
2117 * @const char *expr@ = the expression to quote on failure
2119 * Returns: Nonzero if @t0@ and @t1@ are identical, otherwise zero.
2121 * Use: Check that values of @t0@ and @t1@ are identical. The
2122 * function is exactly equivalent to @tvec_claimeqish_duration@
2123 * with @f == TVFF_EXACT@; the macro is similarly like
2124 * @TVEC_CLAIMEQISH_DURATION@ with @f == TVFF_EXACT@, except
2125 * that it doesn't bother to quote a delta.
2128 int tvec_claimeq_duration(struct tvec_state */*tv*/,
2129 double /*t0*/, double /*t1*/,
2130 const char */*file*/, unsigned /*lno*/,
2131 const char */*expr*/);
2132 #define TVEC_CLAIMEQ_DURATION(tv, t0, t1) \
2133 (tvec_claimeq_float(tv, t0, t1, __FILE__, __LINE__, #t0 " /= " #t1))
2135 /*----- Enumerated types --------------------------------------------------*/
2137 /* An enumeration describes a set of values of some underlying type, each of
2138 * which has a symbolic name. Values outside of the defined set can occur --
2139 * on output, because of bugs in the tested code, or on input to test
2140 * handling of unexpected values.
2142 * There is a distinct enumerated type for each of the branches of
2143 * @tvec_misc@. In the following, we write @t@ for the type code, which is
2144 * @i@ for signed integer, @u@ for unsigned integer, @f@ for floating-point,
2145 * and @p@ for pointer.
2147 * On input, an enumerated value may be given by name or as a literal value.
2148 * For enumerations based on numeric types, the literal values can be written
2149 * in the same syntax as the underlying values. For enumerations based on
2150 * pointers, the only permitted literal is %|#nil|%, which denotes a null
2151 * pointer. On output, names are preferred (with the underlying value given
2155 #define DEFENUMTY(tag, ty, slot) \
2156 extern const struct tvec_regty tvty_##slot##enum;
2157 TVEC_MISCSLOTS(DEFENUMTY)
2160 /* A @struct tvec_tassoc@ associates a string tag with a value. */
2161 #define DEFASSOC(tag_, ty, slot) \
2162 struct tvec_##slot##assoc { const char *tag; ty slot; };
2163 TVEC_MISCSLOTS(DEFASSOC)
2166 #define TVEC_ENDENUM { 0, 0 }
2168 /* Information about an enumerated type. */
2169 #define DEFINFO(tag, ty, slot) \
2170 struct tvec_##slot##enuminfo { \
2171 const char *name; /* type name for diagnostics */ \
2172 const struct tvec_##slot##assoc *av; /* name/value mappings */ \
2173 EXTRA_##tag##_INFOSLOTS /* type-specific extra info */ \
2176 #define EXTRA_INT_INFOSLOTS \
2177 const struct tvec_irange *ir; /* allowed range of raw values */
2179 #define EXTRA_UINT_INFOSLOTS \
2180 const struct tvec_urange *ur; /* allowed range of raw values */
2182 #define EXTRA_FLT_INFOSLOTS \
2183 const struct tvec_floatinfo *fi; /* range and matching policy */
2185 #define EXTRA_PTR_INFOSLOTS /* (nothing) */
2187 TVEC_MISCSLOTS(DEFINFO)
2189 #undef EXTRA_INT_INFOSLOTS
2190 #undef EXTRA_UINT_INFOSLOTS
2191 #undef EXTRA_FLT_INFOSLOTS
2192 #undef EXTRA_PTR_INFOSLOTS
2196 /* Standard enumerations. */
2197 extern const struct tvec_ienuminfo tvenum_bool;
2198 extern const struct tvec_ienuminfo tvenum_cmp;
2200 /* --- @tvec_claimeq_tenum@, @TVEC_CLAIMEQ_TENUM@ --- *
2202 * Arguments: @struct tvec_state *tv@ = test-vector state
2203 * @const struct tvec_typeenuminfo *ei@ = enumeration type info
2204 * @ty t0, t1@ = two values
2205 * @const char *file@, @unsigned @lno@ = calling file and line
2206 * @const char *expr@ = the expression to quote on failure
2208 * Returns: Nonzero if @t0@ and @t1@ are equal, otherwise zero.
2210 * Use: Check that values of @t0@ and @t1@ are equal. As for
2211 * @tvec_claim@ above, a test case is automatically begun and
2212 * ended if none is already underway. If the values are
2213 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
2214 * mismatched values are dumped: @t0@ is printed as the output
2215 * value and @t1@ is printed as the input reference.
2217 * The @TVEC_CLAIM_TENUM@ macro is similar, only it (a)
2218 * identifies the file and line number of the call site
2219 * automatically, and (b) implicitly quotes the source text of
2220 * the @t0@ and @t1@ arguments in the failure message.
2223 #define DECLCLAIM(tag, ty, slot) \
2224 extern int tvec_claimeq_##slot##enum \
2225 (struct tvec_state */*tv*/, \
2226 const struct tvec_##slot##enuminfo */*ei*/, \
2227 ty /*t0*/, ty /*t1*/, \
2228 const char */*file*/, unsigned /*lno*/, const char */*expr*/);
2229 TVEC_MISCSLOTS(DECLCLAIM)
2231 #define TVEC_CLAIMEQ_IENUM(tv, ei, i0, i1) \
2232 (tvec_claimeq_ienum(tv, ei, i0, i1, \
2233 __FILE__, __LINE__, #i0 " /= " #i1))
2234 #define TVEC_CLAIMEQ_UENUM(tv, ei, u0, u1) \
2235 (tvec_claimeq_uenum(tv, ei, u0, u1, \
2236 __FILE__, __LINE__, #u0 " /= " #u1))
2237 #define TVEC_CLAIMEQ_FENUM(tv, ei, f0, f1) \
2238 (tvec_claimeq_fenum(tv, ei, f0, f1, \
2239 __FILE__, __LINE__, #f0 " /= " #f1))
2240 #define TVEC_CLAIMEQ_PENUM(tv, ei, p0, p1) \
2241 (tvec_claimeq_penum(tv, ei, p0, p1, \
2242 __FILE__, __LINE__, #p0 " /= " #p1))
2244 /*----- Flags type --------------------------------------------------------*/
2246 /* A flags value packs a number of fields into a single nonnegative integer.
2247 * Symbolic names are associated with the possible values of the various
2248 * fields; more precisely, each name is associated with a value and a
2251 * The input syntax is a sequence of items separated by `%|||%' signs. Each
2252 * item may be the symbolic name of a field value, or a literal unsigned
2253 * integer. The masks associated with the given symbolic names must be
2254 * disjoint. The resulting numerical value is simply the bitwise OR of the
2257 * On output, the table of symbolic names and their associated values and
2258 * masks is repeatedly scanned, in order, to find disjoint matches -- i.e.,
2259 * entries whose value matches the target value in the bit positions
2260 * indicated by the mask, and whose mask doesn't overlap with any previously
2261 * found matches; the names are then output, separated by `%|||%'. Any
2262 * remaining nonzero bits not covered by any of the matching masks are output
2263 * as a single literal integer, in hex.
2266 extern const struct tvec_regty tvty_flags;
2269 /* Definition of a single flag or bitfield value.
2271 * Each named setting comes with a value @v@ and a mask @m@; the mask
2272 * should cover all of the value bits, i.e., @(v&~m) == 0@.
2275 const char *tag; /* name */
2276 unsigned long m, v; /* mask and value */
2279 #define TVEC_ENDFLAGS { 0, 0, 0 }
2281 struct tvec_flaginfo {
2282 /* Information about a flags type. */
2284 const char *name; /* type name for diagnostics */
2285 const struct tvec_flag *fv; /* name/mask/value mappings */
2286 const struct tvec_urange *range; /* permitted range for literals */
2289 /* --- @tvec_claimeq_flags@, @TVEC_CLAIMEQ_FLAGS@ --- *
2291 * Arguments: @struct tvec_state *tv@ = test-vector state
2292 * @const struct tvec_flaginfo *fi@ = flags type info
2293 * @unsigned long f0, f1@ = two values
2294 * @const char *file@, @unsigned @lno@ = calling file and line
2295 * @const char *expr@ = the expression to quote on failure
2297 * Returns: Nonzero if @f0@ and @f1@ are equal, otherwise zero.
2299 * Use: Check that values of @f0@ and @f1@ are equal. As for
2300 * @tvec_claim@ above, a test case is automatically begun and
2301 * ended if none is already underway. If the values are
2302 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
2303 * mismatched values are dumped: @f0@ is printed as the output
2304 * value and @f1@ is printed as the input reference.
2306 * The @TVEC_CLAIM_FLAGS@ macro is similar, only it (a)
2307 * identifies the file and line number of the call site
2308 * automatically, and (b) implicitly quotes the source text of
2309 * the @f0@ and @f1@ arguments in the failure message.
2312 extern int tvec_claimeq_flags(struct tvec_state */*tv*/,
2313 const struct tvec_flaginfo */*fi*/,
2314 unsigned long /*f0*/, unsigned long /*f1*/,
2315 const char */*file*/, unsigned /*lno*/,
2316 const char */*expr*/);
2317 #define TVEC_CLAIMEQ_FLAGS(tv, fi, f0, f1) \
2318 (tvec_claimeq_flags(tv, fi, f0, f1, \
2319 __FILE__, __LINE__, #f0 " /= " #f1))
2321 /*----- Character type ----------------------------------------------------*/
2323 /* A character value holds a character, as read by @fgetc@. The special
2324 * @EOF@ value can also be represented.
2326 * On input, a character value can be given by symbolic name, with a leading
2327 * `%|#|%'; or a character or `%|\|%'-escape sequence, optionally in single
2330 * The following escape sequences and character names are recognized.
2332 * * `%|#eof|%' is the special end-of-file marker.
2334 * * `%|#nul|%' is the NUL character, sometimes used to terminate strings.
2336 * * `%|bell|%', `%|bel|%', `%|ding|%', or `%|\a|%' is the BEL character
2337 * used to ring the terminal bell (or do some other thing to attract the
2338 * user's attention).
2340 * * %|#backspace|%, %|#bs|%, or %|\b|% is the backspace character, used to
2341 * move the cursor backwords by one cell.
2343 * * %|#escape|% %|#esc|%, or%|\e|% is the escape character, used to
2344 * introduce special terminal commands.
2346 * * %|#formfeed|%, %|#ff|%, or %|\f|% is the formfeed character, used to
2347 * separate pages of text.
2349 * * %|#newline|%, %|#linefeed|%, %|#lf|%, %|#nl|%, or %|\n|% is the
2350 * newline character, used to terminate lines of text or advance the
2351 * cursor to the next line (perhaps without returning it to the start of
2354 * * %|#return|%, %|#carriage-return|%, %|#cr|%, or %|\r|% is the
2355 * carriage-return character, used to return the cursor to the start of
2358 * * %|#tab|%, %|#horizontal-tab|%, %|#ht|%, or %|\t|% is the tab
2359 * character, used to advance the cursor to the next tab stop on the
2362 * * %|#vertical-tab|%, %|#vt|%, %|\v|% is the vertical tab character.
2364 * * %|#space|%, %|#spc|% is the space character.
2366 * * %|#delete|%, %|#del|% is the delete character, used to erase the most
2369 * * %|\'|% is the single-quote character.
2371 * * %|\\|% is the backslash character.
2373 * * %|\"|% is the double-quote character.
2375 * * %|\NNN|% or %|\{NNN}|% is the character with code NNN in octal. The
2376 * NNN may be up to three digits long.
2378 * * %|\xNN|% or %|\x{NN}|% is the character with code NNN in hexadecimal.
2381 extern const struct tvec_regty tvty_char;
2383 /* --- @tvec_claimeq_char@, @TVEC_CLAIMEQ_CHAR@ --- *
2385 * Arguments: @struct tvec_state *tv@ = test-vector state
2386 * @int ch0, ch1@ = two character codes
2387 * @const char *file@, @unsigned @lno@ = calling file and line
2388 * @const char *expr@ = the expression to quote on failure
2390 * Returns: Nonzero if @ch0@ and @ch1@ are equal, otherwise zero.
2392 * Use: Check that values of @ch0@ and @ch1@ are equal. As for
2393 * @tvec_claim@ above, a test case is automatically begun and
2394 * ended if none is already underway. If the values are
2395 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
2396 * mismatched values are dumped: @ch0@ is printed as the output
2397 * value and @ch1@ is printed as the input reference.
2399 * The @TVEC_CLAIM_CHAR@ macro is similar, only it (a)
2400 * identifies the file and line number of the call site
2401 * automatically, and (b) implicitly quotes the source text of
2402 * the @ch0@ and @ch1@ arguments in the failure message.
2405 extern int tvec_claimeq_char(struct tvec_state */*tv*/,
2406 int /*ch0*/, int /*ch1*/,
2407 const char */*file*/, unsigned /*lno*/,
2408 const char */*expr*/);
2409 #define TVEC_CLAIMEQ_CHAR(tv, c0, c1) \
2410 (tvec_claimeq_char(tv, c0, c1, __FILE__, __LINE__, #c0 " /= " #c1))
2412 /*----- Text and binary string types --------------------------------------*/
2414 /* A string is a sequence of octets. Text and binary strings differ
2415 * primarily in presentation: text strings are shown as raw characters where
2416 * possible; binary strings are shown as hex dumps with an auxiliary text
2419 * The input format for both kinds of strings is basically the same: a
2420 * `compound string', consisting of
2422 * * single-quoted strings, which are interpreted entirely literally, but
2423 * can't contain single quotes or newlines;
2425 * * double-quoted strings, in which `%|\|%'-escapes are interpreted as for
2428 * * character names, marked by an initial `%|#|%' sign;
2430 * * special tokens marked by an initial `%|!|%' sign; or
2432 * * barewords interpreted according to the current coding scheme.
2434 * The special tokens are
2436 * * `%|!bare|%', which causes subsequent sequences of barewords to be
2437 * treated as plain text;
2439 * * `%|!hex|%', `%|!base32|%', `%|!base64|%', which cause subsequent
2440 * barewords to be decoded in the requested manner.
2442 * * `%|!repeat|% %$n$% %|{|% %%\textit{string}%% %|}|%', which includes
2443 * %$n$% copies of the (compound) string.
2445 * The only difference between text and binary strings is that the initial
2446 * coding scheme is %|bare|% for text strings and %|hex|% for binary strings.
2448 * Either kind of string can contain internal nul characters. A trailing nul
2449 * is appended -- beyond the stated input length -- to input strings as a
2450 * convenience to test functions. Test functions may include such a nul
2451 * character on output but this is not checked by the equality test.
2453 * A @struct tvec_urange@ may be supplied as an argument: the length of the
2454 * string (in bytes) will be checked against the permitted range.
2457 extern const struct tvec_regty tvty_text, tvty_bytes;
2459 /* --- @tvec_alloctext@, @tvec_allocbytes@ --- *
2461 * Arguments: @union tvec_regval *rv@ = register value
2462 * @size_t sz@ = required size
2466 * Use: Allocated space in a text or binary string register. If the
2467 * current register size is sufficient, its buffer is left
2468 * alone; otherwise, the old buffer, if any, is freed and a
2469 * fresh buffer allocated. These functions are not intended to
2470 * be used to adjust a buffer repeatedly, e.g., while building
2471 * output incrementally: (a) they will perform badly, and (b)
2472 * the old buffer contents are simply discarded if reallocation
2473 * is necessary. Instead, use a @dbuf@ or @dstr@.
2475 * The @tvec_alloctext@ function sneakily allocates an extra
2476 * byte for a terminating zero. The @tvec_allocbytes@ function
2480 extern void tvec_alloctext(union tvec_regval */*rv*/, size_t /*sz*/);
2481 extern void tvec_allocbytes(union tvec_regval */*rv*/, size_t /*sz*/);
2483 /* --- @tvec_claimeq_text@, @TVEC_CLAIMEQ_TEXT@ --- *
2485 * Arguments: @struct tvec_state *tv@ = test-vector state
2486 * @const char *p0@, @size_t sz0@ = first string with length
2487 * @const char *p1@, @size_t sz1@ = second string with length
2488 * @const char *file@, @unsigned @lno@ = calling file and line
2489 * @const char *expr@ = the expression to quote on failure
2491 * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise
2494 * Use: Check that strings at @p0@ and @p1@ are equal. As for
2495 * @tvec_claim@ above, a test case is automatically begun and
2496 * ended if none is already underway. If the values are
2497 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
2498 * mismatched values are dumped: @p0@ is printed as the output
2499 * value and @p1@ is printed as the input reference.
2501 * The @TVEC_CLAIM_TEXT@ macro is similar, only it (a)
2502 * identifies the file and line number of the call site
2503 * automatically, and (b) implicitly quotes the source text of
2504 * the @ch0@ and @ch1@ arguments in the failure message.
2507 extern int tvec_claimeq_text(struct tvec_state */*tv*/,
2508 const char */*p0*/, size_t /*sz0*/,
2509 const char */*p1*/, size_t /*sz1*/,
2510 const char */*file*/, unsigned /*lno*/,
2511 const char */*expr*/);
2512 #define TVEC_CLAIMEQ_TEXT(tv, p0, sz0, p1, sz1) \
2513 (tvec_claimeq_text(tv, p0, sz0, p1, sz1, __FILE__, __LINE__, \
2514 #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
2516 /* --- @tvec_claimeq_textz@, @TVEC_CLAIMEQ_TEXTZ@ --- *
2518 * Arguments: @struct tvec_state *tv@ = test-vector state
2519 * @const char *p0, *p1@ = two strings to compare
2520 * @const char *file@, @unsigned @lno@ = calling file and line
2521 * @const char *expr@ = the expression to quote on failure
2523 * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise
2526 * Use: Check that strings at @p0@ and @p1@ are equal, as for
2527 * @tvec_claimeq_string@, except that the strings are assumed
2528 * null-terminated, so their lengths don't need to be supplied
2529 * explicitly. The macro is similarly like @TVEC_CLAIMEQ_TEXT@.
2532 extern int tvec_claimeq_textz(struct tvec_state */*tv*/,
2533 const char */*p0*/, const char */*p1*/,
2534 const char */*file*/, unsigned /*lno*/,
2535 const char */*expr*/);
2536 #define TVEC_CLAIMEQ_TEXTZ(tv, p0, p1) \
2537 (tvec_claimeq_textz(tv, p0, p1, __FILE__, __LINE__, #p0 " /= " #p1))
2539 /* --- @tvec_claimeq_bytes@, @TVEC_CLAIMEQ_BYTES@ --- *
2541 * Arguments: @struct tvec_state *tv@ = test-vector state
2542 * @const void *p0@, @size_t sz0@ = first string with length
2543 * @const void *p1@, @size_t sz1@ = second string with length
2544 * @const char *file@, @unsigned @lno@ = calling file and line
2545 * @const char *expr@ = the expression to quote on failure
2547 * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise
2550 * Use: Check that binary strings at @p0@ and @p1@ are equal. As for
2551 * @tvec_claim@ above, a test case is automatically begun and
2552 * ended if none is already underway. If the values are
2553 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
2554 * mismatched values are dumped: @p0@ is printed as the output
2555 * value and @p1@ is printed as the input reference.
2557 * The @TVEC_CLAIM_STRING@ macro is similar, only it (a)
2558 * identifies the file and line number of the call site
2559 * automatically, and (b) implicitly quotes the source text of
2560 * the @ch0@ and @ch1@ arguments in the failure message.
2563 extern int tvec_claimeq_bytes(struct tvec_state */*tv*/,
2564 const void */*p0*/, size_t /*sz0*/,
2565 const void */*p1*/, size_t /*sz1*/,
2566 const char */*file*/, unsigned /*lno*/,
2567 const char */*expr*/);
2568 #define TVEC_CLAIMEQ_BYTES(tv, p0, sz0, p1, sz1) \
2569 (tvec_claimeq(tv, p0, sz0, p1, sz1, __FILE__, __LINE__, \
2570 #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
2572 /*----- Buffer type -------------------------------------------------------*/
2574 /* Buffer registers are primarily used for benchmarking. Only a buffer's
2575 * allocation parameters are significant: its contents are ignored on
2576 * comparison and output, and unspecified on input.
2578 * The input format gives the buffer's size, and an optional alignment
2579 * specification, in the form %|SZ [`@' M [`+' A]]|%. Each of %|SZ|%, %|M|%
2580 * and %|A|% are sizes, as an integer, optionally suffixed with a unit `kB',
2581 * `MB', `GB', `TB', `PB', `EB', `ZB', `YB' (with or without the `B')
2582 * denoting a power of 1024. The %|SZ|% gives the (effective) buffer size.
2583 * %|M|% is the `alignment quantum' and %|A|% is the `alignment offset'; both
2584 * default to zero, but if %|M|% is nonzero then the start of the buffer is
2585 * aligned such that it is %|A|% more than a multiple of %|M|% bytes. Note
2586 * that %|M|% need not be a power of two, though this is common.
2588 * Units other than `B' are used on output only when the size would be
2589 * expressed exactly.
2591 * Buffers are %%\emph{not}%% allocated by default. In benchmarks, this is
2592 * best done in a @before@ function.
2594 * No @claimeq@ functions or macros are provided for buffers because they
2595 * don't seem very useful.
2598 extern const struct tvec_regty tvty_buffer;
2600 /* --- @tvec_initbuffer@ --- *
2602 * Arguments: @union tvec_regval *rv@ = register value
2603 * @const union tvec_regval *ref@ = reference buffer
2604 * @size_t sz@ = size to allocate
2608 * Use: Initialize the alignment parameters in @rv@ to match @ref@,
2609 * and the size to @sz@.
2612 extern void tvec_initbuffer(union tvec_regval */*rv*/,
2613 const union tvec_regval */*ref*/, size_t /*sz*/);
2615 /* --- @tvec_allocbuffer@ --- *
2617 * Arguments: @union tvec_regval *rv@ = register value
2621 * Use: Allocate @sz@ bytes to the buffer and fill the space with a
2622 * distinctive pattern.
2625 extern void tvec_allocbuffer(union tvec_regval */*rv*/);
2627 /*----- That's all, folks -------------------------------------------------*/
~mdw / mLib / blob