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 { unsigned char *p
; size_t sz
; } bytes
; /* binary string of bytes */
196 struct { char *p
; size_t sz
; } text
; /* text string */
205 * Note that all of the registers listed as being used by a particular test
206 * group are initialized at all times[1] while that test group is being
207 * processed. (The other register slots don't even have types associated
208 * with them, so there's nothing useful we could do with them.)
210 * The `TVRF_LIVE' flag indicates that the register was assigned a value by
211 * the test vector file: it's the right thing to use to check whether an
212 * optional register is actually present. Even `dead' registers are still
213 * initialized, though.
215 * [1] This isn't quite true. Between individual tests, the registers are
216 * released and reinitialized in order to reset them to known values
217 * ready for the next test. But you won't see them at this point.
220 unsigned f
; /* flags */
221 #define TVRF_LIVE 1u /* used in current test */
222 union tvec_regval v
; /* register value */
226 /* A register definition. Register definitions list the registers which
227 * are used by a particular test group (see `struct tvec_test' below).
229 * A vector of register definitions is terminated by a definition whose
230 * `name' slot is null.
233 const char *name
; /* register name (for input files) */
234 unsigned i
; /* register index */
235 const struct tvec_regty
*ty
; /* register type descriptor */
236 unsigned f
; /* flags */
237 #define TVRF_OPT 1u /* optional register */
238 #define TVRF_ID 2u /* part of test identity */
239 union tvec_misc arg
; /* extra detail for the type */
241 #define TVEC_ENDREGS { 0, 0, 0, 0, { 0 } }
243 /* @TVEC_GREG(vec, i, regsz)@
245 * If @vec@ is a data pointer which happens to contain the address of a
246 * vector of @struct tvec_reg@ objects, @i@ is an integer, and @regsz@ is the
247 * size of a @struct tvec_reg@, then this evaluates to the address of the
248 * @i@th element of the vector.
250 * This is the general tool you need for accessing register vectors when you
251 * don't have absolute knowledge of the size of a @union tvec_regval@.
252 * Usually you want to access one of the register vectors in a @struct
253 * tvec_state@, and @TVEC_REG@ will be more convenient.
255 #define TVEC_GREG(vec, i, regsz) \
256 ((struct tvec_reg *)((unsigned char *)(vec) + (i)*(regsz)))
258 /*----- Register types ----------------------------------------------------*/
260 struct tvec_state
; /* forward declaration */
263 /* A register type. */
265 void (*init
)(union tvec_regval */
*rv*/
, const struct tvec_regdef */
*rd*/
);
266 /* Initialize the value in @*rv@. This will be called before any other
267 * function acting on the value, including @release@.
270 void (*release
)(union tvec_regval */
*rv*/
,
271 const struct tvec_regdef */
*rd*/
);
272 /* Release any resources associated with the value in @*rv@. */
274 int (*eq
)(const union tvec_regval */
*rv0*/
,
275 const union tvec_regval */
*rv1*/
,
276 const struct tvec_regdef */
*rd*/
);
277 /* Return nonzero if @*rv0@ and @*rv1@ are equal values. Asymmetric
278 * criteria are permitted: @tvec_checkregs@ calls @eq@ with the input
279 * register as @rv0@ and the output as @rv1@.
282 int (*tobuf
)(buf */
*b*/
, const union tvec_regval */
*rv*/
,
283 const struct tvec_regdef */
*rd*/
);
284 /* Serialize the value @*rv@, writing the result to @b@. Return zero on
285 * success, or %$-1$% on error.
288 int (*frombuf
)(buf */
*b*/
, union tvec_regval */
*rv*/
,
289 const struct tvec_regdef */
*rd*/
);
290 /* Deserialize a value from @b@, storing it in @*rv@. Return zero on
291 * success, or %$-1$% on error.
294 int (*parse
)(union tvec_regval */
*rv*/
, const struct tvec_regdef */
*rd*/
,
295 struct tvec_state */
*tv*/
);
296 /* Parse a value from @tv->fp@, storing it in @*rv@. Return zero on
297 * success, or %$-1$% on error, having reported one or more errors via
298 * @tvec_error@ or @tvec_syntax@. A successful return should leave the
299 * input position at the start of the next line; the caller will flush
300 * the remainder of the line itself.
303 void (*dump
)(const union tvec_regval */
*rv*/
,
304 const struct tvec_regdef */
*rd*/
,
306 const struct gprintf_ops */
*gops*/
, void */
*go*/
);
307 #define TVSF_COMPACT 1u
308 /* Write a human-readable representation of the value @*rv@ using
309 * @gprintf@ on @gops@ and @go@. The @style@ is a collection of flags:
310 * if @TVSF_COMPACT@ is set, then output should be minimal, and must fit
311 * on a single line; otherwise, output may consist of multiple lines and
312 * may contain redundant information if that is likely to be useful to a
317 /*----- Test descriptions -------------------------------------------------*/
319 typedef void tvec_testfn(const struct tvec_reg */
*in*/
,
320 struct tvec_reg */
*out*/
,
322 /* A test function. It should read inputs from @in@ and write outputs to
323 * @out@. The @TVRF_LIVE@ is set on inputs which are actually present, and
324 * on outputs which are wanted to test. A test function can set additional
325 * `gratuitous outputs' by setting @TVRF_LIVE@ on them; clearing
326 * @TVRF_LIVE@ on a wanted output causes a mismatch.
328 * A test function may be called zero or more times by the environment. In
329 * particular, it may be called multiple times, though usually by prior
330 * arrangement with the environment.
332 * The @ctx@ is supplied by the environment's @run@ function (see below).
333 * The default environment calls the test function once, with a null
334 * @ctx@. There is no expectation that the environment's context has
335 * anything to do with the test function's context.
340 typedef void tvec_envsetupfn(struct tvec_state */
*tv*/
,
341 const struct tvec_env */
*env*/
,
342 void */
*pctx*/
, void */
*ctx*/
);
343 /* Initialize the context; called at the start of a test group; @pctx@ is
344 * null for environments called by the core, but may be non-null for
345 * subordinate environments. If setup fails, the function should call
346 * @tvec_skipgroup@ with a suitable excuse. The @set@, @after@, and
347 * @teardown@ entry points will still be called, but @before@ and @run@
351 typedef int tvec_envsetfn(struct tvec_state */
*tv*/
,
352 const char */
*var*/
, void */
*ctx*/
);
353 /* Called when the parser finds a %|@var|%' setting to parse and store the
354 * value. Return %$+1$% on success, %$0$% if the variable name was not
355 * recognized, or %$-1$% on any other error (which should have been
356 * reported via @tvec_error@).
359 typedef void tvec_envbeforefn(struct tvec_state */
*tv*/
, void */
*ctx*/
);
360 /* Called prior to running a test. This is the right place to act on any
361 * `%|@var|%' settings. If preparation fails, the function should call
362 * @tvec_skip@ with a suitable excuse. This function is never called if
363 * the test group is skipped.
366 typedef void tvec_envrunfn(struct tvec_state */
*tv*/
,
367 tvec_testfn */
*fn*/
, void */
*ctx*/
);
368 /* Run the test. It should either call @tvec_skip@, or run @fn@ one or
369 * more times. In the latter case, it is responsible for checking the
370 * outputs, and calling @tvec_fail@ as necessary; @tvec_checkregs@ will
371 * check the register values against the supplied test vector, while
372 * @tvec_check@ does pretty much everything necessary. This function is
373 * never called if the test group is skipped.
376 typedef void tvec_envafterfn(struct tvec_state */
*tv*/
, void */
*ctx*/
);
377 /* Called after running or skipping a test. Typical actions involve
378 * resetting whatever things were established by @set@. This function
379 * %%\emph{is}%% called if the test group is skipped, so that the test
380 * environment can reset variables set by the @set@ entry point. It should
381 * check the @TVSF_SKIP@ flag if necessary.
384 typedef void tvec_envteardownfn(struct tvec_state */
*tv*/
, void */
*ctx*/
);
385 /* Tear down the environment: called at the end of a test group. */
389 /* A test environment sets things up for and arranges to run the test.
391 * The caller is responsible for allocating storage for the environment's
392 * context, based on the @ctxsz@ slot, and freeing it later; this space is
393 * passed in as the @ctx@ parameter to the remaining functions; if @ctxsz@
394 * is zero then @ctx@ is null.
397 size_t ctxsz
; /* environment context size */
399 tvec_envsetupfn
*setup
; /* setup for group */
400 tvec_envsetfn
*set
; /* set variable */
401 tvec_envbeforefn
*before
; /* prepare for test */
402 tvec_envrunfn
*run
; /* run test function */
403 tvec_envafterfn
*after
; /* clean up after test */
404 tvec_envteardownfn
*teardown
; /* tear down after group */
408 /* A test description. */
410 const char *name
; /* name of the test */
411 const struct tvec_regdef
*regs
; /* descriptions of the registers */
412 const struct tvec_env
*env
; /* environment to run test in */
413 tvec_testfn
*fn
; /* test function */
415 #define TVEC_ENDTESTS { 0, 0, 0, 0 }
418 /* Register output dispositions. */
420 TVRD_INPUT
, /* input-only register */
421 TVRD_OUTPUT
, /* output-only (input is dead) */
422 TVRD_MATCH
, /* matching (equal) registers */
423 TVRD_FOUND
, /* mismatching output register */
424 TVRD_EXPECT
, /* mismatching input register */
425 TVRD_LIMIT
/* (number of dispositions) */
428 /*----- Test state --------------------------------------------------------*/
431 /* Possible test outcomes. */
433 TVOUT_LOSE
, /* test failed */
434 TVOUT_SKIP
, /* test skipped */
435 TVOUT_WIN
, /* test passed */
436 TVOUT_XFAIL
, /* test passed, but shouldn't have */
437 TVOUT_LIMIT
/* (number of possible outcomes) */
441 /* The primary state structure for the test vector machinery. */
443 unsigned f
; /* flags */
444 #define TVSF_SKIP 0x0001u /* skip this test group */
445 #define TVSF_OPEN 0x0002u /* test is open */
446 #define TVSF_ACTIVE 0x0004u /* test is active */
447 #define TVSF_ERROR 0x0008u /* an error occurred */
448 #define TVSF_OUTMASK 0x00f0u /* test outcome (@TVOUT_...@) */
449 #define TVSF_OUTSHIFT 4 /* shift applied to outcome */
450 #define TVSF_XFAIL 0x0100u /* test expected to fail */
451 #define TVSF_MUFFLE 0x0200u /* muffle errors */
453 /* Registers. Available to execution environments. */
454 unsigned nrout
, nreg
; /* number of output/total registers */
455 size_t regsz
; /* size of register entry */
456 struct tvec_reg
*in
, *out
; /* register vectors */
458 /* Test groups state. Available to output formatters. */
459 const struct tvec_test
*tests
, *test
; /* all tests and current test */
461 /* Test scoreboard. Available to output formatters. */
462 unsigned curr
[TVOUT_LIMIT
], all
[TVOUT_LIMIT
], grps
[TVOUT_LIMIT
];
464 /* Output machinery. */
465 struct tvec_output
*output
; /* output formatter */
467 /* Input machinery. Available to type parsers. */
468 const char *infile
; unsigned lno
, test_lno
; /* input file name, line */
469 FILE *fp
; /* input file stream */
472 /* @TVEC_REG(tv, vec, i)@
474 * If @tv@ is a pointer to a @struct tvec_state@, @vec@ is either @in@ or
475 * @out@, and @i@ is an integer, then this evaluates to the address of the
476 * @i@th register in the selected vector.
478 #define TVEC_REG(tv, vec, i) TVEC_GREG((tv)->vec, (i), (tv)->regsz)
481 /* An overall test configuration. */
483 const struct tvec_test
*tests
; /* the tests to be performed */
484 unsigned nrout
, nreg
; /* number of output/total regs */
485 size_t regsz
; /* size of a register */
488 /*----- Output formatting -------------------------------------------------*/
491 /* An output formatter. */
492 const struct tvec_outops
*ops
; /* pointer to operations */
495 /* Benchmarking details. */
497 TVBU_OP
, /* counting operations of some kind */
498 TVBU_BYTE
, /* counting bytes (@rbuf >= 0@) */
499 TVBU_LIMIT
/* (number of units) */
501 struct bench_timing
; /* forward declaration */
504 /* Output operations. */
506 void (*bsession
)(struct tvec_output */
*o*/
, struct tvec_state */
*tv*/
);
507 /* Begin a test session. The output driver will probably want to
508 * save @tv@, because this isn't provided to any other methods.
511 int (*esession
)(struct tvec_output */
*o*/
);
512 /* End a session, and return the suggested exit code. */
514 void (*bgroup
)(struct tvec_output */
*o*/
);
515 /* Begin a test group. The test group description is @tv->test@. */
517 void (*skipgroup
)(struct tvec_output */
*o*/
,
518 const char */
*excuse*/
, va_list */
*ap*/
);
519 /* The group is being skipped; @excuse@ may be null or a format
520 * string explaining why. The @egroup@ method will not be called
524 void (*egroup
)(struct tvec_output */
*o*/
);
525 /* End a test group. At least one test was attempted or @skipgroup@
526 * would have been called instead. If @tv->curr[TVOUT_LOSE]@ is nonzero
527 * then the test group as a whole failed; otherwise it passed.
530 void (*btest
)(struct tvec_output */
*o*/
);
531 /* Begin a test case. */
533 void (*skip
)(struct tvec_output */
*o*/
,
534 const char */
*excuse*/
, va_list */
*ap*/
);
535 /* The test case is being skipped; @excuse@ may be null or a format
536 * string explaining why. The @etest@ function will still be called (so
537 * this works differently from @skipgroup@ and @egroup@). A test case
538 * can be skipped at most once, and, if skipped, it cannot fail.
541 void (*fail
)(struct tvec_output */
*o*/
,
542 const char */
*detail*/
, va_list */
*ap*/
);
543 /* The test case failed.
545 * The output driver should preferably report the filename (@infile@) and
546 * line number (@test_lno@, not @lno@) for the failing test.
548 * The @detail@ may be null or a format string describing detail about
549 * how the failing test was run which can't be determined from the
550 * registers; a @detail@ is usually provided when (and only when) the
551 * test environment potentially invokes the test function more than once.
553 * A single test case can fail multiple times!
556 void (*dumpreg
)(struct tvec_output */
*o*/
,
557 unsigned /*disp*/, const union tvec_regval */
*rv*/
,
558 const struct tvec_regdef */
*rd*/
);
559 /* Dump a register. The `disposition' @disp@ explains what condition the
560 * register is in; see @tvec_dumpreg@ and the @TVRD_...@ codes. The
561 * register value is at @rv@, and its definition, including its type, at
562 * @rd@. Note that this function may be called on virtual registers
563 * which aren't in either of the register vectors or mentioned by the
564 * test description. It may also be called with @rv@ null, indicating
565 * that the register is not live.
568 void (*etest
)(struct tvec_output */
*o*/
, unsigned /*outcome*/);
569 /* The test case concluded with the given @outcome@ (one of the
573 void (*bbench
)(struct tvec_output */
*o*/
,
574 const char */
*ident*/
, unsigned /*unit*/);
575 /* Begin a benchmark. The @ident@ is a formatted string identifying the
576 * benchmark based on the values of the input registered marked
577 * @TVRF_ID@; the output driver is free to use this or come up with its
578 * own way to identify the test, e.g., by inspecting the register values
579 * for itself. The @unit@ is one of the @TVBU_...@ constants explaining
580 * what sort of thing is being measured.
583 void (*ebench
)(struct tvec_output */
*o*/
,
584 const char */
*ident*/
, unsigned /*unit*/,
585 const struct bench_timing */
*tm*/
);
586 /* End a benchmark. The @ident@ and @unit@ arguments are as for
587 * @bbench@. If @tm@ is zero then the measurement failed; otherwise
588 * @tm->n@ counts total number of things (operations or bytes, as
589 * indicated by @unit@) processed in the indicated time.
592 void (*report
)(struct tvec_output */
*o*/
, unsigned /*level*/,
593 const char */
*msg*/
, va_list */
*ap*/
);
594 /* Report a message. The driver should ideally report the filename
595 * (@infile@) and line number (@lno@) prompting the error.
598 void (*destroy
)(struct tvec_output */
*o*/
);
599 /* Release any resources acquired by the driver. */
602 #define TVEC_LEVELS(_) \
603 _(NOTE, "notice", 4) \
607 #define TVEC_DEFLEVEL(tag, name, val) TVLEV_##tag = val,
608 TVEC_LEVELS(TVEC_DEFLEVEL
)
613 /*----- Session lifecycle -------------------------------------------------*/
615 /* --- @tvec_begin@ --- *
617 * Arguments: @struct tvec_state *tv_out@ = state structure to fill in
618 * @const struct tvec_config *config@ = test configuration
619 * @struct tvec_output *o@ = output driver
623 * Use: Initialize a state structure ready to do some testing.
626 extern void tvec_begin(struct tvec_state */
*tv_out*/
,
627 const struct tvec_config */
*config*/
,
628 struct tvec_output */
*o*/
);
630 /* --- @tvec_end@ --- *
632 * Arguments: @struct tvec_state *tv@ = test-vector state
634 * Returns: A proposed exit code.
636 * Use: Conclude testing and suggests an exit code to be returned to
637 * the calling program. (The exit code comes from the output
638 * driver's @esession@ method.)
641 extern int tvec_end(struct tvec_state */
*tv*/
);
643 /* --- @tvec_read@ --- *
645 * Arguments: @struct tvec_state *tv@ = test-vector state
646 * @const char *infile@ = the name of the input file
647 * @FILE *fp@ = stream to read from
649 * Returns: Zero on success, %$-1$% on error.
651 * Use: Read test vector data from @fp@ and exercise test functions.
652 * THe return code doesn't indicate test failures: it's only
653 * concerned with whether there were problems with the input
654 * file or with actually running the tests.
657 extern int tvec_read(struct tvec_state */
*tv*/
,
658 const char */
*infile*/
, FILE */
*fp*/
);
660 /*----- Command-line interface --------------------------------------------*/
662 extern const struct tvec_config tvec_adhocconfig
;
663 /* A special @struct tvec_config@ to use for programs which perform ad-hoc
667 /* --- @tvec_parseargs@ --- *
669 * Arguments: @int argc@ = number of command-line arguments
670 * @char *argv[]@ = vector of argument strings
671 * @struct tvec_state *tv_out@ = test vector state to initialize
672 * @int *argpos_out@ = where to leave unread argument index
673 * @const struct tvec_config *cofig@ = test vector configuration
677 * Use: Parse arguments and set up the test vector state @*tv_out@.
678 * If errors occur, print messages to standard error and exit
682 extern void tvec_parseargs(int /*argc*/, char */
*argv*/
[],
683 struct tvec_state */
*tv_out*/
,
685 const struct tvec_config */
*config*/
);
687 /* --- @tvec_readstdin@, @tvec_readfile@, @tvec_readarg@ --- *
689 * Arguments: @struct tvec_state *tv@ = test vector state
690 * @const char *file@ = pathname of file to read
691 * @const char *arg@ = argument to interpret
693 * Returns: Zero on success, %$-1$% on error.
695 * Use: Read test vector data from stdin or a named file. The
696 * @tvec_readarg@ function reads from stdin if @arg@ is `%|-|%',
697 * and from the named file otherwise.
700 extern int tvec_readstdin(struct tvec_state */
*tv*/
);
701 extern int tvec_readfile(struct tvec_state */
*tv*/
, const char */
*file*/
);
702 extern int tvec_readarg(struct tvec_state */
*tv*/
, const char */
*arg*/
);
704 /* --- @tvec_readdflt@ --- *
706 * Arguments: @struct tvec_state *tv@ = test vector state
707 * @const char *dflt@ = defsault filename or null
709 * Returns: Zero on success, %$-1$% on error.
711 * Use: Reads from the default test vector data. If @file@ is null,
712 * then read from standard input, unless that's a terminal; if
713 * @file@ is not null, then read the named file, looking in the
714 * directory named by the `%|srcdir|%' environment variable if
715 * that's set, or otherwise in the current directory.
718 extern int tvec_readdflt(struct tvec_state */
*tv*/
, const char */
*file*/
);
720 /* --- @tvec_readargs@ --- *
722 * Arguments: @int argc@ = number of command-line arguments
723 * @char *argv[]@ = vector of argument strings
724 * @struct tvec_state *tv@ = test vector state
725 * @int *argpos_inout@ = current argument position (updated)
726 * @const char *dflt@ = default filename or null
728 * Returns: Zero on success, %$-1$% on error.
730 * Use: Reads from the sources indicated by the command-line
731 * arguments, in order, interpreting each as for @tvec_readarg@;
732 * if no arguments are given then read from @dflt@ as for
736 extern int tvec_readargs(int /*argc*/, char */
*argv*/
[],
737 struct tvec_state */
*tv*/
,
738 int */
*argpos_inout*/
, const char */
*dflt*/
);
740 /* --- @tvec_main@ --- *
742 * Arguments: @int argc@ = number of command-line arguments
743 * @char *argv[]@ = vector of argument strings
744 * @const struct tvec_config *cofig@ = test vector configuration
745 * @const char *dflt@ = default filename or null
747 * Returns: Exit code.
749 * Use: All-in-one test vector front-end. Parse options from the
750 * command-line as for @tvec_parseargs@, and then process the
751 * remaining positional arguments as for @tvec_readargs@. The
752 * function constructs and disposes of a test vector state.
755 extern int tvec_main(int /*argc*/, char */
*argv*/
[],
756 const struct tvec_config */
*config*/
,
757 const char */
*dflt*/
);
759 /*----- Test processing ---------------------------------------------------*/
761 /* --- @tvec_skipgroup@, @tvec_skipgroup_v@ --- *
763 * Arguments: @struct tvec_state *tv@ = test-vector state
764 * @const char *excuse@, @va_list *ap@ = reason why skipped
768 * Use: Skip the current group. This should only be called from a
769 * test environment @setup@ function; a similar effect occurs if
770 * the @setup@ function fails.
773 extern PRINTF_LIKE(2, 3)
774 void tvec_skipgroup(struct tvec_state */
*tv*/
,
775 const char */
*excuse*/
, ...);
776 extern void tvec_skipgroup_v(struct tvec_state */
*tv*/
,
777 const char */
*excuse*/
, va_list */
*ap*/
);
779 /* --- @tvec_skip@, @tvec_skip_v@ --- *
781 * Arguments: @struct tvec_state *tv@ = test-vector state
782 * @const char *excuse@, @va_list *ap@ = reason why test skipped
786 * Use: Skip the current test. This should only be called from a
787 * test environment @run@ function; a similar effect occurs if
788 * the @before@ function fails.
791 extern PRINTF_LIKE(2, 3)
792 void tvec_skip(struct tvec_state */
*tv*/
, const char */
*excuse*/
, ...);
793 extern void tvec_skip_v(struct tvec_state */
*tv*/
,
794 const char */
*excuse*/
, va_list */
*ap*/
);
796 /* --- @tvec_fail@, @tvec_fail_v@ --- *
798 * Arguments: @struct tvec_state *tv@ = test-vector state
799 * @const char *detail@, @va_list *ap@ = description of test
803 * Use: Report the current test as a failure. This function can be
804 * called multiple times for a single test, e.g., if the test
805 * environment's @run@ function invokes the test function
806 * repeatedly; but a single test that fails repeatedly still
807 * only counts as a single failure in the statistics. The
808 * @detail@ string and its format parameters can be used to
809 * distinguish which of several invocations failed; it can
810 * safely be left null if the test function is run only once.
813 extern PRINTF_LIKE(2, 3)
814 void tvec_fail(struct tvec_state */
*tv*/
, const char */
*detail*/
, ...);
815 extern void tvec_fail_v(struct tvec_state */
*tv*/
,
816 const char */
*detail*/
, va_list */
*ap*/
);
818 /* --- @tvec_dumpreg@ --- *
820 * Arguments: @struct tvec_state *tv@ = test-vector state
821 * @unsigned disp@ = the register disposition (@TVRD_...@)
822 * @const union tvec_regval *tv@ = register value, or null
823 * @const struct tvec_regdef *rd@ = register definition
827 * Use: Dump a register value to the output. This is the lowest-
828 * level function for dumping registers, and calls the output
829 * formatter directly.
831 * Usually @tvec_mismatch@ is much more convenient. Low-level
832 * access is required for reporting `virtual' registers
833 * corresponding to test environment settings.
836 extern void tvec_dumpreg(struct tvec_state */
*tv*/
,
837 unsigned /*disp*/, const union tvec_regval */
*rv*/
,
838 const struct tvec_regdef */
*rd*/
);
840 /* --- @tvec_initregs@, @tvec_releaseregs@ --- *
842 * Arguments: @struct tvec_state *tv@ = test-vector state
846 * Use: Initialize or release, respectively, the registers required
847 * by the current test. All of the registers, both input and
848 * output, are effected. Initialized registers are not marked
852 extern void tvec_initregs(struct tvec_state */
*tv*/
);
853 extern void tvec_releaseregs(struct tvec_state */
*tv*/
);
855 /* --- @tvec_resetoutputs@ --- *
857 * Arguments: @struct tvec_state *tv@ = test-vector state
861 * Use: Reset (releases and reinitializes) the output registers in
862 * the test state. This is mostly of use to test environment
863 * @run@ functions, between invocations of the test function.
864 * Output registers are marked live if and only if the
865 * corresponding input register is live.
868 extern void tvec_resetoutputs(struct tvec_state */
*tv*/
);
870 /* --- @tvec_checkregs@ --- *
872 * Arguments: @struct tvec_state *tv@ = test-vector state
874 * Returns: Zero on success, %$-1$% on mismatch.
876 * Use: Compare the active output registers (according to the current
877 * test group definition) with the corresponding input register
878 * values. A mismatch occurs if the two values differ
879 * (according to the register type's @eq@ method), or if the
880 * input is live but the output is dead.
882 * This function only checks for a mismatch and returns the
883 * result; it takes no other action. In particular, it doesn't
884 * report a failure, or dump register values.
887 extern int tvec_checkregs(struct tvec_state */
*tv*/
);
889 /* --- @tvec_mismatch@ --- *
891 * Arguments: @struct tvec_state *tv@ = test-vector state
892 * @unsigned f@ = flags (@TVMF_...@)
896 * Use: Dumps registers suitably to report a mismatch. The flag bits
897 * @TVMF_IN@ and @TVF_OUT@ select input-only and output
898 * registers. If both are reset then nothing happens.
899 * Suppressing the output registers may be useful, e.g., if the
900 * test function crashed rather than returning outputs.
905 extern void tvec_mismatch(struct tvec_state */
*tv*/
, unsigned /*f*/);
907 /* --- @tvec_check@, @tvec_check_v@ --- *
909 * Arguments: @struct tvec_state *tv@ = test-vector state
910 * @const char *detail@, @va_list *ap@ = description of test
914 * Use: Check the register values, reporting a failure and dumping
915 * the registers in the event of a mismatch. This just wraps up
916 * @tvec_checkregs@, @tvec_fail@ and @tvec_mismatch@ in the
920 extern PRINTF_LIKE(2, 3)
921 void tvec_check(struct tvec_state */
*tv*/
, const char */
*detail*/
, ...);
922 extern void tvec_check_v(struct tvec_state */
*tv*/
,
923 const char */
*detail*/
, va_list */
*ap*/
);
925 /*----- Ad-hoc testing ----------------------------------------------------*/
927 /* --- @tvec_adhoc@ --- *
929 * Arguments: @struct tvec_state *tv@ = test-vector state
930 * @struct tvec_test *t@ = space for a test definition
934 * Use: Begin ad-hoc testing, i.e., without reading a file of
937 * The structure at @t@ will be used to record information about
938 * the tests underway, which would normally come from a static
939 * test definition. The other functions in this section assume
940 * that @tvec_adhoc@ has been called.
943 extern void tvec_adhoc(struct tvec_state */
*tv*/
, struct tvec_test */
*t*/
);
945 /* --- @tvec_begingroup@, @TVEC_BEGINGROUP@ --- *
947 * Arguments: @struct tvec_state *tv@ = test-vector state
948 * @const char *name@ = name for this test group
949 * @const char *file@, @unsigned @lno@ = calling file and line
953 * Use: Begin an ad-hoc test group with the given name. The @file@
954 * and @lno@ can be anything, but it's usually best if they
955 * refer to the source code performing the test: the macro
956 * @TVEC_BEGINGROUP@ does this automatically.
959 extern void tvec_begingroup(struct tvec_state */
*tv*/
, const char */
*name*/
,
960 const char */
*file*/
, unsigned /*lno*/);
961 #define TVEC_BEGINGROUP(tv, name) \
962 do tvec_begingroup(tv, name, __FILE__, __LINE__); while (0)
964 /* --- @tvec_endgroup@ --- *
966 * Arguments: @struct tvec_state *tv@ = test-vector state
970 * Use: End an ad-hoc test group. The statistics are updated and the
971 * outcome is reported to the output formatter.
974 extern void tvec_endgroup(struct tvec_state */
*tv*/
);
976 /* --- @TVEC_TESTGROUP@, @TVEC_TESTGROUP_TAG@ --- *
978 * Arguments: @tag@ = label-disambiguation tag
979 * @const struct tvec_state *tv = test-vector state
980 * @const char *name@ = test-group name
984 * Use: Control-structure macro: @TVEC_TESTGROUP(tv, name) stmt@
985 * establishes a test group with the given @name@ (attributing
986 * it to the source file and lie number), executes @stmt@, and
987 * ends the test group. If @stmt@ invokes @break@ then the test
988 * group is skipped. @TVEC_TESTGROUP_TAG@ is the same, with an
989 * additional @tag@ argument for use in higher-level macros.
992 #define TVEC_TESTGROUP_TAG(tag, tv, name) \
993 MC_WRAP(tag##__around, \
994 { TVEC_BEGINGROUP(tv, name); }, \
995 { tvec_endgroup(tv); }, \
996 { if (!((tv)->f&TVSF_SKIP)) tvec_skipgroup(tv, 0); \
997 tvec_endgroup(tv); })
998 #define TVEC_TESTGROUP(tv, name) TVEC_TESTGROUP_TAG(grp, tv, name)
1000 /* --- @tvec_begintest@, @TVEC_BEGINTEST@ --- *
1002 * Arguments: @struct tvec_state *tv@ = test-vector state
1003 * @const char *file@, @unsigned @lno@ = calling file and line
1007 * Use: Begin an ad-hoc test case. The @file@ and @lno@ can be
1008 * anything, but it's usually best if they refer to the source
1009 * code performing the test: the macro @TVEC_BEGINGROUP@ does
1010 * this automatically.
1013 extern void tvec_begintest(struct tvec_state */
*tv*/
,
1014 const char */
*file*/
, unsigned /*lno*/);
1015 #define TVEC_BEGINTEST(tv) \
1016 do tvec_begintest(tv, __FILE__, __LINE__); while (0)
1018 /* --- @tvec_endtest@ --- *
1020 * Arguments: @struct tvec_state *tv@ = test-vector state
1024 * Use: End an ad-hoc test case, The statistics are updated and the
1025 * outcome is reported to the output formatter.
1028 extern void tvec_endtest(struct tvec_state */
*tv*/
);
1030 /* --- @TVEC_TEST@, @TVEC_TEST_TAG@ --- *
1032 * Arguments: @tag@ = label-disambiguation tag
1033 * @struct tvec_test *t@ = space for a test definition
1037 * Use: Control-structure macro: @TVEC_TEST(tv) stmt@ begins a test
1038 * case, executes @stmt@, and ends the test case. If @stmt@
1039 * invokes @break@ then the test case is skipped.
1040 * @TVEC_TEST_TAG@ is the same, with an additional @tag@ argumet
1041 * for use in higher-level macros.
1044 #define TVEC_TEST_TAG(tag, tv) \
1045 MC_WRAP(tag##__around, \
1046 { TVEC_BEGINTEST(tv); }, \
1047 { tvec_endtest(tv); }, \
1048 { if ((tv)->f&TVSF_ACTIVE) tvec_skip((tv), 0); \
1049 tvec_endtest(tv); })
1050 #define TVEC_TEST(tv) TVEC_TEST_TAG(test, tv)
1052 /* --- @tvec_claim@, @tvec_claim_v@, @TVEC_CLAIM@ --- *
1054 * Arguments: @struct tvec_state *tv@ = test-vector state
1056 * @const char *file@, @unsigned @lno@ = calling file and line
1057 * @const char *msg@, @va_list *ap@ = message to report on
1060 * Returns: The value @ok@.
1062 * Use: Check that a claimed condition holds, as (part of) a test.
1063 * If no test case is underway (i.e., if @TVSF_OPEN@ is reset in
1064 * @tv->f@), then a new test case is begun and ended. The
1065 * @file@ and @lno@ are passed to the output formatter to be
1066 * reported in case of a failure. If @ok@ is nonzero, then
1067 * nothing else happens; so, in particular, if @tvec_claim@
1068 * established a new test case, then the test case succeeds. If
1069 * @ok@ is zero, then a failure is reported, quoting @msg@.
1071 * The @TVEC_CLAIM@ macro is similar, only it (a) identifies the
1072 * file and line number of the call site automatically, and (b)
1073 * implicitly quotes the source text of the @ok@ condition in
1074 * the failure message.
1077 extern PRINTF_LIKE(5, 6)
1078 int tvec_claim(struct tvec_state */
*tv*/
, int /*ok*/,
1079 const char */
*file*/
, unsigned /*lno*/,
1080 const char */
*msg*/
, ...);
1081 extern int tvec_claim_v(struct tvec_state */
*tv*/
, int /*ok*/,
1082 const char */
*file*/
, unsigned /*lno*/,
1083 const char */
*msg*/
, va_list */
*ap*/
);
1084 #define TVEC_CLAIM(tv, cond) \
1085 (tvec_claim(tv, !!(cond), __FILE__, __LINE__, "%s untrue", #cond))
1087 /* --- @tvec_claimeq@ --- *
1089 * Arguments: @struct tvec_state *tv@ = test-vector state
1090 * @const struct tvec_regty *ty@ = register type
1091 * @const union tvec_misc *arg@ = register type argument
1092 * @const char *file@, @unsigned @lno@ = calling file and line
1093 * @const char *expr@ = the expression to quote on failure
1095 * Returns: Nonzero if the input and output values of register 0 are
1096 * equal, zero if they differ.
1098 * Use: Check that the input and output values of register 0 are
1099 * equal (according to the register type @ty@). As for
1100 * @tvec_claim@ above, a test case is automatically begun and
1101 * ended if none is already underway. If the values are
1102 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
1103 * mismatched values are dumped.
1105 * This function is not expected to be called directly, but
1106 * through type-specific wrapper functions or macros such as
1107 * @TVEC_CLAIMEQ_INT@.
1110 extern int tvec_claimeq(struct tvec_state */
*tv*/
,
1111 const struct tvec_regty */
*ty*/
,
1112 const union tvec_misc */
*arg*/
,
1113 const char */
*file*/
, unsigned /*lno*/,
1114 const char */
*expr*/
);
1116 /*----- Benchmarking ------------------------------------------------------*/
1118 struct tvec_benchenv
{
1119 struct tvec_env _env
; /* benchmarking is an environment */
1120 struct bench_state
**bst
; /* benchmark state anchor or null */
1121 unsigned long niter
; /* iterations done per unit */
1122 int riter
, rbuf
; /* iterations and buffer registers */
1123 const struct tvec_env
*env
; /* subordinate environment */
1126 struct tvec_benchctx
{
1127 const struct tvec_benchenv
*be
; /* environment configuration */
1128 struct bench_state
*bst
; /* benchmark state */
1129 double dflt_target
; /* default time in seconds */
1130 unsigned f
; /* flags */
1131 #define TVBF_SETTRG 1u /* set `@target' */
1132 #define TVBF_SETMASK (TVBF_SETTRG)) /* mask of @TVBF_SET...@ */
1133 void *subctx
; /* subsidiary environment context */
1136 extern struct bench_state
*tvec_benchstate
;
1138 /* --- Environment implementation --- *
1140 * The following special variables are supported.
1142 * * %|@target|% is the (approximate) number of seconds to run the
1145 * Unrecognized variables are passed to the subordinate environment, if there
1146 * is one. Other events are passed through to the subsidiary environment.
1149 extern tvec_envsetupfn tvec_benchsetup
;
1150 extern tvec_envsetfn tvec_benchset
;
1151 extern tvec_envbeforefn tvec_benchbefore
;
1152 extern tvec_envrunfn tvec_benchrun
;
1153 extern tvec_envafterfn tvec_benchafter
;
1154 extern tvec_envteardownfn tvec_benchteardown
;
1156 #define TVEC_BENCHENV \
1157 { sizeof(struct tvec_benchctx), \
1163 tvec_benchteardown }
1164 #define TVEC_BENCHINIT TVEC_BENCHENV, &tvec_benchstate
1166 /* --- @tvec_benchreport@ --- *
1168 * Arguments: @const struct gprintf_ops *gops@ = print operations
1169 * @void *go@ = print destination
1170 * @unsigned unit@ = the unit being measured (~TVBU_...@)
1171 * @const struct bench_timing *tm@ = the benchmark result
1175 * Use: Formats a report about the benchmark performance. This
1176 * function is intended to be called on by an output
1177 * @ebench@ function.
1180 extern void tvec_benchreport
1181 (const struct gprintf_ops */
*gops*/
, void */
*go*/
,
1182 unsigned /*unit*/, const struct bench_timing */
*tm*/
);
1184 /*----- Remote execution --------------------------------------------------*/
1186 struct tvec_remotecomms
{
1187 int infd
, outfd
; /* input and output descriptors */
1188 dbuf bout
; /* output buffer */
1189 unsigned char *bin
; /* input buffer */
1190 size_t binoff
, binlen
, binsz
; /* input offset, length, and size */
1191 size_t t
; /* temporary offset */
1192 unsigned f
; /* flags */
1193 #define TVRF_BROKEN 0x0001u /* communications have failed */
1195 #define TVEC_REMOTECOMMS_INIT { -1, -1, DBUF_INIT, 0, 0, 0, 0, 0, 0 }
1197 struct tvec_remotectx
{
1198 struct tvec_state
*tv
; /* test vector state */
1199 struct tvec_remotecomms rc
; /* communication state */
1200 const struct tvec_remoteenv
*re
; /* environment configuration */
1201 unsigned ver
; /* protocol version */
1202 pid_t kid
; /* child process id */
1203 int errfd
; /* child stderr descriptor */
1204 lbuf errbuf
; /* child stderr line buffer */
1205 dstr prgwant
, progress
; /* progress: wanted/reported */
1206 unsigned exwant
, exit
; /* exit status wanted/reported */
1207 #define TVRF_RCNMASK 0x0300u /* reconnection behaviour: */
1208 #define TVRCN_SKIP 0x0000u /* skip unless connected */
1209 #define TVRCN_DEMAND 0x0100u /* connect on demand */
1210 #define TVRCN_FORCE 0x0200u /* force reconnection */
1211 #define TVRF_MUFFLE 0x0400u /* muffle child stderr */
1212 #define TVRF_SETEXIT 0x0800u /* set `@exit' */
1213 #define TVRF_SETPRG 0x1000u /* set `@progress' */
1214 #define TVRF_SETRCN 0x2000u /* set `@reconnect' */
1215 #define TVRF_SETMASK (TVRF_SETEXIT | TVRF_SETPRG | TVRF_SETRCN)
1216 /* mask of @TVTF_SET...@ */
1219 typedef int tvec_connectfn(pid_t */
*kid_out*/
, int */
*infd_out*/
,
1220 int */
*outfd_out*/
, int */
*errfd_out*/
,
1221 struct tvec_state */
*tv*/
,
1222 const struct tvec_remoteenv */
*env*/
);
1223 /* A connection function. On entry, @tv@ holds the test-vector state, and
1224 * @env@ is the test group's remote environment structure, which will
1225 * typically really be some subclass of @struct tvec_remoteenv@ containing
1226 * additional parameters for establishing the child process.
1228 * On successful completion, the function stores input and output
1229 * descriptors (which need not be distinct) in @*infd_out@ and
1230 * @*outfd_out@, and returns zero; if it creates a child process, it should
1231 * additionally store the child's process-id in @*kid_out@ and store in
1232 * @*errfd_out@ a descriptor from which the child's error output can be
1233 * read. On error, the function should report an appropriate message via
1234 * @tvec_error@ and return %$-1$%.
1237 struct tvec_remoteenv_slots
{
1238 tvec_connectfn
*connect
; /* connection function */
1239 const struct tvec_env
*env
; /* subsidiary environment */
1242 struct tvec_remoteenv
{
1243 struct tvec_env _env
;
1244 struct tvec_remoteenv_slots r
;
1247 struct tvec_remotefork_slots
{
1248 const struct tvec_test
*tests
; /* child tests (or null) */
1251 struct tvec_remotefork
{
1252 struct tvec_env _env
;
1253 struct tvec_remoteenv_slots r
;
1254 struct tvec_remotefork_slots f
;
1257 struct tvec_remoteexec_slots
{
1258 const char *const *args
; /* command line to execute */
1261 struct tvec_remoteexec
{
1262 struct tvec_env _env
;
1263 struct tvec_remoteenv_slots r
;
1264 struct tvec_remoteexec_slots x
;
1267 union tvec_remoteenv_subclass_kludge
{
1268 struct tvec_env _env
;
1269 struct tvec_remoteenv renv
;
1270 struct tvec_remotefork fork
;
1271 struct tvec_remoteexec exec
;
1276 * We don't use the conventional encoding returned by the @wait@(2) family of
1277 * system calls because it's too hard for our flags type to decode. Instead,
1278 * we use our own encoding.
1280 * The exit code or signal number ends up in the `value' field in the low 12
1281 * bits; bit 12 is set if the value field holds a signal, and it if holds an
1282 * exit code. Bits 13--15 hold a code which describes the status of a child
1283 * process or connection.
1285 #define TVXF_VALMASK 0x0fffu /* value (exit code or signal) */
1286 #define TVXF_SIG 0x1000u /* value is signal, not exit code */
1287 #define TVXF_CAUSEMASK 0xe000u /* mask for cause bits */
1288 #define TVXST_RUN 0x0000u /* still running */
1289 #define TVXST_EXIT 0x2000u /* child exited */
1290 #define TVXST_KILL 0x4000u /* child killed by signal */
1291 #define TVXST_CONT 0x6000u /* child continued (?) */
1292 #define TVXST_STOP 0x8000u /* child stopped (?) */
1293 #define TVXST_DISCONN 0xa000u /* disconnected */
1294 #define TVXST_UNK 0xc000u /* unknown */
1295 #define TVXST_ERR 0xe000u /* local error prevented diagnosis */
1297 /* Remote environment. */
1298 extern tvec_envsetupfn tvec_remotesetup
;
1299 extern tvec_envsetfn tvec_remoteset
;
1300 extern tvec_envrunfn tvec_remoterun
;
1301 extern tvec_envafterfn tvec_remoteafter
;
1302 extern tvec_envteardownfn tvec_remoteteardown
;
1303 #define TVEC_REMOTEENV \
1304 { sizeof(struct tvec_remotectx), \
1310 tvec_remoteteardown }
1312 /* --- @tvec_setprogress@, @tvec_setprogress_v@ --- *
1314 * Arguments: @const char *status@ = progress status token format
1315 * @va_list ap@ = argument tail
1319 * Use: Reports the progress of a test execution to the client.
1321 * The framework makes use of tokens beginning with %|%|%:
1323 * * %|%IDLE|%: during the top-level server code;
1325 * * %|%SETUP|%: during the enclosing environment's @before@
1328 * * %|%RUN|%: during the environment's @run@ function, or the
1329 * test function; and
1331 * * %|%DONE|%: during the enclosing environment's @after@
1334 * The intent is that a test can use the progress token to check
1335 * that a function which is expected to crash does so at the
1336 * correct point, so it's expected that more complex test
1337 * functions and/or environments will set their own progress
1338 * tokens to reflect what's going on.
1341 extern PRINTF_LIKE(1, 2) int tvec_setprogress(const char */
*status*/
, ...);
1342 extern int tvec_setprogress_v(const char */
*status*/
, va_list */
*ap*/
);
1344 /* --- @tvec_remoteserver@ --- *
1346 * Arguments: @int infd@, @int outfd@ = input and output file descriptors
1347 * @const struct tvec_config *config@ = test configuration
1349 * Returns: Suggested exit code.
1351 * Use: Run a test server, reading packets from @infd@ and writing
1352 * responses and notifications to @outfd@, and invoking tests as
1353 * described by @config@.
1355 * This function is not particularly general purpose. It
1356 * expects to `take over' the process, and makes use of private
1360 extern int tvec_remoteserver(int /*infd*/, int /*outfd*/,
1361 const struct tvec_config */
*config*/
);
1363 extern tvec_connectfn tvec_fork
, tvec_exec
;
1365 #define TVEC_REMOTEFORK(subenv, tests) \
1366 TVEC_REMOTEENV, { tvec_fork, subenv }, { tests }
1368 #define TVEC_REMOTEEXEC(subenv, args) \
1369 TVEC_REMOTEENV, { tvec_exec, subenv }, { args }
1371 /*----- Timeouts ----------------------------------------------------------*/
1373 struct tvec_timeoutenv
{
1374 struct tvec_env _env
;
1375 unsigned timer
; /* the timer (@ITIMER_...@) */
1376 double t
; /* time to wait (in seconds) */
1377 const struct tvec_env
*env
; /* subsidiary environment */
1380 struct tvec_timeoutctx
{
1381 const struct tvec_timeoutenv
*te
; /* saved environment description */
1382 unsigned timer
; /* timer code (as overridden) */
1383 double t
; /* time to wait (as overridden) */
1384 unsigned f
; /* flags */
1385 #define TVTF_SETTMO 1u /* set `@timeout' */
1386 #define TVTF_SETMASK (TVTF_SETTMO) /* mask of @TVTF_SET...@ */
1390 extern tvec_envsetupfn tvec_timeoutsetup
;
1391 extern tvec_envsetfn tvec_timeoutset
;
1392 extern tvec_envbeforefn tvec_timeoutbefore
;
1393 extern tvec_envrunfn tvec_timeoutrun
;
1394 extern tvec_envafterfn tvec_timeoutafter
;
1395 extern tvec_envteardownfn tvec_timeoutteardown
;
1396 #define TVEC_TIMEOUTENV \
1397 { sizeof(struct tvec_timeoutctx), \
1398 tvec_timeoutsetup, \
1400 tvec_timeoutbefore, \
1402 tvec_timeoutafter, \
1403 tvec_timeoutteardown }
1404 #define TVEC_TIMEOUTINIT(timer, t) TVEC_TIMEOUTENV, timer, t
1406 /*----- Output functions --------------------------------------------------*/
1408 /* --- @tvec_strlevel@ --- *
1410 * Arguments: @unsigned level@ = level code
1412 * Returns: A human-readable description.
1414 * Use: Converts a level code into something that you can print in a
1418 extern const char *tvec_strlevel(unsigned /*level*/);
1420 /* --- @tvec_report@, @tvec_report_v@ --- *
1422 * Arguments: @struct tvec_state *tv@ = test-vector state
1423 * @const char *msg@, @va_list ap@ = error message
1427 * Use: Report an message with a given severity. Messages with level
1428 * @TVLEV_ERR@ or higher force a nonzero exit code.
1431 extern PRINTF_LIKE(3, 4)
1432 void tvec_report(struct tvec_state */
*tv*/
, unsigned /*level*/,
1433 const char */
*msg*/
, ...);
1434 extern void tvec_report_v(struct tvec_state */
*tv*/
, unsigned /*level*/,
1435 const char */
*msg*/
, va_list */
*ap*/
);
1437 /* --- @tvec_error@, @tvec_notice@ --- *
1439 * Arguments: @struct tvec_state *tv@ = test-vector state
1440 * @const char *msg@, @va_list ap@ = error message
1442 * Returns: The @tvec_error@ function returns %$-1$% as a trivial
1443 * convenience; @tvec_notice@ does not return a value.
1445 * Use: Report an error or a notice. Errors are distinct from test
1446 * failures, and indicate that a problem was encountered which
1447 * compromised the activity of testing. Notices are important
1448 * information which doesn't fit into any other obvious
1452 extern PRINTF_LIKE(2, 3)
1453 int tvec_error(struct tvec_state */
*tv*/
, const char */
*msg*/
, ...);
1454 extern PRINTF_LIKE(2, 3)
1455 void tvec_notice(struct tvec_state */
*tv*/
, const char */
*msg*/
, ...);
1457 /* --- @tvec_humanoutput@ --- *
1459 * Arguments: @FILE *fp@ = output file to write on
1461 * Returns: An output formatter.
1463 * Use: Return an output formatter which writes on @fp@ with the
1464 * expectation that a human will be watching and interpreting
1465 * the output. If @fp@ denotes a terminal, the display shows a
1466 * `scoreboard' indicating the outcome of each test case
1467 * attempted, and may in addition use colour and other
1471 extern struct tvec_output
*tvec_humanoutput(FILE */
*fp*/
);
1473 /* --- @tvec_tapoutput@ --- *
1475 * Arguments: @FILE *fp@ = output file to write on
1477 * Returns: An output formatter.
1479 * Use: Return an output formatter which writes on @fp@ in `TAP'
1480 * (`Test Anything Protocol') format.
1482 * TAP comes from the Perl community, but has spread rather
1483 * further. This driver produces TAP version 14, but pretends
1484 * to be version 13. The driver produces a TAP `test point' --
1485 * i.e., a result reported as `ok' or `not ok' -- for each input
1486 * test group. Failure reports and register dumps are produced
1487 * as diagnostic messages before the final group result. (TAP
1488 * permits structuerd YAML data after the test-point result,
1489 * which could be used to report details, but (a) postponing the
1490 * details until after the report is inconvenient, and (b) there
1491 * is no standardization for the YAML anyway, so in practice
1492 * it's no more useful than the unstructured diagnostics.
1495 extern struct tvec_output
*tvec_tapoutput(FILE */
*fp*/
);
1497 /* --- @tvec_dfltoutput@ --- *
1499 * Arguments: @FILE *fp@ = output file to write on
1501 * Returns: An output formatter.
1503 * Use: Selects and instantiates an output formatter suitable for
1504 * writing on @fp@. The policy is subject to change, but
1505 * currently the `human' output format is selected if @fp@ is
1506 * interactive (i.e., if @isatty(fileno(fp))@ is true), and
1507 * otherwise the `tap' format is used.
1510 extern struct tvec_output
*tvec_dfltout(FILE */
*fp*/
);
1512 /*------ Serialization utilities ------------------------------------------*/
1514 /* Serialization format.
1516 * The `candidate register definitions' are those entries @r@ in the @regs@
1517 * vector whose index @r.i@ is strictly less than @nr@. The `selected
1518 * register definitions' are those candidate register definitions @r@ for
1519 * which the indicated register @rv[r.i]@ has the @TVRF_LIVE@ flag set. The
1520 * serialized output begins with a header bitmap: if there are %$n$%
1521 * candidate register definitions then the header bitmap consists of %$\lceil
1522 * n/8 \rceil$% bytes. Bits are ordered starting from the least significant
1523 * bit of the first byte, end ending at the most significant bit of the final
1524 * byte. The bit corresponding to a candidate register definition is set if
1525 * and only if that register defintion is selected. The header bitmap is
1526 * then followed by the serializations of the selected registers -- i.e., for
1527 * each selected register definition @r@, the serialized value of register
1528 * @rv[r.i]@ -- simply concatenated together, with no padding or alignment.
1531 /* --- @tvec_serialize@ --- *
1533 * Arguments: @const struct tvec_reg *rv@ = vector of registers
1534 * @buf *b@ = buffer to write on
1535 * @const struct tvec_regdef *regs@ = vector of register
1536 * descriptions, terminated by an entry with a null
1538 * @unsigned nr@ = number of entries in the @rv@ vector
1539 * @size_t regsz@ = true size of each element of @rv@
1541 * Returns: Zero on success, %$-1$% on failure.
1543 * Use: Serialize a collection of register values.
1545 * The serialized output is written to the buffer @b@. Failure
1546 * can be caused by running out of buffer space, or a failing
1550 extern int tvec_serialize(const struct tvec_reg */
*rv*/
, buf */
*b*/
,
1551 const struct tvec_regdef */
*regs*/
,
1552 unsigned /*nr*/, size_t /*regsz*/);
1554 /* --- @tvec_deserialize@ --- *
1556 * Arguments: @struct tvec_reg *rv@ = vector of registers
1557 * @buf *b@ = buffer to write on
1558 * @const struct tvec_regdef *regs@ = vector of register
1559 * descriptions, terminated by an entry with a null
1561 * @unsigned nr@ = number of entries in the @rv@ vector
1562 * @size_t regsz@ = true size of each element of @rv@
1564 * Returns: Zero on success, %$-1$% on failure.
1566 * Use: Deserialize a collection of register values.
1568 * The size of the register vector @nr@ and the register
1569 * definitions @regs@ must match those used when producing the
1570 * serialization. For each serialized register value,
1571 * deserialize and store the value into the appropriate register
1572 * slot, and set the @TVRF_LIVE@ flag on the register. See
1573 * @tvec_serialize@ for a description of the format.
1575 * Failure results only from a failing register type handler.
1578 extern int tvec_deserialize(struct tvec_reg */
*rv*/
, buf */
*b*/
,
1579 const struct tvec_regdef */
*regs*/
,
1580 unsigned /*nr*/, size_t /*regsz*/);
1582 /*----- Input utilities ---------------------------------------------------*/
1584 /* These are provided by the core for the benefit of type @parse@ methods,
1585 * and test-environment @set@ functions, which get to read from the test
1586 * input file. The latter are usually best implemented by calling on the
1589 * The two main rules are as follows.
1591 * * Leave the file position at the beginning of the line following
1592 * whatever it was that you read.
1594 * * When you read and consume a newline (which you do at least once, by
1595 * the previous rule), then increment @tv->lno@ to keep track of the
1596 * current line number.
1599 /* --- @tvec_syntax@, @tvec_syntax_v@ --- *
1601 * Arguments: @struct tvec_state *tv@ = test-vector state
1602 * @int ch@ = the character found (in @fgetc@ format)
1603 * @const char *expect@, @va_list ap@ = what was expected
1607 * Use: Report a syntax error quoting @ch@ and @expect@. If @ch@ is
1608 * a newline, then back up so that it can be read again (e.g.,
1609 * by @tvec_flushtoeol@ or @tvec_nexttoken@, which will also
1610 * advance the line number).
1613 extern PRINTF_LIKE(3, 4)
1614 int tvec_syntax(struct tvec_state */
*tv*/
, int /*ch*/,
1615 const char */
*expect*/
, ...);
1616 extern int tvec_syntax_v(struct tvec_state */
*tv*/
, int /*ch*/,
1617 const char */
*expect*/
, va_list */
*ap*/
);
1619 /* --- @tvec_dupreg@ --- *
1621 * Arguments: @struct tvec_state *tv@ = test-vector state
1622 * @const char *name@ = register or pseudoregister name
1626 * Use: Reports an error that the register or pseudoregister has been
1627 * assigned already in the current test.
1630 extern int tvec_dupreg(struct tvec_state */
*tv*/
, const char */
*name*/
);
1632 /* --- @tvec_skipspc@ --- *
1634 * Arguments: @struct tvec_state *tv@ = test-vector state
1638 * Use: Advance over any whitespace characters other than newlines.
1639 * This will stop at `;', end-of-file, or any other kind of
1640 * non-whitespace; and it won't consume a newline.
1643 extern void tvec_skipspc(struct tvec_state */
*tv*/
);
1645 /* --- @tvec_flushtoeol@ --- *
1647 * Arguments: @struct tvec_state *tv@ = test-vector state
1648 * @unsigned f@ = flags (@TVFF_...@)
1650 * Returns: Zero on success, %$-1$% on error.
1652 * Use: Advance to the start of the next line, consuming the
1653 * preceding newline.
1655 * A syntax error is reported if no newline character is found,
1656 * i.e., the file ends in mid-line. A syntax error is also
1657 * reported if material other than whitespace or a comment is
1658 * found before the end of the line end, and @TVFF_ALLOWANY@ is
1659 * not set in @f@. The line number count is updated
1663 #define TVFF_ALLOWANY 1u
1664 extern int tvec_flushtoeol(struct tvec_state */
*tv*/
, unsigned /*f*/);
1666 /* --- @tvec_nexttoken@ --- *
1668 * Arguments: @struct tvec_state *tv@ = test-vector state
1670 * Returns: Zero if there is a next token which can be read; %$-1$% if no
1671 * token is available.
1673 * Use: Advance to the next whitespace-separated token, which may be
1676 * Tokens are separated by non-newline whitespace, comments, and
1677 * newlines followed by whitespace; a newline /not/ followed by
1678 * whitespace instead begins the next assignment, and two
1679 * newlines separated only by whitespace terminate the data for
1682 * If this function returns zero, then the next character in the
1683 * file begins a suitable token which can be read and
1684 * processed. If it returns %$-1$% then there is no such token,
1685 * and the file position is left correctly. The line number
1686 * count is updated appropriately.
1689 extern int tvec_nexttoken(struct tvec_state */
*tv*/
);
1691 /* --- @tvec_readword@, @tvec_readword_v@ --- *
1693 * Arguments: @struct tvec_state *tv@ = test-vector state
1694 * @dstr *d@ = string to append the word to
1695 * @const char *delims@ = additional delimiters to stop at
1696 * @const char *expect@, @va_list ap@ = what was expected
1698 * Returns: Zero on success, %$-1$% on failure.
1700 * Use: A `word' consists of characters other than whitespace, null
1701 * characters, and other than those listed in @delims@;
1702 * furthermore, a word does not begin with a `;'. (If you want
1703 * reading to stop at comments not preceded by whitespace, then
1704 * include `;' in @delims@. This is a common behaviour.)
1706 * If there is no word beginning at the current file position,
1707 * then return %$-1$%; furthermore, if @expect@ is not null,
1708 * then report an appropriate error via @tvec_syntax@.
1710 * Otherwise, the word is accumulated in @d@ and zero is
1711 * returned; if @d@ was not empty at the start of the call, the
1712 * newly read word is separated from the existing material by a
1713 * single space character. Since null bytes are never valid
1714 * word constituents, a null terminator is written to @d@, and
1715 * it is safe to treat the string in @d@ as being null-
1719 extern PRINTF_LIKE(4, 5)
1720 int tvec_readword(struct tvec_state */
*tv*/
, dstr */
*d*/
,
1721 const char */
*delims*/
, const char */
*expect*/
, ...);
1722 extern int tvec_readword_v(struct tvec_state */
*tv*/
, dstr */
*d*/
,
1723 const char */
*delims*/
, const char */
*expect*/
,
1726 /*----- Integer types: signed and unsigned --------------------------------*/
1728 /* Integers may be input in decimal, hex, binary, or octal, following
1729 * approximately usual conventions.
1731 * * Signed integers may be preceded with a `+' or `-' sign.
1733 * * Decimal integers are just a sequence of decimal digits `0' ... `9'.
1735 * * Octal integers are a sequence of digits `0' ... `7', preceded by `0o'
1738 * * Hexadecimal integers are a sequence of digits `0' ... `9', `a'
1739 * ... `f', or `A' ... `F', preceded by `0x' or `0X'.
1741 * * Radix-B integers are a sequence of digits `0' ... `9', `a' ... `f', or
1742 * `A' ... `F', each with value less than B, preceded by `Br' or `BR',
1743 * where 0 < B < 36 is expressed in decimal without any leading `0' or
1744 * internal underscores `_'.
1746 * * A digit sequence may contain internal underscore `_' separators, but
1747 * not before or after all of the digits; and two consecutive `_'
1748 * characters are not permitted.
1751 extern const struct tvec_regty tvty_int
, tvty_uint
;
1753 /* The @arg.p@ slot may be null or a pointer to @struct tvec_irange@ or
1754 * @struct tvec_urange@ as appropriate. The bounds are inclusive; use, e.g.,
1755 * @LONG_MAX@ explicitly if one or the other bound is logically inapplicable.
1757 struct tvec_irange
{ long min
, max
; };
1758 struct tvec_urange
{ unsigned long min
, max
; };
1760 /* Bounds corresponding to common integer types. */
1761 extern const struct tvec_irange
1762 tvrange_schar
, tvrange_short
, tvrange_int
, tvrange_long
,
1763 tvrange_sbyte
, tvrange_i16
, tvrange_i32
;
1764 extern const struct tvec_urange
1765 tvrange_uchar
, tvrange_ushort
, tvrange_uint
, tvrange_ulong
, tvrange_size
,
1766 tvrange_byte
, tvrange_u16
, tvrange_u32
;
1768 /* --- @tvec_claimeq_int@, @TVEC_CLAIMEQ_INT@ --- *
1770 * Arguments: @struct tvec_state *tv@ = test-vector state
1771 * @long i0, i1@ = two signed integers
1772 * @const char *file@, @unsigned @lno@ = calling file and line
1773 * @const char *expr@ = the expression to quote on failure
1775 * Returns: Nonzero if @i0@ and @i1@ are equal, otherwise zero.
1777 * Use: Check that values of @i0@ and @i1@ are equal. As for
1778 * @tvec_claim@ above, a test case is automatically begun and
1779 * ended if none is already underway. If the values are
1780 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
1781 * mismatched values are dumped: @i0@ is printed as the output
1782 * value and @i1@ is printed as the input reference.
1784 * The @TVEC_CLAIM_INT@ macro is similar, only it (a) identifies
1785 * the file and line number of the call site automatically, and
1786 * (b) implicitly quotes the source text of the @i0@ and @i1@
1787 * arguments in the failure message.
1790 extern int tvec_claimeq_int(struct tvec_state */
*tv*/
,
1791 long /*i0*/, long /*i1*/,
1792 const char */
*file*/
, unsigned /*lno*/,
1793 const char */
*expr*/
);
1794 #define TVEC_CLAIMEQ_INT(tv, i0, i1) \
1795 (tvec_claimeq_int(tv, i0, i1, __FILE__, __LINE__, #i0 " /= " #i1))
1797 /* --- @tvec_claimeq_uint@, @TVEC_CLAIMEQ_UINT@ --- *
1799 * Arguments: @struct tvec_state *tv@ = test-vector state
1800 * @unsigned long u0, u1@ = two unsigned integers
1801 * @const char *file@, @unsigned @lno@ = calling file and line
1802 * @const char *expr@ = the expression to quote on failure
1804 * Returns: Nonzero if @u0@ and @u1@ are equal, otherwise zero.
1806 * Use: Check that values of @u0@ and @u1@ are equal. As for
1807 * @tvec_claim@ above, a test case is automatically begun and
1808 * ended if none is already underway. If the values are
1809 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
1810 * mismatched values are dumped: @u0@ is printed as the output
1811 * value and @u1@ is printed as the input reference.
1813 * The @TVEC_CLAIM_UINT@ macro is similar, only it (a)
1814 * identifies the file and line number of the call site
1815 * automatically, and (b) implicitly quotes the source text of
1816 * the @u0@ and @u1@ arguments in the failure message.
1819 extern int tvec_claimeq_uint(struct tvec_state */
*tv*/
,
1820 unsigned long /*u0*/, unsigned long /*u1*/,
1821 const char */
*file*/
, unsigned /*lno*/,
1822 const char */
*expr*/
);
1823 #define TVEC_CLAIMEQ_UINT(tv, u0, u1) \
1824 (tvec_claimeq_uint(tv, u0, u1, __FILE__, __LINE__, #u0 " /= " #u1))
1826 /*----- Floating-point type -----------------------------------------------*/
1828 /* Floating-point values are either NaN (%|#nan|%, if supported by the
1829 * platform); positive or negative infinity (%|#inf|%, %|+#inf|%, or
1830 * %|#+inf|% (preferring the last), and %|-#inf|% or %|#-inf|% (preferring
1831 * the latter), if supported by the platform); or a number in strtod(3)
1834 * The comparison rules for floating-point numbers are complex: see
1835 * @tvec_claimeqish_float@ for details.
1838 extern const struct tvec_regty tvty_float
;
1840 struct tvec_floatinfo
{
1841 /* Details about acceptable floating-point values. */
1843 unsigned f
; /* flags (@TVFF_...@ bits) */
1844 #define TVFF_NOMIN 1u /* ignore @min@ (allow -inf) */
1845 #define TVFF_NOMAX 2u /* ignore @max@ (allow +inf) */
1846 #define TVFF_NANOK 4u /* permit NaN */
1847 #define TVFF_EQMASK 0xf0 /* how to compare */
1848 #define TVFF_EXACT 0x00 /* must equal exactly */
1849 #define TVFF_ABSDELTA 0x10 /* must be within @delta@ */
1850 #define TVFF_RELDELTA 0x20 /* diff < @delta@ fraction */
1851 double min
, max
; /* smallest/largest value allowed */
1852 double delta
; /* maximum tolerable difference */
1855 /* --- @tvec_claimeqish_float@, @TVEC_CLAIMEQISH_FLOAT@ --- *
1857 * Arguments: @struct tvec_state *tv@ = test-vector state
1858 * @double f0, f1@ = two floating-point numbers
1859 * @unsigned f@ = flags (@TVFF_...@)
1860 * @double delta@ = maximum tolerable difference
1861 * @const char *file@, @unsigned @lno@ = calling file and line
1862 * @const char *expr@ = the expression to quote on failure
1864 * Returns: Nonzero if @f0@ and @u1@ are sufficiently close, otherwise
1867 * Use: Check that values of @f0@ and @f1@ are sufficiently close.
1868 * As for @tvec_claim@ above, a test case is automatically begun
1869 * and ended if none is already underway. If the values are
1870 * too far apart, then @tvec_fail@ is called, quoting @expr@,
1871 * and the mismatched values are dumped: @f0@ is printed as the
1872 * output value and @f1@ is printed as the input reference.
1874 * The details for the comparison are as follows.
1876 * * A NaN value matches any other NaN, and nothing else.
1878 * * An infinity matches another infinity of the same sign,
1881 * * If @f&TVFF_EQMASK@ is @TVFF_EXACT@, then any
1882 * representable number matches only itself: in particular,
1883 * positive and negative zero are considered distinct.
1884 * (This allows tests to check that they land on the correct
1885 * side of branch cuts, for example.)
1887 * * If @f&TVFF_EQMASK@ is @TVFF_ABSDELTA@, then %$x$% matches
1888 * %$y$% when %$|x - y| < \delta$%.
1890 * * If @f&TVFF_EQMASK@ is @TVFF_RELDELTA@, then %$x$% matches
1891 * %$y$% when %$|1 - y/x| < \delta$%. (Note that this
1892 * criterion is asymmetric FIXME
1894 * The @TVEC_CLAIM_FLOAT@ macro is similar, only it (a)
1895 * identifies the file and line number of the call site
1896 * automatically, and (b) implicitly quotes the source text of
1897 * the @f0@ and @f1@ arguments (and @delta@) in the failure
1901 extern int tvec_claimeqish_float(struct tvec_state */
*tv*/
,
1902 double /*f0*/, double /*f1*/,
1903 unsigned /*f*/, double /*delta*/,
1904 const char */
*file*/
, unsigned /*lno*/,
1905 const char */
*expr*/
);
1906 #define TVEC_CLAIMEQISH_FLOAT(tv, f0, f1, f, delta) \
1907 (tvec_claimeqish_float(tv, f0, f1, f, delta, , __FILE__, __LINE__, \
1908 #f0 " /= " #f1 " (+/- " #delta ")"))
1910 /* --- @tvec_claimeq_float@, @TVEC_CLAIMEQ_FLOAT@ --- *
1912 * Arguments: @struct tvec_state *tv@ = test-vector state
1913 * @double f0, f1@ = two floating-point numbers
1914 * @const char *file@, @unsigned @lno@ = calling file and line
1915 * @const char *expr@ = the expression to quote on failure
1917 * Returns: Nonzero if @f0@ and @u1@ are identical, otherwise zero.
1919 * Use: Check that values of @f0@ and @f1@ are identical. The
1920 * function is exactly equivalent to @tvec_claimeqish_float@
1921 * with @f == TVFF_EXACT@; the macro is similarly like
1922 * @TVEC_CLAIMEQISH_FLOAT@ with @f == TVFF_EXACT@, except that
1923 * it doesn't bother to quote a delta.
1926 extern int tvec_claimeq_float(struct tvec_state */
*tv*/
,
1927 double /*f0*/, double /*f1*/,
1928 const char */
*file*/
, unsigned /*lno*/,
1929 const char */
*expr*/
);
1930 #define TVEC_CLAIMEQ_FLOAT(tv, f0, f1) \
1931 (tvec_claimeq_float(tv, f0, f1, __FILE__, __LINE__, #f0 " /= " #f1))
1933 extern const struct tvec_floatinfo tvflt_finite
, tvflt_nonneg
;
1935 /*----- Enumerated types --------------------------------------------------*/
1937 /* An enumeration describes a set of values of some underlying type, each of
1938 * which has a symbolic name. Values outside of the defined set can occur --
1939 * on output, because of bugs in the tested code, or on input to test
1940 * handling of unexpected values.
1942 * There is a distinct enumerated type for each of the branches of
1943 * @tvec_misc@. In the following, we write @t@ for the type code, which is
1944 * @i@ for signed integer, @u@ for unsigned integer, @f@ for floating-point,
1945 * and @p@ for pointer.
1947 * On input, an enumerated value may be given by name or as a literal value.
1948 * For enumerations based on numeric types, the literal values can be written
1949 * in the same syntax as the underlying values. For enumerations based on
1950 * pointers, the only permitted literal is %|#nil|%, which denotes a null
1951 * pointer. On output, names are preferred (with the underlying value given
1955 #define DEFENUMTY(tag, ty, slot) \
1956 extern const struct tvec_regty tvty_##slot##enum;
1957 TVEC_MISCSLOTS(DEFENUMTY
)
1960 /* A @struct tvec_tassoc@ associates a string tag with a value. */
1961 #define DEFASSOC(tag_, ty, slot) \
1962 struct tvec_##slot##assoc { const char *tag; ty slot; };
1963 TVEC_MISCSLOTS(DEFASSOC
)
1966 #define TVEC_ENDENUM { 0, 0 }
1968 /* Information about an enumerated type. */
1969 #define DEFINFO(tag, ty, slot) \
1970 struct tvec_##slot##enuminfo { \
1971 const char *name; /* type name for diagnostics */ \
1972 const struct tvec_##slot##assoc *av; /* name/value mappings */ \
1973 EXTRA_##tag##_INFOSLOTS /* type-specific extra info */ \
1976 #define EXTRA_INT_INFOSLOTS \
1977 const struct tvec_irange *ir; /* allowed range of raw values */
1979 #define EXTRA_UINT_INFOSLOTS \
1980 const struct tvec_urange *ur; /* allowed range of raw values */
1982 #define EXTRA_FLT_INFOSLOTS \
1983 const struct tvec_floatinfo *fi; /* range and matching policy */
1985 #define EXTRA_PTR_INFOSLOTS /* (nothing) */
1987 TVEC_MISCSLOTS(DEFINFO
)
1989 #undef EXTRA_INT_INFOSLOTS
1990 #undef EXTRA_UINT_INFOSLOTS
1991 #undef EXTRA_FLT_INFOSLOTS
1992 #undef EXTRA_PTR_INFOSLOTS
1996 /* Standard enumerations. */
1997 extern const struct tvec_ienuminfo tvenum_bool
;
1998 extern const struct tvec_ienuminfo tvenum_cmp
;
2000 /* --- @tvec_claimeq_tenum@, @TVEC_CLAIMEQ_TENUM@ --- *
2002 * Arguments: @struct tvec_state *tv@ = test-vector state
2003 * @const struct tvec_typeenuminfo *ei@ = enumeration type info
2004 * @ty t0, t1@ = two values
2005 * @const char *file@, @unsigned @lno@ = calling file and line
2006 * @const char *expr@ = the expression to quote on failure
2008 * Returns: Nonzero if @t0@ and @t1@ are equal, otherwise zero.
2010 * Use: Check that values of @t0@ and @t1@ are equal. As for
2011 * @tvec_claim@ above, a test case is automatically begun and
2012 * ended if none is already underway. If the values are
2013 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
2014 * mismatched values are dumped: @t0@ is printed as the output
2015 * value and @t1@ is printed as the input reference.
2017 * The @TVEC_CLAIM_TENUM@ macro is similar, only it (a)
2018 * identifies the file and line number of the call site
2019 * automatically, and (b) implicitly quotes the source text of
2020 * the @t0@ and @t1@ arguments in the failure message.
2023 #define DECLCLAIM(tag, ty, slot) \
2024 extern int tvec_claimeq_##slot##enum \
2025 (struct tvec_state */*tv*/, \
2026 const struct tvec_##slot##enuminfo */*ei*/, \
2027 ty /*t0*/, ty /*t1*/, \
2028 const char */*file*/, unsigned /*lno*/, const char */*expr*/);
2029 TVEC_MISCSLOTS(DECLCLAIM
)
2031 #define TVEC_CLAIMEQ_IENUM(tv, ei, i0, i1) \
2032 (tvec_claimeq_ienum(tv, ei, i0, i1, \
2033 __FILE__, __LINE__, #i0 " /= " #i1))
2034 #define TVEC_CLAIMEQ_UENUM(tv, ei, u0, u1) \
2035 (tvec_claimeq_uenum(tv, ei, u0, u1, \
2036 __FILE__, __LINE__, #u0 " /= " #u1))
2037 #define TVEC_CLAIMEQ_FENUM(tv, ei, f0, f1) \
2038 (tvec_claimeq_fenum(tv, ei, f0, f1, \
2039 __FILE__, __LINE__, #f0 " /= " #f1))
2040 #define TVEC_CLAIMEQ_PENUM(tv, ei, p0, p1) \
2041 (tvec_claimeq_penum(tv, ei, p0, p1, \
2042 __FILE__, __LINE__, #p0 " /= " #p1))
2044 /*----- Flags type --------------------------------------------------------*/
2046 /* A flags value packs a number of fields into a single nonnegative integer.
2047 * Symbolic names are associated with the possible values of the various
2048 * fields; more precisely, each name is associated with a value and a
2051 * The input syntax is a sequence of items separated by `%|||%' signs. Each
2052 * item may be the symbolic name of a field value, or a literal unsigned
2053 * integer. The masks associated with the given symbolic names must be
2054 * disjoint. The resulting numerical value is simply the bitwise OR of the
2057 * On output, the table of symbolic names and their associated values and
2058 * masks is repeatedly scanned, in order, to find disjoint matches -- i.e.,
2059 * entries whose value matches the target value in the bit positions
2060 * indicated by the mask, and whose mask doesn't overlap with any previously
2061 * found matches; the names are then output, separated by `%|||%'. Any
2062 * remaining nonzero bits not covered by any of the matching masks are output
2063 * as a single literal integer, in hex.
2066 extern const struct tvec_regty tvty_flags
;
2069 /* Definition of a single flag or bitfield value.
2071 * Each named setting comes with a value @v@ and a mask @m@; the mask
2072 * should cover all of the value bits, i.e., @(v&~m) == 0@.
2075 const char *tag
; /* name */
2076 unsigned long m
, v
; /* mask and value */
2079 #define TVEC_ENDFLAGS { 0, 0, 0 }
2081 struct tvec_flaginfo
{
2082 /* Information about a flags type. */
2084 const char *name
; /* type name for diagnostics */
2085 const struct tvec_flag
*fv
; /* name/mask/value mappings */
2086 const struct tvec_urange
*range
; /* permitted range for literals */
2089 /* --- @tvec_claimeq_flags@, @TVEC_CLAIMEQ_FLAGS@ --- *
2091 * Arguments: @struct tvec_state *tv@ = test-vector state
2092 * @const struct tvec_flaginfo *fi@ = flags type info
2093 * @unsigned long f0, f1@ = two values
2094 * @const char *file@, @unsigned @lno@ = calling file and line
2095 * @const char *expr@ = the expression to quote on failure
2097 * Returns: Nonzero if @f0@ and @f1@ are equal, otherwise zero.
2099 * Use: Check that values of @f0@ and @f1@ are equal. As for
2100 * @tvec_claim@ above, a test case is automatically begun and
2101 * ended if none is already underway. If the values are
2102 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
2103 * mismatched values are dumped: @f0@ is printed as the output
2104 * value and @f1@ is printed as the input reference.
2106 * The @TVEC_CLAIM_FLAGS@ macro is similar, only it (a)
2107 * identifies the file and line number of the call site
2108 * automatically, and (b) implicitly quotes the source text of
2109 * the @f0@ and @f1@ arguments in the failure message.
2112 extern int tvec_claimeq_flags(struct tvec_state */
*tv*/
,
2113 const struct tvec_flaginfo */
*fi*/
,
2114 unsigned long /*f0*/, unsigned long /*f1*/,
2115 const char */
*file*/
, unsigned /*lno*/,
2116 const char */
*expr*/
);
2117 #define TVEC_CLAIMEQ_FLAGS(tv, fi, f0, f1) \
2118 (tvec_claimeq_flags(tv, fi, f0, f1, \
2119 __FILE__, __LINE__, #f0 " /= " #f1))
2121 /*----- Character type ----------------------------------------------------*/
2123 /* A character value holds a character, as read by @fgetc@. The special
2124 * @EOF@ value can also be represented.
2126 * On input, a character value can be given by symbolic name, with a leading
2127 * `%|#|%'; or a character or `%|\|%'-escape sequence, optionally in single
2130 * The following escape sequences and character names are recognized.
2132 * * `%|#eof|%' is the special end-of-file marker.
2134 * * `%|#nul|%' is the NUL character, sometimes used to terminate strings.
2136 * * `%|bell|%', `%|bel|%', `%|ding|%', or `%|\a|%' is the BEL character
2137 * used to ring the terminal bell (or do some other thing to attract the
2138 * user's attention).
2140 * * %|#backspace|%, %|#bs|%, or %|\b|% is the backspace character, used to
2141 * move the cursor backwords by one cell.
2143 * * %|#escape|% %|#esc|%, or%|\e|% is the escape character, used to
2144 * introduce special terminal commands.
2146 * * %|#formfeed|%, %|#ff|%, or %|\f|% is the formfeed character, used to
2147 * separate pages of text.
2149 * * %|#newline|%, %|#linefeed|%, %|#lf|%, %|#nl|%, or %|\n|% is the
2150 * newline character, used to terminate lines of text or advance the
2151 * cursor to the next line (perhaps without returning it to the start of
2154 * * %|#return|%, %|#carriage-return|%, %|#cr|%, or %|\r|% is the
2155 * carriage-return character, used to return the cursor to the start of
2158 * * %|#tab|%, %|#horizontal-tab|%, %|#ht|%, or %|\t|% is the tab
2159 * character, used to advance the cursor to the next tab stop on the
2162 * * %|#vertical-tab|%, %|#vt|%, %|\v|% is the vertical tab character.
2164 * * %|#space|%, %|#spc|% is the space character.
2166 * * %|#delete|%, %|#del|% is the delete character, used to erase the most
2169 * * %|\'|% is the single-quote character.
2171 * * %|\\|% is the backslash character.
2173 * * %|\"|% is the double-quote character.
2175 * * %|\NNN|% or %|\{NNN}|% is the character with code NNN in octal. The
2176 * NNN may be up to three digits long.
2178 * * %|\xNN|% or %|\x{NN}|% is the character with code NNN in hexadecimal.
2181 extern const struct tvec_regty tvty_char
;
2183 /* --- @tvec_claimeq_char@, @TVEC_CLAIMEQ_CHAR@ --- *
2185 * Arguments: @struct tvec_state *tv@ = test-vector state
2186 * @int ch0, ch1@ = two character codes
2187 * @const char *file@, @unsigned @lno@ = calling file and line
2188 * @const char *expr@ = the expression to quote on failure
2190 * Returns: Nonzero if @ch0@ and @ch1@ are equal, otherwise zero.
2192 * Use: Check that values of @ch0@ and @ch1@ are equal. As for
2193 * @tvec_claim@ above, a test case is automatically begun and
2194 * ended if none is already underway. If the values are
2195 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
2196 * mismatched values are dumped: @ch0@ is printed as the output
2197 * value and @ch1@ is printed as the input reference.
2199 * The @TVEC_CLAIM_CHAR@ macro is similar, only it (a)
2200 * identifies the file and line number of the call site
2201 * automatically, and (b) implicitly quotes the source text of
2202 * the @ch0@ and @ch1@ arguments in the failure message.
2205 extern int tvec_claimeq_char(struct tvec_state */
*tv*/
,
2206 int /*ch0*/, int /*ch1*/,
2207 const char */
*file*/
, unsigned /*lno*/,
2208 const char */
*expr*/
);
2209 #define TVEC_CLAIMEQ_CHAR(tv, c0, c1) \
2210 (tvec_claimeq_char(tv, c0, c1, __FILE__, __LINE__, #c0 " /= " #c1))
2212 /*----- Text and binary string types --------------------------------------*/
2214 /* A string is a sequence of octets. Text and binary strings differ
2215 * primarily in presentation: text strings are shown as raw characters where
2216 * possible; binary strings are shown as hex dumps with an auxiliary text
2219 * The input format for both kinds of strings is basically the same: a
2220 * `compound string', consisting of
2222 * * single-quoted strings, which are interpreted entirely literally, but
2223 * can't contain single quotes or newlines;
2225 * * double-quoted strings, in which `%|\|%'-escapes are interpreted as for
2228 * * character names, marked by an initial `%|#|%' sign;
2230 * * special tokens marked by an initial `%|!|%' sign; or
2232 * * barewords interpreted according to the current coding scheme.
2234 * The special tokens are
2236 * * `%|!bare|%', which causes subsequent sequences of barewords to be
2237 * treated as plain text;
2239 * * `%|!hex|%', `%|!base32|%', `%|!base64|%', which cause subsequent
2240 * barewords to be decoded in the requested manner.
2242 * * `%|!repeat|% %$n$% %|{|% %%\textit{string}%% %|}|%', which includes
2243 * %$n$% copies of the (compound) string.
2245 * The only difference between text and binary strings is that the initial
2246 * coding scheme is %|bare|% for text strings and %|hex|% for binary strings.
2248 * Either kind of string can contain internal nul characters. A trailing nul
2249 * is appended -- beyond the stated input length -- to input strings as a
2250 * convenience to test functions. Test functions may include such a nul
2251 * character on output but this is not checked by the equality test.
2253 * A @struct tvec_urange@ may be supplied as an argument: the length of the
2254 * string (in bytes) will be checked against the permitted range.
2257 extern const struct tvec_regty tvty_text
, tvty_bytes
;
2259 /* --- @tvec_claimeq_text@, @TVEC_CLAIMEQ_TEXT@ --- *
2261 * Arguments: @struct tvec_state *tv@ = test-vector state
2262 * @const char *p0@, @size_t sz0@ = first string with length
2263 * @const char *p1@, @size_t sz1@ = second string with length
2264 * @const char *file@, @unsigned @lno@ = calling file and line
2265 * @const char *expr@ = the expression to quote on failure
2267 * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise
2270 * Use: Check that strings at @p0@ and @p1@ are equal. As for
2271 * @tvec_claim@ above, a test case is automatically begun and
2272 * ended if none is already underway. If the values are
2273 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
2274 * mismatched values are dumped: @p0@ is printed as the output
2275 * value and @p1@ is printed as the input reference.
2277 * The @TVEC_CLAIM_TEXT@ macro is similar, only it (a)
2278 * identifies the file and line number of the call site
2279 * automatically, and (b) implicitly quotes the source text of
2280 * the @ch0@ and @ch1@ arguments in the failure message.
2283 extern int tvec_claimeq_text(struct tvec_state */
*tv*/
,
2284 const char */
*p0*/
, size_t /*sz0*/,
2285 const char */
*p1*/
, size_t /*sz1*/,
2286 const char */
*file*/
, unsigned /*lno*/,
2287 const char */
*expr*/
);
2288 #define TVEC_CLAIMEQ_TEXT(tv, p0, sz0, p1, sz1) \
2289 (tvec_claimeq_text(tv, p0, sz0, p1, sz1, __FILE__, __LINE__, \
2290 #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
2292 /* --- @tvec_claimeq_textz@, @TVEC_CLAIMEQ_TEXTZ@ --- *
2294 * Arguments: @struct tvec_state *tv@ = test-vector state
2295 * @const char *p0, *p1@ = two strings to compare
2296 * @const char *file@, @unsigned @lno@ = calling file and line
2297 * @const char *expr@ = the expression to quote on failure
2299 * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise
2302 * Use: Check that strings at @p0@ and @p1@ are equal, as for
2303 * @tvec_claimeq_string@, except that the strings are assumed
2304 * null-terminated, so their lengths don't need to be supplied
2305 * explicitly. The macro is similarly like @TVEC_CLAIMEQ_TEXT@.
2308 extern int tvec_claimeq_textz(struct tvec_state */
*tv*/
,
2309 const char */
*p0*/
, const char */
*p1*/
,
2310 const char */
*file*/
, unsigned /*lno*/,
2311 const char */
*expr*/
);
2312 #define TVEC_CLAIMEQ_TEXTZ(tv, p0, p1) \
2313 (tvec_claimeq_textz(tv, p0, p1, __FILE__, __LINE__, #p0 " /= " #p1))
2315 /* --- @tvec_claimeq_bytes@, @TVEC_CLAIMEQ_BYTES@ --- *
2317 * Arguments: @struct tvec_state *tv@ = test-vector state
2318 * @const void *p0@, @size_t sz0@ = first string with length
2319 * @const void *p1@, @size_t sz1@ = second string with length
2320 * @const char *file@, @unsigned @lno@ = calling file and line
2321 * @const char *expr@ = the expression to quote on failure
2323 * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise
2326 * Use: Check that binary strings at @p0@ and @p1@ are equal. As for
2327 * @tvec_claim@ above, a test case is automatically begun and
2328 * ended if none is already underway. If the values are
2329 * unequal, then @tvec_fail@ is called, quoting @expr@, and the
2330 * mismatched values are dumped: @p0@ is printed as the output
2331 * value and @p1@ is printed as the input reference.
2333 * The @TVEC_CLAIM_STRING@ macro is similar, only it (a)
2334 * identifies the file and line number of the call site
2335 * automatically, and (b) implicitly quotes the source text of
2336 * the @ch0@ and @ch1@ arguments in the failure message.
2339 extern int tvec_claimeq_bytes(struct tvec_state */
*tv*/
,
2340 const void */
*p0*/
, size_t /*sz0*/,
2341 const void */
*p1*/
, size_t /*sz1*/,
2342 const char */
*file*/
, unsigned /*lno*/,
2343 const char */
*expr*/
);
2344 #define TVEC_CLAIMEQ_BYTES(tv, p0, sz0, p1, sz1) \
2345 (tvec_claimeq(tv, p0, sz0, p1, sz1, __FILE__, __LINE__, \
2346 #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
2348 /* --- @tvec_alloctext@, @tvec_allocbytes@ --- *
2350 * Arguments: @union tvec_regval *rv@ = register value
2351 * @size_t sz@ = required size
2355 * Use: Allocated space in a text or binary string register. If the
2356 * current register size is sufficient, its buffer is left
2357 * alone; otherwise, the old buffer, if any, is freed and a
2358 * fresh buffer allocated. These functions are not intended to
2359 * be used to adjust a buffer repeatedly, e.g., while building
2360 * output incrementally: (a) they will perform badly, and (b)
2361 * the old buffer contents are simply discarded if reallocation
2362 * is necessary. Instead, use a @dbuf@ or @dstr@.
2364 * The @tvec_alloctext@ function sneakily allocates an extra
2365 * byte for a terminating zero. The @tvec_allocbytes@ function
2369 extern void tvec_alloctext(union tvec_regval */
*rv*/
, size_t /*sz*/);
2370 extern void tvec_allocbytes(union tvec_regval */
*rv*/
, size_t /*sz*/);
2372 /*----- Buffer type -------------------------------------------------------*/
2374 /* Buffer registers are primarily used for benchmarking. Only a buffer's
2375 * size is significant: its contents are ignored on comparison and output,
2376 * and unspecified on input.
2378 * The input is simply the buffer size, as an integer, optionally suffixed
2379 * with a unit `kB', `MB', `GB', `TB', `PB', `EB', `ZB', `YB' (with or
2380 * without the `B') denoting a power of 1024. Units are used on output only
2381 * when the size would be expressed exactly.
2383 * No @claimeq@ functions or macros are provided for buffers because they
2384 * don't seem very useful.
2387 extern const struct tvec_regty tvty_buffer
;
2389 /*----- That's all, folks -------------------------------------------------*/