remove support for 'trademark files'
[unleashed/tickless.git] / share / man / man7d / sd.7d
blobe0cbc53c7d2de2b154ffa7dac382c16d51a73442
1 '\" te
2 .\" Copyright (c) 2009 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. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
4 .\"  See the License for the specific language governing permissions and limitations under the License. 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,
5 .\" with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH SD 7D "Sep 8, 2009"
7 .SH NAME
8 sd \- SCSI disk and ATAPI/SCSI CD-ROM device driver
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBsd@target,lun:partition\fR
13 .fi
15 .SH DESCRIPTION
16 .sp
17 .LP
18 To open a device without checking if the vtoc is valid, use the O_NDELAY flag.
19 When the device is opened using O_NDELAY, the first read or write to the device
20 that happens after the open results in the label being read if the label is not
21 currently valid. Once read, the label remains valid until the last close of the
22 device. Except for reading the label, O_NDELAY has no impact on the driver.
23 .SS "SPARC"
24 .sp
25 .LP
26 The \fBsd\fR \fBSCSI\fR and \fBSCSI/ATAPI\fR driver supports embedded
27 \fBSCSI\fR-2 and \fBCCS\fR-compatible \fBSCSI\fR disk and CD-ROM drives,
28 \fBATAPI \fR 2.6 (SFF-8020i)-compliant CD-ROM drives, SFF-8090-compliant
29 \fBSCSI/ATAPI\fR DVD-ROM drives, IOMEGA \fBSCSI/ATAPI\fR ZIP drives, \fBSCSI
30 JAZ\fR drives, and USB mass storage devices (refer to \fBscsa2usb\fR(7D)).
31 .sp
32 .LP
33 To determine the disk drive type, use the \fBSCSI/ATAPI\fR inquiry command and
34 read the volume label stored on block 0 of the drive. (The volume label
35 describes the disk geometry and partitioning and must be present for the disk
36 to be mounted by the system.) A volume label is not required for removable,
37 re-writable or read-only media.
38 .SS "x86 Only"
39 .sp
40 .LP
41 The \fBsd\fRdriver supports embedded \fBSCSI\fR-2 and \fBCCS\fR-compatible
42 \fBSCSI \fRdisk and CD-ROM drives, \fBATAPI \fR2.6 (SFF-8020i)-compliant CD-ROM
43 drives, SFF-8090-compliant \fBSCSI/ATAPI\fR DVD-ROM drives, IOMEGA
44 \fBSCSI/ATAPI\fR ZIP drives\fB, and SCSI JAZ\fR drives.
45 .sp
46 .LP
47 The x86 BIOS legacy requires a master boot record (MBR) and \fBfdisk\fR table
48 in the first physical sector of the bootable media. If the x86 hard disk
49 contains a Solaris disk label, it is located in the second 512-byte sector of
50 the FDISK partition.
51 .SH DEVICE SPECIAL FILES
52 .sp
53 .LP
54 Block-files access the disk using normal buffering mechanism and are read-from
55 and written-to without regard to physical disk records. A \fBraw\fR interface
56 enables direct transmission between the disk and the user's read or write
57 buffer. A single \fBread\fR or \fBwrite\fR call usually results in a single I/O
58 operation, therefore raw I/O is more efficient when many bytes are transmitted.
59 Block files names are found in \fB/dev/dsk\fR; raw file names are found in
60 \fB/dev/rdsk\fR.
61 .sp
62 .LP
63 I/O requests to the raw device must be aligned on a 512-byte (\fBDEV_BSIZE\fR)
64 boundary and all I/O request lengths must be in multiples of 512 bytes.
65 Requests that do not meet these requirements will trigger an \fBEINVAL\fR
66 error. There are no alignment or length restrictions on I/O requests to the
67 block device.
68 .SH CD-ROM DRIVE SUPPORT
69 .sp
70 .LP
71 A CD-ROM disk is single-sided and contains approximately 640 megabytes of data
72 or 74 minutes of audio. When the CD-ROM is opened, the eject button is disabled
73 to prevent manual removal of the disk until the last \fBclose()\fR is called.
74 No volume label is required for a CD-ROM. The disk geometry and partitioning
75 information are constant and never change. If the CD-ROM contains data recorded
76 in a Solaris-aware file system format, it can be mounted using the appropriate
77 Solaris file system support.
78 .SH DVD-ROM DRIVE SUPPORT
79 .sp
80 .LP
81 DVD-ROM media can be single or double-sided and can be recorded upon using a
82 single or double layer structure. Double-layer media provides parallel or
83 opposite track paths. A DVD-ROM can hold from between 4.5 Gbytes and 17 Gbytes
84 of data, depending on the layer structure used for recording and if the DVD-ROM
85 is single or double-sided.
86 .sp
87 .LP
88 When the DVD-ROM is opened, the eject button is disabled to prevent the manual
89 removal of a disk until the last \fBclose()\fR is called. No volume label is
90 required for a DVD-ROM. If the DVD-ROM contains data recorded in a
91 Solaris-aware file system format, it can be mounted using the appropriate
92 Solaris file system support.
93 .SH ZIP/JAZ DRIVE SUPPORT
94 .sp
95 .LP
96 \fBZIP/JAZ\fR media provide varied data capacity points; a single \fBJAZ
97 \fRdrive can store up to 2 GBytes of data, while a ZIP-250 can store up to
98 250MBytes of data. \fBZIP/JAZ\fR drives can be read-from or written-to using
99 the appropriate drive.
102 When a \fBZIP/JAZ\fR drive is opened, the eject button is disabled to prevent
103 the manual removal of a disk until the last \fBclose()\fR is called. No volume
104 label is required for a \fBZIP/JAZ\fR drive. If the \fBZIP/JAZ\fR drive
105 contains data recorded in a Solaris-aware file system format, it can be mounted
106 using the appropriate Solaris file system support.
107 .SH DEVICE STATISTICS SUPPORT
110 Each device maintains I/O statistics for the device and for partitions
111 allocated for that device. For each device/partition, the driver accumulates
112 reads, writes, bytes read, and bytes written. The driver also initiates
113 hi-resolution time stamps at queue entry and exit points to enable monitoring
114 of residence time and cumulative residence-length product for each queue.
117 Not all device drivers make per-partition IO statistics available for
118 reporting. \fBsd\fR and \fBssd\fR(7D) per-partition statistics are enabled by
119 default but may disabled in their configuration files.
120 .SH IOCTLS
123 Refer to \fBdkio\fR(7I), and \fBcdio\fR(7I)
124 .SS "ERRORS"
126 .ne 2
128 \fB\fBEACCES\fR\fR
130 .RS 10n
131 Permission denied
135 .ne 2
137 \fB\fBEBUSY\fR\fR
139 .RS 10n
140 The partition was opened exclusively by another thread
144 .ne 2
146 \fB\fBEFAULT\fR\fR
148 .RS 10n
149 The argument features a bad address
153 .ne 2
155 \fB\fBEINVAL\fR\fR
157 .RS 10n
158 Invalid argument
162 .ne 2
164 \fB\fBENOTTY\fR\fR
166 .RS 10n
167 The device does not support the requested ioctl function
171 .ne 2
173 \fB\fBENXIO\fR\fR
175 .RS 10n
176 During opening, the device did not exist. During close, the drive unlock failed
180 .ne 2
182 \fB\fBEROFS\fR\fR
184 .RS 10n
185 The device is read-only
189 .ne 2
191 \fB\fBEAGAIN\fR\fR
193 .RS 10n
194 Resource temporarily unavailable
198 .ne 2
200 \fB\fBEINTR\fR\fR
202 .RS 10n
203 A signal was caught during the execution of the \fBioctl()\fR function
207 .ne 2
209 \fB\fBENOMEM\fR\fR
211 .RS 10n
212 Insufficient memory
216 .ne 2
218 \fB\fBEPERM\fR\fR
220 .RS 10n
221 Insufficent access permission
225 .ne 2
227 \fB\fBEIO\fR\fR
229 .RS 10n
230 An I/O error occurred. Refer to notes for details on copy-protected DVD-ROM
231 media.
234 .SH CONFIGURATION
237 The \fBsd\fR driver can be configured by defining properties in the
238 \fBsd.conf\fR file. The \fBsd\fR driver supports the following properties:
240 .ne 2
242 \fB\fBenable-partition-kstats\fR\fR
244 .RS 27n
245 The default value is 1, which causes partition IO statistics to be maintained.
246 Set this value to zero to prevent the driver from recording partition
247 statistics. This slightly reduces the CPU overhead for IO, mimimizes the amount
248 of \fBsar\fR(1) data collected and makes these statistics unavailable for
249 reporting by \fBiostat\fR(1M) even though the \fB-p\fR/\fB-P\fR option is
250 specified. Regardless of this setting, disk IO statistics are always
251 maintained.
255 .ne 2
257 \fB\fBqfull-retries\fR\fR
259 .RS 27n
260 The supplied value is passed as the \fBqfull-retries\fR capability value of the
261 HBA driver. See \fBscsi_ifsetcap\fR(9F) for details.
265 .ne 2
267 \fB\fBqfull-retry-interval\fR\fR
269 .RS 27n
270 The supplied value is passed as the \fBqfull-retry interval\fR capability value
271 of the HBA driver. See \fBscsi_ifsetcap\fR(9F) for details.
275 .ne 2
277 \fB\fBallow-bus-device-reset\fR\fR
279 .RS 27n
280 The default value is 1, which allows resetting to occur. Set this value to
281 \fB0\fR (zero) to prevent the \fBsd\fR driver from calling \fBscsi_reset\fR(9F)
282 with a second argument of \fBRESET_TARGET\fR when in error-recovery mode. This
283 \fBscsi_reset\fR(9F) call may prompt the HBA driver to send a SCSI Bus Device
284 Reset message. The \fBscsi_reset\fR(9F) call with a second argument of
285 \fBRESET_TARGET\fR may result from an explicit request via the \fBUSCSICMD\fR
286 \fBioctl\fR. Some high-availability multi-initiator systems may wish to
287 prohibit the Bus Device Reset message; to do this, set the
288 \fBallow-bus-device-reset\fR property to \fB0\fR.
292 .ne 2
294 \fBoptical-device-bind\fR
296 .RS 27n
297 Controls the binding of the driver to non self-identifying SCSI target optical
298 devices. (See \fBscsi\fR(4)). The default value is 1, which causes \fBsd\fR to
299 bind to DTYPE_OPTICAL devices (as noted in \fBscsi\fR(4)).  Setting this value
300 to 0 prevents automatic binding. The default behavior for the SPARC-based
301 \fBsd\fR driver prior to Solaris 9 was not to bind to optical devices.
305 .ne 2
307 \fB\fBpower-condition\fR\fR
309 .RS 27n
310 Boolean type, when set to \fBFalse\fR, it indicates that the disk does not
311 support \fBpower condition\fR field in th\fBe START STOP UNIT\fR command.
316 In addition to the above properties, some device-specific tunables can be
317 configured in \fBsd.conf\fR using the \fBsd-config-list\fR global property. The
318 value of this property is a list of duplets. The formal syntax is:
320 .in +2
322 sd-config-list = <duplet> [, <duplet> ]* ;
324 where
326 <duplet>:= "<vid+pid>" , "<tunable-list>"
330 <tunable-list>:= <tunable>  [, <tunable> ]*;
331 <tunable> = <name> : <value>
333 The <vid+pid> is the string that is returned by the target device
334 on a SCSI inquiry command.
336 The <tunable-list> contains one or more tunables to apply to
337 all target devices with the specified <vid+pid>.
339 Each <tunable> is a <name> : <value> pair. Supported
340 tunable names are:
342    delay-busy: when busy, nsecs of delay before retry.
344    retries-timeout: retries to perform on an IO timeout.
346 .in -2
349 .ne 2
351 \fB\fBmmc-gesn-polling\fR\fR
353 .RS 20n
354 For optical drives compliant with \fBMMC-3\fR and supporting the \fBGET EVENT
355 STATUS NOTIFICATION\fR command, this command is used for periodic media state
356 polling, usually initiated by the \fBDKIOCSTATE\fR \fBdkio\fR(7I) ioctl. To
357 disable the use of this command, set this boolean property to \fBfalse\fR. In
358 that case, either the \fBTEST UNIT READY\fR or zero-length \fBWRITE(10)\fR
359 command is used instead.
362 .SH EXAMPLES
364 .in +2
366 The following is an example of a global sd-config-list property:
368    sd-config-list =
369       "SUN     T4", "delay-busy:600, retries-timeout:6",
370       "SUN     StorEdge_3510", "retries-timeout:3";
372 .in -2
374 .SH FILES
376 .ne 2
378 \fB\fB/kernel/drv/sd.conf\fR\fR
380 .RS 23n
381 Driver configuration file
385 .ne 2
387 \fB\fB/dev/dsk/cntndnsn\fR\fR
389 .RS 23n
390 Block files
394 .ne 2
396 \fB\fB/dev/rdsk/cntndnsn\fR\fR
398 .RS 23n
399 Raw files
404 Where:
406 .ne 2
408 \fBcn\fR
410 .RS 6n
411 controller n
415 .ne 2
417 \fBtn\fR
419 .RS 6n
420 SCSI target id n (0-6)
424 .ne 2
426 \fBdn\fR
428 .RS 6n
429 SCSI LUN n (0-7 normally; some HBAs support LUNs to 15 or 32. See the specific
430 manpage for details)
434 .ne 2
436 \fBsn\fR
438 .RS 6n
439 partition n (0-7)
442 .SS "x86 Only"
444 .ne 2
446 \fB\fB/dev/rdsk/cntndnpn\fR\fR
448 .RS 22n
449 raw files
454 Where:
456 .ne 2
458 \fBpn\fR
460 .RS 6n
461 Where \fIn\fR=0 the node corresponds to the entire disk.
464 .SH SEE ALSO
467 \fBsar\fR(1), \fBcfgadm_scsi\fR(1M), \fBfdisk\fR(1M), \fBformat\fR(1M),
468 \fBiostat\fR(1M), \fBclose\fR(2), \fBioctl\fR(2), \fBlseek\fR(2),
469 \fBread\fR(2), \fBwrite\fR(2), \fBdriver.conf\fR(4), \fBscsi\fR(4),
470 \fBfilesystem\fR(5), \fBscsa2usb\fR(7D), \fBssd\fR(7D), \fBhsfs\fR(7FS),
471 \fBpcfs\fR(7FS), \fBudfs\fR(7FS), \fBcdio\fR(7I), \fBdkio\fR(7I),
472 \fBscsi_ifsetcap\fR(9F), \fBscsi_reset\fR(9F)
475 \fIANSI Small Computer System Interface-2 (SCSI-2)\fR
478 \fIATA Packet Interface for CD-ROMs, SFF-8020i\fR
481 \fIMt.Fuji Commands for CD and DVD, SFF8090v3\fR
484 http://\fIwww.sun.com/io\fR
485 .SH DIAGNOSTICS
487 .in +2
489 Error for Command:\fI<command name>\fR
490 Error Level: Fatal
491 Requested Block: \fI<n>\fR
492 Error  Block: \fI<m>\fR
493 Vendor:'\fI<vendorname>\fR\&'
494 Serial Number:'\fI<serial number>\fR\&'
495 Sense Key:\fI<sense key name>\fR
497 .in -2
501 .ne 2
503 \fBASC: 0x<a> (<ASC name>), ASCQ: 0x<b>, FRU: 0x<c>\fR
505 .sp .6
506 .RS 4n
507 The command indicated by <command name> failed. The Requested Block is the
508 block where the transfer started and the Error Block is the block that caused
509 the error. Sense Key, \fBASC\fR, and \fBASCQ\fR information is returned by the
510 target in response to a request sense command.
514 .ne 2
516 \fBCaddy not inserted in drive\fR
518 .sp .6
519 .RS 4n
520 The drive is not ready because no caddy has been inserted.
524 .ne 2
526 \fBCheck Condition on REQUEST SENSE\fR
528 .sp .6
529 .RS 4n
530 A REQUEST SENSE command completed with a check condition. The original command
531 will be retried a number of times.
535 .ne 2
537 \fBLabel says <m> blocks Drive says <n> blocks\fR
539 .sp .6
540 .RS 4n
541 There is a discrepancy between the label and what the drive returned on the
542 \fBREAD CAPACITY\fR command.
546 .ne 2
548 \fBNot enough sense information\fR
550 .sp .6
551 .RS 4n
552 The request sense data was less than expected.
556 .ne 2
558 \fBRequest Sense couldn't get sense data\fR
560 .sp .6
561 .RS 4n
562 The \fBREQUEST SENSE\fR command did not transfer any data.
566 .ne 2
568 \fBReservation Conflict\fR
570 .sp .6
571 .RS 4n
572 The drive was reserved by another initiator.
576 .ne 2
578 \fBSCSI transport failed: reason \fB\&'xxxx'\fR: {retrying|giving up}\fR
580 .sp .6
581 .RS 4n
582 The host adapter has failed to transport a command to the target for the reason
583 stated. The driver will either retry the command or, ultimately, give up.
587 .ne 2
589 \fBUnhandled Sense Key<\fIn\fR>\fR
591 .sp .6
592 .RS 4n
593 The REQUEST SENSE data included an invalid sense.
597 .ne 2
599 \fBUnit not ready. Additional sense code 0x\fR
601 .sp .6
602 .RS 4n
603 \fI<n>\fR The drive is not ready.
607 .ne 2
609 \fBCan't do switch back to mode 1\fR
611 .sp .6
612 .RS 4n
613 A failure to switch back to read mode 1.
617 .ne 2
619 \fBCorrupt label - bad geometry\fR
621 .sp .6
622 .RS 4n
623 The disk label is corrupted.
627 .ne 2
629 \fBCorrupt label - label checksum failed\fR
631 .sp .6
632 .RS 4n
633 The disk label is corrupted.
637 .ne 2
639 \fBCorrupt label - wrong magic number\fR
641 .sp .6
642 .RS 4n
643 The disk label is corrupted.
647 .ne 2
649 \fBDevice busy too long\fR
651 .sp .6
652 .RS 4n
653 The drive returned busy during a number of retries.
657 .ne 2
659 \fBDisk not responding to selection\fR
661 .sp .6
662 .RS 4n
663 The drive is powered down or died
667 .ne 2
669 \fBFailed to handle UA\fR
671 .sp .6
672 .RS 4n
673 A retry on a Unit Attention condition failed.
677 .ne 2
679 \fBI/O to invalid geometry\fR
681 .sp .6
682 .RS 4n
683 The geometry of the drive could not be established.
687 .ne 2
689 \fBIncomplete read/write - retrying/giving up\fR
691 .sp .6
692 .RS 4n
693 There was a residue after the command completed normally.
697 .ne 2
699 \fBNo bp for direct access device format geometry\fR
701 .sp .6
702 .RS 4n
703 A bp with consistent memory could not be allocated.
707 .ne 2
709 \fBNo bp for disk label\fR
711 .sp .6
712 .RS 4n
713 A bp with consistent memory could not be allocated.
717 .ne 2
719 \fBNo bp for fdisk\fR
721 .sp .6
722 .RS 4n
723 A bp with consistent memory could not be allocated.
727 .ne 2
729 \fBNo bp for rigid disk geometry\fR
731 .sp .6
732 .RS 4n
733 A bp with consistent memory could not be allocated.
737 .ne 2
739 \fBNo mem for property\fR
741 .sp .6
742 .RS 4n
743 Free memory pool exhausted.
747 .ne 2
749 \fBNo memory for direct access device format geometry\fR
751 .sp .6
752 .RS 4n
753 Free memory pool exhausted.
757 .ne 2
759 \fBNo memory for disk label\fR
761 .sp .6
762 .RS 4n
763 Free memory pool exhausted.
767 .ne 2
769 \fBNo memory for rigid disk geometry\fR
771 .sp .6
772 .RS 4n
773 The disk label is corrupted.
777 .ne 2
779 \fBNo resources for dumping\fR
781 .sp .6
782 .RS 4n
783 A packet could not be allocated during dumping.
787 .ne 2
789 \fBOffline\fR
791 .sp .6
792 .RS 4n
793 Drive went offline; probably powered down.
797 .ne 2
799 \fBRequeue of command fails\fR
801 .sp .6
802 .RS 4n
803 Driver attempted to retry a command and experienced a transport error.
807 .ne 2
809 \fBsdrestart transport failed()\fR
811 .sp .6
812 .RS 4n
813 Driver attempted to retry a command and experienced a transport error.
817 .ne 2
819 \fBTransfer length not modulo\fR
821 .sp .6
822 .RS 4n
823 Illegal request size.
827 .ne 2
829 \fBTransport of request sense fails()\fR
831 .sp .6
832 .RS 4n
833 Driver attempted to submit a request sense command and failed.
837 .ne 2
839 \fBTransport rejected()\fR
841 .sp .6
842 .RS 4n
843 Host adapter driver was unable to accept a command.
847 .ne 2
849 \fBUnable to read label\fR
851 .sp .6
852 .RS 4n
853 Failure to read disk label.
857 .ne 2
859 \fBUnit does not respond to selection\fR
861 .sp .6
862 .RS 4n
863 Drive went offline; probably powered down.
866 .SH NOTES
869 DVD-ROM media containing DVD-Video data may follow/adhere to the requirements
870 of content scrambling system or copy protection scheme. Reading of
871 copy-protected sector will cause I/O error. Users are advised to use the
872 appropriate playback software to view video contents on DVD-ROM media
873 containing DVD-Video data.