.\" -*-nroff-*-
.\"
.\" Manual for test environments
.\"
.\" (c) 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH tvec-env 3mLib "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
.\" @TVEG_GREG
.\" @TVEG_REG
.
.\" @tvec_skipgroup
.\" @tvec_skipgroup_v
.\" @tvec_skip
.\" @tvec_skip_v
.\" @tvec_fail
.\" @tvec_fail_v
.\" @tvec_dumpreg
.
.\" @tvec_checkregs
.\" @tvec_mismatch
.\" @tvec_check
.\" @tvec_check_v
.
.\" @tvec_report
.\" @tvec_report_v
.\" @tvec_error
.\" @tvec_notice
.\" @tvec_info
.\" @tvec_unkregerr
.\" @tvec_dupregerr
.
.\" @tvec_serialize
.\" @tvec_deserialize
.
.\" @tvec_initregs
.\" @tvec_releaseregs
.\" @tvec_releaseoutputs
.
.\"--------------------------------------------------------------------------
.SH NAME
tvec-env \- test vector framework environments
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.nf
.B "#include <mLib/tvec.h>"
.PP
.ta 2n
.B "enum {"
.B "	TVRD_INPUT,"
.B "	TVRD_OUTPUT,"
.B "	TVRD_MATCH,"
.B "	TVRD_FOUND,"
.B "	TVRD_EXPECT,"
.B "	TVRD_LIMIT"
.B "};"
.B "struct tvec_state {"
.B "	unsigned f;"
.B "	arena *a;"
.B "	struct tvec_config cfg;"
.B "	struct tvec_reg *in, *out;"
.B "	const struct tvec_test *test;"
.B "	..."
.B "};"
.B "#define TVSF_SKIP ..."
.B "#define TVSF_ACTIVE ..."
.B "#define TVSF_OUTMASK ..."
.B "#define TVSF_OUTSHIFT ..."
.B "#define TVSF_XFAIL ..."
.PP
.ta \w'\fBtypedef int tvec_setvarfn('u
.BI "typedef int tvec_setvarfn(struct tvec_state *" tv ", const char *" var ,
.BI "	const union tvec_regval *" rv ", void *" ctx );
.ta \w'\fBtypedef int tvec_envsetupfn('u
.BI "typedef void tvec_envsetupfn(struct tvec_state *" tv ,
.BI "	const struct tvec_env *" env ,
.BI "	void *" pctx ", void *" ctx );
.ta 2n +\w'\fB('u
.B "typedef const struct tvec_vardef *tvec_envfindvarfn"
.BI "	(struct tvec_state *" tv ", const char *" name ,
.BI "		void **" ctx_out ", void *" ctx );
.BI "typedef void tvec_envbeforefn(struct tvec_state *" tv ", void *" ctx );
.ta \w'\fBtypedef void tvec_envrunfn('u
.BI "typedef void tvec_envrunfn(struct tvec_state *" tv ,
.BI "	tvec_testfn *" fn ", void *" ctx );
.BI "typedef void tvec_envafterfn(struct tvec_state *" tv ", void *" ctx );
.BI "typedef void tvec_envteardownfn(struct tvec_state *" tv ", void *" ctx );
.ta 2n
.B "struct tvec_env {"
.B "	size_t ctxsz;"
.B "	tvec_envsetupfn *setup;"
.B "	tvec_envfindvarfn *findvar;"
.B "	tvec_envbeforefn *before;"
.B "	tvec_envrunfn *run;"
.B "	tvec_envafterfn *after;"
.B "	tvec_envteardownfn *teardown;"
.B "};"
.PP
.ta \w'\fBstruct tvec_reg *TVEC_GREG('u
.BI "struct tvec_reg *TVEC_GREG(struct tvec_reg *" vec ,
.BI "	unsigned " i ", size_t " regsz );
.ta \w'\fBstruct tvec_reg *TVEC_REG('u
.BI "struct tvec_reg *TVEC_REG(struct tvec_state *" tv ", " vec ", unsigned " i );
.PP
.BI "void tvec_skipgroup(struct tvec_state *" tv ", const char *" excuse ", ...);"
.ta \w'\fBvoid tvec_skipgroup_v('u
.BI "void tvec_skipgroup_v(struct tvec_state *" tv ,
.BI "	const char *" excuse ", va_list *" ap );
.BI "void tvec_skip(struct tvec_state *" tv ", const char *" excuse ", ...);"
.ta \w'\fBvoid tvec_skip_v('u
.BI "void tvec_skip_v(struct tvec_state *" tv ,
.BI "	const char *" excuse ", va_list *" ap );
.BI "void tvec_fail(struct tvec_state *" tv ", const char *" detail ", ...);"
.ta \w'\fBvoid tvec_fail_v('u
.BI "void tvec_fail_v(struct tvec_state *" tv ,
.BI "	const char *" detail ", va_list *" ap );
.ta \w'\fBvoid tvec_dumpreg('u
.BI "void tvec_dumpreg(struct tvec_state *" tv ,
.BI "	unsigned " disp ", const union tvec_regval *" rv ,
.BI "	const struct tvec_regdef *" rd );
.PP
.BI "void tvec_checkregs(struct tvec_state *" tv );
.BI "void tvec_mismatch(struct tvec_state *" tv ", unsigned " f );
.BI "void tvec_check(struct tvec_state *" tv ", const char *" detail ", ...);"
.ta \w'\fBvoid tvec_check_v('u
.BI "void tvec_check_v(struct tvec_state *" tv ,
.B "#define TVMF_IN ..."
.B "#define TVMF_OUT ..."
.PP
.B "enum {"
.B "	TVLEV_INFO = ...,"
.B "	TVLEV_NOTE = ...,"
.B "	TVLEV_ERR = ...,"
.B "	..."
.B "};"
.ta \w'\fBvoid tvec_report('u
.BI "void tvec_report(struct tvec_state *" tv ", unsigned " level ,
.BI "	const char *" msg ", ...);"
.ta \w'\fBvoid tvec_report_v('u
.BI "void tvec_report_v(struct tvec_state *" tv ", unsigned " level ,
.BI "	const char *" msg ", va_list *" ap );
.BI "int tvec_error(struct tvec_state *" tv ", const char *" msg ", ...);"
.BI "void tvec_notice(struct tvec_state *" tv ", const char *" msg ", ...);"
.BI "void tvec_info(struct tvec_state *" tv ", const char *" msg ", ...);"
.BI "int tvec_unkregerr(struct tvec_state *" tv ", const char *" name );
.BI "int tvec_dupregerr(struct tvec_state *" tv ", const char *" name );
.PP
.ta \w'\fBint tvec_serialize('u
.BI "int tvec_serialize(const struct tvec_reg *" rv ", buf *" b ,
.BI "	const struct tvec_regdef *" regs ,
.BI "	unsigned " nr ", size_t " regsz );
.ta \w'\fBint tvec_deserialize('u
.BI "int tvec_deserialize(struct tvec_reg *" rv ", buf *" b ,
.BI "	const struct tvec_regdef *" regs ,
.BI "	unsigned " nr ", size_t " regsz );
.PP
.BI "void tvec_initregs(struct tvec_state *" tv );
.BI "void tvec_releaseregs(struct tvec_state *" tv );
.BI "void tvec_releaseoutputs(struct tvec_state *" tv );
.fi