share/man/man9/fail.9

   1 .\"
   2 .\" Copyright (c) 2009-2019 Dell EMC Isilon http://www.isilon.com/
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice(s), this list of conditions and the following disclaimer as
   9 .\"    the first lines of this file unmodified other than the possible
  10 .\"    addition of one or more copyright notices.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice(s), this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  16 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  17 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  18 .\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
  19 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  20 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  21 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  22 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  25 .\" DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd June 6, 2019
  30 .Dt FAIL 9
  31 .Os
  32 .Sh NAME
  33 .Nm DEBUG_FP ,
  34 .Nm KFAIL_POINT_CODE ,
  35 .Nm KFAIL_POINT_CODE_FLAGS ,
  36 .Nm KFAIL_POINT_CODE_COND ,
  37 .Nm KFAIL_POINT_ERROR ,
  38 .Nm KFAIL_POINT_EVAL ,
  39 .Nm KFAIL_POINT_DECLARE ,
  40 .Nm KFAIL_POINT_DEFINE ,
  41 .Nm KFAIL_POINT_GOTO ,
  42 .Nm KFAIL_POINT_RETURN ,
  43 .Nm KFAIL_POINT_RETURN_VOID ,
  44 .Nm KFAIL_POINT_SLEEP_CALLBACKS ,
  45 .Nm fail_point
  46 .Nd fail points
  47 .Sh SYNOPSIS
  48 .In sys/fail.h
  49 .Fn KFAIL_POINT_CODE "parent" "name" "code"
  50 .Fn KFAIL_POINT_CODE_FLAGS "parent" "name" "flags" "code"
  51 .Fn KFAIL_POINT_CODE_COND "parent" "name" "cond" "flags" "code"
  52 .Fn KFAIL_POINT_ERROR "parent" "name" "error_var"
  53 .Fn KFAIL_POINT_EVAL "name" "code"
  54 .Fn KFAIL_POINT_DECLARE "name"
  55 .Fn KFAIL_POINT_DEFINE "parent" "name" "flags"
  56 .Fn KFAIL_POINT_GOTO "parent" "name" "error_var" "label"
  57 .Fn KFAIL_POINT_RETURN "parent" "name"
  58 .Fn KFAIL_POINT_RETURN_VOID "parent" "name"
  59 .Fn KFAIL_POINT_SLEEP_CALLBACKS "parent" "name" "pre_func" "pre_arg" "post_func" "post_arg" "code"
  60 .Sh DESCRIPTION
  61 Fail points are used to add code points where errors may be injected
  62 in a user controlled fashion.
  63 Fail points provide a convenient wrapper around user-provided error
  64 injection code, providing a
  65 .Xr sysctl 9
  66 MIB, and a parser for that MIB that describes how the error
  67 injection code should fire.
  68 .Pp
  69 The base fail point macro is
  70 .Fn KFAIL_POINT_CODE
  71 where
  72 .Fa parent
  73 is a sysctl tree (frequently
  74 .Sy DEBUG_FP
  75 for kernel fail points, but various subsystems may wish to provide
  76 their own fail point trees), and
  77 .Fa name
  78 is the name of the MIB in that tree, and
  79 .Fa code
  80 is the error injection code.
  81 The
  82 .Fa code
  83 argument does not require braces, but it is considered good style to
  84 use braces for any multi-line code arguments.
  85 Inside the
  86 .Fa code
  87 argument, the evaluation of
  88 .Sy RETURN_VALUE
  89 is derived from the
  90 .Fn return
  91 value set in the sysctl MIB.
  92 .Pp
  93 Additionally,
  94 .Fn KFAIL_POINT_CODE_FLAGS
  95 provides a
  96 .Fa flags
  97 argument which controls the fail point's behaviour.
  98 This can be used to e.g., mark the fail point's context as non-sleepable,
  99 which causes the
 100 .Sy sleep
 101 action to be coerced to a busy wait.
 102 The supported flags are:
 103 .Bl -ohang -offset indent
 104 .It FAIL_POINT_USE_TIMEOUT_PATH
 105 Rather than sleeping on a
 106 .Fn sleep
 107 call, just fire the post-sleep function after a timeout fires.
 108 .It FAIL_POINT_NONSLEEPABLE
 109 Mark the fail point as being in a non-sleepable context, which coerces
 110 .Fn sleep
 111 calls to
 112 .Fn delay
 113 calls.
 114 .El
 115 .Pp
 116 Likewise,
 117 .Fn KFAIL_POINT_CODE_COND
 118 supplies a
 119 .Fa cond
 120 argument, which allows you to set the condition under which the fail point's
 121 code may fire.
 122 This is equivalent to:
 123 .Bd -literal
 124         if (cond)
 125                 KFAIL_POINT_CODE_FLAGS(...);
 126
 127 .Ed
 128 See
 129 .Sx SYSCTL VARIABLES
 130 below.
 131 .Pp
 132 The remaining
 133 .Fn KFAIL_POINT_*
 134 macros are wrappers around common error injection paths:
 135 .Bl -inset
 136 .It Fn KFAIL_POINT_RETURN parent name
 137 is the equivalent of
 138 .Sy KFAIL_POINT_CODE(..., return RETURN_VALUE)
 139 .It Fn KFAIL_POINT_RETURN_VOID parent name
 140 is the equivalent of
 141 .Sy KFAIL_POINT_CODE(..., return)
 142 .It Fn KFAIL_POINT_ERROR parent name error_var
 143 is the equivalent of
 144 .Sy KFAIL_POINT_CODE(..., error_var = RETURN_VALUE)
 145 .It Fn KFAIL_POINT_GOTO parent name error_var label
 146 is the equivalent of
 147 .Sy KFAIL_POINT_CODE(..., { error_var = RETURN_VALUE; goto label;})
 148 .El
 149 .Pp
 150 You can also introduce fail points by separating the declaration,
 151 definition, and evaluation portions.
 152 .Bl -inset
 153 .It Fn KFAIL_POINT_DECLARE name
 154 is used to declare the
 155 .Sy fail_point
 156 struct.
 157 .It Fn KFAIL_POINT_DEFINE parent name flags
 158 defines and initializes the
 159 .Sy fail_point
 160 and sets up its
 161 .Xr sysctl 9 .
 162 .It Fn KFAIL_POINT_EVAL name code
 163 is used at the point that the fail point is executed.
 164 .El
 165 .Sh SYSCTL VARIABLES
 166 The
 167 .Fn KFAIL_POINT_*
 168 macros add sysctl MIBs where specified.
 169 Many base kernel MIBs can be found in the
 170 .Sy debug.fail_point
 171 tree (referenced in code by
 172 .Sy DEBUG_FP ) .
 173 .Pp
 174 The sysctl variable may be set in a number of ways:
 175 .Bd -literal
 176   [<pct>%][<cnt>*]<type>[(args...)][-><more terms>]
 177 .Ed
 178 .Pp
 179 The <type> argument specifies which action to take; it can be one of:
 180 .Bl -tag -width ".Dv return"
 181 .It Sy off
 182 Take no action (does not trigger fail point code)
 183 .It Sy return
 184 Trigger fail point code with specified argument
 185 .It Sy sleep
 186 Sleep the specified number of milliseconds
 187 .It Sy panic
 188 Panic
 189 .It Sy break
 190 Break into the debugger, or trap if there is no debugger support
 191 .It Sy print
 192 Print that the fail point executed
 193 .It Sy pause
 194 Threads sleep at the fail point until the fail point is set to
 195 .Sy off
 196 .It Sy yield
 197 Thread yields the cpu when the fail point is evaluated
 198 .It Sy delay
 199 Similar to sleep, but busy waits the cpu.
 200 (Useful in non-sleepable contexts.)
 201 .El
 202 .Pp
 203 The <pct>% and <cnt>* modifiers prior to <type> control when
 204 <type> is executed.
 205 The <pct>% form (e.g. "1.2%") can be used to specify a
 206 probability that <type> will execute.
 207 This is a decimal in the range (0, 100] which can specify up to
 208 1/10,000% precision.
 209 The <cnt>* form (e.g. "5*") can be used to specify the number of
 210 times <type> should be executed before this <term> is disabled.
 211 Only the last probability and the last count are used if multiple
 212 are specified, i.e. "1.2%2%" is the same as "2%".
 213 When both a probability and a count are specified, the probability
 214 is evaluated before the count, i.e. "2%5*" means "2% of the time,
 215 but only 5 times total".
 216 .Pp
 217 The operator -> can be used to express cascading terms.
 218 If you specify <term1>-><term2>, it means that if <term1> does not
 219 .Ql execute ,
 220 <term2> is evaluated.
 221 For the purpose of this operator, the
 222 .Fn return
 223 and
 224 .Fn print
 225 operators are the only types that cascade.
 226 A
 227 .Fn return
 228 term only cascades if the code executes, and a
 229 .Fn print
 230 term only cascades when passed a non-zero argument.
 231 A pid can optionally be specified.
 232 The fail point term is only executed when invoked by a process with a
 233 matching p_pid.
 234 .Sh EXAMPLES
 235 .Bl -tag -width Sy
 236 .It Sy sysctl debug.fail_point.foobar="2.1%return(5)"
 237 21/1000ths of the time, execute
 238 .Fa code
 239 with RETURN_VALUE set to 5.
 240 .It Sy sysctl debug.fail_point.foobar="2%return(5)->5%return(22)"
 241 2/100ths of the time, execute
 242 .Fa code
 243 with RETURN_VALUE set to 5.
 244 If that does not happen, 5% of the time execute
 245 .Fa code
 246 with RETURN_VALUE set to 22.
 247 .It Sy sysctl debug.fail_point.foobar="5*return(5)->0.1%return(22)"
 248 For 5 times, return 5.
 249 After that, 1/1000th of the time, return 22.
 250 .It Sy sysctl debug.fail_point.foobar="0.1%5*return(5)"
 251 Return 5 for 1 in 1000 executions, but only 5 times total.
 252 .It Sy sysctl debug.fail_point.foobar="1%*sleep(50)"
 253 1/100th of the time, sleep 50ms.
 254 .It Sy sysctl debug.fail_point.foobar="1*return(5)[pid 1234]"
 255 Return 5 once, when pid 1234 executes the fail point.
 256 .El
 257 .Sh AUTHORS
 258 .An -nosplit
 259 This manual page was written by
 260 .Pp
 261 .An Matthew Bryan Aq Mt matthew.bryan@isilon.com
 262 and
 263 .Pp
 264 .An Zach Loafman Aq Mt zml@FreeBSD.org .
 265 .Sh CAVEATS
 266 It is easy to shoot yourself in the foot by setting fail points too
 267 aggressively or setting too many in combination.
 268 For example, forcing
 269 .Fn malloc
 270 to fail consistently is potentially harmful to uptime.
 271 .Pp
 272 The
 273 .Fn sleep
 274 sysctl setting may not be appropriate in all situations.
 275 Currently,
 276 .Fn fail_point_eval
 277 does not verify whether the context is appropriate for calling
 278 .Fn msleep .
 279 You can force it to evaluate a
 280 .Sy sleep
 281 action as a
 282 .Sy delay
 283 action by specifying the
 284 .Sy FAIL_POINT_NONSLEEPABLE
 285 flag at the point the fail point is declared.