usr/src/man/man7d/ssd.7d

   1 '\" te
   2 .\" Copyright (c) 2008, 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 SSD 7D "Aug 9, 2008"
   7 .SH NAME
   8 ssd \- Fibre Channel Arbitrated Loop disk device driver
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBssd@\fR\fIport\fR\fB,\fR\fItarget\fR\fB:\fR\fIpartition\fR
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18  The \fBssd\fR driver supports Fibre Channel disk devices.
  19 .sp
  20 .LP
  21 The specific type of each disk is determined by the \fBSCSI\fR inquiry command
  22 and reading the volume label stored on block 0 of the drive. The volume label
  23 describes the disk geometry and partitioning; it must be present or the disk
  24 cannot be mounted by the system.
  25 .sp
  26 .LP
  27 The block-files access the disk using the system's normal buffering mechanism
  28 and are read and written without regard to physical disk records. A "raw"
  29 interface provides for direct transmission between the disk and the read or
  30 write buffer. A single read or write call usually results in one I/O operation;
  31 raw I/O is therefore more efficient when many bytes are transmitted. Block file
  32 names are found in \fB/dev/dsk\fR; the names of the raw files are found in
  33 \fB/dev/rdsk\fR.
  34 .sp
  35 .LP
  36 I/O requests (such as \fBlseek\fR(2)) to the \fBSCSI\fR disk must have an
  37 offset that is a multiple of 512 bytes (\fBDEV_BSIZE\fR), or the driver returns
  38 an \fBEINVAL\fR error. If the transfer length is not a multiple of 512 bytes,
  39 the transfer count is rounded up by the driver.
  40 .sp
  41 .LP
  42 Partition 0 is normally used for the root file system on a disk, with partition
  43 1 as a paging area (for example, \fBswap\fR). Partition 2 is used to back up
  44 the entire disk. Partition 2 normally maps the entire disk and may also be used
  45 as the mount point for secondary disks in the system. The rest of the disk is
  46 normally partition 6. For the primary disk, the user file system is located
  47 here.
  48 .sp
  49 .LP
  50 The device has associated error statistics. These must include counters for
  51 hard errors, soft errors and transport errors. Other data may be implemented as
  52 required.
  53 .SH DEVICE STATISTICS SUPPORT
  54 .sp
  55 .LP
  56 The device maintains I/O statistics for the device and for partitions allocated
  57 for that device. For each device/partition, the  driver accumulates reads,
  58 writes, bytes read, and bytes written. The driver also initiates hi-resolution
  59 time stamps at queue entry and exit points to enable monitoring of residence
  60 time and cumulative residence-length product for each queue.
  61 .sp
  62 .LP
  63 Not all device drivers make per-partition IO statistics available for
  64 reporting. \fBssd\fR and \fBsd\fR(7D) per-partition statistics are  enabled by
  65 default but may be disabled in their configuration files.
  66 .SH IOCTLS
  67 .sp
  68 .LP
  69 Refer to  \fBdkio\fR(7I).
  70 .SH ERRORS
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fBEACCES\fR\fR
  75 .ad
  76 .RS 10n
  77 Permission denied.
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fBEBUSY\fR\fR
  84 .ad
  85 .RS 10n
  86 The partition was opened exclusively by another thread.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fBEFAULT\fR\fR
  93 .ad
  94 .RS 10n
  95 The argument was a bad address.
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBEINVAL\fR\fR
 102 .ad
 103 .RS 10n
 104 Invalid argument.
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBEIO\fR\fR
 111 .ad
 112 .RS 10n
 113 An I/O error occurred.
 114 .RE
 115
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBENOTTY\fR\fR
 120 .ad
 121 .RS 10n
 122 The device does not support the requested ioctl function.
 123 .RE
 124
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fBENXIO\fR\fR
 129 .ad
 130 .RS 10n
 131 When returned during  \fBopen\fR(2), this error indicates the device does not
 132 exist.
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fBEROFS\fR\fR
 139 .ad
 140 .RS 10n
 141 The device is a read-only device.
 142 .RE
 143
 144 .SH CONFIGURATION
 145 .sp
 146 .LP
 147 You configure the \fBssd\fR driver by defining  properties in the
 148 \fBssd.conf\fR file. The \fBssd\fR driver supports the following properties:
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fBenable-partition-kstats\fR\fR
 153 .ad
 154 .RS 27n
 155 The default value is 1, which causes partition IO statistics to be maintained.
 156 Set this value to zero to prevent the driver from recording partition
 157 statistics. This slightly reduces the CPU overhead for IO, mimimizes the amount
 158 of \fBsar\fR(1) data collected and makes these statistics unavailable for
 159 reporting by \fBiostat\fR(1M) even though the \fB-p\fR/\fB-P\fR option is
 160 specified.  Regardless of this setting, disk IO statistics are always
 161 maintained.
 162 .RE
 163
 164 .sp
 165 .LP
 166 In addition to the above properties, some device-specific tunables can be
 167 configured in \fBssd.conf\fR using the 'ssd-config-list' global property. The
 168 value of this property is a list of duplets. The formal syntax is:
 169 .sp
 170 .in +2
 171 .nf
 172 ssd-config-list =       <duplet> [, <duplet> ]* ;
 173
 174 where
 175
 176 <duplet>:=        "<vid+pid>" , "<tunable-list>"
 177
 178 and
 179
 180 <tunable-list>:=   <tunable>  [, <tunable> ]*;
 181 <tunable> =        <name> : <value>
 182
 183 The <vid+pid> is the string that is returned by the target device
 184 on a SCSI inquiry command.
 185
 186 The <tunable-list> contains one or more tunables to apply to
 187 all target devices with the specified <vid+pid>.
 188
 189 Each <tunable> is a <name> : <value> pair. Supported
 190 tunable names are:
 191
 192    delay-busy:  when busy, nsecs of delay before retry.
 193
 194    retries-timeout:     retries to perform on an IO timeout.
 195 .fi
 196 .in -2
 197
 198 .SH EXAMPLES
 199 .sp
 200 .in +2
 201 .nf
 202 The following is an example of a global ssd-config-list property:
 203
 204    ssd-config-list =
 205       "SUN     T4", "delay-busy:600, retries-timeout:6",
 206       "SUN     StorEdge_3510", "retries-timeout:3";
 207 .fi
 208 .in -2
 209
 210 .SH FILES
 211 .sp
 212 .ne 2
 213 .na
 214 \fBssd.conf\fR
 215 .ad
 216 .RS 22n
 217 Driver configuration file
 218 .RE
 219
 220 .sp
 221 .ne 2
 222 .na
 223 \fB/dev/dsk/c\fIn\fR\fBt\fR\fIn\fR\fBd\fR\fIn\fR\fBs\fR\fIn\fR\fR
 224 .ad
 225 .RS 22n
 226 block files
 227 .RE
 228
 229 .sp
 230 .ne 2
 231 .na
 232 \fB/dev/rdsk/c\fIn\fR\fBt\fR\fIn\fR\fBd\fR\fIn\fR\fBs\fR\fIn\fR\fR
 233 .ad
 234 .RS 22n
 235 raw files
 236 .RE
 237
 238 .sp
 239 .ne 2
 240 .na
 241 \fBc\fIn\fR\fR
 242 .ad
 243 .RS 22n
 244 is the controller number on the system.
 245 .RE
 246
 247 .sp
 248 .ne 2
 249 .na
 250 \fBt\fIn\fR\fR
 251 .ad
 252 .RS 22n
 253 7-bit disk loop identifier, such as switch setting
 254 .RE
 255
 256 .sp
 257 .ne 2
 258 .na
 259 \fBd\fIn\fR\fR
 260 .ad
 261 .RS 22n
 262 SCSI lun  \fIn\fR
 263 .RE
 264
 265 .sp
 266 .ne 2
 267 .na
 268 \fB\fBs\fR\fIn\fR\fR
 269 .ad
 270 .RS 22n
 271 partition \fIn\fR (0-7)
 272 .RE
 273
 274 .SH SEE ALSO
 275 .sp
 276 .LP
 277 \fBsar\fR(1), \fBformat\fR(1M), \fBiostat\fR(1M), \fBioctl\fR(2),
 278 \fBlseek\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2),
 279 \fBscsi\fR(4), \fBdriver.conf\fR(4), \fBcdio\fR(7I), \fBdkio\fR(7I)
 280 .sp
 281 .LP
 282 \fIANSI Small Computer System Interface-2 (SCSI-2)\fR
 283 .sp
 284 .LP
 285 \fIANSI X3.272-1996, Fibre Channel Arbitrated Loop (FC-AL)\fR
 286 .sp
 287 .LP
 288 \fIFibre Channel - Private Loop SCSI Direct Attach (FC-PLDA)\fR
 289 .SH DIAGNOSTICS
 290 .sp
 291 .in +2
 292 .nf
 293 Error for command '<command name>' Error Level: Fatal Requested Block <n>,
 294 Error  Block: <m>, Sense Key: <sense key name>, Vendor '<vendor name>':
 295 ASC = 0x<a> (<ASC name>), ASCQ = 0x<b>, FRU = 0x<c>
 296 .fi
 297 .in -2
 298 .sp
 299
 300 .sp
 301 .LP
 302 The command indicated by <command name> failed. The Requested Block is the
 303 block where the transfer started and the Error Block is the block that caused
 304 the error. Sense Key, ASC, and ASCQ information is returned by the target in
 305 response to a request sense command.
 306 .sp
 307 .in +2
 308 .nf
 309 Check Condition on REQUEST SENSE
 310 .fi
 311 .in -2
 312 .sp
 313
 314 .sp
 315 .LP
 316 A REQUEST SENSE command completed with a check condition. The original command
 317 will be retried a number of times.
 318 .sp
 319 .in +2
 320 .nf
 321 Label says <m> blocks Drive says <\fIn\fR> blocks
 322 .fi
 323 .in -2
 324 .sp
 325
 326 .sp
 327 .LP
 328 There is a discrepancy between the label and what the drive returned on the
 329 READ CAPACITY command.
 330 .sp
 331 .in +2
 332 .nf
 333 Not enough sense information
 334 .fi
 335 .in -2
 336 .sp
 337
 338 .sp
 339 .LP
 340 The request sense data was less than expected.
 341 .sp
 342 .in +2
 343 .nf
 344 Request Sense couldn't get sense data
 345 .fi
 346 .in -2
 347 .sp
 348
 349 .sp
 350 .LP
 351 The REQUEST SENSE command did not transfer any data.
 352 .sp
 353 .in +2
 354 .nf
 355 Reservation Conflict
 356 .fi
 357 .in -2
 358 .sp
 359
 360 .sp
 361 .LP
 362 The drive was reserved by another initiator.
 363 .sp
 364 .in +2
 365 .nf
 366 SCSI transport failed: reason 'xxxx' : {retrying|giving up}
 367 .fi
 368 .in -2
 369 .sp
 370
 371 .sp
 372 .LP
 373 The host adapter has failed to transport a command to the target for the
 374 reason stated. The driver will either retry the command or, ultimately, give
 375 up.
 376 .sp
 377 .in +2
 378 .nf
 379 Unhandled Sense Key <\fIn\fR>
 380 .fi
 381 .in -2
 382 .sp
 383
 384 .sp
 385 .LP
 386 The REQUEST SENSE data included an invalid sense key.
 387 .sp
 388 .in +2
 389 .nf
 390 Unit not Ready. Additional sense code 0x<\fIn\fR>
 391 .fi
 392 .in -2
 393 .sp
 394
 395 .sp
 396 .LP
 397 The drive is not ready.
 398 .sp
 399 .in +2
 400 .nf
 401 corrupt label - bad geometry
 402 .fi
 403 .in -2
 404 .sp
 405
 406 .sp
 407 .LP
 408 The disk label is corrupted.
 409 .sp
 410 .in +2
 411 .nf
 412 corrupt label - label checksum failed
 413 .fi
 414 .in -2
 415 .sp
 416
 417 .sp
 418 .LP
 419 The disk label is corrupted.
 420 .sp
 421 .in +2
 422 .nf
 423 corrupt label - wrong magic number
 424 .fi
 425 .in -2
 426 .sp
 427
 428 .sp
 429 .LP
 430 The disk label is corrupted.
 431 .sp
 432 .in +2
 433 .nf
 434 device busy too long
 435 .fi
 436 .in -2
 437 .sp
 438
 439 .sp
 440 .LP
 441 The drive returned busy during a number of retries.
 442 .sp
 443 .in +2
 444 .nf
 445 disk not responding to selection
 446 .fi
 447 .in -2
 448 .sp
 449
 450 .sp
 451 .LP
 452 The drive was probably powered down or died.
 453 .sp
 454 .in +2
 455 .nf
 456 i/o to invalid geometry
 457 .fi
 458 .in -2
 459 .sp
 460
 461 .sp
 462 .LP
 463 The geometry of the drive could not be established.
 464 .sp
 465 .in +2
 466 .nf
 467 incomplete read/write - retrying/giving up
 468 .fi
 469 .in -2
 470 .sp
 471
 472 .sp
 473 .LP
 474 There was a residue after the command completed normally.
 475 .sp
 476 .in +2
 477 .nf
 478 logical unit not ready
 479 .fi
 480 .in -2
 481 .sp
 482
 483 .sp
 484 .LP
 485 The drive is not ready.
 486 .sp
 487 .in +2
 488 .nf
 489 no bp for disk label
 490 .fi
 491 .in -2
 492 .sp
 493
 494 .sp
 495 .LP
 496 A bp with consistent memory could not be allocated.
 497 .sp
 498 .in +2
 499 .nf
 500 no mem for property
 501 .fi
 502 .in -2
 503 .sp
 504
 505 .sp
 506 .LP
 507 Free memory pool exhausted.
 508 .sp
 509 .in +2
 510 .nf
 511 no memory for disk label
 512 .fi
 513 .in -2
 514 .sp
 515
 516 .sp
 517 .LP
 518 Free memory pool exhausted.
 519 .sp
 520 .in +2
 521 .nf
 522 no resources for dumping
 523 .fi
 524 .in -2
 525 .sp
 526
 527 .sp
 528 .LP
 529 A packet could not be allocated during dumping.
 530 .sp
 531 .in +2
 532 .nf
 533 offline
 534 .fi
 535 .in -2
 536 .sp
 537
 538 .sp
 539 .LP
 540 Drive went offline; probably powered down.
 541 .sp
 542 .in +2
 543 .nf
 544 requeue of command fails<\fIn\fR>
 545 .fi
 546 .in -2
 547 .sp
 548
 549 .sp
 550 .LP
 551 Driver attempted to retry a command and experienced a transport error.
 552 .sp
 553 .in +2
 554 .nf
 555 ssdrestart transport failed <\fIn\fR>
 556 .fi
 557 .in -2
 558 .sp
 559
 560 .sp
 561 .LP
 562 Driver attempted to retry a command and experienced a transport error.
 563 .sp
 564 .in +2
 565 .nf
 566 transfer length not modulo <\fIn\fR>
 567 .fi
 568 .in -2
 569 .sp
 570
 571 .sp
 572 .LP
 573 Illegal request size.
 574 .sp
 575 .in +2
 576 .nf
 577 transport rejected <\fIn\fR>
 578 .fi
 579 .in -2
 580 .sp
 581
 582 .sp
 583 .LP
 584 Host adapter driver was unable to accept a command.
 585 .sp
 586 .in +2
 587 .nf
 588 unable to read label
 589 .fi
 590 .in -2
 591 .sp
 592
 593 .sp
 594 .LP
 595 Failure to read disk label.
 596 .sp
 597 .in +2
 598 .nf
 599 unit does not respond to selection
 600 .fi
 601 .in -2
 602 .sp
 603
 604 .sp
 605 .LP
 606 Drive went offline; probably powered down.