1 '\" te
   2 .\" Copyright (c) 2001 Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH TH_DEFINE 1M "April 9, 2016"
   7 .SH NAME
   8 th_define \- create fault injection test harness error specifications
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBth_define\fR [\fB-n\fR \fIname\fR \fB-i\fR \fIinstance\fR| \fB-P\fR \fIpath\fR] [\fB-a\fR \fIacc_types\fR]
  13      [\fB-r\fR \fIreg_number\fR] [\fB-l\fR \fIoffset\fR [\fIlength\fR]]
  14      [\fB-c\fR \fIcount\fR [\fIfailcount\fR]] [\fB-o\fR \fIoperator\fR [\fIoperand\fR]]
  15      [\fB-f\fR \fIacc_chk\fR] [\fB-w\fR \fImax_wait_period\fR [\fIreport_interval\fR]]
  16 .fi
  17 
  18 .LP
  19 .nf
  20 \fBor\fR
  21 .fi
  22 
  23 .LP
  24 .nf
  25 \fBth_define\fR [\fB-n\fR \fIname\fR \fB-i\fR \fIinstance\fR| \fB-P\fR \fIpath\fR]
  26      [\fB-a\fR log [\fIacc_types\fR] [\fB-r\fR \fIreg_number\fR] [\fB-l\fR \fIoffset\fR [\fIlength\fR]]]
  27      [\fB-c\fR \fIcount\fR [\fIfailcount\fR]] [\fB-s\fR \fIcollect_time\fR] [\fB-p\fR \fIpolicy\fR]
  28      [\fB-x\fR \fIflags\fR] [\fB-C\fR \fIcomment_string\fR]
  29      [\fB-e\fR \fIfixup_script\fR [\fIargs\fR]]
  30 .fi
  31 
  32 .LP
  33 .nf
  34 \fBor\fR
  35 .fi
  36 
  37 .LP
  38 .nf
  39 \fBth_define\fR [\fB-h\fR]
  40 .fi
  41 
  42 .SH DESCRIPTION
  43 .LP
  44 The \fBth_define\fR utility provides an interface to the \fBbus_ops\fR fault
  45 injection \fBbofi\fR device driver for defining error injection specifications
  46 (referred to as errdefs). An errdef corresponds to a specification of how to
  47 corrupt a device driver's accesses to its hardware. The command line arguments
  48 determine the precise nature of the fault to be injected. If the supplied
  49 arguments define a consistent errdef, the \fBth_define\fR process will store
  50 the errdef with the \fBbofi\fR driver and suspend itself until the criteria
  51 given by the errdef become satisfied (in practice, this will occur when the
  52 access counts go to zero).
  53 .sp
  54 .LP
  55 You use the \fBth_manage\fR(1M) command with the \fBstart\fR option to activate
  56 the resulting errdef. The effect of \fBth_manage\fR with the \fBstart\fR option
  57 is that the \fBbofi\fR driver acts upon the errdef by matching the number of
  58 hardware accesses\(emspecified in \fIcount\fR, that are of the type specified
  59 in \fIacc_types\fR, made by instance number \fIinstance\fR\(emof the driver
  60 whose name is \fIname\fR, (or by the driver instance specified by \fIpath\fR)
  61 to the register set (or DMA handle) specified by \fIreg_number\fR, that lie
  62 within the range \fIoffset\fR to \fIoffset\fR +\fI length\fR from the beginning
  63 of the register set or DMA handle. It then applies \fIoperator\fR and
  64 \fIoperand\fR to the next \fIfailcount\fR matching accesses.
  65 .sp
  66 .LP
  67 If \fIacc_types\fR includes \fBlog\fR, \fBth_define\fR runs in automatic test
  68 script generation mode, and a set of test scripts (written in the Korn shell)
  69 is created and placed in a sub-directory of the current directory with the name
  70 \fB\fI<driver>\fR\&.test.\fI<id>\fR\fR (for example, \fBglm.test.978177106\fR).
  71 A separate, executable script is generated for each access handle that matches
  72 the logging criteria. The log of accesses is placed at the top of each script
  73 as a record of the session. If the current directory is not writable, file
  74 output is written to standard output. The base name of each test file is the
  75 driver name, and the extension is a number that discriminates between different
  76 access handles. A control script (with the same name as the created test
  77 directory) is generated that will run all the test scripts sequentially.
  78 .sp
  79 .LP
  80 Executing the scripts will install, and then activate, the resulting error
  81 definitions. Error definitions are activated sequentially and the driver
  82 instance under test is taken offline and brought back online before each test
  83 (refer to the \fB-e\fR option for more information). By default, logging
  84 applies to all \fBPIO\fR accesses, all interrupts, and all DMA accesses to and
  85 from areas mapped for both reading and writing. You can constrain logging by
  86 specifying additional \fIacc_types\fR, \fIreg_number\fR, \fIoffset\fR and
  87 \fIlength\fR. Logging will continue for \fIcount\fR matching accesses, with an
  88 optional time limit of \fIcollect_time\fR seconds.
  89 .sp
  90 .LP
  91 Either the \fB-n\fR or \fB-P\fR option must be provided. The other options are
  92 optional. If an option (other than \fB-a\fR) is specified multiple times, only
  93 the final value for the option is used. If an option is not specified, its
  94 associated value is set to an appropriate default, which will provide maximal
  95 error coverage as described below.
  96 .SH OPTIONS
  97 .LP
  98 The following options are available:
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fB-n\fR \fIname\fR \fR
 103 .ad
 104 .sp .6
 105 .RS 4n
 106 Specify the name of the driver to test. (String)
 107 .RE
 108 
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fB-i\fR\fI instance\fR \fR
 113 .ad
 114 .sp .6
 115 .RS 4n
 116 Test only the specified driver instance (-1 matches all instances of driver).
 117 (Numeric)
 118 .RE
 119 
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fB-P\fR\fI path\fR \fR
 124 .ad
 125 .sp .6
 126 .RS 4n
 127 Specify the full device path of the driver to test. (String)
 128 .RE
 129 
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fB-r\fR \fIreg_number\fR \fR
 134 .ad
 135 .sp .6
 136 .RS 4n
 137 Test only the given register set or DMA handle (-1 matches all register sets
 138 and DMA handles). (Numeric)
 139 .RE
 140 
 141 .sp
 142 .ne 2
 143 .na
 144 \fB\fB-a\fR\fI acc_types\fR \fR
 145 .ad
 146 .sp .6
 147 .RS 4n
 148 Only the specified access types will be matched. Valid values for the
 149 \fIacc_types\fR argument are \fBlog\fR, \fBpio\fR, \fBpio_r\fR, \fBpio_w\fR,
 150 \fBdma\fR, \fBdma_r\fR, \fBdma_w\fR and \fBintr\fR. Multiple access types,
 151 separated by spaces, can be specified. The default is to match all hardware
 152 accesses.
 153 .sp
 154 If \fIacc_types\fR is set to \fBlog\fR, logging will match all \fBPIO\fR
 155 accesses, interrupts and DMA accesses to and from areas mapped for both reading
 156 and writing. \fBlog\fR can be combined with other \fIacc_types\fR, in which
 157 case the matching condition for logging will be restricted to the specified
 158 additional \fIacc_types\fR. Note that \fBdma_r\fR will match only DMA handles
 159 mapped for reading only; \fBdma_w\fR will match only DMA handles mapped for
 160 writing only; \fBdma\fR will match only DMA handles mapped for both reading and
 161 writing.
 162 .RE
 163 
 164 .sp
 165 .ne 2
 166 .na
 167 \fB\fB-l\fR \fIoffset \fR\fB[\fR\fIlength\fR\fB]\fR\fR
 168 .ad
 169 .sp .6
 170 .RS 4n
 171 Constrain the range of qualifying accesses. The \fIoffset\fR and \fIlength\fR
 172 arguments indicate that any access of the type specified with the \fB-a\fR
 173 option, to the register set or DMA handle specified with the \fB-r\fR option,
 174 lie at least \fIoffset\fR bytes into the register set or DMA handle and at most
 175 \fIoffset\fR + \fIlength\fR bytes into it. The default for \fIoffset\fR is 0.
 176 The default for \fIlength\fR is the maximum value that can be placed in an
 177 \fBoffset_t\fR C data type (see \fBtypes.h\fR). Negative values are converted
 178 into unsigned quantities. Thus, \fB\fR\fBth_define\fR\fB \fR\fB-l\fR 0 \fB-1\fR
 179 is maximal.
 180 .RE
 181 
 182 .sp
 183 .ne 2
 184 .na
 185 \fB\fB-c\fR \fIcount\fR\fB[\fR\fIfailcount\fR\fB]\fR \fR
 186 .ad
 187 .sp .6
 188 .RS 4n
 189 Wait for \fIcount\fR number of matching accesses, then apply an operator and
 190 operand (see the \fB-o\fR option) to the next \fIfailcount\fR number of
 191 matching accesses. If the access type (see the \fB-a\fR option) includes
 192 logging, the number of logged accesses is given by \fIcount\fR +
 193 \fIfailcount\fR - 1. The -1 is required because the last access coincides with
 194 the first faulting access.
 195 .sp
 196 Note that access logging may be combined with error injection if
 197 \fIfailcount\fR and \fIoperator\fR are nonzero and if the access type includes
 198 logging and any of the other access types (\fBpio\fR, \fBdma\fR and \fBintr\fR)
 199 See the description of access types in the definition of the \fB-a\fR option,
 200 above.
 201 .sp
 202 When the \fIcount\fR and \fIfailcount\fR fields reach zero, the status of the
 203 errdef is reported to standard output. When all active errdefs created by the
 204 \fBth_define\fR process complete, the process exits. If \fIacc_types\fR
 205 includes \fBlog\fR, \fIcount\fR determines how many accesses to log. If
 206 \fIcount\fR is not specified, a default value is used. If \fIfailcount\fR is
 207 set in this mode, it will simply increase the number of accesses logged by a
 208 further \fIfailcount\fR - 1.
 209 .RE
 210 
 211 .sp
 212 .ne 2
 213 .na
 214 \fB\fB-o\fR\fI operator \fR\fB[\fR\fIoperand\fR\fB]\fR \fR
 215 .ad
 216 .sp .6
 217 .RS 4n
 218 For qualifying PIO read and write accesses, the value read from or written to
 219 the hardware is corrupted according to the value of \fIoperator\fR:
 220 .sp
 221 .ne 2
 222 .na
 223 \fB\fBEQ\fR\fR
 224 .ad
 225 .RS 7n
 226 \fIoperand\fR is returned to the driver.
 227 .RE
 228 
 229 .sp
 230 .ne 2
 231 .na
 232 \fB\fBOR\fR\fR
 233 .ad
 234 .RS 7n
 235 \fIoperand\fR is bitwise ORed with the real value.
 236 .RE
 237 
 238 .sp
 239 .ne 2
 240 .na
 241 \fB\fBAND\fR\fR
 242 .ad
 243 .RS 7n
 244 \fIoperand\fR is bitwise ANDed with the real value.
 245 .RE
 246 
 247 .sp
 248 .ne 2
 249 .na
 250 \fB\fBXOR\fR\fR
 251 .ad
 252 .RS 7n
 253 \fIoperand\fR is bitwise XORed with the real value.
 254 .RE
 255 
 256 For PIO write accesses, the following operator is allowed:
 257 .sp
 258 .ne 2
 259 .na
 260 \fB\fBNO\fR\fR
 261 .ad
 262 .RS 6n
 263 Simply ignore the driver's attempt to write to the hardware.
 264 .RE
 265 
 266 Note that a driver performs PIO via the \fBddi_get\fIX\fR()\fR,
 267 \fBddi_put\fIX\fR()\fR, \fBddi_rep_get\fIX\fR()\fR and
 268 \fBddi_rep_put\fIX\fR()\fR routines (where \fIX\fR is 8, 16, 32 or 64).
 269 Accesses made using \fBddi_get\fIX\fR()\fR and \fBddi_put\fIX\fR()\fR are
 270 treated as a single access, whereas an access made using the
 271 \fBddi_rep_*\fR(9F) routines are broken down into their respective number of
 272 accesses, as given by the \fIrepcount\fR parameter to these DDI calls. If the
 273 access is performed via a DMA handle, \fIoperator\fR and \fIvalue\fR are
 274 applied to every access that comprises the DMA request. If interference with
 275 interrupts has been requested then the operator may take any of the following
 276 values:
 277 .sp
 278 .ne 2
 279 .na
 280 \fB\fBDELAY\fR\fR
 281 .ad
 282 .RS 9n
 283 After \fIcount\fR accesses (see the \fB-c\fR option), delay delivery of the
 284 next \fIfailcount\fR number of interrupts for \fIoperand\fR number of
 285 microseconds.
 286 .RE
 287 
 288 .sp
 289 .ne 2
 290 .na
 291 \fB\fBLOSE\fR\fR
 292 .ad
 293 .RS 9n
 294 After \fIcount\fR number of interrupts, fail to deliver the next
 295 \fIfailcount\fR number of real interrupts to the driver.
 296 .RE
 297 
 298 .sp
 299 .ne 2
 300 .na
 301 \fB\fBEXTRA\fR\fR
 302 .ad
 303 .RS 9n
 304 After \fIcount\fR number of interrupts, start delivering \fIoperand\fR number
 305 of extra interrupts for the next \fIfailcount\fR number of real interrupts.
 306 .RE
 307 
 308 The default value for \fIoperand\fR and \fIoperator\fR is to corrupt the data
 309 access by flipping each bit (XOR with -1).
 310 .RE
 311 
 312 .sp
 313 .ne 2
 314 .na
 315 \fB\fB-f\fR \fIacc_chk\fR\fR
 316 .ad
 317 .sp .6
 318 .RS 4n
 319 If the \fIacc_chk\fR parameter is set to 1 or \fBpio\fR, then the driver's
 320 calls to \fBddi_check_acc_handle\fR(9F) return \fBDDI_FAILURE\fR when the
 321 access count goes to 1. If the \fIacc_chk\fR parameter is set to 2 or
 322 \fBdma\fR, then the driver's calls to \fBddi_check_dma_handle\fR(9F) return
 323 \fBDDI_FAILURE\fR when the access count goes to 1.
 324 .RE
 325 
 326 .sp
 327 .ne 2
 328 .na
 329 \fB\fB-w\fR \fImax_wait_period\fR\fB [\fR\fIreport_interval\fR\fB]\fR \fR
 330 .ad
 331 .sp .6
 332 .RS 4n
 333 Constrain the period for which an error definition will remain active. The
 334 option applies only to non-logging errdefs. If an error definition remains
 335 active for \fImax_wait_period\fR seconds, the test will be aborted. If
 336 \fIreport_interval\fR is set to a nonzero value, the current status of the
 337 error definition is reported to standard output every \fIreport_interval\fR
 338 seconds. The default value is zero. The status of the errdef is reported in
 339 parsable format (eight fields, each separated by a colon (\fB:\fR) character,
 340 the last of which is a string enclosed by double quotes and the remaining seven
 341 fields are integers):
 342 .sp
 343 \fIft\fR:\fImt\fR:\fIac\fR:\fIfc\fR:\fIchk\fR:\fIec\fR:\fIs\fR:\fI"message"\fR
 344 which are defined as follows:
 345 .sp
 346 .ne 2
 347 .na
 348 \fB\fIft\fR\fR
 349 .ad
 350 .RS 13n
 351 The UTC time when the fault was injected.
 352 .RE
 353 
 354 .sp
 355 .ne 2
 356 .na
 357 \fB\fImt\fR\fR
 358 .ad
 359 .RS 13n
 360 The UTC time when the driver reported the fault.
 361 .RE
 362 
 363 .sp
 364 .ne 2
 365 .na
 366 \fB\fIac\fR\fR
 367 .ad
 368 .RS 13n
 369 The number of remaining non-faulting accesses.
 370 .RE
 371 
 372 .sp
 373 .ne 2
 374 .na
 375 \fB\fIfc\fR\fR
 376 .ad
 377 .RS 13n
 378 The number of remaining faulting accesses.
 379 .RE
 380 
 381 .sp
 382 .ne 2
 383 .na
 384 \fB\fIchk\fR\fR
 385 .ad
 386 .RS 13n
 387 The value of the \fIacc_chk\fR field of the errdef.
 388 .RE
 389 
 390 .sp
 391 .ne 2
 392 .na
 393 \fB\fIec\fR\fR
 394 .ad
 395 .RS 13n
 396 The number of fault reports issued by the driver against this errdef (\fImt\fR
 397 holds the time of the initial report).
 398 .RE
 399 
 400 .sp
 401 .ne 2
 402 .na
 403 \fB\fIs\fR\fR
 404 .ad
 405 .RS 13n
 406 The severity level reported by the driver.
 407 .RE
 408 
 409 .sp
 410 .ne 2
 411 .na
 412 \fB\fI"message"\fR\fR
 413 .ad
 414 .RS 13n
 415 Textual reason why the driver has reported a fault.
 416 .RE
 417 
 418 .RE
 419 
 420 .sp
 421 .ne 2
 422 .na
 423 \fB\fB-h\fR\fR
 424 .ad
 425 .sp .6
 426 .RS 4n
 427 Display the command usage string.
 428 .RE
 429 
 430 .sp
 431 .ne 2
 432 .na
 433 \fB\fB-s\fR \fIcollect_time\fR \fR
 434 .ad
 435 .sp .6
 436 .RS 4n
 437 If \fIacc_types\fR is given with the \fB-a\fR option and includes \fBlog\fR,
 438 the errdef will log accesses for \fIcollect_time\fR seconds (the default is to
 439 log until the log becomes full). Note that, if the errdef specification matches
 440 multiple driver handles, multiple logging errdefs are registered with the
 441 \fBbofi\fR driver and logging terminates when all logs become full or when
 442 \fIcollect_time\fR expires or when the associated errdefs are cleared. The
 443 current state of the log can be checked with the \fBth_manage\fR(1M) command,
 444 using the \fBbroadcast\fR parameter. A log can be terminated by running
 445 \fBth_manage\fR(1M) with the \fBclear_errdefs\fR option or by sending a
 446 \fBSIGALRM\fR signal to the \fBth_define\fR process. See \fBalarm\fR(2) for the
 447 semantics of \fBSIGALRM\fR.
 448 .RE
 449 
 450 .sp
 451 .ne 2
 452 .na
 453 \fB\fB-p\fR \fIpolicy\fR\fR
 454 .ad
 455 .sp .6
 456 .RS 4n
 457 Applicable when the \fIacc_types\fR option includes \fBlog\fR. The parameter
 458 modifies the policy used for converting from logged accesses to errdefs. All
 459 policies are inclusive:
 460 .RS +4
 461 .TP
 462 .ie t \(bu
 463 .el o
 464 Use \fBrare\fR to bias error definitions toward rare accesses (default).
 465 .RE
 466 .RS +4
 467 .TP
 468 .ie t \(bu
 469 .el o
 470 Use \fBoperator\fR to produce a separate error definition for each operator
 471 type (default).
 472 .RE
 473 .RS +4
 474 .TP
 475 .ie t \(bu
 476 .el o
 477 Use \fBcommon\fR to bias error definitions toward common accesses.
 478 .RE
 479 .RS +4
 480 .TP
 481 .ie t \(bu
 482 .el o
 483 Use \fBmedian\fR to bias error definitions toward median accesses.
 484 .RE
 485 .RS +4
 486 .TP
 487 .ie t \(bu
 488 .el o
 489 Use \fBmaximal\fR to produce multiple error definitions for duplicate accesses.
 490 .RE
 491 .RS +4
 492 .TP
 493 .ie t \(bu
 494 .el o
 495 Use \fBunbiased\fR to create unbiased error definitions.
 496 .RE
 497 .RS +4
 498 .TP
 499 .ie t \(bu
 500 .el o
 501 Use \fBonebyte\fR, \fBtwobyte\fR, \fBfourbyte\fR, or \fBeightbyte\fR to select
 502 errdefs corresponding to 1, 2, 4 or 8 byte accesses (if chosen, the
 503 \fB-x\fR\fBr\fR option is enforced in order to ensure that \fBddi_rep_*()\fR
 504 calls are decomposed into \fBmultiple single accesses\fR).
 505 .RE
 506 .RS +4
 507 .TP
 508 .ie t \(bu
 509 .el o
 510 Use \fBmultibyte\fR to create error definitions for multibyte accesses
 511 performed using \fBddi_rep_get*()\fR and \fBddi_rep_put*()\fR.
 512 .RE
 513 Policies can be combined by adding together these options. See the NOTES
 514 section for further information.
 515 .RE
 516 
 517 .sp
 518 .ne 2
 519 .na
 520 \fB\fB-x\fR \fIflags\fR\fR
 521 .ad
 522 .sp .6
 523 .RS 4n
 524 Applicable when the \fIacc_types\fR option includes \fBlog\fR. The \fIflags\fR
 525 parameter modifies the way in which the \fBbofi\fR driver logs accesses. It is
 526 specified as a string containing any combination of the following letters:
 527 .sp
 528 .ne 2
 529 .na
 530 \fB\fBw\fR\fR
 531 .ad
 532 .RS 5n
 533 Continuous logging (that is, the log will wrap when full).
 534 .RE
 535 
 536 .sp
 537 .ne 2
 538 .na
 539 \fB\fBt\fR\fR
 540 .ad
 541 .RS 5n
 542 Timestamp each log entry (access times are in seconds).
 543 .RE
 544 
 545 .sp
 546 .ne 2
 547 .na
 548 \fB\fBr\fR\fR
 549 .ad
 550 .RS 5n
 551 Log repeated I/O as individual accesses (for example, a \fBddi_rep_get16\fR(9F)
 552 call which has a repcount of \fIN\fR is logged \fIN\fR times with each
 553 transaction logged as size 2 bytes. Without this option, the default logging
 554 behavior is to log this access once only, with a transaction size of twice the
 555 \fIrepcount\fR).
 556 .RE
 557 
 558 .RE
 559 
 560 .sp
 561 .ne 2
 562 .na
 563 \fB\fB-C\fR \fIcomment_string\fR\fR
 564 .ad
 565 .sp .6
 566 .RS 4n
 567 Applicable when the \fIacc_types\fR option includes \fBlog\fR. It provides a
 568 comment string to be placed in any generated test scripts. The string must be
 569 enclosed in double quotes.
 570 .RE
 571 
 572 .sp
 573 .ne 2
 574 .na
 575 \fB\fB-e\fR \fIfixup_script\fR \fB[\fR\fIargs\fR\fB]\fR \fR
 576 .ad
 577 .sp .6
 578 .RS 4n
 579 Applicable when the \fIacc_types\fR option includes \fBlog\fR. The output of a
 580 logging errdefs is to generate a test script for each driver access handle. Use
 581 this option to embed a command in the resulting script before the errors are
 582 injected. The generated test scripts will take an instance offline and bring it
 583 back online before injecting errors in order to bring the instance into a known
 584 fault-free state. The executable \fIfixup_script\fR will be called twice with
 585 the set of optional \fIargs\fR\(em once just before the instance is taken
 586 offline and again after the instance has been brought online. The following
 587 variables are passed into the environment of the called executable:
 588 .sp
 589 .ne 2
 590 .na
 591 \fB\fBDRIVER_PATH\fR\fR
 592 .ad
 593 .RS 22n
 594 Identifies the device path of the instance.
 595 .RE
 596 
 597 .sp
 598 .ne 2
 599 .na
 600 \fB\fBDRIVER_INSTANCE\fR\fR
 601 .ad
 602 .RS 22n
 603 Identifies the instance number of the device.
 604 .RE
 605 
 606 .sp
 607 .ne 2
 608 .na
 609 \fB\fBDRIVER_UNCONFIGURE\fR\fR
 610 .ad
 611 .RS 22n
 612 Has the value 1 when the instance is about to be taken offline.
 613 .RE
 614 
 615 .sp
 616 .ne 2
 617 .na
 618 \fB\fBDRIVER_CONFIGURE\fR\fR
 619 .ad
 620 .RS 22n
 621 Has the value 1 when the instance has just been brought online.
 622 .RE
 623 
 624 Typically, the executable ensures that the device under test is in a suitable
 625 state to be taken offline (unconfigured) or in a suitable state for error
 626 injection (for example configured, error free and servicing a workload). A
 627 minimal script for a network driver could be:
 628 .sp
 629 .in +2
 630 .nf
 631 #!/bin/ksh
 632 
 633 driver=xyznetdriver
 634 ifnum=$driver$DRIVER_INSTANCE
 635 
 636 if [[ $DRIVER_CONFIGURE = 1 ]]; then
 637         ifconfig $ifnum plumb
 638         ifconfig $ifnum ...
 639         ifworkload start $ifnum
 640 elif [[ $DRIVER_UNCONFIGURE = 1 ]]; then
 641         ifworkload stop $ifnum
 642         ifconfig $ifnum down
 643         ifconfig $ifnum unplumb
 644 fi
 645 exit $?
 646 .fi
 647 .in -2
 648 .sp
 649 
 650 The \fB-e\fR option must be the last option on the command line.
 651 .RE
 652 
 653 .sp
 654 .LP
 655 If the \fB-a\fR \fBlog\fR option is selected but the \fB-e\fR option is not
 656 given, a default script is used. This script repeatedly attempts to detach and
 657 then re-attach the device instance under test.
 658 .SH EXAMPLES
 659 .SS "Examples of Error Definitions"
 660 .LP
 661 \fBth_define -n foo -i 1 -a log\fR
 662 .sp
 663 .LP
 664 Logs all accesses to all handles used by instance 1 of the \fBfoo\fR driver
 665 while running the default workload (attaching and detaching the instance). Then
 666 generates a set of test scripts to inject appropriate errdefs while running
 667 that default workload.
 668 .sp
 669 .LP
 670 \fBth_define -n foo -i 1 -a log pio\fR
 671 .sp
 672 .LP
 673 Logs PIO accesses to each PIO handle used by instance 1 of the \fBfoo\fR driver
 674 while running the default workload (attaching and detaching the instance). Then
 675 generates a set of test scripts to inject appropriate errdefs while running
 676 that default workload.
 677 .sp
 678 .LP
 679 \fBth_define -n foo -i 1 -p onebyte median -e fixup arg -now\fR
 680 .sp
 681 .LP
 682 Logs all accesses to all handles used by instance 1 of the \fBfoo\fR driver
 683 while running the workload defined in the fixup script \fBfixup\fR with
 684 arguments \fBarg\fR and \fB-now\fR. Then generates a set of test scripts to
 685 inject appropriate errdefs while running that workload. The resulting error
 686 definitions are requested to focus upon single byte accesses to locations that
 687 are accessed a \fBmedian\fR number of times with respect to frequency of access
 688 to I/O addresses.
 689 .sp
 690 .LP
 691 \fBth_define -n se -l 0x20 1 -a pio_r -o OR 0x4 -c 10 1000\fR
 692 .sp
 693 .LP
 694 Simulates a stuck serial chip command by forcing 1000 consecutive read accesses
 695 made by any instance of the \fBse\fR driver to its command status register,
 696 thereby returning status busy.
 697 .sp
 698 .LP
 699 \fBth_define -n foo -i 3 -r 1 -a pio_r -c 0 1 -f 1 -o OR 0x100\fR
 700 .sp
 701 .LP
 702 Causes 0x100 to be ORed into the next physical I/O read access from any
 703 register in register set 1 of instance 3 of the \fBfoo\fR driver. Subsequent
 704 calls in the driver to \fBddi_check_acc_handle()\fR return \fBDDI_FAILURE\fR.
 705 .sp
 706 .LP
 707 \fBth_define -n foo -i 3 -r 1 -a pio_r -c 0 1 -o OR 0x0\fR
 708 .sp
 709 .LP
 710 Causes 0x0 to be ORed into the next physical I/O read access from any register
 711 in register set 1 of instance 3 of the \fBfoo\fR driver. This is of course a
 712 no-op.
 713 .sp
 714 .LP
 715 \fBth_define -n foo -i 3 -r 1 -l 0x8100 1 -a pio_r -c 0 10 -o EQ 0x70003\fR
 716 .sp
 717 .LP
 718 Causes the next ten next physical I/O reads from the register at offset 0x8100
 719 in register set 1 of instance 3 of the \fBfoo\fR driver to return 0x70003.
 720 .sp
 721 .LP
 722 \fBth_define -n foo -i 3 -r 1 -l 0x8100 1 -a pio_w -c 100 3 -o AND
 723 0xffffffffffffefff\fR
 724 .sp
 725 .LP
 726 The next 100 physical I/O writes to the register at offset 0x8100 in register
 727 set 1 of instance 3 of the \fBfoo\fR driver take place as normal. However, on
 728 each of the three subsequent accesses, the 0x1000 bit will be cleared.
 729 .sp
 730 .LP
 731 \fBth_define -n foo -i 3 -r 1 -l 0x8100 0x10 -a pio_r -c 0 1 -f 1 -o XOR 7\fR
 732 .sp
 733 .LP
 734 Causes the bottom three bits to have their values toggled for the next physical
 735 I/O read access to registers with offsets in the range 0x8100 to 0x8110 in
 736 register set 1 of instance 3 of the \fBfoo\fR driver. Subsequent calls in the
 737 driver to \fBddi_check_acc_handle()\fR return \fBDDI_FAILURE\fR.
 738 .sp
 739 .LP
 740 \fBth_define -n foo -i 3 -a pio_w -c 0 1 -o NO 0\fR
 741 .sp
 742 .LP
 743 Prevents the next physical I/O write access to any register in any register set
 744 of instance 3 of the \fBfoo\fR driver from going out on the bus.
 745 .sp
 746 .LP
 747 \fBth_define -n foo -i 3 -l 0 8192 -a dma_r -c 0 1 -o OR 7\fR
 748 .sp
 749 .LP
 750 Causes 0x7 to be ORed into each \fBlong long\fR in the first 8192 bytes of the
 751 next DMA read, using any DMA handle for instance 3 of the \fBfoo\fR driver.
 752 .sp
 753 .LP
 754 \fBth_define -n foo -i 3 -r 2 -l 0 8 -a dma_r -c 0 1 -o OR
 755 0x7070707070707070\fR
 756 .sp
 757 .LP
 758 Causes 0x70 to be ORed into each byte of the first \fBlong long\fR of the next
 759 DMA read, using the DMA handle with sequential allocation number 2 for instance
 760 3 of the \fBfoo\fR driver.
 761 .sp
 762 .LP
 763 \fBth_define -n foo -i 3 -l 256 256 -a dma_w -c 0 1 -f 2 -o OR 7\fR
 764 .sp
 765 .LP
 766 Causes 0x7 to be ORed into each \fBlong long\fR in the range from offset 256 to
 767 offset 512 of the next DMA write, using any DMA handle for instance 3 of the
 768 \fBfoo\fR driver. Subsequent calls in the driver to
 769 \fBddi_check_dma_handle()\fR return \fBDDI_FAILURE\fR.
 770 .sp
 771 .LP
 772 \fBth_define -n foo -i 3 -r 0 -l 0 8 -a dma_w -c 100 3 -o AND
 773 0xffffffffffffefff\fR
 774 .sp
 775 .LP
 776 The next 100 DMA writes using the DMA handle with sequential allocation number
 777 0 for instance 3 of the \fBfoo\fR driver take place as normal. However, on each
 778 of the three subsequent accesses, the 0x1000 bit will be cleared in the first
 779 \fBlong long\fR of the transfer.
 780 .sp
 781 .LP
 782 \fBth_define -n foo -i 3 -a intr -c 0 6 -o LOSE 0\fR
 783 .sp
 784 .LP
 785 Causes the next six interrupts for instance 3 of the \fBfoo\fR driver to be
 786 lost.
 787 .sp
 788 .LP
 789 \fBth_define -n foo -i 3 -a intr -c 30 1 -o EXTRA 10\fR
 790 .sp
 791 .LP
 792 When the thirty-first subsequent interrupt for instance 3 of the \fBfoo\fR
 793 driver occurs, a further ten interrupts are also generated.
 794 .sp
 795 .LP
 796 \fBth_define -n foo -i 3 -a intr -c 0 1 -o DELAY 1024\fR
 797 .sp
 798 .LP
 799 Causes the next interrupt for instance 3 of the \fBfoo\fR driver to be delayed
 800 by 1024 microseconds.
 801 .SH NOTES
 802 .LP
 803 The policy option in the \fBth_define\fR \fB-p\fR syntax determines how a set
 804 of logged accesses will be converted into the set of error definitions. Each
 805 logged access will be matched against the chosen policies to determine whether
 806 an error definition should be created based on the access.
 807 .sp
 808 .LP
 809 Any number of policy options can be combined to modify the generated error
 810 definitions.
 811 .SS "Bytewise Policies"
 812 .LP
 813 These select particular I/O transfer sizes. Specifying a byte policy will
 814 exclude other byte policies that have not been chosen. If none of the byte type
 815 policies is selected, all transfer sizes are treated equally. Otherwise, only
 816 those specified transfer sizes will be selected.
 817 .sp
 818 .ne 2
 819 .na
 820 \fB\fBonebyte\fR\fR
 821 .ad
 822 .RS 13n
 823 Create errdefs for one byte accesses (\fBddi_get8()\fR)
 824 .RE
 825 
 826 .sp
 827 .ne 2
 828 .na
 829 \fB\fBtwobyte\fR\fR
 830 .ad
 831 .RS 13n
 832 Create errdefs for two byte accesses (\fBddi_get16()\fR)
 833 .RE
 834 
 835 .sp
 836 .ne 2
 837 .na
 838 \fB\fBfourbyte\fR\fR
 839 .ad
 840 .RS 13n
 841 Create errdefs for four byte accesses (\fBddi_get32()\fR)
 842 .RE
 843 
 844 .sp
 845 .ne 2
 846 .na
 847 \fB\fBeightbyte\fR\fR
 848 .ad
 849 .RS 13n
 850 Create errdefs for eight byte accesses (\fBddi_get64()\fR)
 851 .RE
 852 
 853 .sp
 854 .ne 2
 855 .na
 856 \fB\fBmultibyte\fR\fR
 857 .ad
 858 .RS 13n
 859 Create errdefs for repeated byte accesses (\fBddi_rep_get*()\fR)
 860 .RE
 861 
 862 .SS "Frequency of Access Policies"
 863 .LP
 864 The frequency of access to a location is determined according to the access
 865 type, location and transfer size (for example, a two-byte read access to
 866 address A is considered distinct from a four-byte read access to address A).
 867 The algorithm is to count the number of accesses (of a given type and size) to
 868 a given location, and find the locations that were most and least accessed (let
 869 \fImaxa\fR and \fImina\fR be the number of times these locations were accessed,
 870 and \fImean\fR the total number of accesses divided by total number of
 871 locations that were accessed). Then a rare access is a location that was
 872 accessed less than
 873 .sp
 874 .LP
 875 \fI(mean - mina) / 3 + mina\fR
 876 .sp
 877 .LP
 878 times. Similarly for the definition of common accesses:
 879 .sp
 880 .LP
 881 \fImaxa - (maxa - mean) / 3\fR
 882 .sp
 883 .LP
 884 A location whose access patterns lies within these cutoffs is regarded as a
 885 location that is accessed with median frequency.
 886 .sp
 887 .ne 2
 888 .na
 889 \fB\fBrare\fR\fR
 890 .ad
 891 .RS 10n
 892 Create errdefs for locations that are rarely accessed.
 893 .RE
 894 
 895 .sp
 896 .ne 2
 897 .na
 898 \fB\fBcommon\fR\fR
 899 .ad
 900 .RS 10n
 901 Create errdefs for locations that are commonly accessed.
 902 .RE
 903 
 904 .sp
 905 .ne 2
 906 .na
 907 \fB\fBmedian\fR\fR
 908 .ad
 909 .RS 10n
 910 Create errdefs for locations that are accessed a median frequency.
 911 .RE
 912 
 913 .SS "Policies for Minimizing errdefs"
 914 .LP
 915 If a transaction is duplicated, either a single or multiple errdefs will be
 916 written to the test scripts, depending upon the following two policies:
 917 .sp
 918 .ne 2
 919 .na
 920 \fB\fBmaximal\fR\fR
 921 .ad
 922 .RS 13n
 923 Create multiple errdefs for locations that are repeatedly accessed.
 924 .RE
 925 
 926 .sp
 927 .ne 2
 928 .na
 929 \fB\fBunbiased\fR\fR
 930 .ad
 931 .RS 13n
 932 Create a single errdef for locations that are repeatedly accessed.
 933 .RE
 934 
 935 .sp
 936 .ne 2
 937 .na
 938 \fB\fBoperators\fR\fR
 939 .ad
 940 .RS 13n
 941 For each location, a default operator and operand is typically applied. For
 942 maximal test coverage, this default may be modified using the \fBoperators\fR
 943 policy so that a separate errdef is created for each of the possible corruption
 944 operators.
 945 .RE
 946 
 947 .SH SEE ALSO
 948 .LP
 949 \fBkill\fR(1), \fBth_manage\fR(1M), \fBalarm\fR(2),
 950 \fBddi_check_acc_handle\fR(9F), \fBddi_check_dma_handle\fR(9F)