[unix-history] / share / man / man4 / sd.4

.Dd August 27, 1993
.Dt SD 4
.Os 386BSD/NetBSD
.Sh NAME
.Nm sd
.Nd scsi disk driver
.Sh SYNOPSIS
.Nm device-driver sd
.Op Ar count
.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. The first found will be attached as
.Em sd0
and the next, 
.Em sd1
etc.
.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 .
Commit	Line	Data
0f4bf035 RG	1	.Dd August 27, 1993
	2	.Dt SD 4
	3	.Os 386BSD/NetBSD
	4	.Sh NAME
	5	.Nm sd
	6	.Nd scsi disk driver
	7	.Sh SYNOPSIS
	8	.Nm device-driver sd
	9	.Op Ar count
	10	.Sh DESCRIPTION
	11	The
	12	.Xr sd
	13	driver provides support for a
	14	.Em scsi
	15	disk. It allows the disk
	16	to be divided up into a set of pseudo devices called
	17	.Em partitions.
	18	A Partition can have both a
	19	.Em raw
	20	interface
	21	and a
	22	.Em Block mode
	23	interface.
	24	In general the interfaces are similar to those described by
	25	.Xr wd 4
	26	or
	27	.Xr dk 4 .
	28
	29	.Pp
	30	Where the
	31	.Xr wd 4
	32	device has a fairly low level interface to the system,
	33	.Em SCSI
	34	devices have a much higher level interface and talk to the system via
	35	a
	36	.Em SCSI Adapter
	37	and a
	38	.Em Scsi Adapter driver
	39	e.g.
	40	.Xr AHA1542 .
	41	A scsi adapter must also be separatly configured into the system
	42	before a scsi disk can be configured.
	43	.Pp
	44	As the scsi adapter is probed during boot, the
	45	.Em SCSI
	46	bus is scanned for devices. Any devices found which answer as 'Direct'
	47	type devices will be 'attached' to the
	48	.Nm
	49	driver. The first found will be attached as
	50	.Em sd0
	51	and the next,
	52	.Em sd1
	53	etc.
	54	.Pp
22c961eb	55	.Sh PARTITIONING
0f4bf035 RG	56	The
	57	.Nm
	58	driver allows the disk to have two levels of partitioning.
	59	One which allows it to have
	60	partitions for different Operating systems, (one of which is BSD unix),
	61	(see also for the 386 port,
	62	.Xr fdisk 1
	63	), and within a BSD partition, further partitions which are individually
	64	addressable as separate entries in the
	65	.Em /dev
	66	directory. The second level of partitioning is controlled by the program
	67	.Xr disklabel 1
	68	and is common in format across most BSD operating systems. In most of
	69	the original BSD ports, what is the
	70	BSD part here, is the entire disk, and the outer layer of partitionning
	71	does not exist.
	72	.Nm
	73	will also run in this manner if
	74	.Xr disklabel 1
	75	is run with a blank disk, without first partitioning it
	76	with
	77	.Xr fdisk 1
	78	(or similar).
	79
	80	.Pp
	81	Apologies for the two conflicting usages of the word Partition, but
	82	it's a historical artifact, and the meaning must be judged from context
	83	in each case. The next paragraph will discuss partitions exclusively
	84	in the context of WITHIN a BSD partition on the disk.
	85	.Pp
	86	The first few blocks of the BSD section (maybe all) of the disk contain
	87	some boot code, and a structure, known as the
	88	.Xr disklabel 5
	89	which describes the disk's characteristics and partitioning for BSD.
	90	It is set up by the
	91	.Xr disklabel 1
	92	program, and read in by the kernel when the device is first initialised
	93	during boot. It describes how the drive is further divided. The
	94	.Xr disklabel 5
	95	structure contains room for 8 (usually) partitions. Usually these
	96	partitions are calculated so as to fall evenly on cylinder boundaries,
	97	however on a
	98	.Em SCSI
	99	disk this is sometimes not possible. The reason for doing this is historically
	100	to get better performance, however modern
	101	.Em SCSI
	102	disks often have a variable format, so that it is hard to know at any point
	103	in the disk, where the cylinder or track boundaries are. Added to this, the
	104	fact that
	105	.Em SCSI
	106	disk blocks are addressed soley by their 'block number' and not by
	107	any geometry, leads to the common occurance on
	108	.Em SCSI
	109	disks, of laying out partitions on arbitrary boundaries. Because
	110	modern disks often have large track caches, this often leads to only small
	111	degadations of performance, and is in fact sometimes unavoidable. The
	112	boot messages will suggest a geometry similar in heads and cylinders
	113	to the real geometry, but the disklable need not agree with this for the
	114	system to be able to successfully work with the disk.
	115	.Pp
	116	During booting
	117	with an uninitialised disk, the
	118	.Nm
	119	driver will initialise the 'in-core' copy of the disklabel to the suggested
