freebsd-nq/share/man/man4/sd.4

.Dd August 27, 1993
.Dt SD 4
.Os FreeBSD
.Sh NAME
.Nm sd
.Nd scsi disk driver
.Sh SYNOPSIS
.Nm disk sd
.Nm disk sd1 target 4 lun 0
.Sh DESCRIPTION
The
.Xr sd
driver provides support for a 
.Em scsi
disk. It allows the disk
to be divided up into a set of pseudo devices called
.Em partitions.
A Partition can have both a 
.Em raw
interface
and a
.Em Block mode
interface.
In general the interfaces are similar to those described by 
.Xr wd 4 
or
.Xr dk 4 .

.Pp
Where the 
.Xr wd 4
device has a fairly low level interface to the system, 
.Em SCSI
devices have a much higher level interface and talk to the system via
a 
.Em SCSI Adapter
and a
.Em Scsi Adapter driver
e.g. 
.Xr AHA1542 .
A scsi adapter must also be separatly configured into the system
before a scsi disk can be configured.
.Pp
As the scsi adapter is probed during boot, the 
.Em SCSI
bus is scanned for devices. Any devices found which answer as 'Direct'
type devices will be 'attached' to the 
.Nm
driver.
In FreeBSD releases prior to 2.1, the first found will be attached as
.Em sd0
and the next, 
.Em sd1
etc.
Beginning in 2.1 it is possible to specify what sd unit a device should
come on line as; refer to
.Xr scsi 4
for details on kernel configuration.
.Pp
.Sh PARTITIONING
The 
.Nm
driver allows the disk to have two levels of partitioning.
One which allows it to have
partitions for different Operating systems, (one of which is BSD unix),
(see also for the 386 port, 
.Xr fdisk 1
), and within a BSD partition, further partitions which are individually 
addressable as separate entries in the 
.Em /dev
directory. The second level of partitioning  is controlled by the program
.Xr disklabel 1
and is common in format across most BSD operating systems. In most of
the original BSD ports, what is the 
BSD part here, is the entire disk, and the outer layer of partitionning
does not exist. 
.Nm
will also run in this manner if
.Xr disklabel 1
is run with a blank disk, without first partitioning it
with
.Xr fdisk 1
(or similar).

.Pp
Apologies for the two conflicting usages of the word Partition, but
it's a historical artifact, and the meaning must be judged from context
in each case. The next paragraph will discuss partitions exclusively
in the context of WITHIN a BSD partition on the disk.
.Pp
The first few blocks of the BSD section (maybe all) of the disk contain 
some boot code, and a structure, known as the 
.Xr disklabel 5
which describes the disk's characteristics and partitioning for BSD.
It is set up by the 
.Xr disklabel 1
program, and read in by the kernel when the device is first initialised
during boot. It describes how the drive is further divided. The
.Xr disklabel 5
structure contains room for 8 (usually) partitions.  Usually these
partitions are calculated so as to fall evenly on cylinder boundaries,
however on a 
.Em SCSI
disk this is sometimes not possible. The reason for doing this is historically
to get better performance, however modern 
.Em SCSI
disks often have a variable format, so that it is hard to know at any point
in the disk, where the cylinder or track boundaries are. Added to this, the
fact that 
.Em SCSI
disk blocks are addressed soley by their 'block number' and not by
any geometry, leads to the common occurance on 
.Em SCSI
disks, of laying out partitions on arbitrary boundaries. Because
modern disks often have large track caches, this often leads to only small
degadations of performance, and is in fact sometimes unavoidable. The 
boot messages will suggest a geometry similar in heads and cylinders 
to the real geometry, but the disklable need not agree with this for the
system to be able to successfully work with the disk. 
.Pp
During booting
with an uninitialised disk, the
.Nm 
driver will initialise the 'in-core' copy of the disklabel to the suggested
values, however they are not written to the disk.
.Pp
The fourth partition is special. No matter what the disklabel 
says, the fourth partition (partition d) reflectls the entire disk, including 
those areas OUTSIDE the BSD partitions. At some times it is suggested that
the c partition might be used to represent the entire BSD partition, so these
two partitions should be avoided when laying out filesystems. The fourth
partition must be used for general
.Xr scsi 4
ioctls.
.Pp
While partitions are only theoretically valid within the BSD partition, they
are specified in terms of absolute block numbers, so it is possible to
specify a partition that lies outside of the BSD partition. This is useful
if one wants to have a /dev entry that points to a partition belonging
to another OS (e.g. DOS).
.Pp
.Sh KERNEL CONFIGURATION
In configuring, if an optional
.Ar count
is given in
the specification, that number of scsi disks are configured;
Most storage for them is allocated only when found so a large number 
of configured devices is cheap. (once the first has included the driver).

.Pp
.Sh IOCTLS
The following 
.Xr ioctl 2
calls apply to scsi disks as well as to other disks. They are defined
in the header file
.Em disklabel.h.

.Bl -tag -width DIOCSDINFO

.It Dv DIOCSBAD
Usually used to set up a bad-block mapping system on the disk. Scsi
drive incorporate their own bad-block mapping so this is not implimented,
however it MAY be implimented in the future as a 'kludged' interface to the
scsi bad-block mapping.
.It Dv DIOCGDINFO
Read, from the kernel, the in-core copy of the disklabel for the
drive. This may be a ficticious disklabel if the drive has never
been initialised, in which case it will contain information read
from the scsi inquiry commands, and should be the same as
the information printed at boot.
.It Dv DIOCSDINFO
Give the driver a new disklabel to use. The driver will NOT try write the new
disklabel to the disk.
.It Dv DIOCWLABEL
Enable or Disable the driver's software
write protect of the disklabel on the disk.
.It Dv DIOCWDINFO
Give the driver a new disklabel to use. The driver WILL try write the new
disklabel to the disk.
.El
.Pp
In addition, the 
.Xr scsi 4
general ioctls may be used with the 
.Nm
driver, but only against the fourth (whole disk) partition.
.Sh NOTES
If a removable device is attached to the 
.Nm
driver, then the act of changing the media will invalidate the 
disklabel and information held within the kernel. To stop corruption,
All accesses to the device will be discarded until there are no more
open file descriptors referencing the device. During this period, all 
new open attempts will be rejected. When No more open file descriptors
reference the device, the first next open will load a new set of
figures (including disklabel) for the drive.

An ioctl to map out a bad block is planned. (the code is already present
in the driver).

.Sh FILES
.Bl -tag -width /dev/rsd[0-9][a-h] -compact
.It Pa /dev/sd[0-9][a-h]
block mode scsi disks
.It Pa /dev/rsd[0-9][a-h]
raw scsi disks
.El
.Sh DIAGNOSTICS
None.
.Sh SEE ALSO
.Xr disklabel 1
.Xr disklabel 5
.Xr fdisk 1
.Xr wd 4
.Xr dk 4
(on other systems)
.Sh HISTORY
The
.Nm
driver appeared in MACH 2.5 .