Manual page for generic SCSI subsystem; from FreeBSD

2 files changed, 159 insertions, 3 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 7b2169e153b..4e98c8b422c 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1,11 +1,11 @@
-#	$OpenBSD: Makefile,v 1.10 1996/08/04 06:26:13 downsj Exp $
+#	$OpenBSD: Makefile,v 1.11 1996/08/04 20:28:20 tholo Exp $
 #	$NetBSD: Makefile,v 1.22.4.2 1996/07/18 00:51:10 jtc Exp $
 #	@(#)Makefile	8.1 (Berkeley) 6/18/93
 
 MAN=	audio.4 acd.4 ahc.4 bpf.4 ccd.4 clnp.4 cltp.4 ddb.4 drum.4 esis.4 \
 	fd.4 icmp.4 idp.4 imp.4 inet.4 ip.4 ipl.4 iso.4 lkm.4 lo.4 \
-	netintro.4 ns.4 nsip.4 null.4 pty.4 rnd.4 route.4 spp.4 tb.4 tcp.4 \
-	termios.4 tty.4 tp.4 udp.4 unix.4 vnd.4
+	netintro.4 ns.4 nsip.4 null.4 pty.4 rnd.4 route.4 scsi.4  spp.4 tb.4 \
+	tcp.4 termios.4 tty.4 tp.4 udp.4 unix.4 vnd.4
 MLINKS+=fd.4 stderr.4 fd.4 stdin.4 fd.4 stdout.4
 MLINKS+=netintro.4 networking.4
 MLINKS+=rnd.4 srnd.4 rnd.4 urnd.4 rnd.4 prnd.4
