chiark - git - mdw - mLib/blob - test/tvec-env.3.in

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for test environments
   4 .\"
   5 .\" (c) 2024 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 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH tvec-env 3mLib "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @TVEG_GREG
  33 .\" @TVEG_REG
  34 .
  35 .\" @tvec_skipgroup
  36 .\" @tvec_skipgroup_v
  37 .\" @tvec_skip
  38 .\" @tvec_skip_v
  39 .\" @tvec_fail
  40 .\" @tvec_fail_v
  41 .\" @tvec_dumpreg
  42 .
  43 .\" @tvec_checkregs
  44 .\" @tvec_mismatch
  45 .\" @tvec_check
  46 .\" @tvec_check_v
  47 .
  48 .\" @tvec_report
  49 .\" @tvec_report_v
  50 .\" @tvec_error
  51 .\" @tvec_notice
  52 .\" @tvec_info
  53 .\" @tvec_unkregerr
  54 .\" @tvec_dupregerr
  55 .
  56 .\" @tvec_serialize
  57 .\" @tvec_deserialize
  58 .
  59 .\" @tvec_initregs
  60 .\" @tvec_releaseregs
  61 .\" @tvec_releaseoutputs
  62 .
  63 .\"--------------------------------------------------------------------------
  64 .SH NAME
  65 tvec-env \- test vector framework environments
  66 .
  67 .\"--------------------------------------------------------------------------
  68 .SH SYNOPSIS
  69 .
  70 .nf
  71 .B "#include <mLib/tvec.h>"
  72 .PP
  73 .ta 2n
  74 .B "enum {"
  75 .B "    TVRD_INPUT,"
  76 .B "    TVRD_OUTPUT,"
  77 .B "    TVRD_MATCH,"
  78 .B "    TVRD_FOUND,"
  79 .B "    TVRD_EXPECT,"
  80 .B "    TVRD_LIMIT"
  81 .B "};"
  82 .B "struct tvec_state {"
  83 .B "    unsigned f;"
  84 .B "    arena *a;"
  85 .B "    struct tvec_config cfg;"
  86 .B "    struct tvec_reg *in, *out;"
  87 .B "    const struct tvec_test *test;"
  88 .B "    ..."
  89 .B "};"
  90 .B "#define TVSF_SKIP ..."
  91 .B "#define TVSF_ACTIVE ..."
  92 .B "#define TVSF_OUTMASK ..."
  93 .B "#define TVSF_OUTSHIFT ..."
  94 .B "#define TVSF_XFAIL ..."
  95 .PP
  96 .ta \w'\fBtypedef int tvec_setvarfn('u
  97 .BI "typedef int tvec_setvarfn(struct tvec_state *" tv ", const char *" var ,
  98 .BI "   const union tvec_regval *" rv ", void *" ctx );
  99 .ta \w'\fBtypedef int tvec_envsetupfn('u
 100 .BI "typedef void tvec_envsetupfn(struct tvec_state *" tv ,
 101 .BI "   const struct tvec_env *" env ,
 102 .BI "   void *" pctx ", void *" ctx );
 103 .ta 2n +\w'\fB('u
 104 .B "typedef const struct tvec_vardef *tvec_envfindvarfn"
 105 .BI "   (struct tvec_state *" tv ", const char *" name ,
 106 .BI "           void **" ctx_out ", void *" ctx );
 107 .BI "typedef void tvec_envbeforefn(struct tvec_state *" tv ", void *" ctx );
 108 .ta \w'\fBtypedef void tvec_envrunfn('u
 109 .BI "typedef void tvec_envrunfn(struct tvec_state *" tv ,
 110 .BI "   tvec_testfn *" fn ", void *" ctx );
 111 .BI "typedef void tvec_envafterfn(struct tvec_state *" tv ", void *" ctx );
 112 .BI "typedef void tvec_envteardownfn(struct tvec_state *" tv ", void *" ctx );
 113 .ta 2n
 114 .B "struct tvec_env {"
 115 .B "    size_t ctxsz;"
 116 .B "    tvec_envsetupfn *setup;"
 117 .B "    tvec_envfindvarfn *findvar;"
 118 .B "    tvec_envbeforefn *before;"
 119 .B "    tvec_envrunfn *run;"
 120 .B "    tvec_envafterfn *after;"
 121 .B "    tvec_envteardownfn *teardown;"
 122 .B "};"
 123 .PP
 124 .ta \w'\fBstruct tvec_reg *TVEC_GREG('u
 125 .BI "struct tvec_reg *TVEC_GREG(struct tvec_reg *" vec ,
 126 .BI "   unsigned " i ", size_t " regsz );
 127 .ta \w'\fBstruct tvec_reg *TVEC_REG('u
 128 .BI "struct tvec_reg *TVEC_REG(struct tvec_state *" tv ", " vec ", unsigned " i );
 129 .PP
 130 .BI "void tvec_skipgroup(struct tvec_state *" tv ", const char *" excuse ", ...);"
 131 .ta \w'\fBvoid tvec_skipgroup_v('u
 132 .BI "void tvec_skipgroup_v(struct tvec_state *" tv ,
 133 .BI "   const char *" excuse ", va_list *" ap );
 134 .BI "void tvec_skip(struct tvec_state *" tv ", const char *" excuse ", ...);"
 135 .ta \w'\fBvoid tvec_skip_v('u
 136 .BI "void tvec_skip_v(struct tvec_state *" tv ,
 137 .BI "   const char *" excuse ", va_list *" ap );
 138 .BI "void tvec_fail(struct tvec_state *" tv ", const char *" detail ", ...);"
 139 .ta \w'\fBvoid tvec_fail_v('u
 140 .BI "void tvec_fail_v(struct tvec_state *" tv ,
 141 .BI "   const char *" detail ", va_list *" ap );
 142 .ta \w'\fBvoid tvec_dumpreg('u
 143 .BI "void tvec_dumpreg(struct tvec_state *" tv ,
 144 .BI "   unsigned " disp ", const union tvec_regval *" rv ,
 145 .BI "   const struct tvec_regdef *" rd );
 146 .PP
 147 .BI "void tvec_checkregs(struct tvec_state *" tv );
 148 .BI "void tvec_mismatch(struct tvec_state *" tv ", unsigned " f );
 149 .BI "void tvec_check(struct tvec_state *" tv ", const char *" detail ", ...);"
 150 .ta \w'\fBvoid tvec_check_v('u
 151 .BI "void tvec_check_v(struct tvec_state *" tv ,
 152 .B "#define TVMF_IN ..."
 153 .B "#define TVMF_OUT ..."
 154 .PP
 155 .B "enum {"
 156 .B "    TVLEV_INFO = ...,"
 157 .B "    TVLEV_NOTE = ...,"
 158 .B "    TVLEV_ERR = ...,"
 159 .B "    ..."
 160 .B "};"
 161 .ta \w'\fBvoid tvec_report('u
 162 .BI "void tvec_report(struct tvec_state *" tv ", unsigned " level ,
 163 .BI "   const char *" msg ", ...);"
 164 .ta \w'\fBvoid tvec_report_v('u
 165 .BI "void tvec_report_v(struct tvec_state *" tv ", unsigned " level ,
 166 .BI "   const char *" msg ", va_list *" ap );
 167 .BI "int tvec_error(struct tvec_state *" tv ", const char *" msg ", ...);"
 168 .BI "void tvec_notice(struct tvec_state *" tv ", const char *" msg ", ...);"
 169 .BI "void tvec_info(struct tvec_state *" tv ", const char *" msg ", ...);"
 170 .BI "int tvec_unkregerr(struct tvec_state *" tv ", const char *" name );
 171 .BI "int tvec_dupregerr(struct tvec_state *" tv ", const char *" name );
 172 .PP
 173 .ta \w'\fBint tvec_serialize('u
 174 .BI "int tvec_serialize(const struct tvec_reg *" rv ", buf *" b ,
 175 .BI "   const struct tvec_regdef *" regs ,
 176 .BI "   unsigned " nr ", size_t " regsz );
 177 .ta \w'\fBint tvec_deserialize('u
 178 .BI "int tvec_deserialize(struct tvec_reg *" rv ", buf *" b ,
 179 .BI "   const struct tvec_regdef *" regs ,
 180 .BI "   unsigned " nr ", size_t " regsz );
 181 .PP
 182 .BI "void tvec_initregs(struct tvec_state *" tv );
 183 .BI "void tvec_releaseregs(struct tvec_state *" tv );
 184 .BI "void tvec_releaseoutputs(struct tvec_state *" tv );
 185 .fi