xref: /dflybsd-src/share/man/man9/tbridge.9 (revision 50d0636a45e2986e5835554f000f0f6649856163)

.\"
.\" Copyright (c) 2011
.\"	The DragonFly Project.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\" 3. Neither the name of The DragonFly Project nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific, prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd November 18, 2011
.Dt TBRIDGE 9
.Os
.Sh NAME
.Nm tbridge_printf ,
.Nm tbridge_test_done ,
.Nm TBRIDGE_TESTCASE_MODULE
.Nd kernel test bridge for dfregress
.Sh SYNOPSIS
.In sys/systm.h
.In sys/kernel.h
.In sys/module.h
.In sys/tbridge.h
.Pp
Functions:
.Ft int
.Fn tbridge_printf "const char *fmt" "..."
.Ft void
.Fn tbridge_test_done "int result"
.Pp
Macros:
.Fn TBRIDGE_TESTCASE_MODULE "name" "struct tbridge_testcase *testcase"
.Pp
Defines:
.Dv RESULT_TIMEOUT ,
.Dv RESULT_SIGNALLED ,
.Dv RESULT_NOTRUN ,
.Dv RESULT_FAIL ,
.Dv RESULT_PASS ,
.Dv RESULT_UNKNOWN
.Pp
Callbacks:
.Ft typedef int
.Fn (*tbridge_abort_t) "void"
.Ft typedef void
.Fn (*tbridge_run_t) "void *"
.Sh DESCRIPTION
To create a new kernel testcase
.Sq testfoo
the following is required:
.Bd -literal
TBRIDGE_TESTCASE_MODULE(testfoo, &testfoo_case);

struct tbridge_testcase testfoo_case = {
	.tb_run = testfoo_run,

	/* The following are optional */
	.tb_abort = testfoo_abort
};
.Ed
.Pp
The
.Fa tb_run
callback is called from a separate kernel thread to start testcase
execution.
.Pp
The
.Fa tb_abort
callback is optional, but highly recommended.
It is called whenever a testcase execution times out, so that the
testcase can clean up and abort all running tasks, if possible.
If this is not applicable to your test because it is impossible
to interrupt, set to
.Dv NULL .
.Sh FUNCTIONS
The
.Fn TBRIDGE_TESTCASE_MODULE
macro declares a
.Nm
testcase kernel module.
.Fa testcase
is a structure of type
.Ft struct tbridge_testcase ,
as described above.
.Pp
The
.Fn tbridge_printf
function acts as a kprintf replacement that will log all the output
into the testcase metadata that is passed back to userland upon completion.
Its syntax is equivalent to that of
.Xr kprintf 9 .
.Pp
The
.Fn tbridge_test_done
function should be called whenever a result for the testcase is available.
The parameter
.Fa result
should be set to one of the
.Dv RESULT_
defines.
.Sh SEE ALSO
.Xr dfregress 8
.Sh HISTORY
The
.Nm
module first appeared in
.Dx 2.13 .
.Sh AUTHORS
The
.Nm
module was written by
.An Alex Hornung .