share/man/man4/sd.4

   1 .\"     $NetBSD: sd.4,v 1.16 2003/06/27 18:44:51 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 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
  39 The
  40 .Nm
  41 driver provides support for
  42 .Tn SCSI
  43 bus and Advanced Technology Attachment Packet Interface
  44 .Pq Tn ATAPI
  45 disks.
  46 It allows the disk to be divided up into a set of pseudo devices called
  47 .Em partitions .
  48 In general the interfaces are similar to those described by
  49 .Xr wd 4 .
  50 .Pp
  51 Where the
  52 .Xr wd 4
  53 device has a fairly low level interface to the system,
  54 .Tn SCSI
  55 devices have a much higher level interface and talk to the system via a
  56 .Tn SCSI
  57 host adapter
  58 (e.g.,
  59 .Xr ahc 4 ) .
  60 A
  61 .Tn SCSI
  62 adapter must also be separately configured into the system
  63 before a
  64 .Tn SCSI
  65 disk can be configured.
  66 .Pp
  67 When the
  68 .Tn SCSI
  69 adapter is probed during boot, the
  70 .Tn SCSI
  71 bus is scanned for devices.
  72 Any devices found which answer as
  73 .Sq Em Direct
  74 type devices will be attached to the
  75 .Nm
  76 driver.
  77 .Pp
  78 For 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.)
 116 On many systems
 117 .Xr disklabel 8
 118 is used to partition the drive into filesystems.
 119 On some systems the
 120 .Nx
 121 portion of the disk resides within a native partition, and another
 122 program is used to create the
 123 .Nx
 124 portion.
 125 .Pp
 126 For example, the i386 port uses
 127 .Xr fdisk 8
 128 to partition the disk into a
 129 .Tn BIOS
 130 level partition.
 131 This 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
 151 The following
 152 .Xr config 1
 153 options may be applied to
 154 .Tn SCSI
 155 disks as well as to other disks.
 156 .Pp
 157 .Bl -tag -width SD_IO_TIMEOUT
 158 .It Dv SDRETRIES
 159 Set the number of retries that will be performed for operations it
 160 makes sense to retry (e.g., normal reads and writes). The default
 161 is four (4).
 162 .It Dv SD_IO_TIMEOUT
 163 Set amount of time, in milliseconds, a normal read or write is expected
 164 to take. The defaults is sixty seconds (60000 milliseconds). This is used
 165 to set watchdog timers in the
 166 .Tn SCSI
 167 HBA driver to catch commands that might have died on the device.
 168 .El
 169 .Sh IOCTLS
 170 The following
 171 .Xr ioctl 2
 172 calls apply to
 173 .Tn SCSI
 174 disks as well as to other disks.
 175 They 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
 185 Read, from the kernel, the in-core copy of the disklabel for the drive.
 186 This may be a fictitious disklabel if the drive has never
 187 been initialized, in which case it will contain information read
 188 from the
 189 .Tn SCSI
 190 inquiry commands.
 191 .It Dv DIOCSDINFO
 192 Give the driver a new disklabel to use.
 193 The driver
 194 .Em will not
 195 write the new
 196 disklabel to the disk.
 197 .It Dv DIOCKLABEL
 198 Keep or drop the in-core disklabel on the last close.
 199 .It Dv DIOCWLABEL
 200 Enable or disable the driver's software
 201 write protect of the disklabel on the disk.
 202 .It Dv DIOCWDINFO
 203 Give the driver a new disklabel to use.
 204 The driver
 205 .Em will
 206 write the new disklabel to the disk.
 207 .It Dv DIOCLOCK
 208 Lock the media cartridge into the device, or unlock a cartridge previously
 209 locked.
 210 Used to prevent user and software eject while the media is in use.
 211 .It Dv DIOCEJECT
 212 Eject the media cartridge from a removable device.
 213 .El
 214 .Pp
 215 In addition, the
 216 .Xr scsi 4
 217 general
 218 .Fn ioctl
 219 commands may be used with the
 220 .Nm
 221 driver, but only against the
 222 .Sq Li c
 223 (whole disk) partition.
 224 .Sh NOTES
 225 If a removable device is attached to the
 226 .Nm
 227 driver, then the act of changing the media will invalidate the
 228 disklabel and information held within the kernel.
 229 To avoid corruption, all accesses to the device will be discarded
 230 until there are no more open file descriptors referencing the
 231 device.
 232 During this period, all new open attempts will be rejected.
 233 When no more open file descriptors reference the device, the first
 234 next open will load a new set of parameters (including disklabel)
 235 for the drive.
 236 .Sh FILES
 237 .Bl -tag -width /dev/rsdXXXXX -compact
 238 .It Pa /dev/sd Ns Ar u Ns Ar p
 239 block mode
 240 .Tn SCSI
 241 disk unit
 242 .Ar u ,
 243 partition
 244 .Ar p
 245 .It Pa /dev/rsd Ns Ar u Ns Ar p
 246 raw mode
 247 .Tn SCSI
 248 disk unit
 249 .Ar u ,
 250 partition
 251 .Ar p
 252 .El
 253 .Sh DIAGNOSTICS
 254 None.
 255 .Sh SEE ALSO
 256 .Xr ioctl 2 ,
 257 .Xr intro 4 ,
 258 .Xr scsi 4 ,
 259 .Xr wd 4 ,
 260 .Xr disklabel 5 ,
 261 .Xr disklabel 8 ,
 262 .Xr fdisk 8 ,
 263 .Xr scsictl 8
 264 .Sh HISTORY
 265 The
 266 .Nm
 267 driver was originally written for
 268 .Tn Mach
 269 2.5, and was ported to
 270 .Fx
 271 by Julian Elischer.
 272 It was later ported to
 273 .Nx .