1.\" $NetBSD: sd.4,v 1.14 2002/05/28 04:08:52 grant 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.Sh IOCTLS 170The following 171.Xr ioctl 2 172calls apply to 173.Tn SCSI 174disks as well as to other disks. 175They are defined in the header file 176.Aq Pa disklabel.h . 177.Pp 178.Bl -tag -width DIOCSDINFO 179.\".It Dv DIOCSBAD 180.\"Usually used to set up a bad-block mapping system on the disk. 181.\".Tn SCSI 182.\"drive incorporate their own bad-block mapping so this command is not 183.\"implemented. 184.It Dv DIOCGDINFO 185Read, from the kernel, the in-core copy of the disklabel for the drive. 186This may be a fictitious disklabel if the drive has never 187been initialized, in which case it will contain information read 188from the 189.Tn SCSI 190inquiry commands. 191.It Dv DIOCSDINFO 192Give the driver a new disklabel to use. 193The driver 194.Em will not 195write the new 196disklabel to the disk. 197.It Dv DIOCKLABEL 198Keep or drop the in-core disklabel on the last close. 199.It Dv DIOCWLABEL 200Enable or disable the driver's software 201write protect of the disklabel on the disk. 202.It Dv DIOCWDINFO 203Give the driver a new disklabel to use. 204The driver 205.Em will 206write the new disklabel to the disk. 207.It Dv DIOCLOCK 208Lock the media cartridge into the device, or unlock a cartridge previously 209locked. 210Used to prevent user and software eject while the media is in use. 211.It Dv DIOCEJECT 212Eject the media cartridge from a removable device. 213.El 214.Pp 215In addition, the 216.Xr scsi 4 217general 218.Fn ioctl 219commands may be used with the 220.Nm 221driver, but only against the 222.Sq Li c 223(whole disk) partition. 224.Sh NOTES 225If a removable device is attached to the 226.Nm 227driver, then the act of changing the media will invalidate the 228disklabel and information held within the kernel. 229To avoid corruption, all accesses to the device will be discarded 230until there are no more open file descriptors referencing the 231device. 232During this period, all new open attempts will be rejected. 233When no more open file descriptors reference the device, the first 234next open will load a new set of parameters (including disklabel) 235for the drive. 236.Sh FILES 237.Bl -tag -width /dev/rsdXXXXX -compact 238.It Pa /dev/sd Ns Ar u Ns Ar p 239block mode 240.Tn SCSI 241disk unit 242.Ar u , 243partition 244.Ar p 245.It Pa /dev/rsd Ns Ar u Ns Ar p 246raw mode 247.Tn SCSI 248disk unit 249.Ar u , 250partition 251.Ar p 252.Sm off 253.El 254.Sh DIAGNOSTICS 255None. 256.Sh SEE ALSO 257.Xr ioctl 2 , 258.Xr intro 4 , 259.Xr scsi 4 , 260.Xr wd 4 , 261.Xr disklabel 5 , 262.Xr disklabel 8 , 263.Xr fdisk 8 , 264.Xr scsictl 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