1.\" $NetBSD: sd.4,v 1.20 2016/06/10 08:05:13 wiz 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. 137.\"Similarly, if an uninitialized 138.\"(or 139.\".No non- Ns Tn FreeBSD ) 140.\"slice is opened, its disklabel will be initialized with parameters returned 141.\"by the drive and a single 142.\".Sq Li c 143.\"partition encompassing the entire slice. 144.\".Sh KERNEL CONFIGURATION 145.\"It is only necessary to explicitly configure one 146.\".Nm 147.\"device; data structures are dynamically allocated as disks are found 148.\"on the 149.\".Tn SCSI 150.\"bus. 151.Sh CONFIGURATION OPTIONS 152The following 153.Xr config 1 154options may be applied to 155.Tn SCSI 156disks as well as to other disks. 157.Pp 158.Bl -tag -width SD_IO_TIMEOUT 159.It Dv SDRETRIES 160Set the number of retries that will be performed for operations it 161makes sense to retry (e.g., normal reads and writes). 162The default is four (4). 163.It Dv SD_IO_TIMEOUT 164Set amount of time, in milliseconds, a normal read or write is expected 165to take. 166The defaults is sixty seconds (60000 milliseconds). 167This is used to set watchdog timers in the 168.Tn SCSI 169HBA driver to catch commands that might have died on the device. 170.El 171.Sh IOCTLS 172The following 173.Xr ioctl 2 174calls apply to 175.Tn SCSI 176disks as well as to other disks. 177They are defined in the header file 178.In sys/dkio.h 179and use data structures defined in 180.In sys/disklabel.h . 181.Pp 182.Bl -tag -width DIOCSDINFO 183.\".It Dv DIOCSBAD 184.\"Usually used to set up a bad-block mapping system on the disk. 185.\".Tn SCSI 186.\"drive incorporate their own bad-block mapping so this command is not 187.\"implemented. 188.It Dv DIOCGDINFO 189Read, from the kernel, the in-core copy of the disklabel for the drive. 190This may be a fictitious disklabel if the drive has never 191been initialized, in which case it will contain information read 192from the 193.Tn SCSI 194inquiry commands. 195.It Dv DIOCSDINFO 196Give the driver a new disklabel to use. 197The driver 198.Em will not 199write the new 200disklabel to the disk. 201.It Dv DIOCKLABEL 202Keep or drop the in-core disklabel on the last close. 203.It Dv DIOCWLABEL 204Enable or disable the driver's software 205write protect of the disklabel on the disk. 206.It Dv DIOCWDINFO 207Give the driver a new disklabel to use. 208The driver 209.Em will 210write the new disklabel to the disk. 211.It Dv DIOCLOCK 212Lock the media cartridge into the device, or unlock a cartridge previously 213locked. 214Used to prevent user and software eject while the media is in use. 215.It Dv DIOCEJECT 216Eject the media cartridge from a removable device. 217.El 218.Pp 219In addition, the 220.Xr scsi 4 221general 222.Fn ioctl 223commands may be used with the 224.Nm 225driver, but only against the 226.Sq Li c 227(whole disk) partition. 228.Sh NOTES 229If a removable device is attached to the 230.Nm 231driver, then the act of changing the media will invalidate the 232disklabel and information held within the kernel. 233To avoid corruption, all accesses to the device will be discarded 234until there are no more open file descriptors referencing the 235device. 236During this period, all new open attempts will be rejected. 237When no more open file descriptors reference the device, the first 238next open will load a new set of parameters (including disklabel) 239for the drive. 240.Sh FILES 241.Bl -tag -width /dev/rsdXXXXX -compact 242.It Pa /dev/sd Ns Ar u Ns Ar p 243block mode 244.Tn SCSI 245disk unit 246.Ar u , 247partition 248.Ar p 249.It Pa /dev/rsd Ns Ar u Ns Ar p 250raw mode 251.Tn SCSI 252disk unit 253.Ar u , 254partition 255.Ar p 256.El 257.Sh DIAGNOSTICS 258None. 259.Sh SEE ALSO 260.Xr ioctl 2 , 261.Xr intro 4 , 262.Xr scsi 4 , 263.Xr wd 4 , 264.Xr disklabel 5 , 265.Xr disklabel 8 , 266.Xr fdisk 8 , 267.Xr scsictl 8 268.Sh HISTORY 269The 270.Nm 271driver was originally written for 272.Tn Mach 2732.5, and was ported to 274.Fx 275by Julian Elischer. 276It was later ported to 277.Nx . 278