diff --git a/share/man/man4/scsi.4 b/share/man/man4/scsi.4
new file mode 100644
index 00000000000..85c6cb91439
--- /dev/null
+++ b/share/man/man4/scsi.4
@@ -0,0 +1,156 @@
+.\"	$OpenBSD: scsi.4,v 1.1 1996/08/04 20:28:20 tholo Exp $
+.\"
+.Dd August 4, 1996
+.Dt SD 4
+.Os OpenBSD
+.Sh NAME
+.Nm scsi
+.Nd scsi system
+.Sh SYNOPSIS
+.Nm scsibus* at aha?
+.Nm scsibus* at ncr?
+.Nm device cd* at scsibus? target ? lun ?
+.Nm device ch* at scsibus? target ? lun ?
+.Nm device sd* at scsibus? target ? lun ?
+.Nm device st* at scsibus? target ? lun ?
+.Nm device ss* at scsibus? target ? lun ?
+.Nm device su* at scsibus? target ? lun ?
+.Nm device uk* at scsibus? target ? lun ?
+.Sh DESCRIPTION
+The
+.Em scsi
+system provides a uniform and modular system for the implementation
+of drivers to control various scsi devices, and to utilize different
+scsi host adapters through host adapter drivers. When the system probes the 
+.Em SCSI
+busses, it attaches any devices it finds to the appropriate
+drivers. If no driver seems appropriate, then it attaches the device to the
+uk (unknown) driver so that user level scsi ioctls may
+still be performed against the device.
+.Sh KERNEL CONFIGURATION
+The option SCSIDEBUG enables the debug ioctl.
+.Pp
+All devices and the SCSI busses support boot time allocation so that
+an upper number of devices and controllers does not need to be configured;
+.Em "device sd* at scsibus? target ? lun ?"
+will suffice for any number of disk drivers.
+.Pp
+The devices are either
+.Em wired
+so they appear as a particular device unit or
+.Em counted
+so that they appear as the next available unused unit.
+.Pp
+To configure a driver in the kernel without wiring down the device use a
+config line similar to
+.Em "device ch* at scsibus? target ? lun ?"
+to include the changer driver.
+.Pp
+To wire down a unit use a config line similar to
+.Em "device ch1 at scsibus0 target 4 lun 0"
+to assign changer 1 as the changer with SCSI ID 4,
+SCSI logical unit 0 on SCSI bus 0.
+Individual scsibuses can be wired down to specific controllers with
+a config line similar to
+.Em "scsibus0 at ahc0"
+which assigns scsi bus 0 to the first unit using the ahc driver.
+For controllers supporting more than one bus,
+the particular bus can be specified as in
+.Em "scsibus3 at ahc1 bus 1"
+which assigns scsibus 1 to the second bus probed on the ahc1 device.
+.Pp
+When you have a mixture of wired down and counted devices then the
+counting begins with the first non-wired down unit for a particular
+type.  That is, if you have a disk wired down as
+.Em "disk sd1 at scsibus? target ? lun ?" ,
+then the first non-wired disk shall come on line as
+.Em sd2 .
+.Sh IOCTLS
+There are a number of ioctls that work on any 
+.Em SCSI
+device. They are defined in
+.Em sys/scsiio.h
+and can be applied against any scsi device that permits them.
+For the tape, it must be applied against the control
+device. See the manual page for each device type for more information about
+how generic scsi ioctls may be applied to a specific device.
+.Bl -tag -width DIOCSDINFO____
+.It Dv SCIOCRESET*
+reset a device.
+.It Dv SCIOCDEBUG
+Turn on debugging.. All scsi operations originating from this device's driver
+will be traced to the console, along with other information. Debugging is
+controlled by four bits, described in the header file. If no debugging is
+configured into the kernel, debugging will have no effect. 
+.Em SCSI
+debugging is controlled by the configuration option
+.Em SCSIDEBUG.
+.It Dv SCIOCCOMMAND
+Take a scsi command and data from a user process and apply them to the scsi
+device. Return all status information and return data to the process. The 
+ioctl will return a successful status even if the device rejected the
+command. As all status is returned to the user, it is up to the user
+process to examine this information to decide the success of the command.
+.It Dv SCIOCREPROBE
+Ask the system to probe the scsi busses for any new devices. If it finds
+any, they will be attached to the appropriate drivers. The search can be
+narrowed to a specific bus, target or lun. The new device may or may not
+be related to the device on which the ioctl was performed.
+.It Dv SCIOCIDENTIFY
+Ask the driver what it's bus, target and lun are.
+.It Dv SCIOCDECONFIG
+Ask the device to disappear. This may not happen if the device is in use.
+.El
+.Sh NOTES
+the generic scsi part of the system is still being mapped out.
+Watch this space for changes.
+.Pp
+ A device by the name of su (scsi_user)
+(e.g  su0-0-0) will map bus, target and lun to  minor numbers. It has not
+yet decided yet whether this device will be able to open a device that is
+already controlled by an explicit driver.
+.Sh ADAPTERS
+The system allows common device drivers to work through many different
+types of adapters. The adapters take requests from the upper layers and do
+all IO between the 
+.Em SCSI
+bus and the system. The maximum size of a transfer is governed by the
+adapter. Most adapters can transfer 64KB in a single operation, however
+many can transfer larger amounts.
+.Sh TARGET MODE
+Some adapters support 
+.Em target mode
+in which the system is capable of operating as a device, responding to
+operations initiated by another system. Target mode will be supported for
+some adapters, but is not yet complete for this version of the scsi system.
+.Sh DIAGNOSTICS
+When the kernel is compiled with option SCSIDEBUG, the SCIOCDEBUG ioctl 
+can be used to enable various amounts of tracing information on any 
+specific device. Devices not being traced will not produce trace information.
+The four bits that make up the debug level, each control certain types
+of debugging information. 
+.Bl -tag -width "Bit 0"
+.It Dv Bit 0
+shows all scsi bus operations including scsi commands,
+error information and the first 48 bytes of any data transferred.
+.It Dv Bit 1
+shows routines called.
+.It Dv Bit 2
+shows information about what branches are taken and often some
+of the return values of functions.
+.It Dv Bit 3
+shows more detailed information including DMA scatter-gather logs.
+.El
+.Sh SEE ALSO
+.Xr ch 4 ,
+.Xr cd 4 ,
+.Xr sd 4 ,
+.Xr ss 4 ,
+.Xr st 4 ,
+.Xr su 4
+and
+.Xr uk 4
+.Sh HISTORY
+This
+.Nm
+system appeared in MACH 2.5 at TRW.