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