| 1 | /* -*-c-*- |
| 2 | * |
| 3 | * Test vector processing framework |
| 4 | * |
| 5 | * (c) 2023 Straylight/Edgeware |
| 6 | */ |
| 7 | |
| 8 | /*----- Licensing notice --------------------------------------------------* |
| 9 | * |
| 10 | * This file is part of the mLib utilities library. |
| 11 | * |
| 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. |
| 16 | * |
| 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. |
| 21 | * |
| 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, |
| 25 | * USA. |
| 26 | */ |
| 27 | |
| 28 | #ifndef MLIB_TVEC_H |
| 29 | #define MLIB_TVEC_H |
| 30 | |
| 31 | #ifdef __cplusplus |
| 32 | extern "C" { |
| 33 | #endif |
| 34 | |
| 35 | /* Here's the overall flow for a testing session. |
| 36 | * |
| 37 | * @tvec_begin@ |
| 38 | * -> output @bsession@ |
| 39 | * @tvec_read@ |
| 40 | * -> output @bgroup@ |
| 41 | * -> env @setup@ |
| 42 | * one or more tests |
| 43 | * -> type @init@ (input and output) |
| 44 | * -> type @parse@ (input) |
| 45 | * -> output @btest@ |
| 46 | * -> env @before@ |
| 47 | * -> @tvec_skipgroup@ |
| 48 | * -> output @skipgroup@ |
| 49 | * -> env @run@ |
| 50 | * -> @tvec_skip@ |
| 51 | * -> output @skip@ |
| 52 | * -> test @fn@ |
| 53 | * -> @tvec_checkregs@ |
| 54 | * -> type @eq@ |
| 55 | * -> @tvec_fail@ |
| 56 | * -> output @fail@ |
| 57 | * -> @tvec_mismatch@ |
| 58 | * -> output @dumpreg@ |
| 59 | * -> type @dump@ |
| 60 | * -> output @etest@ |
| 61 | * -> env @after@ |
| 62 | * finally |
| 63 | * -> output @egroup@ |
| 64 | * -> env @teardown@ |
| 65 | * |
| 66 | * @tvec_adhoc@ |
| 67 | * @tvec_begingroup@ |
| 68 | * -> output @bgroup@ |
| 69 | * -> env @setup@ |
| 70 | * @tvec_begintest@ |
| 71 | * -> output @btest@ |
| 72 | * @tvec_skip@ |
| 73 | * -> output @skip@ |
| 74 | * @tvec_claimeq@ |
| 75 | * -> @tvec_fail@ |
| 76 | * -> output @fail@ |
| 77 | * -> @tvec_mismatch@ |
| 78 | * -> output @dumpreg@ |
| 79 | * -> type @dump@ |
| 80 | * @tvec_endtest@ |
| 81 | * -> output @etest@ |
| 82 | * or @tvec_skipgroup@ |
| 83 | * -> output @skipgroup@ |
| 84 | * @tvec_endgroup@ |
| 85 | * -> output @egroup@ |
| 86 | * |
| 87 | * @tvec_end@ |
| 88 | * -> output @esession@ |
| 89 | * -> output @destroy@ |
| 90 | * |
| 91 | * @tvec_benchrun@ |
| 92 | * -> type @dump@ (compact style) |
| 93 | * -> output @bbench@ |
| 94 | * -> subenv @run@ |
| 95 | * -> test @fn@ |
| 96 | * -> output @ebench@ |
| 97 | * -> @tvec_benchreport@ |
| 98 | * |
| 99 | * The output functions @error@ and @notice@ can be called at arbitrary |
| 100 | * times. |
| 101 | */ |
| 102 | |
| 103 | /*----- Header files ------------------------------------------------------*/ |
| 104 | |
| 105 | #include <stdarg.h> |
| 106 | #include <stddef.h> |
| 107 | #include <stdio.h> |
| 108 | #include <string.h> |
| 109 | |
| 110 | #ifndef MLIB_BUF_H |
| 111 | # include "buf.h" |
| 112 | #endif |
| 113 | |
| 114 | #ifndef MLIB_CONTROL_H |
| 115 | # include "control.h" |
| 116 | #endif |
| 117 | |
| 118 | #ifndef MLIB_BUF_H |
| 119 | # include "dstr.h" |
| 120 | #endif |
| 121 | |
| 122 | #ifndef MLIB_GPRINTF_H |
| 123 | # include "gprintf.h" |
| 124 | #endif |
| 125 | |
| 126 | #ifndef MLIB_LBUF_H |
| 127 | # include "lbuf.h" |
| 128 | #endif |
| 129 | |
| 130 | #ifndef MLIB_MACROS_H |
| 131 | # include "macros.h" |
| 132 | #endif |
| 133 | |
| 134 | /*----- Miscellaneous values ----------------------------------------------*/ |
| 135 | |
| 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. |
| 138 | */ |
| 139 | |
| 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 */ |
| 145 | |
| 146 | union tvec_misc { |
| 147 | #define TVEC_DEFSLOT(tag, ty, slot) ty slot; |
| 148 | TVEC_MISCSLOTS(TVEC_DEFSLOT) |
| 149 | #undef TVEC_DEFSLOT |
| 150 | }; |
| 151 | enum { |
| 152 | #define TVEC_DEFCONST(tag, ty, slot) TVMISC_##tag, |
| 153 | TVEC_MISCSLOTS(TVEC_DEFCONST) |
| 154 | TVMISC_LIMIT |
| 155 | }; |
| 156 | |
| 157 | /*----- Register values ---------------------------------------------------*/ |
| 158 | |
| 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. |
| 167 | * |
| 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.) |
| 177 | */ |
| 178 | |
| 179 | union tvec_regval { |
| 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. |
| 183 | * |
| 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 |
| 188 | * it. |
| 189 | */ |
| 190 | |
| 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 */ |
| 201 | } buf; |
| 202 | #ifdef TVEC_REGSLOTS |
| 203 | TVEC_REGSLOTS |
| 204 | #endif |
| 205 | }; |
| 206 | |
| 207 | struct tvec_reg { |
| 208 | /* A register. |
| 209 | * |
| 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.) |
| 214 | * |
| 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. |
| 219 | * |
| 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. |
| 223 | */ |
| 224 | |
| 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 */ |
| 229 | }; |
| 230 | |
| 231 | struct tvec_regdef { |
| 232 | /* A register definition. Register definitions list the registers which |
| 233 | * are used by a particular test group (see `struct tvec_test' below). |
| 234 | * |
| 235 | * A vector of register definitions is terminated by a definition whose |
| 236 | * `name' slot is null. |
| 237 | */ |
| 238 | |
| 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 */ |
| 247 | }; |
| 248 | #define TVEC_ENDREGS { 0, 0, 0, 0, { 0 } } |
| 249 | |
| 250 | /* @TVEC_GREG(vec, i, regsz)@ |
| 251 | * |
| 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. |
| 256 | * |
| 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. |
| 261 | */ |
| 262 | #define TVEC_GREG(vec, i, regsz) \ |
| 263 | ((struct tvec_reg *)((unsigned char *)(vec) + (i)*(regsz))) |
| 264 | |
| 265 | /*----- Register types ----------------------------------------------------*/ |
| 266 | |
| 267 | struct tvec_state; /* forward declaration */ |
| 268 | |
| 269 | struct tvec_regty { |
| 270 | /* A register type. */ |
| 271 | |
| 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 |
| 276 | * points. |
| 277 | */ |
| 278 | |
| 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. |
| 283 | */ |
| 284 | |
| 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@. |
| 291 | */ |
| 292 | |
| 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. |
| 297 | */ |
| 298 | |
| 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. |
| 303 | */ |
| 304 | |
| 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. |
| 312 | */ |
| 313 | |
| 314 | void (*dump)(const union tvec_regval */*rv*/, |
| 315 | const struct tvec_regdef */*rd*/, |
| 316 | unsigned /*style*/, |
| 317 | const struct gprintf_ops */*gops*/, void */*go*/); |
| 318 | #define TVSF_COMPACT 1u |
| 319 | #define TVSF_RAW 2u |
| 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. |
| 327 | */ |
| 328 | }; |
| 329 | |
| 330 | /*----- Test descriptions -------------------------------------------------*/ |
| 331 | |
| 332 | struct tvec_env; |
| 333 | |
| 334 | typedef void tvec_testfn(const struct tvec_reg */*in*/, |
| 335 | struct tvec_reg */*out*/, |
| 336 | void */*ctx*/); |
| 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. |
| 342 | * |
| 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. |
| 346 | * |
| 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. |
| 351 | */ |
| 352 | |
| 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. |
| 357 | */ |
| 358 | |
| 359 | struct tvec_vardef { |
| 360 | size_t regsz; /* (minimum) register size */ |
| 361 | tvec_setvarfn *setvar; /* function to set variable */ |
| 362 | struct tvec_regdef def; /* register definition */ |
| 363 | }; |
| 364 | |
| 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@ |
| 373 | * will not. |
| 374 | */ |
| 375 | |
| 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. |
| 384 | */ |
| 385 | |
| 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@ |
| 392 | * flag if necessary. |
| 393 | */ |
| 394 | |
| 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. |
| 403 | */ |
| 404 | |
| 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. |
| 411 | */ |
| 412 | |
| 413 | typedef void tvec_envteardownfn(struct tvec_state */*tv*/, void */*ctx*/); |
| 414 | /* Tear down the environment: called at the end of a test group. */ |
| 415 | |
| 416 | |
| 417 | struct tvec_env { |
| 418 | /* A test environment sets things up for and arranges to run the test. |
| 419 | * |
| 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. |
| 424 | */ |
| 425 | |
| 426 | size_t ctxsz; /* environment context size */ |
| 427 | |
| 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 */ |
| 434 | }; |
| 435 | |
| 436 | struct tvec_test { |
| 437 | /* A test description. */ |
| 438 | |
| 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 */ |
| 443 | }; |
| 444 | #define TVEC_ENDTESTS { 0, 0, 0, 0 } |
| 445 | |
| 446 | /*----- Test state --------------------------------------------------------*/ |
| 447 | |
| 448 | enum { |
| 449 | /* Possible test outcomes. */ |
| 450 | |
| 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) */ |
| 456 | }; |
| 457 | |
| 458 | struct tvec_config { |
| 459 | /* An overall test configuration. */ |
| 460 | |
| 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 */ |
| 464 | }; |
| 465 | |
| 466 | struct tvec_state { |
| 467 | /* The primary state structure for the test vector machinery. */ |
| 468 | |
| 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 */ |
| 479 | |
| 480 | /* Test configuration. Read-only for all callers. */ |
| 481 | struct tvec_config cfg; /* test configuration */ |
| 482 | |
| 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. |
| 486 | */ |
| 487 | struct tvec_reg *in, *out; /* register vectors */ |
| 488 | |
| 489 | /* Test group state. Read-only for all callers. */ |
| 490 | const struct tvec_test *test; /* current test */ |
| 491 | |
| 492 | /* Test scoreboard. Available to output formatters. */ |
| 493 | unsigned curr[TVOUT_LIMIT], all[TVOUT_LIMIT], grps[TVOUT_LIMIT]; |
| 494 | |
| 495 | /* Output machinery. */ |
| 496 | struct tvec_output *output; /* output formatter */ |
| 497 | |
| 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 */ |
| 501 | }; |
| 502 | |
| 503 | /* @TVEC_REG(tv, vec, i)@ |
| 504 | * |
| 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. |
| 508 | */ |
| 509 | #define TVEC_REG(tv, vec, i) TVEC_GREG((tv)->vec, (i), (tv)->cfg.regsz) |
| 510 | |
| 511 | /*----- Output formatting -------------------------------------------------*/ |
| 512 | |
| 513 | struct tvec_output { |
| 514 | /* An output formatter. */ |
| 515 | const struct tvec_outops *ops; /* pointer to operations */ |
| 516 | }; |
| 517 | |
| 518 | enum { |
| 519 | /* Register output dispositions. */ |
| 520 | |
| 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) */ |
| 527 | }; |
| 528 | |
| 529 | #define TVEC_LEVELS(_) \ |
| 530 | _(NOTE, "notice", 4) \ |
| 531 | _(ERR, "ERROR", 8) |
| 532 | enum { |
| 533 | #define TVEC_DEFLEVEL(tag, name, val) TVLEV_##tag = val, |
| 534 | TVEC_LEVELS(TVEC_DEFLEVEL) |
| 535 | #undef TVEC_DEFLEVEL |
| 536 | TVLEV_LIMIT |
| 537 | }; |
| 538 | |
| 539 | /* Benchmarking details. */ |
| 540 | enum { |
| 541 | TVBU_OP, /* counting operations of some kind */ |
| 542 | TVBU_BYTE, /* counting bytes (@rbuf >= 0@) */ |
| 543 | TVBU_LIMIT /* (number of units) */ |
| 544 | }; |
| 545 | struct bench_timing; /* include <mLib/bench.h> for the real definition */ |
| 546 | |
| 547 | struct tvec_outops { |
| 548 | /* Output operations. */ |
| 549 | |
| 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. |
| 553 | */ |
| 554 | |
| 555 | int (*esession)(struct tvec_output */*o*/); |
| 556 | /* End a session, and return the suggested exit code. */ |
| 557 | |
| 558 | void (*bgroup)(struct tvec_output */*o*/); |
| 559 | /* Begin a test group. The test group description is @tv->test@. */ |
| 560 | |
| 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 |
| 565 | * separately. |
| 566 | */ |
| 567 | |
| 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. |
| 572 | */ |
| 573 | |
| 574 | void (*btest)(struct tvec_output */*o*/); |
| 575 | /* Begin a test case. */ |
| 576 | |
| 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. |
| 583 | */ |
| 584 | |
| 585 | void (*fail)(struct tvec_output */*o*/, |
| 586 | const char */*detail*/, va_list */*ap*/); |
| 587 | /* The test case failed. |
| 588 | * |
| 589 | * The output driver should preferably report the filename (@infile@) and |
| 590 | * line number (@test_lno@, not @lno@) for the failing test. |
| 591 | * |
| 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. |
| 596 | * |
| 597 | * A single test case can fail multiple times! |
| 598 | */ |
| 599 | |
| 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. |
| 610 | */ |
| 611 | |
| 612 | void (*etest)(struct tvec_output */*o*/, unsigned /*outcome*/); |
| 613 | /* The test case concluded with the given @outcome@ (one of the |
| 614 | * @TVOUT_...@ codes. |
| 615 | */ |
| 616 | |
| 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. |
| 625 | */ |
| 626 | |
| 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. |
| 634 | */ |
| 635 | |
| 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. |
| 640 | */ |
| 641 | |
| 642 | void (*destroy)(struct tvec_output */*o*/); |
| 643 | /* Release any resources acquired by the driver. */ |
| 644 | }; |
| 645 | |
| 646 | /*----- Session lifecycle -------------------------------------------------*/ |
| 647 | |
| 648 | /* --- @tvec_begin@ --- * |
| 649 | * |
| 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 |
| 653 | * |
| 654 | * Returns: --- |
| 655 | * |
| 656 | * Use: Initialize a state structure ready to do some testing. |
| 657 | */ |
| 658 | |
| 659 | extern void tvec_begin(struct tvec_state */*tv_out*/, |
| 660 | const struct tvec_config */*config*/, |
| 661 | struct tvec_output */*o*/); |
| 662 | |
| 663 | /* --- @tvec_end@ --- * |
| 664 | * |
| 665 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 666 | * |
| 667 | * Returns: A proposed exit code. |
| 668 | * |
| 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.) |
| 672 | */ |
| 673 | |
| 674 | extern int tvec_end(struct tvec_state */*tv*/); |
| 675 | |
| 676 | /* --- @tvec_read@ --- * |
| 677 | * |
| 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 |
| 681 | * |
| 682 | * Returns: Zero on success, %$-1$% on error. |
| 683 | * |
| 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. |
| 688 | */ |
| 689 | |
| 690 | extern int tvec_read(struct tvec_state */*tv*/, |
| 691 | const char */*infile*/, FILE */*fp*/); |
| 692 | |
| 693 | /*----- Command-line interface --------------------------------------------*/ |
| 694 | |
| 695 | extern const struct tvec_config tvec_adhocconfig; |
| 696 | /* A special @struct tvec_config@ to use for programs which perform ad-hoc |
| 697 | * testing. |
| 698 | */ |
| 699 | |
| 700 | /* --- @tvec_parseargs@ --- * |
| 701 | * |
| 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 |
| 707 | * |
| 708 | * Returns: --- |
| 709 | * |
| 710 | * Use: Parse arguments and set up the test vector state @*tv_out@. |
| 711 | * If errors occur, print messages to standard error and exit |
| 712 | * with status 2. |
| 713 | */ |
| 714 | |
| 715 | extern void tvec_parseargs(int /*argc*/, char */*argv*/[], |
| 716 | struct tvec_state */*tv_out*/, |
| 717 | int */*argpos_out*/, |
| 718 | const struct tvec_config */*config*/); |
| 719 | |
| 720 | /* --- @tvec_readstdin@, @tvec_readfile@, @tvec_readarg@ --- * |
| 721 | * |
| 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 |
| 725 | * |
| 726 | * Returns: Zero on success, %$-1$% on error. |
| 727 | * |
| 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. |
| 731 | */ |
| 732 | |
| 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*/); |
| 736 | |
| 737 | /* --- @tvec_readdflt@ --- * |
| 738 | * |
| 739 | * Arguments: @struct tvec_state *tv@ = test vector state |
| 740 | * @const char *dflt@ = defsault filename or null |
| 741 | * |
| 742 | * Returns: Zero on success, %$-1$% on error. |
| 743 | * |
| 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. |
| 749 | */ |
| 750 | |
| 751 | extern int tvec_readdflt(struct tvec_state */*tv*/, const char */*file*/); |
| 752 | |
| 753 | /* --- @tvec_readargs@ --- * |
| 754 | * |
| 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 |
| 760 | * |
| 761 | * Returns: Zero on success, %$-1$% on error. |
| 762 | * |
| 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 |
| 766 | * @tvec_readdflt@. |
| 767 | */ |
| 768 | |
| 769 | extern int tvec_readargs(int /*argc*/, char */*argv*/[], |
| 770 | struct tvec_state */*tv*/, |
| 771 | int */*argpos_inout*/, const char */*dflt*/); |
| 772 | |
| 773 | /* --- @tvec_main@ --- * |
| 774 | * |
| 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 |
| 779 | * |
| 780 | * Returns: Exit code. |
| 781 | * |
| 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. |
| 786 | */ |
| 787 | |
| 788 | extern int tvec_main(int /*argc*/, char */*argv*/[], |
| 789 | const struct tvec_config */*config*/, |
| 790 | const char */*dflt*/); |
| 791 | |
| 792 | /*----- Test processing ---------------------------------------------------*/ |
| 793 | |
| 794 | /* --- @tvec_skipgroup@, @tvec_skipgroup_v@ --- * |
| 795 | * |
| 796 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 797 | * @const char *excuse@, @va_list *ap@ = reason why skipped |
| 798 | * |
| 799 | * Returns: --- |
| 800 | * |
| 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. |
| 804 | */ |
| 805 | |
| 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*/); |
| 811 | |
| 812 | /* --- @tvec_skip@, @tvec_skip_v@ --- * |
| 813 | * |
| 814 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 815 | * @const char *excuse@, @va_list *ap@ = reason why test skipped |
| 816 | * |
| 817 | * Returns: --- |
| 818 | * |
| 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. |
| 822 | */ |
| 823 | |
| 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*/); |
| 828 | |
| 829 | /* --- @tvec_fail@, @tvec_fail_v@ --- * |
| 830 | * |
| 831 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 832 | * @const char *detail@, @va_list *ap@ = description of test |
| 833 | * |
| 834 | * Returns: --- |
| 835 | * |
| 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. |
| 844 | */ |
| 845 | |
| 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*/); |
| 850 | |
| 851 | /* --- @tvec_dumpreg@ --- * |
| 852 | * |
| 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 |
| 857 | * |
| 858 | * Returns: --- |
| 859 | * |
| 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. |
| 863 | * |
| 864 | * Usually @tvec_mismatch@ is much more convenient. Low-level |
| 865 | * access is required for reporting `virtual' registers |
| 866 | * corresponding to test environment settings. |
| 867 | */ |
| 868 | |
| 869 | extern void tvec_dumpreg(struct tvec_state */*tv*/, |
| 870 | unsigned /*disp*/, const union tvec_regval */*rv*/, |
| 871 | const struct tvec_regdef */*rd*/); |
| 872 | |
| 873 | /* --- @tvec_initregs@, @tvec_releaseregs@ --- * |
| 874 | * |
| 875 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 876 | * |
| 877 | * Returns: --- |
| 878 | * |
| 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 |
| 882 | * live. |
| 883 | */ |
| 884 | |
| 885 | extern void tvec_initregs(struct tvec_state */*tv*/); |
| 886 | extern void tvec_releaseregs(struct tvec_state */*tv*/); |
| 887 | |
| 888 | /* --- @tvec_resetoutputs@ --- * |
| 889 | * |
| 890 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 891 | * |
| 892 | * Returns: --- |
| 893 | * |
| 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. |
| 899 | */ |
| 900 | |
| 901 | extern void tvec_resetoutputs(struct tvec_state */*tv*/); |
| 902 | |
| 903 | /* --- @tvec_checkregs@ --- * |
| 904 | * |
| 905 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 906 | * |
| 907 | * Returns: Zero on success, %$-1$% on mismatch. |
| 908 | * |
| 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. |
| 914 | * |
| 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. |
| 918 | */ |
| 919 | |
| 920 | extern int tvec_checkregs(struct tvec_state */*tv*/); |
| 921 | |
| 922 | /* --- @tvec_mismatch@ --- * |
| 923 | * |
| 924 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 925 | * @unsigned f@ = flags (@TVMF_...@) |
| 926 | * |
| 927 | * Returns: --- |
| 928 | * |
| 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. |
| 934 | */ |
| 935 | |
| 936 | #define TVMF_IN 1u |
| 937 | #define TVMF_OUT 2u |
| 938 | extern void tvec_mismatch(struct tvec_state */*tv*/, unsigned /*f*/); |
| 939 | |
| 940 | /* --- @tvec_check@, @tvec_check_v@ --- * |
| 941 | * |
| 942 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 943 | * @const char *detail@, @va_list *ap@ = description of test |
| 944 | * |
| 945 | * Returns: --- |
| 946 | * |
| 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 |
| 950 | * obvious way. |
| 951 | */ |
| 952 | |
| 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*/); |
| 957 | |
| 958 | /*----- Ad-hoc testing ----------------------------------------------------*/ |
| 959 | |
| 960 | /* --- @tvec_adhoc@ --- * |
| 961 | * |
| 962 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 963 | * @struct tvec_test *t@ = space for a test definition |
| 964 | * |
| 965 | * Returns: --- |
| 966 | * |
| 967 | * Use: Begin ad-hoc testing, i.e., without reading a file of |
| 968 | * test-vector data. |
| 969 | * |
| 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. |
| 974 | */ |
| 975 | |
| 976 | extern void tvec_adhoc(struct tvec_state */*tv*/, struct tvec_test */*t*/); |
| 977 | |
| 978 | /* --- @tvec_begingroup@, @TVEC_BEGINGROUP@ --- * |
| 979 | * |
| 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 |
| 983 | * |
| 984 | * Returns: --- |
| 985 | * |
| 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. |
| 990 | */ |
| 991 | |
| 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) |
| 996 | |
| 997 | /* --- @tvec_endgroup@ --- * |
| 998 | * |
| 999 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 1000 | * |
| 1001 | * Returns: --- |
| 1002 | * |
| 1003 | * Use: End an ad-hoc test group. The statistics are updated and the |
| 1004 | * outcome is reported to the output formatter. |
| 1005 | */ |
| 1006 | |
| 1007 | extern void tvec_endgroup(struct tvec_state */*tv*/); |
| 1008 | |
| 1009 | /* --- @TVEC_TESTGROUP@, @TVEC_TESTGROUP_TAG@ --- * |
| 1010 | * |
| 1011 | * Arguments: @tag@ = label-disambiguation tag |
| 1012 | * @const struct tvec_state *tv = test-vector state |
| 1013 | * @const char *name@ = test-group name |
| 1014 | * |
| 1015 | * Returns: --- |
| 1016 | * |
| 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. |
| 1023 | */ |
| 1024 | |
| 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) |
| 1032 | |
| 1033 | /* --- @tvec_begintest@, @TVEC_BEGINTEST@ --- * |
| 1034 | * |
| 1035 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 1036 | * @const char *file@, @unsigned @lno@ = calling file and line |
| 1037 | * |
| 1038 | * Returns: --- |
| 1039 | * |
| 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. |
| 1044 | */ |
| 1045 | |
| 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) |
| 1050 | |
| 1051 | /* --- @tvec_endtest@ --- * |
| 1052 | * |
| 1053 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 1054 | * |
| 1055 | * Returns: --- |
| 1056 | * |
| 1057 | * Use: End an ad-hoc test case, The statistics are updated and the |
| 1058 | * outcome is reported to the output formatter. |
| 1059 | */ |
| 1060 | |
| 1061 | extern void tvec_endtest(struct tvec_state */*tv*/); |
| 1062 | |
| 1063 | /* --- @TVEC_TEST@, @TVEC_TEST_TAG@ --- * |
| 1064 | * |
| 1065 | * Arguments: @tag@ = label-disambiguation tag |
| 1066 | * @struct tvec_test *t@ = space for a test definition |
| 1067 | * |
| 1068 | * Returns: --- |
| 1069 | * |
| 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. |
| 1075 | */ |
| 1076 | |
| 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) |
| 1084 | |
| 1085 | /* --- @tvec_claim@, @tvec_claim_v@, @TVEC_CLAIM@ --- * |
| 1086 | * |
| 1087 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 1088 | * @int ok@ = a flag |
| 1089 | * @const char *file@, @unsigned @lno@ = calling file and line |
| 1090 | * @const char *msg@, @va_list *ap@ = message to report on |
| 1091 | * failure |
| 1092 | * |
| 1093 | * Returns: The value @ok@. |
| 1094 | * |
| 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@. |
| 1103 | * |
| 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. |
| 1108 | */ |
| 1109 | |
| 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)) |
| 1119 | |
| 1120 | /* --- @tvec_claimeq@ --- * |
| 1121 | * |
| 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 |
| 1127 | * |
| 1128 | * Returns: Nonzero if the input and output values of register 0 are |
| 1129 | * equal, zero if they differ. |
| 1130 | * |
| 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. |
| 1137 | * |
| 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@. |
| 1141 | */ |
| 1142 | |
| 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*/); |
| 1148 | |
| 1149 | /*----- Benchmarking ------------------------------------------------------*/ |
| 1150 | |
| 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 */ |
| 1157 | }; |
| 1158 | |
| 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 */ |
| 1167 | }; |
| 1168 | |
| 1169 | extern struct bench_state *tvec_benchstate; |
| 1170 | |
| 1171 | /* --- Environment implementation --- * |
| 1172 | * |
| 1173 | * The following special variables are supported. |
| 1174 | * |
| 1175 | * * %|@target|% is the (approximate) number of seconds to run the |
| 1176 | * benchmark. |
| 1177 | * |
| 1178 | * Unrecognized variables are passed to the subordinate environment, if there |
| 1179 | * is one. Other events are passed through to the subsidiary environment. |
| 1180 | */ |
| 1181 | |
| 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; |
| 1188 | |
| 1189 | #define TVEC_BENCHENV \ |
| 1190 | { sizeof(struct tvec_benchctx), \ |
| 1191 | tvec_benchsetup, \ |
| 1192 | tvec_benchfindvar, \ |
| 1193 | tvec_benchbefore, \ |
| 1194 | tvec_benchrun, \ |
| 1195 | tvec_benchafter, \ |
| 1196 | tvec_benchteardown } |
| 1197 | #define TVEC_BENCHINIT TVEC_BENCHENV, &tvec_benchstate |
| 1198 | |
| 1199 | /* --- @tvec_benchreport@ --- * |
| 1200 | * |
| 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 |
| 1206 | * |
| 1207 | * Returns: --- |
| 1208 | * |
| 1209 | * Use: Formats a report about the benchmark performance. This |
| 1210 | * function is intended to be called on by an output @ebench@ |
| 1211 | * function. |
| 1212 | */ |
| 1213 | |
| 1214 | extern void tvec_benchreport |
| 1215 | (const struct gprintf_ops */*gops*/, void */*go*/, |
| 1216 | unsigned /*unit*/, unsigned /*style*/, const struct bench_timing */*tm*/); |
| 1217 | |
| 1218 | /*----- Remote execution --------------------------------------------------*/ |
| 1219 | |
| 1220 | struct tvec_remoteenv; |
| 1221 | |
| 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 */ |
| 1230 | }; |
| 1231 | #define TVEC_REMOTECOMMS_INIT { -1, -1, DBUF_INIT, 0, 0, 0, 0, 0, 0 } |
| 1232 | |
| 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...@ */ |
| 1255 | }; |
| 1256 | |
| 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. |
| 1265 | * |
| 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$%. |
| 1273 | */ |
| 1274 | |
| 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 */ |
| 1279 | }; |
| 1280 | |
| 1281 | struct tvec_remoteenv { |
| 1282 | struct tvec_env _env; |
| 1283 | struct tvec_remoteenv_slots r; |
| 1284 | }; |
| 1285 | |
| 1286 | struct tvec_remotefork_slots { |
| 1287 | const struct tvec_test *tests; /* child tests (or null) */ |
| 1288 | }; |
| 1289 | |
| 1290 | struct tvec_remotefork { |
| 1291 | struct tvec_env _env; |
| 1292 | struct tvec_remoteenv_slots r; |
| 1293 | struct tvec_remotefork_slots f; |
| 1294 | }; |
| 1295 | |
| 1296 | struct tvec_remoteexec_slots { |
| 1297 | const char *const *args; /* command line to execute */ |
| 1298 | }; |
| 1299 | |
| 1300 | struct tvec_remoteexec { |
| 1301 | struct tvec_env _env; |
| 1302 | struct tvec_remoteenv_slots r; |
| 1303 | struct tvec_remoteexec_slots x; |
| 1304 | }; |
| 1305 | |
| 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; |
| 1311 | }; |
| 1312 | |
| 1313 | /* Exit status. |
| 1314 | * |
| 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. |
| 1318 | * |
| 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. |
| 1323 | */ |
| 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 */ |
| 1335 | |
| 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), \ |
| 1345 | tvec_remotesetup, \ |
| 1346 | tvec_remotefindvar, \ |
| 1347 | tvec_remotebefore, \ |
| 1348 | tvec_remoterun, \ |
| 1349 | tvec_remoteafter, \ |
| 1350 | tvec_remoteteardown } |
| 1351 | |
| 1352 | /* --- @tvec_setprogress@, @tvec_setprogress_v@ --- * |
| 1353 | * |
| 1354 | * Arguments: @const char *status@ = progress status token format |
| 1355 | * @va_list ap@ = argument tail |
| 1356 | * |
| 1357 | * Returns: --- |
| 1358 | * |
| 1359 | * Use: Reports the progress of a test execution to the client. |
| 1360 | * |
| 1361 | * The framework makes use of tokens beginning with %|%|%: |
| 1362 | * |
| 1363 | * * %|%IDLE|%: during the top-level server code; |
| 1364 | * |
| 1365 | * * %|%SETUP|%: during the enclosing environment's @before@ |
| 1366 | * function; |
| 1367 | * |
| 1368 | * * %|%RUN|%: during the environment's @run@ function, or the |
| 1369 | * test function; and |
| 1370 | * |
| 1371 | * * %|%DONE|%: during the enclosing environment's @after@ |
| 1372 | * function. |
| 1373 | * |
| 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. |
| 1379 | */ |
| 1380 | |
| 1381 | extern PRINTF_LIKE(1, 2) int tvec_setprogress(const char */*status*/, ...); |
| 1382 | extern int tvec_setprogress_v(const char */*status*/, va_list */*ap*/); |
| 1383 | |
| 1384 | /* --- @tvec_remoteserver@ --- * |
| 1385 | * |
| 1386 | * Arguments: @int infd@, @int outfd@ = input and output file descriptors |
| 1387 | * @const struct tvec_config *config@ = test configuration |
| 1388 | * |
| 1389 | * Returns: Suggested exit code. |
| 1390 | * |
| 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@. |
| 1394 | * |
| 1395 | * This function is not particularly general purpose. It |
| 1396 | * expects to `take over' the process, and makes use of private |
| 1397 | * global variables. |
| 1398 | */ |
| 1399 | |
| 1400 | extern int tvec_remoteserver(int /*infd*/, int /*outfd*/, |
| 1401 | const struct tvec_config */*config*/); |
| 1402 | |
| 1403 | extern tvec_connectfn tvec_fork, tvec_exec; |
| 1404 | |
| 1405 | #define TVEC_REMOTEFORK(subenv, tests) \ |
| 1406 | TVEC_REMOTEENV, { tvec_fork, subenv }, { tests } |
| 1407 | |
| 1408 | #define TVEC_REMOTEEXEC(subenv, args) \ |
| 1409 | TVEC_REMOTEENV, { tvec_exec, subenv }, { args } |
| 1410 | |
| 1411 | /*----- Timeouts ----------------------------------------------------------*/ |
| 1412 | |
| 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 */ |
| 1418 | }; |
| 1419 | |
| 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...@ */ |
| 1429 | void *subctx; |
| 1430 | }; |
| 1431 | |
| 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, \ |
| 1443 | tvec_timeoutrun, \ |
| 1444 | tvec_timeoutafter, \ |
| 1445 | tvec_timeoutteardown } |
| 1446 | #define TVEC_TIMEOUTINIT(timer, t) TVEC_TIMEOUTENV, timer, t |
| 1447 | |
| 1448 | /*----- Output functions --------------------------------------------------*/ |
| 1449 | |
| 1450 | /* --- @tvec_strlevel@ --- * |
| 1451 | * |
| 1452 | * Arguments: @unsigned level@ = level code |
| 1453 | * |
| 1454 | * Returns: A human-readable description. |
| 1455 | * |
| 1456 | * Use: Converts a level code into something that you can print in a |
| 1457 | * message. |
| 1458 | */ |
| 1459 | |
| 1460 | extern const char *tvec_strlevel(unsigned /*level*/); |
| 1461 | |
| 1462 | /* --- @tvec_report@, @tvec_report_v@ --- * |
| 1463 | * |
| 1464 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 1465 | * @const char *msg@, @va_list ap@ = error message |
| 1466 | * |
| 1467 | * Returns: --- |
| 1468 | * |
| 1469 | * Use: Report an message with a given severity. Messages with level |
| 1470 | * @TVLEV_ERR@ or higher force a nonzero exit code. |
| 1471 | */ |
| 1472 | |
| 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*/); |
| 1478 | |
| 1479 | /* --- @tvec_error@, @tvec_notice@ --- * |
| 1480 | * |
| 1481 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 1482 | * @const char *msg@, @va_list ap@ = error message |
| 1483 | * |
| 1484 | * Returns: The @tvec_error@ function returns %$-1$% as a trivial |
| 1485 | * convenience; @tvec_notice@ does not return a value. |
| 1486 | * |
| 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 |
| 1491 | * category. |
| 1492 | */ |
| 1493 | |
| 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*/, ...); |
| 1498 | |
| 1499 | /* --- @tvec_unkregerr@ --- * |
| 1500 | * |
| 1501 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 1502 | * @const char *name@ = register or pseudoregister name |
| 1503 | * |
| 1504 | * Returns: %$-1$%. |
| 1505 | * |
| 1506 | * Use: Reports an error that the register or pseudoregister is |
| 1507 | * unrecognized. |
| 1508 | */ |
| 1509 | |
| 1510 | extern int tvec_unkregerr(struct tvec_state */*tv*/, const char */*name*/); |
| 1511 | |
| 1512 | /* --- @tvec_dupregerr@ --- * |
| 1513 | * |
| 1514 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 1515 | * @const char *name@ = register or pseudoregister name |
| 1516 | * |
| 1517 | * Returns: %$-1$%. |
| 1518 | * |
| 1519 | * Use: Reports an error that the register or pseudoregister has been |
| 1520 | * assigned already in the current test. |
| 1521 | */ |
| 1522 | |
| 1523 | extern int tvec_dupregerr(struct tvec_state */*tv*/, const char */*name*/); |
| 1524 | |
| 1525 | /* --- @tvec_humanoutput@ --- * |
| 1526 | * |
| 1527 | * Arguments: @FILE *fp@ = output file to write on |
| 1528 | * @unsigned style@ = output style (@TVSF_...@) |
| 1529 | * |
| 1530 | * Returns: An output formatter. |
| 1531 | * |
| 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 |
| 1537 | * highlighting. |
| 1538 | */ |
| 1539 | |
| 1540 | extern struct tvec_output *tvec_humanoutput(FILE */*fp*/); |
| 1541 | |
| 1542 | /* --- @tvec_machineoutput@ --- * |
| 1543 | * |
| 1544 | * Arguments: @FILE *fp@ = output file to write on |
| 1545 | * |
| 1546 | * Returns: An output formatter. |
| 1547 | * |
| 1548 | * Use: Return an output formatter which writes on @fp@ in a |
| 1549 | * moderately simple machine-readable format. |
| 1550 | */ |
| 1551 | |
| 1552 | struct tvec_output *tvec_machineoutput(FILE *fp); |
| 1553 | |
| 1554 | /* --- @tvec_tapoutput@ --- * |
| 1555 | * |
| 1556 | * Arguments: @FILE *fp@ = output file to write on |
| 1557 | * @unsigned style@ = output style (@TVSF_...@) |
| 1558 | * |
| 1559 | * Returns: An output formatter. |
| 1560 | * |
| 1561 | * Use: Return an output formatter which writes on @fp@ in `TAP' |
| 1562 | * (`Test Anything Protocol') format. |
| 1563 | * |
| 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. |
| 1576 | */ |
| 1577 | |
| 1578 | extern struct tvec_output *tvec_tapoutput(FILE */*fp*/); |
| 1579 | |
| 1580 | /* --- @tvec_dfltoutput@ --- * |
| 1581 | * |
| 1582 | * Arguments: @FILE *fp@ = output file to write on |
| 1583 | * |
| 1584 | * Returns: An output formatter. |
| 1585 | * |
| 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. |
| 1591 | */ |
| 1592 | |
| 1593 | extern struct tvec_output *tvec_dfltout(FILE */*fp*/); |
| 1594 | |
| 1595 | /*------ Serialization utilities ------------------------------------------*/ |
| 1596 | |
| 1597 | /* Serialization format. |
| 1598 | * |
| 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. |
| 1612 | */ |
| 1613 | |
| 1614 | /* --- @tvec_serialize@ --- * |
| 1615 | * |
| 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 |
| 1620 | * @name@ slot |
| 1621 | * @unsigned nr@ = number of entries in the @rv@ vector |
| 1622 | * @size_t regsz@ = true size of each element of @rv@ |
| 1623 | * |
| 1624 | * Returns: Zero on success, %$-1$% on failure. |
| 1625 | * |
| 1626 | * Use: Serialize a collection of register values. |
| 1627 | * |
| 1628 | * The serialized output is written to the buffer @b@. Failure |
| 1629 | * can be caused by running out of buffer space, or a failing |
| 1630 | * type handler. |
| 1631 | */ |
| 1632 | |
| 1633 | extern int tvec_serialize(const struct tvec_reg */*rv*/, buf */*b*/, |
| 1634 | const struct tvec_regdef */*regs*/, |
| 1635 | unsigned /*nr*/, size_t /*regsz*/); |
| 1636 | |
| 1637 | /* --- @tvec_deserialize@ --- * |
| 1638 | * |
| 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 |
| 1643 | * @name@ slot |
| 1644 | * @unsigned nr@ = number of entries in the @rv@ vector |
| 1645 | * @size_t regsz@ = true size of each element of @rv@ |
| 1646 | * |
| 1647 | * Returns: Zero on success, %$-1$% on failure. |
| 1648 | * |
| 1649 | * Use: Deserialize a collection of register values. |
| 1650 | * |
| 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. |
| 1657 | * |
| 1658 | * Failure results only from a failing register type handler. |
| 1659 | */ |
| 1660 | |
| 1661 | extern int tvec_deserialize(struct tvec_reg */*rv*/, buf */*b*/, |
| 1662 | const struct tvec_regdef */*regs*/, |
| 1663 | unsigned /*nr*/, size_t /*regsz*/); |
| 1664 | |
| 1665 | /*----- Input utilities ---------------------------------------------------*/ |
| 1666 | |
| 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 |
| 1670 | * former. |
| 1671 | * |
| 1672 | * The two main rules are as follows. |
| 1673 | * |
| 1674 | * * Leave the file position at the beginning of the line following |
| 1675 | * whatever it was that you read. |
| 1676 | * |
| 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. |
| 1680 | */ |
| 1681 | |
| 1682 | /* --- @tvec_syntax@, @tvec_syntax_v@ --- * |
| 1683 | * |
| 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 |
| 1687 | * |
| 1688 | * Returns: %$-1$%. |
| 1689 | * |
| 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). |
| 1694 | */ |
| 1695 | |
| 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*/); |
| 1701 | |
| 1702 | /* --- @tvec_skipspc@ --- * |
| 1703 | * |
| 1704 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 1705 | * |
| 1706 | * Returns: --- |
| 1707 | * |
| 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. |
| 1711 | */ |
| 1712 | |
| 1713 | extern void tvec_skipspc(struct tvec_state */*tv*/); |
| 1714 | |
| 1715 | /* --- @tvec_flushtoeol@ --- * |
| 1716 | * |
| 1717 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 1718 | * @unsigned f@ = flags (@TVFF_...@) |
| 1719 | * |
| 1720 | * Returns: Zero on success, %$-1$% on error. |
| 1721 | * |
| 1722 | * Use: Advance to the start of the next line, consuming the |
| 1723 | * preceding newline. |
| 1724 | * |
| 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 |
| 1730 | * appropriately. |
| 1731 | */ |
| 1732 | |
| 1733 | #define TVFF_ALLOWANY 1u |
| 1734 | extern int tvec_flushtoeol(struct tvec_state */*tv*/, unsigned /*f*/); |
| 1735 | |
| 1736 | /* --- @tvec_nexttoken@ --- * |
| 1737 | * |
| 1738 | * Arguments: @struct tvec_state *tv@ = test-vector state |
| 1739 | * |
| 1740 | * Returns: Zero if there is a next token which can be read; %$-1$% if no |
| 1741 | * token is available. |
| 1742 | * |
| 1743 | * Use: Advance to the next whitespace-separated token, which may be |
| 1744 | * on the next line. |
| 1745 | * |
| 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 |
| 1750 | * a test. |
| 1751 | * |
| 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. |
| 1757 | */ |
| 1758 | |
| 1759 | extern int tvec_nexttoken(struct tvec_state */*tv*/); |
| 1760 | |
| 1761 | /* --- @tvec_readword@, @tvec_readword_v@ --- * |
| 1762 | * |
| 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 |
| 1768 | * |
| 1769 | * Returns: Zero on success, %$-1$% on failure. |
| 1770 | * |
| 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.) |
| 1776 | * |
| 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@. |
| 1780 | * |
| 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- |
| 1787 | * terminated. |
| 1788 | * |
| 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. |
| 1796 | */ |
| 1797 | |
| 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*/); |
| 1805 | |
| 1806 | /*----- Integer types: signed and unsigned --------------------------------*/ |
| 1807 | |
| 1808 | /* Integers may be input in decimal, hex, binary, or octal, following |
| 1809 | * approximately usual conventions. |
| 1810 | * |
| 1811 | * * Signed integers may be preceded with a `+' or `-' sign. |
| 1812 | * |
| 1813 | * * Decimal integers are just a sequence of decimal digits `0' ... `9'. |
| 1814 | * |
| 1815 | * * Octal integers are a sequence of digits `0' ... `7', preceded by `0o' |
| 1816 | * or `0O'. |
| 1817 | * |
| 1818 | * * Hexadecimal integers are a sequence of digits `0' ... `9', `a' |
| 1819 | * ... `f', or `A' ... `F', preceded by `0x' or `0X'. |
| 1820 | * |
| 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 `_'. |
| 1825 | * |
| 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. |
| 1829 | */ |
| 1830 | |
| 1831 | extern const struct tvec_regty tvty_int, tvty_uint; |
| 1832 | |
| 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. |
| 1836 | */ |
| 1837 | struct tvec_irange { long min, max; }; |
| 1838 | struct tvec_urange { unsigned long min, max; }; |
| 1839 | |
| 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; |
| 1847 | |
| 1848 | /* --- @tvec_claimeq_int@, @TVEC_CLAIMEQ_INT@ --- * |
| 1849 | * |
| 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 |
| 1854 | * |
| 1855 | * Returns: Nonzero if @i0@ and @i1@ are equal, otherwise zero. |
| 1856 | * |
| 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. |
| 1863 | * |
| 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. |
| 1868 | */ |
| 1869 | |
| 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)) |
| 1876 | |
| 1877 | /* --- @tvec_claimeq_uint@, @TVEC_CLAIMEQ_UINT@ --- * |
| 1878 | * |
| 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 |
| 1883 | * |
| 1884 | * Returns: Nonzero if @u0@ and @u1@ are equal, otherwise zero. |
| 1885 | * |
| 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. |
| 1892 | * |
| 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. |
| 1897 | */ |
| 1898 | |
| 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)) |
| 1905 | |
| 1906 | /*----- Size type ---------------------------------------------------------*/ |
| 1907 | |
| 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'. |
| 1910 | */ |
| 1911 | |
| 1912 | extern const struct tvec_regty tvty_size; |
| 1913 | |
| 1914 | /* --- @tvec_claimeq_size@ --- * |
| 1915 | * |
| 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 |
| 1920 | * |
| 1921 | * Returns: Nonzero if @sz0@ and @sz1@ are equal, otherwise zero. |
| 1922 | * |
| 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. |
| 1929 | * |
| 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. |
| 1934 | */ |
| 1935 | |
| 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)) |
| 1941 | |
| 1942 | /*----- Floating-point type -----------------------------------------------*/ |
| 1943 | |
| 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) |
| 1948 | * syntax. |
| 1949 | * |
| 1950 | * The comparison rules for floating-point numbers are complex: see |
| 1951 | * @tvec_claimeqish_float@ for details. |
| 1952 | */ |
| 1953 | |
| 1954 | extern const struct tvec_regty tvty_float; |
| 1955 | |
| 1956 | struct tvec_floatinfo { |
| 1957 | /* Details about acceptable floating-point values. */ |
| 1958 | |
| 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 */ |
| 1969 | }; |
| 1970 | |
| 1971 | extern const struct tvec_floatinfo tvflt_finite, tvflt_nonneg; |
| 1972 | |
| 1973 | /* --- @tvec_claimeqish_float@, @TVEC_CLAIMEQISH_FLOAT@ --- * |
| 1974 | * |
| 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 |
| 1981 | * |
| 1982 | * Returns: Nonzero if @f0@ and @f1@ are sufficiently close, otherwise |
| 1983 | * zero. |
| 1984 | * |
| 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. |
| 1991 | * |
| 1992 | * The details for the comparison are as follows. |
| 1993 | * |
| 1994 | * * A NaN value matches any other NaN, and nothing else. |
| 1995 | * |
| 1996 | * * An infinity matches another infinity of the same sign, |
| 1997 | * and nothing else. |
| 1998 | * |
| 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.) |
| 2004 | * |
| 2005 | * * If @f&TVFF_EQMASK@ is @TVFF_ABSDELTA@, then %$x$% matches |
| 2006 | * %$y$% when %$|x - y| < \delta$%. |
| 2007 | * |
| 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$%.) |
| 2014 | * |
| 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 |
| 2019 | * message. |
| 2020 | */ |
| 2021 | |
| 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 ")")) |
| 2030 | |
| 2031 | /* --- @tvec_claimeq_float@, @TVEC_CLAIMEQ_FLOAT@ --- * |
| 2032 | * |
| 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 |
| 2037 | * |
| 2038 | * Returns: Nonzero if @f0@ and @u1@ are identical, otherwise zero. |
| 2039 | * |
| 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. |
| 2045 | */ |
| 2046 | |
| 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)) |
| 2053 | |
| 2054 | /*----- Durations ---------------------------------------------------------*/ |
| 2055 | |
| 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. |
| 2059 | */ |
| 2060 | |
| 2061 | extern const struct tvec_regty tvty_duration; |
| 2062 | |
| 2063 | /* --- @tvec_parsedurunit@ --- * |
| 2064 | * |
| 2065 | * Arguments: @double *scale_out@ = where to leave the scale |
| 2066 | * @const char **p_inout@ = input unit string, updated |
| 2067 | * |
| 2068 | * Returns: Zero on success, %$-1$% on error. |
| 2069 | * |
| 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, |
| 2074 | * return %$-1$%. |
| 2075 | */ |
| 2076 | |
| 2077 | extern int tvec_parsedurunit(double */*scale_out*/, |
| 2078 | const char **/*p_inout*/); |
| 2079 | |
| 2080 | /* --- @tvec_claimeqish_duration@, @TVEC_CLAIMEQISH_DURATION@ --- * |
| 2081 | * |
| 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 |
| 2088 | * |
| 2089 | * Returns: Nonzero if @t0@ and @t1@ are sufficiently close, otherwise |
| 2090 | * zero. |
| 2091 | * |
| 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. |
| 2095 | * |
| 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 |
| 2100 | * message. |
| 2101 | */ |
| 2102 | |
| 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 ")")) |
| 2111 | |
| 2112 | /* --- @tvec_claimeq_duration@, @TVEC_CLAIMEQ_DURATION@ --- * |
| 2113 | * |
| 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 |
| 2118 | * |
| 2119 | * Returns: Nonzero if @t0@ and @t1@ are identical, otherwise zero. |
| 2120 | * |
| 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. |
| 2126 | */ |
| 2127 | |
| 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)) |
| 2134 | |
| 2135 | /*----- Enumerated types --------------------------------------------------*/ |
| 2136 | |
| 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. |
| 2141 | * |
| 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. |
| 2146 | * |
| 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 |
| 2152 | * in a comment). |
| 2153 | */ |
| 2154 | |
| 2155 | #define DEFENUMTY(tag, ty, slot) \ |
| 2156 | extern const struct tvec_regty tvty_##slot##enum; |
| 2157 | TVEC_MISCSLOTS(DEFENUMTY) |
| 2158 | #undef DEFENUMTY |
| 2159 | |
| 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) |
| 2164 | #undef DEFASSOC |
| 2165 | |
| 2166 | #define TVEC_ENDENUM { 0, 0 } |
| 2167 | |
| 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 */ \ |
| 2174 | }; |
| 2175 | |
| 2176 | #define EXTRA_INT_INFOSLOTS \ |
| 2177 | const struct tvec_irange *ir; /* allowed range of raw values */ |
| 2178 | |
| 2179 | #define EXTRA_UINT_INFOSLOTS \ |
| 2180 | const struct tvec_urange *ur; /* allowed range of raw values */ |
| 2181 | |
| 2182 | #define EXTRA_FLT_INFOSLOTS \ |
| 2183 | const struct tvec_floatinfo *fi; /* range and matching policy */ |
| 2184 | |
| 2185 | #define EXTRA_PTR_INFOSLOTS /* (nothing) */ |
| 2186 | |
| 2187 | TVEC_MISCSLOTS(DEFINFO) |
| 2188 | |
| 2189 | #undef EXTRA_INT_INFOSLOTS |
| 2190 | #undef EXTRA_UINT_INFOSLOTS |
| 2191 | #undef EXTRA_FLT_INFOSLOTS |
| 2192 | #undef EXTRA_PTR_INFOSLOTS |
| 2193 | |
| 2194 | #undef DEFINFO |
| 2195 | |
| 2196 | /* Standard enumerations. */ |
| 2197 | extern const struct tvec_ienuminfo tvenum_bool; |
| 2198 | extern const struct tvec_ienuminfo tvenum_cmp; |
| 2199 | |
| 2200 | /* --- @tvec_claimeq_tenum@, @TVEC_CLAIMEQ_TENUM@ --- * |
| 2201 | * |
| 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 |
| 2207 | * |
| 2208 | * Returns: Nonzero if @t0@ and @t1@ are equal, otherwise zero. |
| 2209 | * |
| 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. |
| 2216 | * |
| 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. |
| 2221 | */ |
| 2222 | |
| 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) |
| 2230 | #undef 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)) |
| 2243 | |
| 2244 | /*----- Flags type --------------------------------------------------------*/ |
| 2245 | |
| 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 |
| 2249 | * covering bitmask. |
| 2250 | * |
| 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 |
| 2255 | * given values. |
| 2256 | * |
| 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. |
| 2264 | */ |
| 2265 | |
| 2266 | extern const struct tvec_regty tvty_flags; |
| 2267 | |
| 2268 | struct tvec_flag { |
| 2269 | /* Definition of a single flag or bitfield value. |
| 2270 | * |
| 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@. |
| 2273 | */ |
| 2274 | |
| 2275 | const char *tag; /* name */ |
| 2276 | unsigned long m, v; /* mask and value */ |
| 2277 | }; |
| 2278 | |
| 2279 | #define TVEC_ENDFLAGS { 0, 0, 0 } |
| 2280 | |
| 2281 | struct tvec_flaginfo { |
| 2282 | /* Information about a flags type. */ |
| 2283 | |
| 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 */ |
| 2287 | }; |
| 2288 | |
| 2289 | /* --- @tvec_claimeq_flags@, @TVEC_CLAIMEQ_FLAGS@ --- * |
| 2290 | * |
| 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 |
| 2296 | * |
| 2297 | * Returns: Nonzero if @f0@ and @f1@ are equal, otherwise zero. |
| 2298 | * |
| 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. |
| 2305 | * |
| 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. |
| 2310 | */ |
| 2311 | |
| 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)) |
| 2320 | |
| 2321 | /*----- Character type ----------------------------------------------------*/ |
| 2322 | |
| 2323 | /* A character value holds a character, as read by @fgetc@. The special |
| 2324 | * @EOF@ value can also be represented. |
| 2325 | * |
| 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 |
| 2328 | * quotes. |
| 2329 | * |
| 2330 | * The following escape sequences and character names are recognized. |
| 2331 | * |
| 2332 | * * `%|#eof|%' is the special end-of-file marker. |
| 2333 | * |
| 2334 | * * `%|#nul|%' is the NUL character, sometimes used to terminate strings. |
| 2335 | * |
| 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). |
| 2339 | * |
| 2340 | * * %|#backspace|%, %|#bs|%, or %|\b|% is the backspace character, used to |
| 2341 | * move the cursor backwords by one cell. |
| 2342 | * |
| 2343 | * * %|#escape|% %|#esc|%, or%|\e|% is the escape character, used to |
| 2344 | * introduce special terminal commands. |
| 2345 | * |
| 2346 | * * %|#formfeed|%, %|#ff|%, or %|\f|% is the formfeed character, used to |
| 2347 | * separate pages of text. |
| 2348 | * |
| 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 |
| 2352 | * the line). |
| 2353 | * |
| 2354 | * * %|#return|%, %|#carriage-return|%, %|#cr|%, or %|\r|% is the |
| 2355 | * carriage-return character, used to return the cursor to the start of |
| 2356 | * the line. |
| 2357 | * |
| 2358 | * * %|#tab|%, %|#horizontal-tab|%, %|#ht|%, or %|\t|% is the tab |
| 2359 | * character, used to advance the cursor to the next tab stop on the |
| 2360 | * current line. |
| 2361 | * |
| 2362 | * * %|#vertical-tab|%, %|#vt|%, %|\v|% is the vertical tab character. |
| 2363 | * |
| 2364 | * * %|#space|%, %|#spc|% is the space character. |
| 2365 | * |
| 2366 | * * %|#delete|%, %|#del|% is the delete character, used to erase the most |
| 2367 | * recent character. |
| 2368 | * |
| 2369 | * * %|\'|% is the single-quote character. |
| 2370 | * |
| 2371 | * * %|\\|% is the backslash character. |
| 2372 | * |
| 2373 | * * %|\"|% is the double-quote character. |
| 2374 | * |
| 2375 | * * %|\NNN|% or %|\{NNN}|% is the character with code NNN in octal. The |
| 2376 | * NNN may be up to three digits long. |
| 2377 | * |
| 2378 | * * %|\xNN|% or %|\x{NN}|% is the character with code NNN in hexadecimal. |
| 2379 | */ |
| 2380 | |
| 2381 | extern const struct tvec_regty tvty_char; |
| 2382 | |
| 2383 | /* --- @tvec_claimeq_char@, @TVEC_CLAIMEQ_CHAR@ --- * |
| 2384 | * |
| 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 |
| 2389 | * |
| 2390 | * Returns: Nonzero if @ch0@ and @ch1@ are equal, otherwise zero. |
| 2391 | * |
| 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. |
| 2398 | * |
| 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. |
| 2403 | */ |
| 2404 | |
| 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)) |
| 2411 | |
| 2412 | /*----- Text and binary string types --------------------------------------*/ |
| 2413 | |
| 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 |
| 2417 | * display. |
| 2418 | * |
| 2419 | * The input format for both kinds of strings is basically the same: a |
| 2420 | * `compound string', consisting of |
| 2421 | * |
| 2422 | * * single-quoted strings, which are interpreted entirely literally, but |
| 2423 | * can't contain single quotes or newlines; |
| 2424 | * |
| 2425 | * * double-quoted strings, in which `%|\|%'-escapes are interpreted as for |
| 2426 | * characters; |
| 2427 | * |
| 2428 | * * character names, marked by an initial `%|#|%' sign; |
| 2429 | * |
| 2430 | * * special tokens marked by an initial `%|!|%' sign; or |
| 2431 | * |
| 2432 | * * barewords interpreted according to the current coding scheme. |
| 2433 | * |
| 2434 | * The special tokens are |
| 2435 | * |
| 2436 | * * `%|!bare|%', which causes subsequent sequences of barewords to be |
| 2437 | * treated as plain text; |
| 2438 | * |
| 2439 | * * `%|!hex|%', `%|!base32|%', `%|!base64|%', which cause subsequent |
| 2440 | * barewords to be decoded in the requested manner. |
| 2441 | * |
| 2442 | * * `%|!repeat|% %$n$% %|{|% %%\textit{string}%% %|}|%', which includes |
| 2443 | * %$n$% copies of the (compound) string. |
| 2444 | * |
| 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. |
| 2447 | * |
| 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. |
| 2452 | * |
| 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. |
| 2455 | */ |
| 2456 | |
| 2457 | extern const struct tvec_regty tvty_text, tvty_bytes; |
| 2458 | |
| 2459 | /* --- @tvec_alloctext@, @tvec_allocbytes@ --- * |
| 2460 | * |
| 2461 | * Arguments: @union tvec_regval *rv@ = register value |
| 2462 | * @size_t sz@ = required size |
| 2463 | * |
| 2464 | * Returns: --- |
| 2465 | * |
| 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@. |
| 2474 | * |
| 2475 | * The @tvec_alloctext@ function sneakily allocates an extra |
| 2476 | * byte for a terminating zero. The @tvec_allocbytes@ function |
| 2477 | * doesn't do this. |
| 2478 | */ |
| 2479 | |
| 2480 | extern void tvec_alloctext(union tvec_regval */*rv*/, size_t /*sz*/); |
| 2481 | extern void tvec_allocbytes(union tvec_regval */*rv*/, size_t /*sz*/); |
| 2482 | |
| 2483 | /* --- @tvec_claimeq_text@, @TVEC_CLAIMEQ_TEXT@ --- * |
| 2484 | * |
| 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 |
| 2490 | * |
| 2491 | * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise |
| 2492 | * zero. |
| 2493 | * |
| 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. |
| 2500 | * |
| 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. |
| 2505 | */ |
| 2506 | |
| 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 "]")) |
| 2515 | |
| 2516 | /* --- @tvec_claimeq_textz@, @TVEC_CLAIMEQ_TEXTZ@ --- * |
| 2517 | * |
| 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 |
| 2522 | * |
| 2523 | * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise |
| 2524 | * zero. |
| 2525 | * |
| 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@. |
| 2530 | */ |
| 2531 | |
| 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)) |
| 2538 | |
| 2539 | /* --- @tvec_claimeq_bytes@, @TVEC_CLAIMEQ_BYTES@ --- * |
| 2540 | * |
| 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 |
| 2546 | * |
| 2547 | * Returns: Nonzero if the strings at @p0@ and @p1@ are equal, otherwise |
| 2548 | * zero. |
| 2549 | * |
| 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. |
| 2556 | * |
| 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. |
| 2561 | */ |
| 2562 | |
| 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 "]")) |
| 2571 | |
| 2572 | /*----- Buffer type -------------------------------------------------------*/ |
| 2573 | |
| 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. |
| 2577 | * |
| 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. |
| 2587 | * |
| 2588 | * Units other than `B' are used on output only when the size would be |
| 2589 | * expressed exactly. |
| 2590 | * |
| 2591 | * Buffers are %%\emph{not}%% allocated by default. In benchmarks, this is |
| 2592 | * best done in a @before@ function. |
| 2593 | * |
| 2594 | * No @claimeq@ functions or macros are provided for buffers because they |
| 2595 | * don't seem very useful. |
| 2596 | */ |
| 2597 | |
| 2598 | extern const struct tvec_regty tvty_buffer; |
| 2599 | |
| 2600 | /* --- @tvec_initbuffer@ --- * |
| 2601 | * |
| 2602 | * Arguments: @union tvec_regval *rv@ = register value |
| 2603 | * @const union tvec_regval *ref@ = reference buffer |
| 2604 | * @size_t sz@ = size to allocate |
| 2605 | * |
| 2606 | * Returns: --- |
| 2607 | * |
| 2608 | * Use: Initialize the alignment parameters in @rv@ to match @ref@, |
| 2609 | * and the size to @sz@. |
| 2610 | */ |
| 2611 | |
| 2612 | extern void tvec_initbuffer(union tvec_regval */*rv*/, |
| 2613 | const union tvec_regval */*ref*/, size_t /*sz*/); |
| 2614 | |
| 2615 | /* --- @tvec_allocbuffer@ --- * |
| 2616 | * |
| 2617 | * Arguments: @union tvec_regval *rv@ = register value |
| 2618 | * |
| 2619 | * Returns: --- |
| 2620 | * |
| 2621 | * Use: Allocate @sz@ bytes to the buffer and fill the space with a |
| 2622 | * distinctive pattern. |
| 2623 | */ |
| 2624 | |
| 2625 | extern void tvec_allocbuffer(union tvec_regval */*rv*/); |
| 2626 | |
| 2627 | /*----- That's all, folks -------------------------------------------------*/ |
| 2628 | |
| 2629 | #ifdef __cplusplus |
| 2630 | } |
| 2631 | #endif |
| 2632 | |
| 2633 | #endif |