#	$Id: README,v 1.2.2.1 2002/07/27 00:16:10 garloff Exp $	
NOTE: This docu is out of date. Please refer to the man page and the
=====  web page mentioned there.  KG.

	The linux SCSI code assigns minor numbers to devices dynamically.  
Thus if you add or remove a device, the device numbering will change, and this
obviously screws up things like /etc/fstab, /etc/rc*, and a few other things.
What we desire is a uniform naming scheme whereby the name used for a device
remains the same as you add or remove other bits of hardware.

	This program attempts to fill this need.  It populates a
/dev/scsi subtree, with entries like:

ls -lf /dev/scsi
total 0
crw-------   1 root     root       9, 128 Aug  4 13:16 rsth4-334c0i5l0
brw-------   1 root     root       8,   0 Aug  4 13:16 sdh4-334c0i0l0
brw-------   1 root     root       8,   1 Aug  4 13:16 sdh4-334c0i0l0p1
brw-------   1 root     root       8,   2 Aug  4 13:16 sdh4-334c0i0l0p2
brw-------   1 root     root       8,   3 Aug  4 13:16 sdh4-334c0i0l0p3
crw-------   1 root     root      21,   0 Aug  4 13:16 sgh4-334c0i0l0
crw-------   1 root     root      21,   1 Aug  4 13:16 sgh4-334c0i2l0
crw-------   1 root     root      21,   2 Aug  4 13:16 sgh4-334c0i5l0
br--------   1 root     root      11,   0 Aug  4 13:16 srh4-334c0i2l0
crw-------   1 root     root       9,   0 Aug  4 13:16 sth4-334c0i5l0
bash$ 

The challenge has been to find a way of uniquely identifying the host
adapter to which a given device is attached.  The "h%d-%x" part of the
name attempts to accomplish this.

	The first part of the number, 4 in this case, is the low 8
bits of the inode number of /proc/scsi/aha1542 (since I am using a
1542).  By using this number, we uniquely identify what type of driver
the device is attached to.

	Secondly we need a way of uniquely identifying which 1542 we
are using.  The 334 represents the I/O port that is used for the 1542
that I am using.  Note that many drivers do not support multiple cards
in the system at the same time, and if this is the case, this field
will be "0".   For other cards, the number will probably have some other
meaning, but the general idea is that if we were to add another 1542 at
I/O address 330, that we would still be able to easily tell them apart.

	The "c0" is used for host adapters that support multi-channels
(or multiple busses).  Some boards can drive 2 busses, so this would be
0 or 1 in these cases.

	The "i%d" and "l%d" are the id and lun of the device.
For disk drives, there is also a "p%d" which indicates the partition number.

	The scsidev program should be run at boot time after the root
filesystem has been checked and marked R/W, and before you attempt to
use any other devices on the scsi bus.  Obviously the device number of
the root filesystem may have changed too, but this is controlled by lilo
and not by any /dev/ entries.

	At some point in the future, a checksum of some kind may be
generated by the kernel which would allow scsidev to quickly determine
whether anything has changed, but scsidev runs so quickly now that it is not
worth the trouble.

	If scsidev notices that an existing /dev/scsi entry exists but
the minor number is wrong, it saves the ownership and permissions and
applies these to the new /dev/scsi entry that is created.  Thus the
only thing that changes is effectively the minor number.

	There are a few options to scsidev:

	-v 
	   Verbose, used for debugging purposes (you need to use -v -v to get
	   anything).
	-f 
	   Flush /dev/scsi before creating anything.  All ownership and
	   permission information for /dev/scsi is lost.
	-m mode
	   Use mode as the permission mask for any new entries that need to be
	   created.
	-l
	   Symlink mode.  Symbolic links are created to the regular /dev
	   entries for scsi devices.  I am not sure why I added this, but
	   I thought it might be neat.
	-s
	   Print out serial numbers for all devices we detect.  Useful for
	   forming aliases.

ALIASES

	It is often useful to assign an alias name to a given device.
This is done through a configuration file /etc/scsi.alias, which
specifies the names of the aliases and enough information about
the device in order to uniquely identify the device.  Here are
some examples:

	serial_number="DX908FK", devtype=disk, alias=fourgig
	manufacturer=WANGTEK, devtype=tape, alias=qictape
	id=2, devtype=generic, alias=cdwriter

The name and devtype fields are required, everything else is just
to provide enough information to uniquely identify the device.
Given those lines, and the devices identifed above, the following
entries would be created in /dev/scsi:

crw-------   1 root     root      21,   1 Feb 25 01:59 cdwriter
brw-------   1 root     root       8,   0 Feb 25 01:59 fourgig
brw-------   1 root     root       8,   1 Feb 25 01:59 fourgig-p1
brw-------   1 root     root       8,   2 Feb 25 01:59 fourgig-p2
brw-------   1 root     root       8,   3 Feb 25 01:59 fourgig-p3
crw-------   1 root     root       9,   0 Feb 25 01:59 qictape
crw-------   1 root     root       9, 128 Feb 25 01:59 rqictape

The idea is that the qictape device will always point to a tape
drive created by wangtek.  The cdwriter will always point to a
device with an ID of 2, and the fourgig entries will always point
to a device with a serial number of "XYZZY".

For a list of all of the qualifiers that can be used to identify an
alias, see the scsidev man page.

BUGS:

	The only remaining issue that I know of is that booting will still
be affected by adding/removing devices.  Since the device number would change
as devices are added/removed, it means that you would be attempting to boot
the wrong disk.  This can be worked around with lilo, of course, but a better
solution is probably required.  We probably do not have room to store
additional information besides the major/minor that we already use.
It would be preferable if we could map these numbers to real physical
devices in some way.

	One solution would be to generate a mapping table when the
kernel is built that could be used to map the major/minor numbers into
the correct real device.

	When you boot the system, you still have a few limitations -
the boot disk usually must be ID 0, and there are issues related to the order
in which the scsi adapters are detected.

