1.\" $NetBSD: sd.4,v 1.19 2016/06/09 14:52:48 kre 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 June 9, 2016 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 1 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.In sys/dkio.h 177and use data structures defined in 178.In sys/disklabel.h . 179.Pp 180.Bl -tag -width DIOCSDINFO 181.\".It Dv DIOCSBAD 182.\"Usually used to set up a bad-block mapping system on the disk. 183.\".Tn SCSI 184.\"drive incorporate their own bad-block mapping so this command is not 185.\"implemented. 186.It Dv DIOCGDINFO 187Read, from the kernel, the in-core copy of the disklabel for the drive. 188This may be a fictitious disklabel if the drive has never 189been initialized, in which case it will contain information read 190from the 191.Tn SCSI 192inquiry commands. 193.It Dv DIOCSDINFO 194Give the driver a new disklabel to use. 195The driver 196.Em will not 197write the new 198disklabel to the disk. 199.It Dv DIOCKLABEL 200Keep or drop the in-core disklabel on the last close. 201.It Dv DIOCWLABEL 202Enable or disable the driver's software 203write protect of the disklabel on the disk. 204.It Dv DIOCWDINFO 205Give the driver a new disklabel to use. 206The driver 207.Em will 208write the new disklabel to the disk. 209.It Dv DIOCLOCK 210Lock the media cartridge into the device, or unlock a cartridge previously 211locked. 212Used to prevent user and software eject while the media is in use. 213.It Dv DIOCEJECT 214Eject the media cartridge from a removable device. 215.El 216.Pp 217In addition, the 218.Xr scsi 4 219general 220.Fn ioctl 221commands may be used with the 222.Nm 223driver, but only against the 224.Sq Li c 225(whole disk) partition. 226.Sh NOTES 227If a removable device is attached to the 228.Nm 229driver, then the act of changing the media will invalidate the 230disklabel and information held within the kernel. 231To avoid corruption, all accesses to the device will be discarded 232until there are no more open file descriptors referencing the 233device. 234During this period, all new open attempts will be rejected. 235When no more open file descriptors reference the device, the first 236next open will load a new set of parameters (including disklabel) 237for the drive. 238.Sh FILES 239.Bl -tag -width /dev/rsdXXXXX -compact 240.It Pa /dev/sd Ns Ar u Ns Ar p 241block mode 242.Tn SCSI 243disk unit 244.Ar u , 245partition 246.Ar p 247.It Pa /dev/rsd Ns Ar u Ns Ar p 248raw mode 249.Tn SCSI 250disk unit 251.Ar u , 252partition 253.Ar p 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.Xr scsictl 8 266.Sh HISTORY 267The 268.Nm 269driver was originally written for 270.Tn Mach 2712.5, and was ported to 272.Fx 273by Julian Elischer. 274It was later ported to 275.Nx . 276