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