1.\" $NetBSD: sd.4,v 1.11 2001/06/26 00:14:32 hubertf Exp $ 2.\" 3.\" Copyright (c) 1996 4.\" Julian Elischer <julian@freebsd.org>. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd January 18, 1996 29.Dt SD 4 30.Os 31.Sh NAME 32.Nm sd 33.Nd SCSI and ATAPI disk driver 34.Sh SYNOPSIS 35.Cd sd* at scsibus? target ? lun ? 36.Cd sd3 at scsibus0 target 3 lun 0 37.Cd "sd* at atapibus? drive ? flags 0x0000" 38.Sh DESCRIPTION 39The 40.Nm 41driver provides support for 42.Tn SCSI 43bus and Advanced Technology Attachment Packet Interface 44.Pq Tn ATAPI 45disks. 46It allows the disk to be divided up into a set of pseudo devices called 47.Em partitions . 48In general the interfaces are similar to those described by 49.Xr wd 4 . 50.Pp 51Where the 52.Xr wd 4 53device has a fairly low level interface to the system, 54.Tn SCSI 55devices have a much higher level interface and talk to the system via a 56.Tn SCSI 57host adapter 58(e.g., 59.Xr ahc 4 ) . 60A 61.Tn SCSI 62adapter must also be separately configured into the system 63before a 64.Tn SCSI 65disk can be configured. 66.Pp 67When the 68.Tn SCSI 69adapter is probed during boot, the 70.Tn SCSI 71bus is scanned for devices. 72Any devices found which answer as 73.Sq Em Direct 74type devices will be attached to the 75.Nm 76driver. 77.Pp 78For the use of flags with ATAPI devices, see 79.Xr wd 4 . 80.\"In 81.\".Tn FreeBSD 82.\"releases prior to 2.1, the first found was attached as 83.\".Li sd0 , 84.\"the second 85.\".Li sd1 , 86.\"and so on. 87.\"Beginning in 2.1 it became possible to lock down the assignment of 88.\"devices on the 89.\".Tn SCSI 90.\"bus to particular units of the 91.\".Nm 92.\"device; refer to 93.\".Xr scsi 4 94.\"for details on kernel configuration. 95.Sh PARTITIONING 96.\"The 97.\".Nm 98.\"driver allows the disk to have two levels of partitioning. 99.\"One layer, called the 100.\".Dq slice layer , 101.\"is used to separate the 102.\".Tn FreeBSD 103.\"areas of the disk from areas used by other operating systems. 104.\"The second layer is the native 105.\".Bx 4.4 106.\"partitioning scheme, 107.\".Xr disklabel 5 , 108.\"which is used to subdivide the 109.\".Tn FreeBSD 110.\"slices into areas for individual filesystems and swap spaces. 111.\"For more information, see 112.\".Xr fdisk 8 113.\"and 114.\".Xr disklabel 8 , 115.\"respectively.) 116On many systems 117.Xr disklabel 8 118is used to partition the drive into filesystems. 119On some systems the 120.Nx 121portion of the disk resides within a native partition, and another 122program is used to create the 123.Nx 124portion. 125.Pp 126For example, the i386 port uses 127.Xr fdisk 8 128to partition the disk into a 129.Tn BIOS 130level partition. 131This allows sharing the disk with other operating systems. 132.Pp 133.\"If an uninitialized disk is opened, the slice table will be 134.\"initialized with a fictitious 135.\".Tn FreeBSD 136.\"slice spanning the entire disk. Similarly, if an uninitialized 137.\"(or 138.\".No non- Ns Tn FreeBSD ) 139.\"slice is opened, its disklabel will be initialized with parameters returned 140.\"by the drive and a single 141.\".Sq Li c 142.\"partition encompassing the entire slice. 143.\".Sh KERNEL CONFIGURATION 144.\"It is only necessary to explicitly configure one 145.\".Nm 146.\"device; data structures are dynamically allocated as disks are found 147.\"on the 148.\".Tn SCSI 149.\"bus. 150.Sh CONFIGURATION OPTIONS 151The following 152.Xr config 8 153options may be applied to 154.Tn SCSI 155disks as well as to other disks. 156.Pp 157.Bl -tag -width SD_IO_TIMEOUT 158.It Dv SDRETRIES 159Set the number of retries that will be performed for operations it 160makes sense to retry (e.g., normal reads and writes). The default 161is four (4). 162.It Dv SD_IO_TIMEOUT 163Set amount of time, in milliseconds, a normal read or write is expected 164to take. The defaults is sixty seconds (60000 milliseconds). This is used 165to set watchdog timers in the 166.Tn SCSI 167HBA driver to catch commands that might have died on the device. 168.El 169.Pp 170.Sh IOCTLS 171The following 172.Xr ioctl 2 173calls apply to 174.Tn SCSI 175disks as well as to other disks. 176They are defined in the header file 177.Aq Pa disklabel.h . 178.Pp 179.Bl -tag -width DIOCSDINFO 180.\".It Dv DIOCSBAD 181.\"Usually used to set up a bad-block mapping system on the disk. 182.\".Tn SCSI 183.\"drive incorporate their own bad-block mapping so this command is not 184.\"implemented. 185.It Dv DIOCGDINFO 186Read, from the kernel, the in-core copy of the disklabel for the drive. 187This may be a fictitious disklabel if the drive has never 188been initialized, in which case it will contain information read 189from the 190.Tn SCSI 191inquiry commands. 192.It Dv DIOCSDINFO 193Give the driver a new disklabel to use. 194The driver 195.Em will not 196write the new 197disklabel to the disk. 198.It Dv DIOCKLABEL 199Keep or drop the in-core disklabel on the last close. 200.It Dv DIOCWLABEL 201Enable or disable the driver's software 202write protect of the disklabel on the disk. 203.It Dv DIOCWDINFO 204Give the driver a new disklabel to use. 205The driver 206.Em will 207write the new disklabel to the disk. 208.It Dv DIOCLOCK 209Lock the media cartridge into the device, or unlock a cartridge previously 210locked. 211Used to prevent user and software eject while the media is in use. 212.It Dv DIOCEJECT 213Eject the media cartridge from a removable device. 214.El 215.Pp 216In addition, the 217.Xr scsi 4 218general 219.Fn ioctl 220commands may be used with the 221.Nm 222driver, but only against the 223.Sq Li c 224(whole disk) partition. 225.Sh NOTES 226If a removable device is attached to the 227.Nm 228driver, then the act of changing the media will invalidate the 229disklabel and information held within the kernel. 230To avoid corruption, all accesses to the device will be discarded 231until there are no more open file descriptors referencing the 232device. 233During this period, all new open attempts will be rejected. 234When no more open file descriptors reference the device, the first 235next open will load a new set of parameters (including disklabel) 236for the drive. 237.Sh FILES 238.Bl -tag -width /dev/rsdXXXXX -compact 239.It Pa /dev/sd Ns Ar u Ns Ar p 240block mode 241.Tn SCSI 242disk unit 243.Ar u , 244partition 245.Ar p 246.It Pa /dev/rsd Ns Ar u Ns Ar p 247raw mode 248.Tn SCSI 249disk unit 250.Ar u , 251partition 252.Ar p 253.Sm off 254.El 255.Sh DIAGNOSTICS 256None. 257.Sh SEE ALSO 258.Xr ioctl 2 , 259.Xr intro 4 , 260.Xr scsi 4 , 261.Xr wd 4 , 262.Xr disklabel 5 , 263.Xr disklabel 8 , 264.Xr fdisk 8 265.Sh HISTORY 266The 267.Nm 268driver was originally written for 269.Tn Mach 2702.5, and was ported to 271.Fx 272by Julian Elischer. 273It was later ported to 274.Nx . 275