@@@ misc wip
[mLib] / test / tvec.h
CommitLineData
b64eb60f
MW
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
c91413e6
MW
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@
c91413e6 60 * -> output @etest@
31d0247c 61 * -> env @after@
c91413e6
MW
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
b64eb60f
MW
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
e63124bc
MW
122#ifndef MLIB_GPRINTF_H
123# include "gprintf.h"
124#endif
125
c91413e6
MW
126#ifndef MLIB_LBUF_H
127# include "lbuf.h"
128#endif
129
b64eb60f
MW
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 */ \
e63124bc
MW
143 _(UINT, unsigned long, u) /* signed integer */ \
144 _(FLT, double, f) /* floating point */
b64eb60f
MW
145
146union tvec_misc {
147#define TVEC_DEFSLOT(tag, ty, slot) ty slot;
148 TVEC_MISCSLOTS(TVEC_DEFSLOT)
149#undef TVEC_DEFSLOT
150};
151enum {
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
179union tvec_regval {
31d0247c
MW
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 */
b64eb60f
MW
190
191 long i; /* signed integer */
192 unsigned long u; /* unsigned integer */
193 void *p; /* pointer */
e63124bc 194 double f; /* floating point */
c81c35df 195 struct { char *p; size_t sz; } text; /* text string */
d056fbdf 196 struct { unsigned char *p; size_t sz; } bytes; /* binary string of bytes */
adec5584
MW
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;
b64eb60f
MW
202#ifdef TVEC_REGSLOTS
203 TVEC_REGSLOTS
204#endif
205};
206
207struct tvec_reg {
31d0247c
MW
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 */
b64eb60f
MW
224
225 unsigned f; /* flags */
c4ccbbf9
MW
226#define TVRF_SEEN 1u /* assignment seen in file */
227#define TVRF_LIVE 2u /* used in current test */
b64eb60f
MW
228 union tvec_regval v; /* register value */
229};
230
231struct tvec_regdef {
31d0247c
MW
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 */
b64eb60f
MW
238
239 const char *name; /* register name (for input files) */
b64eb60f 240 const struct tvec_regty *ty; /* register type descriptor */
d056fbdf 241 unsigned i; /* register index */
b64eb60f 242 unsigned f; /* flags */
c4ccbbf9
MW
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 */
b64eb60f
MW
246 union tvec_misc arg; /* extra detail for the type */
247};
db2bf411 248#define TVEC_ENDREGS { 0, 0, 0, 0, { 0 } }
b64eb60f 249
e63124bc
MW
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
c91413e6
MW
265/*----- Register types ----------------------------------------------------*/
266
267struct tvec_state; /* forward declaration */
268
269struct tvec_regty {
270 /* A register type. */
271
272 void (*init)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/);
31d0247c 273 /* Initialize the value in @*rv@. This will be called before any other
c4ccbbf9
MW
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.
31d0247c 277 */
c91413e6
MW
278
279 void (*release)(union tvec_regval */*rv*/,
280 const struct tvec_regdef */*rd*/);
c4ccbbf9
MW
281 /* Release any resources associated with the value in @*rv@. The
282 * register value may be left in an invalid state.
283 */
c91413e6
MW
284
285 int (*eq)(const union tvec_regval */*rv0*/,
286 const union tvec_regval */*rv1*/,
287 const struct tvec_regdef */*rd*/);
31d0247c
MW
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 */
c91413e6
MW
292
293 int (*tobuf)(buf */*b*/, const union tvec_regval */*rv*/,
294 const struct tvec_regdef */*rd*/);
31d0247c
MW
295 /* Serialize the value @*rv@, writing the result to @b@. Return zero on
296 * success, or %$-1$% on error.
297 */
c91413e6
MW
298
299 int (*frombuf)(buf */*b*/, union tvec_regval */*rv*/,
300 const struct tvec_regdef */*rd*/);
31d0247c
MW
301 /* Deserialize a value from @b@, storing it in @*rv@. Return zero on
302 * success, or %$-1$% on error.
303 */
c91413e6
MW
304
305 int (*parse)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/,
306 struct tvec_state */*tv*/);
31d0247c
MW
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 */
c91413e6
MW
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
5c0f2e08 319#define TVSF_RAW 2u
31d0247c
MW
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
5c0f2e08
MW
325 * human reader. If @TVSF_RAW@ is set, then output should prefer
326 * machine-readability over human-readability.
31d0247c 327 */
c91413e6
MW
328};
329
330/*----- Test descriptions -------------------------------------------------*/
331
d056fbdf
MW
332struct tvec_env;
333
c91413e6
MW
334typedef 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
814e42ff
MW
353typedef 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
359struct 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
c91413e6
MW
365typedef 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
31d0247c
MW
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.
c91413e6
MW
374 */
375
814e42ff
MW
376typedef 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.
c91413e6
MW
384 */
385
386typedef 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
814e42ff
MW
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.
c91413e6
MW
393 */
394
395typedef 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
405typedef void tvec_envafterfn(struct tvec_state */*tv*/, void */*ctx*/);
406 /* Called after running or skipping a test. Typical actions involve
31d0247c 407 * resetting whatever things were established by @set@. This function
814e42ff
MW
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.
c91413e6
MW
411 */
412
413typedef void tvec_envteardownfn(struct tvec_state */*tv*/, void */*ctx*/);
414 /* Tear down the environment: called at the end of a test group. */
415
416
417struct 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 */
814e42ff 429 tvec_envfindvarfn *findvar; /* find variable */
c91413e6
MW
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
436struct 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
b64eb60f
MW
446/*----- Test state --------------------------------------------------------*/
447
3efcfd2d
MW
448enum {
449 /* Possible test outcomes. */
450
451 TVOUT_LOSE, /* test failed */
452 TVOUT_SKIP, /* test skipped */
20ba6b0b 453 TVOUT_XFAIL, /* test passed, but shouldn't have */
5c0f2e08 454 TVOUT_WIN, /* test passed */
3efcfd2d
MW
455 TVOUT_LIMIT /* (number of possible outcomes) */
456};
b64eb60f 457
d056fbdf
MW
458struct 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
b64eb60f 466struct tvec_state {
e63124bc
MW
467 /* The primary state structure for the test vector machinery. */
468
d056fbdf 469 /* Flags. Read-only for all callers. */
b64eb60f 470 unsigned f; /* flags */
20ba6b0b
MW
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_...@) */
3efcfd2d 476#define TVSF_OUTSHIFT 4 /* shift applied to outcome */
20ba6b0b 477#define TVSF_XFAIL 0x0100u /* test expected to fail */
31d0247c 478#define TVSF_MUFFLE 0x0200u /* muffle errors */
e63124bc 479
d056fbdf
MW
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 */
b64eb60f 487 struct tvec_reg *in, *out; /* register vectors */
e63124bc 488
d056fbdf
MW
489 /* Test group state. Read-only for all callers. */
490 const struct tvec_test *test; /* current test */
e63124bc
MW
491
492 /* Test scoreboard. Available to output formatters. */
b64eb60f 493 unsigned curr[TVOUT_LIMIT], all[TVOUT_LIMIT], grps[TVOUT_LIMIT];
e63124bc
MW
494
495 /* Output machinery. */
b64eb60f 496 struct tvec_output *output; /* output formatter */
e63124bc
MW
497
498 /* Input machinery. Available to type parsers. */
b64eb60f
MW
499 const char *infile; unsigned lno, test_lno; /* input file name, line */
500 FILE *fp; /* input file stream */
501};
502
e63124bc
MW
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 */
d056fbdf 509#define TVEC_REG(tv, vec, i) TVEC_GREG((tv)->vec, (i), (tv)->cfg.regsz)
67b5031e
MW
510
511/*----- Output formatting -------------------------------------------------*/
512
513struct tvec_output {
514 /* An output formatter. */
515 const struct tvec_outops *ops; /* pointer to operations */
516};
517
d056fbdf
MW
518enum {
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)
532enum {
533#define TVEC_DEFLEVEL(tag, name, val) TVLEV_##tag = val,
534 TVEC_LEVELS(TVEC_DEFLEVEL)
535#undef TVEC_DEFLEVEL
536 TVLEV_LIMIT
537};
538
67b5031e
MW
539/* Benchmarking details. */
540enum {
541 TVBU_OP, /* counting operations of some kind */
c91413e6
MW
542 TVBU_BYTE, /* counting bytes (@rbuf >= 0@) */
543 TVBU_LIMIT /* (number of units) */
67b5031e 544};
adec5584 545struct bench_timing; /* include <mLib/bench.h> for the real definition */
67b5031e
MW
546
547struct tvec_outops {
548 /* Output operations. */
549
550 void (*bsession)(struct tvec_output */*o*/, struct tvec_state */*tv*/);
31d0247c
MW
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 */
67b5031e
MW
554
555 int (*esession)(struct tvec_output */*o*/);
31d0247c 556 /* End a session, and return the suggested exit code. */
67b5031e
MW
557
558 void (*bgroup)(struct tvec_output */*o*/);
31d0247c 559 /* Begin a test group. The test group description is @tv->test@. */
67b5031e
MW
560
561 void (*skipgroup)(struct tvec_output */*o*/,
562 const char */*excuse*/, va_list */*ap*/);
31d0247c
MW
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 */
67b5031e
MW
567
568 void (*egroup)(struct tvec_output */*o*/);
31d0247c
MW
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 */
67b5031e
MW
573
574 void (*btest)(struct tvec_output */*o*/);
31d0247c 575 /* Begin a test case. */
67b5031e
MW
576
577 void (*skip)(struct tvec_output */*o*/,
578 const char */*excuse*/, va_list */*ap*/);
31d0247c
MW
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 */
67b5031e
MW
584
585 void (*fail)(struct tvec_output */*o*/,
586 const char */*detail*/, va_list */*ap*/);
31d0247c
MW
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 */
67b5031e
MW
599
600 void (*dumpreg)(struct tvec_output */*o*/,
601 unsigned /*disp*/, const union tvec_regval */*rv*/,
602 const struct tvec_regdef */*rd*/);
31d0247c
MW
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 */
67b5031e
MW
611
612 void (*etest)(struct tvec_output */*o*/, unsigned /*outcome*/);
31d0247c
MW
613 /* The test case concluded with the given @outcome@ (one of the
614 * @TVOUT_...@ codes.
615 */
67b5031e
MW
616
617 void (*bbench)(struct tvec_output */*o*/,
618 const char */*ident*/, unsigned /*unit*/);
31d0247c
MW
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 */
67b5031e
MW
626
627 void (*ebench)(struct tvec_output */*o*/,
628 const char */*ident*/, unsigned /*unit*/,
629 const struct bench_timing */*tm*/);
31d0247c
MW
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 */
67b5031e 635
c91413e6 636 void (*report)(struct tvec_output */*o*/, unsigned /*level*/,
67b5031e 637 const char */*msg*/, va_list */*ap*/);
31d0247c
MW
638 /* Report a message. The driver should ideally report the filename
639 * (@infile@) and line number (@lno@) prompting the error.
640 */
67b5031e
MW
641
642 void (*destroy)(struct tvec_output */*o*/);
31d0247c 643 /* Release any resources acquired by the driver. */
67b5031e
MW
644};
645
67b5031e
MW
646/*----- Session lifecycle -------------------------------------------------*/
647
67b5031e
MW
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
659extern 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
674extern 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 *
31d0247c 682 * Returns: Zero on success, %$-1$% on error.
67b5031e
MW
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
690extern int tvec_read(struct tvec_state */*tv*/,
691 const char */*infile*/, FILE */*fp*/);
692
693/*----- Command-line interface --------------------------------------------*/
694
695extern const struct tvec_config tvec_adhocconfig;
20ba6b0b
MW
696 /* A special @struct tvec_config@ to use for programs which perform ad-hoc
697 * testing.
698 */
67b5031e
MW
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
715extern 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 *
31d0247c 726 * Returns: Zero on success, %$-1$% on error.
67b5031e
MW
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
733extern int tvec_readstdin(struct tvec_state */*tv*/);
734extern int tvec_readfile(struct tvec_state */*tv*/, const char */*file*/);
735extern 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 *
31d0247c 742 * Returns: Zero on success, %$-1$% on error.
67b5031e
MW
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
751extern 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 *
31d0247c 761 * Returns: Zero on success, %$-1$% on error.
67b5031e
MW
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
769extern 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
788extern 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
31d0247c
MW
806extern PRINTF_LIKE(2, 3)
807 void tvec_skipgroup(struct tvec_state */*tv*/,
808 const char */*excuse*/, ...);
67b5031e
MW
809extern 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
31d0247c
MW
824extern PRINTF_LIKE(2, 3)
825 void tvec_skip(struct tvec_state */*tv*/, const char */*excuse*/, ...);
67b5031e
MW
826extern void tvec_skip_v(struct tvec_state */*tv*/,
827 const char */*excuse*/, va_list */*ap*/);
828
e63124bc
MW
829/* --- @tvec_fail@, @tvec_fail_v@ --- *
830 *
831 * Arguments: @struct tvec_state *tv@ = test-vector state
3efcfd2d 832 * @const char *detail@, @va_list *ap@ = description of test
e63124bc
MW
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
31d0247c
MW
846extern PRINTF_LIKE(2, 3)
847 void tvec_fail(struct tvec_state */*tv*/, const char */*detail*/, ...);
e63124bc
MW
848extern 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_...@)
c91413e6 855 * @const union tvec_regval *tv@ = register value, or null
e63124bc
MW
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
869extern void tvec_dumpreg(struct tvec_state */*tv*/,
870 unsigned /*disp*/, const union tvec_regval */*rv*/,
871 const struct tvec_regdef */*rd*/);
872
31d0247c
MW
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
885extern void tvec_initregs(struct tvec_state */*tv*/);
886extern 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
901extern 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
920extern int tvec_checkregs(struct tvec_state */*tv*/);
921
e63124bc
MW
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
938extern 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
3efcfd2d 943 * @const char *detail@, @va_list *ap@ = description of test
e63124bc
MW
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
31d0247c
MW
953extern PRINTF_LIKE(2, 3)
954 void tvec_check(struct tvec_state */*tv*/, const char */*detail*/, ...);
e63124bc
MW
955extern void tvec_check_v(struct tvec_state */*tv*/,
956 const char */*detail*/, va_list */*ap*/);
b64eb60f 957
67b5031e 958/*----- Ad-hoc testing ----------------------------------------------------*/
b64eb60f 959
67b5031e 960/* --- @tvec_adhoc@ --- *
c5e0e403 961 *
67b5031e
MW
962 * Arguments: @struct tvec_state *tv@ = test-vector state
963 * @struct tvec_test *t@ = space for a test definition
c5e0e403
MW
964 *
965 * Returns: ---
966 *
67b5031e
MW
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.
c5e0e403 974 */
b64eb60f 975
67b5031e 976extern void tvec_adhoc(struct tvec_state */*tv*/, struct tvec_test */*t*/);
b64eb60f 977
67b5031e 978/* --- @tvec_begingroup@, @TVEC_BEGINGROUP@ --- *
c5e0e403
MW
979 *
980 * Arguments: @struct tvec_state *tv@ = test-vector state
67b5031e
MW
981 * @const char *name@ = name for this test group
982 * @const char *file@, @unsigned @lno@ = calling file and line
c5e0e403 983 *
67b5031e 984 * Returns: ---
c5e0e403 985 *
67b5031e
MW
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.
c5e0e403 990 */
b64eb60f 991
67b5031e
MW
992extern 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)
b64eb60f 996
67b5031e 997/* --- @tvec_endgroup@ --- *
c5e0e403
MW
998 *
999 * Arguments: @struct tvec_state *tv@ = test-vector state
c5e0e403 1000 *
67b5031e 1001 * Returns: ---
c5e0e403 1002 *
67b5031e
MW
1003 * Use: End an ad-hoc test group. The statistics are updated and the
1004 * outcome is reported to the output formatter.
3efcfd2d
MW
1005 */
1006
1007extern 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
1046extern 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
31d0247c 1051/* --- @tvec_endtest@ --- *
3efcfd2d
MW
1052 *
1053 * Arguments: @struct tvec_state *tv@ = test-vector state
1054 *
1055 * Returns: ---
1056 *
31d0247c 1057 * Use: End an ad-hoc test case, The statistics are updated and the
3efcfd2d
MW
1058 * outcome is reported to the output formatter.
1059 */
1060
1061extern 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
31d0247c
MW
1110extern PRINTF_LIKE(5, 6)
1111 int tvec_claim(struct tvec_state */*tv*/, int /*ok*/,
1112 const char */*file*/, unsigned /*lno*/,
1113 const char */*msg*/, ...);
3efcfd2d
MW
1114extern 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
1143extern 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
67b5031e 1149/*----- Benchmarking ------------------------------------------------------*/
b64eb60f 1150
c91413e6 1151struct tvec_benchenv {
67b5031e
MW
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 */
b64eb60f
MW
1157};
1158
67b5031e 1159struct tvec_benchctx {
c91413e6
MW
1160 const struct tvec_benchenv *be; /* environment configuration */
1161 struct bench_state *bst; /* benchmark state */
1162 double dflt_target; /* default time in seconds */
31d0247c
MW
1163 unsigned f; /* flags */
1164#define TVBF_SETTRG 1u /* set `@target' */
1165#define TVBF_SETMASK (TVBF_SETTRG)) /* mask of @TVBF_SET...@ */
c91413e6 1166 void *subctx; /* subsidiary environment context */
3efcfd2d 1167};
c5e0e403 1168
67b5031e 1169extern struct bench_state *tvec_benchstate;
3efcfd2d 1170
c91413e6 1171/* --- Environment implementation --- *
67b5031e 1172 *
c91413e6 1173 * The following special variables are supported.
67b5031e 1174 *
c91413e6
MW
1175 * * %|@target|% is the (approximate) number of seconds to run the
1176 * benchmark.
67b5031e 1177 *
c91413e6
MW
1178 * Unrecognized variables are passed to the subordinate environment, if there
1179 * is one. Other events are passed through to the subsidiary environment.
67b5031e 1180 */
b64eb60f 1181
c91413e6 1182extern tvec_envsetupfn tvec_benchsetup;
814e42ff 1183extern tvec_envfindvarfn tvec_benchfindvar;
c91413e6
MW
1184extern tvec_envbeforefn tvec_benchbefore;
1185extern tvec_envrunfn tvec_benchrun;
1186extern tvec_envafterfn tvec_benchafter;
1187extern tvec_envteardownfn tvec_benchteardown;
b64eb60f 1188
c91413e6
MW
1189#define TVEC_BENCHENV \
1190 { sizeof(struct tvec_benchctx), \
1191 tvec_benchsetup, \
814e42ff 1192 tvec_benchfindvar, \
c91413e6
MW
1193 tvec_benchbefore, \
1194 tvec_benchrun, \
1195 tvec_benchafter, \
1196 tvec_benchteardown }
1197#define TVEC_BENCHINIT TVEC_BENCHENV, &tvec_benchstate
3efcfd2d 1198
67b5031e
MW
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_...@)
5c0f2e08 1204 * @unsigned style@ = output style (@TVSF_...@)
67b5031e
MW
1205 * @const struct bench_timing *tm@ = the benchmark result
1206 *
1207 * Returns: ---
1208 *
1209 * Use: Formats a report about the benchmark performance. This
6e683a79
MW
1210 * function is intended to be called on by an output @ebench@
1211 * function.
67b5031e 1212 */
3efcfd2d 1213
67b5031e
MW
1214extern void tvec_benchreport
1215 (const struct gprintf_ops */*gops*/, void */*go*/,
5c0f2e08 1216 unsigned /*unit*/, unsigned /*style*/, const struct bench_timing */*tm*/);
b64eb60f 1217
c91413e6
MW
1218/*----- Remote execution --------------------------------------------------*/
1219
d056fbdf
MW
1220struct tvec_remoteenv;
1221
c91413e6
MW
1222struct tvec_remotecomms {
1223 int infd, outfd; /* input and output descriptors */
31d0247c
MW
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 */
c91413e6
MW
1228 unsigned f; /* flags */
1229#define TVRF_BROKEN 0x0001u /* communications have failed */
c91413e6 1230};
31d0247c 1231#define TVEC_REMOTECOMMS_INIT { -1, -1, DBUF_INIT, 0, 0, 0, 0, 0, 0 }
c91413e6
MW
1232
1233struct 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 */
814e42ff
MW
1237 void *subctx; /* subenvironment context */
1238 struct tvec_vardef vd; /* temporary variable definition */
c91413e6
MW
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: */
814e42ff
MW
1246#define TVRCN_DEMAND 0x0000u /* connect on demand */
1247#define TVRCN_SKIP 0x0100u /* skip unless connected */
c91413e6
MW
1248#define TVRCN_FORCE 0x0200u /* force reconnection */
1249#define TVRF_MUFFLE 0x0400u /* muffle child stderr */
31d0247c
MW
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...@ */
c91413e6
MW
1255};
1256
1257typedef 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*/);
c81c35df
MW
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 */
c91413e6
MW
1274
1275struct tvec_remoteenv_slots {
1276 tvec_connectfn *connect; /* connection function */
1277 const struct tvec_env *env; /* subsidiary environment */
814e42ff 1278 unsigned dflt_reconn; /* default reconnection */
c91413e6
MW
1279};
1280
1281struct tvec_remoteenv {
1282 struct tvec_env _env;
1283 struct tvec_remoteenv_slots r;
1284};
1285
1286struct tvec_remotefork_slots {
1287 const struct tvec_test *tests; /* child tests (or null) */
1288};
1289
1290struct tvec_remotefork {
1291 struct tvec_env _env;
1292 struct tvec_remoteenv_slots r;
1293 struct tvec_remotefork_slots f;
1294};
1295
1296struct tvec_remoteexec_slots {
1297 const char *const *args; /* command line to execute */
1298};
1299
1300struct tvec_remoteexec {
1301 struct tvec_env _env;
1302 struct tvec_remoteenv_slots r;
1303 struct tvec_remoteexec_slots x;
1304};
1305
1306union 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
c81c35df
MW
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. */
c91413e6 1337extern tvec_envsetupfn tvec_remotesetup;
814e42ff
MW
1338extern tvec_envfindvarfn tvec_remotefindvar;
1339extern tvec_envbeforefn tvec_remotebefore;
c91413e6
MW
1340extern tvec_envrunfn tvec_remoterun;
1341extern tvec_envafterfn tvec_remoteafter;
1342extern tvec_envteardownfn tvec_remoteteardown;
1343#define TVEC_REMOTEENV \
1344 { sizeof(struct tvec_remotectx), \
1345 tvec_remotesetup, \
814e42ff
MW
1346 tvec_remotefindvar, \
1347 tvec_remotebefore, \
c91413e6
MW
1348 tvec_remoterun, \
1349 tvec_remoteafter, \
1350 tvec_remoteteardown }
1351
c81c35df
MW
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
31d0247c
MW
1381extern PRINTF_LIKE(1, 2) int tvec_setprogress(const char */*status*/, ...);
1382extern int tvec_setprogress_v(const char */*status*/, va_list */*ap*/);
c91413e6 1383
c81c35df
MW
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
c91413e6
MW
1400extern int tvec_remoteserver(int /*infd*/, int /*outfd*/,
1401 const struct tvec_config */*config*/);
1402
1403extern tvec_connectfn tvec_fork, tvec_exec;
1404
31d0247c 1405#define TVEC_REMOTEFORK(subenv, tests) \
c91413e6
MW
1406 TVEC_REMOTEENV, { tvec_fork, subenv }, { tests }
1407
1408#define TVEC_REMOTEEXEC(subenv, args) \
1409 TVEC_REMOTEENV, { tvec_exec, subenv }, { args }
1410
31d0247c
MW
1411/*----- Timeouts ----------------------------------------------------------*/
1412
1413struct tvec_timeoutenv {
1414 struct tvec_env _env;
d056fbdf 1415 int timer; /* the timer (@ITIMER_...@) */
c81c35df
MW
1416 double t; /* time to wait (in seconds) */
1417 const struct tvec_env *env; /* subsidiary environment */
31d0247c
MW
1418};
1419
1420struct tvec_timeoutctx {
c81c35df 1421 const struct tvec_timeoutenv *te; /* saved environment description */
814e42ff 1422 int timer; /* timer code (as overridden) */
c81c35df 1423 double t; /* time to wait (as overridden) */
31d0247c
MW
1424 unsigned f; /* flags */
1425#define TVTF_SETTMO 1u /* set `@timeout' */
814e42ff
MW
1426#define TVTF_SETTMR 2u /* set `@timer' */
1427#define TVTF_SETMASK (TVTF_SETTMO | TVTF_SETTMR)
1428 /* mask of @TVTF_SET...@ */
31d0247c
MW
1429 void *subctx;
1430};
1431
1432extern tvec_envsetupfn tvec_timeoutsetup;
814e42ff 1433extern tvec_envfindvarfn tvec_timeoutfindvar;
31d0247c
MW
1434extern tvec_envbeforefn tvec_timeoutbefore;
1435extern tvec_envrunfn tvec_timeoutrun;
1436extern tvec_envafterfn tvec_timeoutafter;
1437extern tvec_envteardownfn tvec_timeoutteardown;
1438#define TVEC_TIMEOUTENV \
1439 { sizeof(struct tvec_timeoutctx), \
1440 tvec_timeoutsetup, \
814e42ff 1441 tvec_timeoutfindvar, \
31d0247c
MW
1442 tvec_timeoutbefore, \
1443 tvec_timeoutrun, \
1444 tvec_timeoutafter, \
1445 tvec_timeoutteardown }
1446#define TVEC_TIMEOUTINIT(timer, t) TVEC_TIMEOUTENV, timer, t
1447
67b5031e 1448/*----- Output functions --------------------------------------------------*/
b64eb60f 1449
31d0247c
MW
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
d056fbdf 1460extern const char *tvec_strlevel(unsigned /*level*/);
31d0247c 1461
c91413e6 1462/* --- @tvec_report@, @tvec_report_v@ --- *
3efcfd2d
MW
1463 *
1464 * Arguments: @struct tvec_state *tv@ = test-vector state
1465 * @const char *msg@, @va_list ap@ = error message
1466 *
c91413e6 1467 * Returns: ---
3efcfd2d 1468 *
c91413e6
MW
1469 * Use: Report an message with a given severity. Messages with level
1470 * @TVLEV_ERR@ or higher force a nonzero exit code.
3efcfd2d
MW
1471 */
1472
31d0247c
MW
1473extern PRINTF_LIKE(3, 4)
1474 void tvec_report(struct tvec_state */*tv*/, unsigned /*level*/,
1475 const char */*msg*/, ...);
c91413e6
MW
1476extern void tvec_report_v(struct tvec_state */*tv*/, unsigned /*level*/,
1477 const char */*msg*/, va_list */*ap*/);
b64eb60f 1478
c91413e6 1479/* --- @tvec_error@, @tvec_notice@ --- *
3efcfd2d
MW
1480 *
1481 * Arguments: @struct tvec_state *tv@ = test-vector state
c91413e6 1482 * @const char *msg@, @va_list ap@ = error message
3efcfd2d 1483 *
31d0247c 1484 * Returns: The @tvec_error@ function returns %$-1$% as a trivial
c91413e6 1485 * convenience; @tvec_notice@ does not return a value.
3efcfd2d 1486 *
c91413e6
MW
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.
3efcfd2d
MW
1492 */
1493
31d0247c
MW
1494extern PRINTF_LIKE(2, 3)
1495 int tvec_error(struct tvec_state */*tv*/, const char */*msg*/, ...);
1496extern PRINTF_LIKE(2, 3)
1497 void tvec_notice(struct tvec_state */*tv*/, const char */*msg*/, ...);
b64eb60f 1498
6e683a79 1499/* --- @tvec_unkregerr@ --- *
d056fbdf
MW
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
6e683a79 1510extern int tvec_unkregerr(struct tvec_state */*tv*/, const char */*name*/);
d056fbdf 1511
6e683a79 1512/* --- @tvec_dupregerr@ --- *
d056fbdf
MW
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
6e683a79 1523extern int tvec_dupregerr(struct tvec_state */*tv*/, const char */*name*/);
d056fbdf 1524
3efcfd2d
MW
1525/* --- @tvec_humanoutput@ --- *
1526 *
1527 * Arguments: @FILE *fp@ = output file to write on
5c0f2e08 1528 * @unsigned style@ = output style (@TVSF_...@)
3efcfd2d
MW
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
e63124bc 1540extern struct tvec_output *tvec_humanoutput(FILE */*fp*/);
3efcfd2d 1541
5c0f2e08
MW
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
1552struct tvec_output *tvec_machineoutput(FILE *fp);
1553
3efcfd2d
MW
1554/* --- @tvec_tapoutput@ --- *
1555 *
1556 * Arguments: @FILE *fp@ = output file to write on
5c0f2e08 1557 * @unsigned style@ = output style (@TVSF_...@)
3efcfd2d
MW
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
6e683a79
MW
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.
3efcfd2d
MW
1576 */
1577
e63124bc 1578extern struct tvec_output *tvec_tapoutput(FILE */*fp*/);
3efcfd2d
MW
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
e63124bc 1593extern struct tvec_output *tvec_dfltout(FILE */*fp*/);
b64eb60f 1594
67b5031e 1595/*------ Serialization utilities ------------------------------------------*/
b64eb60f 1596
c91413e6
MW
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
67b5031e
MW
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 *
31d0247c 1624 * Returns: Zero on success, %$-1$% on failure.
67b5031e
MW
1625 *
1626 * Use: Serialize a collection of register values.
1627 *
67b5031e
MW
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 */
3efcfd2d 1632
67b5031e
MW
1633extern int tvec_serialize(const struct tvec_reg */*rv*/, buf */*b*/,
1634 const struct tvec_regdef */*regs*/,
1635 unsigned /*nr*/, size_t /*regsz*/);
3efcfd2d 1636
67b5031e
MW
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 *
31d0247c 1647 * Returns: Zero on success, %$-1$% on failure.
67b5031e
MW
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 *
c91413e6 1658 * Failure results only from a failing register type handler.
67b5031e 1659 */
3efcfd2d 1660
67b5031e
MW
1661extern int tvec_deserialize(struct tvec_reg */*rv*/, buf */*b*/,
1662 const struct tvec_regdef */*regs*/,
1663 unsigned /*nr*/, size_t /*regsz*/);
3efcfd2d 1664
67b5031e
MW
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
67b5031e
MW
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 *
31d0247c 1688 * Returns: %$-1$%.
67b5031e
MW
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
31d0247c
MW
1696extern PRINTF_LIKE(3, 4)
1697 int tvec_syntax(struct tvec_state */*tv*/, int /*ch*/,
1698 const char */*expect*/, ...);
67b5031e
MW
1699extern int tvec_syntax_v(struct tvec_state */*tv*/, int /*ch*/,
1700 const char */*expect*/, va_list */*ap*/);
1701
31d0247c
MW
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
1713extern void tvec_skipspc(struct tvec_state */*tv*/);
1714
67b5031e
MW
1715/* --- @tvec_flushtoeol@ --- *
1716 *
1717 * Arguments: @struct tvec_state *tv@ = test-vector state
1718 * @unsigned f@ = flags (@TVFF_...@)
1719 *
31d0247c 1720 * Returns: Zero on success, %$-1$% on error.
67b5031e
MW
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
1734extern int tvec_flushtoeol(struct tvec_state */*tv*/, unsigned /*f*/);
1735
1736/* --- @tvec_nexttoken@ --- *
1737 *
1738 * Arguments: @struct tvec_state *tv@ = test-vector state
1739 *
31d0247c 1740 * Returns: Zero if there is a next token which can be read; %$-1$% if no
67b5031e
MW
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
31d0247c 1754 * processed. If it returns %$-1$% then there is no such token,
67b5031e
MW
1755 * and the file position is left correctly. The line number
1756 * count is updated appropriately.
1757 */
3efcfd2d 1758
67b5031e 1759extern int tvec_nexttoken(struct tvec_state */*tv*/);
3efcfd2d 1760
31d0247c 1761/* --- @tvec_readword@, @tvec_readword_v@ --- *
67b5031e
MW
1762 *
1763 * Arguments: @struct tvec_state *tv@ = test-vector state
1764 * @dstr *d@ = string to append the word to
adec5584 1765 * @const char **p_inout@ = pointer into string, updated
67b5031e
MW
1766 * @const char *delims@ = additional delimiters to stop at
1767 * @const char *expect@, @va_list ap@ = what was expected
1768 *
31d0247c 1769 * Returns: Zero on success, %$-1$% on failure.
67b5031e
MW
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,
31d0247c
MW
1778 * then return %$-1$%; furthermore, if @expect@ is not null,
1779 * then report an appropriate error via @tvec_syntax@.
67b5031e
MW
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.
adec5584
MW
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.
67b5031e 1796 */
3efcfd2d 1797
adec5584 1798extern PRINTF_LIKE(5, 6)
31d0247c 1799 int tvec_readword(struct tvec_state */*tv*/, dstr */*d*/,
adec5584
MW
1800 const char **/*p_inout*/, const char */*delims*/,
1801 const char */*expect*/, ...);
67b5031e 1802extern int tvec_readword_v(struct tvec_state */*tv*/, dstr */*d*/,
adec5584
MW
1803 const char **/*p_inout*/, const char */*delims*/,
1804 const char */*expect*/, va_list */*ap*/);
b64eb60f 1805
67b5031e 1806/*----- Integer types: signed and unsigned --------------------------------*/
3efcfd2d
MW
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
b64eb60f 1831extern const struct tvec_regty tvty_int, tvty_uint;
3efcfd2d
MW
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 */
b64eb60f
MW
1837struct tvec_irange { long min, max; };
1838struct tvec_urange { unsigned long min, max; };
1839
3efcfd2d 1840/* Bounds corresponding to common integer types. */
b64eb60f
MW
1841extern const struct tvec_irange
1842 tvrange_schar, tvrange_short, tvrange_int, tvrange_long,
1843 tvrange_sbyte, tvrange_i16, tvrange_i32;
1844extern const struct tvec_urange
1845 tvrange_uchar, tvrange_ushort, tvrange_uint, tvrange_ulong, tvrange_size,
1846 tvrange_byte, tvrange_u16, tvrange_u32;
3efcfd2d 1847
67b5031e 1848/* --- @tvec_claimeq_int@, @TVEC_CLAIMEQ_INT@ --- *
3efcfd2d
MW
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 */
b64eb60f
MW
1869
1870extern int tvec_claimeq_int(struct tvec_state */*tv*/,
1871 long /*i0*/, long /*i1*/,
1872 const char */*file*/, unsigned /*lno*/,
1873 const char */*expr*/);
3efcfd2d
MW
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
b64eb60f
MW
1899extern 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*/);
b64eb60f
MW
1903#define TVEC_CLAIMEQ_UINT(tv, u0, u1) \
1904 (tvec_claimeq_uint(tv, u0, u1, __FILE__, __LINE__, #u0 " /= " #u1))
1905
c4ccbbf9
MW
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
1912extern 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
1936int 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
3efcfd2d
MW
1942/*----- Floating-point type -----------------------------------------------*/
1943
c81c35df
MW
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.
3efcfd2d
MW
1949 *
1950 * The comparison rules for floating-point numbers are complex: see
1951 * @tvec_claimeqish_float@ for details.
1952 */
1953
e63124bc 1954extern const struct tvec_regty tvty_float;
3efcfd2d 1955
e63124bc 1956struct tvec_floatinfo {
3efcfd2d
MW
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 */
e63124bc
MW
1969};
1970
d056fbdf
MW
1971extern const struct tvec_floatinfo tvflt_finite, tvflt_nonneg;
1972
3efcfd2d
MW
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 *
c4ccbbf9 1982 * Returns: Nonzero if @f0@ and @f1@ are sufficiently close, otherwise
3efcfd2d
MW
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
c4ccbbf9
MW
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$%.)
3efcfd2d
MW
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
e63124bc
MW
2022extern 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*/);
3efcfd2d 2027#define TVEC_CLAIMEQISH_FLOAT(tv, f0, f1, f, delta) \
c4ccbbf9 2028 (tvec_claimeqish_float(tv, f0, f1, f, delta, __FILE__, __LINE__, \
3efcfd2d
MW
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
e63124bc
MW
2047extern int tvec_claimeq_float(struct tvec_state */*tv*/,
2048 double /*f0*/, double /*f1*/,
2049 const char */*file*/, unsigned /*lno*/,
2050 const char */*expr*/);
e63124bc
MW
2051#define TVEC_CLAIMEQ_FLOAT(tv, f0, f1) \
2052 (tvec_claimeq_float(tv, f0, f1, __FILE__, __LINE__, #f0 " /= " #f1))
2053
814e42ff
MW
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.
814e42ff
MW
2059 */
2060
2061extern const struct tvec_regty tvty_duration;
2062
13ee7406
MW
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
2077extern int tvec_parsedurunit(double */*scale_out*/,
2078 const char **/*p_inout*/);
2079
c4ccbbf9
MW
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
2103extern 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
2128int 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
3efcfd2d
MW
2135/*----- Enumerated types --------------------------------------------------*/
2136
67b5031e
MW
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
3efcfd2d
MW
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.
67b5031e
MW
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
c81c35df 2150 * pointers, the only permitted literal is %|#nil|%, which denotes a null
67b5031e
MW
2151 * pointer. On output, names are preferred (with the underlying value given
2152 * in a comment).
3efcfd2d 2153 */
b64eb60f 2154
3efcfd2d
MW
2155#define DEFENUMTY(tag, ty, slot) \
2156 extern const struct tvec_regty tvty_##slot##enum;
2157TVEC_MISCSLOTS(DEFENUMTY)
2158#undef DEFENUMTY
2159
2160/* A @struct tvec_tassoc@ associates a string tag with a value. */
b64eb60f
MW
2161#define DEFASSOC(tag_, ty, slot) \
2162 struct tvec_##slot##assoc { const char *tag; ty slot; };
2163TVEC_MISCSLOTS(DEFASSOC)
2164#undef DEFASSOC
2165
67b5031e
MW
2166#define TVEC_ENDENUM { 0, 0 }
2167
3efcfd2d
MW
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) */
b64eb60f 2186
3efcfd2d
MW
2187TVEC_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. */
20ba6b0b
MW
2197extern const struct tvec_ienuminfo tvenum_bool;
2198extern const struct tvec_ienuminfo tvenum_cmp;
e63124bc 2199
3efcfd2d
MW
2200/* --- @tvec_claimeq_tenum@, @TVEC_CLAIMEQ_TENUM@ --- *
2201 *
2202 * Arguments: @struct tvec_state *tv@ = test-vector state
67b5031e 2203 * @const struct tvec_typeenuminfo *ei@ = enumeration type info
3efcfd2d
MW
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
67b5031e
MW
2214 * mismatched values are dumped: @t0@ is printed as the output
2215 * value and @t1@ is printed as the input reference.
3efcfd2d
MW
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
67b5031e 2220 * the @t0@ and @t1@ arguments in the failure message.
3efcfd2d
MW
2221 */
2222
b64eb60f
MW
2223#define DECLCLAIM(tag, ty, slot) \
2224 extern int tvec_claimeq_##slot##enum \
2225 (struct tvec_state */*tv*/, \
e63124bc 2226 const struct tvec_##slot##enuminfo */*ei*/, \
3efcfd2d 2227 ty /*t0*/, ty /*t1*/, \
b64eb60f
MW
2228 const char */*file*/, unsigned /*lno*/, const char */*expr*/);
2229TVEC_MISCSLOTS(DECLCLAIM)
2230#undef DECLCLAIM
3efcfd2d
MW
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
67b5031e
MW
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 *
c81c35df
MW
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.
67b5031e
MW
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
c81c35df
MW
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.
67b5031e 2264 */
b64eb60f
MW
2265
2266extern const struct tvec_regty tvty_flags;
3efcfd2d
MW
2267
2268struct 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
67b5031e 2272 * should cover all of the value bits, i.e., @(v&~m) == 0@.
3efcfd2d
MW
2273 */
2274
2275 const char *tag; /* name */
2276 unsigned long m, v; /* mask and value */
2277};
2278
67b5031e
MW
2279#define TVEC_ENDFLAGS { 0, 0, 0 }
2280
b64eb60f 2281struct tvec_flaginfo {
67b5031e
MW
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 */
b64eb60f
MW
2287};
2288
67b5031e
MW
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
b64eb60f
MW
2312extern 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
67b5031e
MW
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 *
c81c35df
MW
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.
67b5031e
MW
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
e63124bc 2381extern const struct tvec_regty tvty_char;
67b5031e
MW
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
e63124bc
MW
2405extern 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
67b5031e
MW
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 *
c81c35df
MW
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 *
67b5031e
MW
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
c81c35df 2457extern const struct tvec_regty tvty_text, tvty_bytes;
b64eb60f 2458
d056fbdf
MW
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
2480extern void tvec_alloctext(union tvec_regval */*rv*/, size_t /*sz*/);
2481extern void tvec_allocbytes(union tvec_regval */*rv*/, size_t /*sz*/);
2482
c81c35df 2483/* --- @tvec_claimeq_text@, @TVEC_CLAIMEQ_TEXT@ --- *
67b5031e
MW
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 *
c81c35df 2501 * The @TVEC_CLAIM_TEXT@ macro is similar, only it (a)
67b5031e
MW
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
c81c35df
MW
2507extern 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 "]"))
67b5031e 2515
c81c35df 2516/* --- @tvec_claimeq_textz@, @TVEC_CLAIMEQ_TEXTZ@ --- *
67b5031e
MW
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
c81c35df 2529 * explicitly. The macro is similarly like @TVEC_CLAIMEQ_TEXT@.
67b5031e
MW
2530 */
2531
c81c35df
MW
2532extern 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))
67b5031e
MW
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
b64eb60f
MW
2563extern 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*/);
b64eb60f
MW
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
67b5031e 2572/*----- Buffer type -------------------------------------------------------*/
c5e0e403 2573
67b5031e 2574/* Buffer registers are primarily used for benchmarking. Only a buffer's
adec5584
MW
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.
67b5031e 2587 *
adec5584
MW
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.
c81c35df
MW
2593 *
2594 * No @claimeq@ functions or macros are provided for buffers because they
2595 * don't seem very useful.
67b5031e 2596 */
c5e0e403 2597
67b5031e 2598extern const struct tvec_regty tvty_buffer;
c5e0e403 2599
adec5584
MW
2600/* --- @tvec_initbuffer@ --- *
2601 *
2602 * Arguments: @union tvec_regval *rv@ = register value
d056fbdf 2603 * @const union tvec_regval *ref@ = reference buffer
adec5584
MW
2604 * @size_t sz@ = size to allocate
2605 *
2606 * Returns: ---
2607 *
d056fbdf 2608 * Use: Initialize the alignment parameters in @rv@ to match @ref@,
adec5584
MW
2609 * and the size to @sz@.
2610 */
2611
2612extern void tvec_initbuffer(union tvec_regval */*rv*/,
d056fbdf 2613 const union tvec_regval */*ref*/, size_t /*sz*/);
adec5584
MW
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
2625extern void tvec_allocbuffer(union tvec_regval */*rv*/);
2626
b64eb60f
MW
2627/*----- That's all, folks -------------------------------------------------*/
2628
2629#ifdef __cplusplus
2630 }
2631#endif
2632
2633#endif