From: Alex Hornung <ahornung@gmail.com>
Date: Fri, 18 Nov 2011 08:55:56 +0000 (+0000)
Subject: tbridge(9) - add man page
X-Git-Tag: v3.0.0~621
X-Git-Url: https://gitweb.dragonflybsd.org/dragonfly.git/commitdiff_plain/ae9799f1d0c59ff3bb42aa153bdcfc83bc14ae13

tbridge(9) - add man page
---

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 6a52431d60..93a3f990da 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -151,6 +151,7 @@ MAN=	accept_filter.9 \
 	SYSINIT.9 \
 	systimer.9 \
 	taskqueue.9 \
+	tbridge.9 \
 	time.9 \
 	token.9 \
 	tvtohz.9 \
diff --git a/share/man/man9/tbridge.9 b/share/man/man9/tbridge.9
new file mode 100644
index 0000000000..3ed0e64772
--- /dev/null
+++ b/share/man/man9/tbridge.9
@@ -0,0 +1,132 @@
+.\"
+.\" 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
+.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_rpintf "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 ""
+.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 thread 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 .