share/man/man9/tbridge.9

   1 .\"
   2 .\" Copyright (c) 2011
   3 .\"     The DragonFly Project.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\" 3. Neither the name of The DragonFly Project nor the names of its
  16 .\"    contributors may be used to endorse or promote products derived
  17 .\"    from this software without specific, prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .Dd November 18, 2011
  33 .Dt TBRIDGE 9
  34 .Os
  35 .Sh NAME
  36 .Nm tbridge_printf ,
  37 .Nm tbridge_test_done
  38 .Nd kernel test bridge for dfregress
  39 .Sh SYNOPSIS
  40 .In sys/systm.h
  41 .In sys/kernel.h
  42 .In sys/module.h
  43 .In sys/tbridge.h
  44 .Pp
  45 Functions:
  46 .Ft int
  47 .Fn tbridge_rpintf "const char *fmt" "..."
  48 .Ft void
  49 .Fn tbridge_test_done "int result"
  50 .Pp
  51 Macros:
  52 .Fn TBRIDGE_TESTCASE_MODULE "name" "struct tbridge_testcase *testcase"
  53 .Pp
  54 Defines:
  55 .Dv RESULT_TIMEOUT ,
  56 .Dv RESULT_SIGNALLED ,
  57 .Dv RESULT_NOTRUN ,
  58 .Dv RESULT_FAIL ,
  59 .Dv RESULT_PASS ,
  60 .Dv RESULT_UNKNOWN
  61 .Pp
  62 Callbacks:
  63 .Ft typedef int
  64 .Fn tbridge_abort_t ""
  65 .Ft typedef void
  66 .Fn tbridge_run_t "void *"
  67 .Sh DESCRIPTION
  68 To create a new kernel testcase
  69 .Sq testfoo
  70 the following is required:
  71 .Bd -literal
  72 TBRIDGE_TESTCASE_MODULE(testfoo, &testfoo_case);
  73
  74 struct tbridge_testcase testfoo_case = {
  75         .tb_run = testfoo_run,
  76
  77         /* The following are optional */
  78         .tb_abort = testfoo_abort
  79 };
  80 .Ed
  81 .Pp
  82 The
  83 .Fa tb_run
  84 callback is called from a separate kernel thread to start testcase
  85 execution.
  86 .Pp
  87 The
  88 .Fa tb_abort
  89 callback is optional, but highly recommended.
  90 It is called whenever a testcase execution times out, so that the
  91 testcase can clean up and abort all running tasks, if possible.
  92 If this is not applicable to your thread because it is impossible
  93 to interrupt, set to
  94 .Dv NULL .
  95 .Sh FUNCTIONS
  96 The
  97 .Fn TBRIDGE_TESTCASE_MODULE
  98 macro declares a
  99 .Nm
 100 testcase kernel module.
 101 .Fa testcase
 102 is a structure of type
 103 .Ft struct tbridge_testcase ,
 104 as described above.
 105 .Pp
 106 The
 107 .Fn tbridge_printf
 108 function acts as a kprintf replacement that will log all the output
 109 into the testcase metadata that is passed back to userland upon completion.
 110 Its syntax is equivalent to that of
 111 .Xr kprintf 9 .
 112 .Pp
 113 The
 114 .Fn tbridge_test_done
 115 function should be called whenever a result for the testcase is available.
 116 The parameter
 117 .Fa result
 118 should be set to one of the
 119 .Dv RESULT_
 120 defines.
 121 .Sh SEE ALSO
 122 .Xr dfregress 8
 123 .Sh HISTORY
 124 The
 125 .Nm
 126 module first appeared in
 127 .Dx 2.13 .
 128 .Sh AUTHORS
 129 The
 130 .Nm
 131 module was written by
 132 .An Alex Hornung .