120	values, however they are not written to the disk.
121	.Pp
122	The fourth partition is special. No matter what the disklabel
123	says, the fourth partition (partition d) reflectls the entire disk, including
124	those areas OUTSIDE the BSD partitions. At some times it is suggested that
125	the c partition might be used to represent the entire BSD partition, so these
22c961eb RG	126	two partitions should be avoided when laying out filesystems. The fourth
	127	partition must be used for general
	128	.Xr scsi 4
	129	ioctls.
0f4bf035 RG	130	.Pp
	131	While partitions are only theoretically valid within the BSD partition, they
	132	are specified in terms of absolute block numbers, so it is possible to
	133	specify a partition that lies outside of the BSD partition. This is useful
	134	if one wants to have a /dev entry that points to a partition belonging
	135	to another OS (e.g. DOS).
	136	.Pp
22c961eb	137	.Sh KERNEL CONFIGURATION
0f4bf035 RG	138	In configuring, if an optional
	139	.Ar count
	140	is given in
	141	the specification, that number of scsi disks are configured;
	142	Most storage for them is allocated only when found so a large number
	143	of configured devices is cheap. (once the first has included the driver).
	144
	145	.Pp
22c961eb	146	.Sh IOCTLS
0f4bf035 RG	147	The following
	148	.Xr ioctl 2
	149	calls apply to scsi disks as well as to other disks. They are defined
	150	in the header file
	151	.Em disklabel.h.
	152
	153	.Bl -tag -width DIOCSDINFO
	154
	155	.It Dv DIOCSBAD
	156	Usually used to set up a bad-block mapping system on the disk. Scsi
	157	drive incorporate their own bad-block mapping so this is not implimented,
	158	however it MAY be implimented in the future as a 'kludged' interface to the
	159	scsi bad-block mapping.
	160	.It Dv DIOCGDINFO
	161	Read, from the kernel, the in-core copy of the disklabel for the
	162	drive. This may be a ficticious disklabel if the drive has never
	163	been initialised, in which case it will contain information read
	164	from the scsi inquiry commands, and should be the same as
	165	the information printed at boot.
	166	.It Dv DIOCSDINFO
	167	Give the driver a new disklabel to use. The driver will NOT try write the new
	168	disklabel to the disk.
	169	.It Dv DIOCWLABEL
	170	Enable or Disable the driver's software
	171	write protect of the disklabel on the disk.
	172	.It Dv DIOCWDINFO
	173	Give the driver a new disklabel to use. The driver WILL try write the new
	174	disklabel to the disk.
0f4bf035	175	.El
22c961eb RG	176	.Pp
	177	In addition, the
	178	.Xr scsi 4
	179	general ioctls may be used with the
	180	.Nm
	181	driver, but only against the fourth (whole disk) partition.
	182	.Sh NOTES
	183	If a removable device is attached to the
	184	.Nm
	185	driver, then the act of changing the media will invalidate the
	186	disklabel and information held within the kernel. To stop corruption,
	187	All accesses to the device will be discarded until there are no more
	188	open file descriptors referencing the device. During this period, all
	189	new open attempts will be rejected. When No more open file descriptors
	190	reference the device, the first next open will load a new set of
	191	figures (including disklabel) for the drive.
	192
	193	An ioctl to map out a bad block is planned. (the code is already present
	194	in the driver).
0f4bf035 RG	195
	196	.Sh FILES
	197	.Bl -tag -width /dev/rsd[0-9][a-h] -compact
	198	.It Pa /dev/sd[0-9][a-h]
	199	block mode scsi disks
	200	.It Pa /dev/rsd[0-9][a-h]
	201	raw scsi disks
	202	.El
	203	.Sh DIAGNOSTICS
	204	None.
	205	.Sh SEE ALSO
	206	.Xr disklabel 1
	207	.Xr disklabel 5
	208	.Xr fdisk 1
	209	.Xr wd 4
	210	.Xr dk 4
	211	(on other systems)
	212	.Sh HISTORY
	213	The
	214	.Nm
	215	driver appeared in MACH 2.5 .
	216