head	1.2;
access;
symbols
	V1_6_7:1.2
	V1_6_6:1.2
	V1_6_5:1.2
	V1_6_4:1.2
	V1_6_3:1.2
	V1_6_2:1.2
	V1_6_1:1.2
	V1_6:1.2
	V1_5_2:1.2
	V1_4_1:1.2
	V1_4:1.1
	V1_3_3:1.1;
locks; strict;
comment	@# @;


1.2
date	95.10.06.05.58.54;	author vandys;	state Exp;
branches;
next	1.1;

1.1
date	94.10.05.19.40.46;	author vandys;	state Exp;
branches;
next	;


desc
@Initial RCS check-in of Mike Larson's SCSI subsystem
@


1.2
log
@1.4.1 SCSI update
@
text
@
		README for VSTa SCSI/CAM


Welcome to SCSI/CAM for VSTa.

This file contains a short description of the VSTa CAM environment,
instructions for configuring the driver, and a list of the source files
associated with the VSTa SCSI/CAM driver.

Except where noted in the source code and/or in this file, the
VSTa SCSI/CAM driver was written from scratch by Mike Larson
(larz@@world.std.com). The following notice applies to all files
in this distribution:

    Copyright (C) 1993-1995  Michael A. Larson

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 1, or (at your option)
    any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


Revision History
----------------

VSTa 1.4.1

	Add SCSI tape peripheral driver.

	Add autosense code.

	Some reorginization of the SIM code to allow both driver
	and per-HBA initialization.

	Bug fixes - fix disk accesses to LBN's > 1024K. Fix
	"can't allow media removal" on close message.

VSTa 1.3.2

	Add CDROM support.

	Make libcam.a - a library of functions that can be used
	by user code to format CCB's and CDB's.

	Add pass-thru code. This code allows CCB's and CDB's
	received from an application to be sent directly to
	peripheral devices.

	Move VSTa specific code out of peripheral device drivers.

	Some changes to the Adaptec 1542 driver, including the
	addition of bounce buffers for support of systems with
	greater than 16MB memory (this code is currently turned
	off, however), disabling of the extended BIOS (if enabled),
	support for no-bus-reset-on-boot etc. Note that adaptor
	autosense has been disabled to support REQUEST SENSE
	operations from the peripheral drivers.

	Some bug fixes and code clean up.

VSTa 1.3

	Add a generic peripheral driver to give limited support to
	not-yet-supported devices.

	Move/conditionalize disk specific code.

	Modify the peripheral disk driver to use the new libdpart
	library. Remove fdisk.c.

	Convert to syslog interface.

VSTa 1.2

	Initial revision of VSTA SCSI/CAM driver.


What is CAM?
------------

From the SCSI FAQ:

	QUESTION: What is CAM?
	ANSWER From: ctjones@@bnr.ca (Clifton Jones)
	====
	
	Common Access Method.
	
	It is a proposed ANSI standard to make it easier to program
	SCSI applications by encapsulating the SCSI functions into a
	standardized calling convention.

In CAM, the disk and tape drivers are called peripheral drivers (PDRV's
for short). At the top, PDRV's system level interface similar to that
of any other device driver in the operating system
(open/close/read/write/ioctl entry points for *nix, for example).
PDRV's do their job by sending SCSI commands down to the next CAM
layer, called the transport (or XPT) layer. The commands are contained
in a data structure called a CCB (CAM Control Block).

One of the jobs of the XPT layer is to route requests from the PDRV's
above to one of the SCSI Interface Modules (SIM's) below.  There may be
more than one SIM per system.

SIM's contain HBA (or dumb SCSI chip, etc.) specific code. The 154x
code is a SIM module, for example.


Quick VSTa SCSI/CAM Description
-------------------------------

The VSTa SCSI/CAM driver is loosley divided into three parts: code that
is relatively generic, code that is specific to VSTa, and hardware
specific code.

The generic code is simply a library of functions which may be called
by, or which may call functions in the VSTa code. The generic functions
include open/close/read/write/ioctl PDRV functions, most of the XPT
layer, and the "top part" the SIM layer (schedule the next request,
start a request, complete a request).

The VSTa specific code is responsible for sending and receiving
messages, interfacing with the operating system, dispatching to the
appropriate CAM code, and various utilities.

The hardware specific code is the "bottom" part of the SIM layer, which
interfaces to host adaptor hardware. Note that an attempt has been made
to package the necessary VSTa interfaces in a different module. This
may ease ports of drivers for host adaptors not currently supported by
VSTa.


Configuring the Driver
----------------------

The following explains how to get VSTa to "see" a root DOS filesystem
on a SCSI disk.

	Add or uncomment the following. This must go before the
	'DOS filesystem' section:

		# Adaptec 1542b/c SCSI disk support
		cam

	Add or uncomment the following in the 'DOS filesystem' section:

		# If your filesystem is on a SCSI disk, you might use:
		dos -p cam:sd0_dos0 fs/root

Note that 'sd0_dos0' is disk (target) 0 partition 0.  Substitute the
appropriate disk and partition numbers for other disk/partition
combinations.  For example, 'sd0_dos1' is disk 0 partition 1.

The SCSI/CAM server accepts the following command line options:

	-nobootbrst		don't do a SCSI BUS RESET during
				bootstrap initialization.

	-d N			sets the debug flags (see cam.h).
				'N' is either a decimal integer or
				a hexadecimal integer (with a leading
				"0x").


Peripheral Tape Interface Notes
-------------------------------

Access to SCSI tape drives is provided by the VSTa SCSI/CAM driver
Peripheral Tape driver.  The Peripheral tape driver supports standard
I/O operations, no rewind tape devices, magnetic tape I/O operations
(MTIO) commands, fixed and variable length block sizes, and various
other tape drive characteristics.

Access to tape devices is through the SCSI/CAM "raw" interface.  To use
this interface, you must first mount the SCSI/CAM server.  For example,
here's a sample /vsta/etc/fstab entry:

	cam	/dev/cam

Once the SCSI/CAM server is mounted, the various SCSI raw device
entries can be seen using the "ls" command. In general, SCSI tape
devices show up as "stN" and "nstN", where 'N' is the device's target
ID.

Non-read/write operations are performed using the VSTa stat/wstat
interface. The stat interface returns various tape device parameters.
The wstat interface accepts the following standard MTIO tape ioctl
commands.

	COMMAND		DESCRIPTION
	-------		-----------
	MTWEOF          write COUNT EOF records
	MTFSF           forward space COUNT filemarks
	MTBSF           backward space COUNT filemarks
	MTFSR           forward space COUNT records
	MTBSR           backward space COUNT records
	MTREW           rewind
	MTOFFL          rewind and put the drive offline (TBD)
	MTNOP           no operation, sets status only
	MTSETBSIZ       set (fixed length) block size
	MTSETDNSTY      set density
	MTSETDRVBUFFER	set device write buffer flags


Included in the VSTa distribution is the "mt" tape control program.
The VSTa version of "mt" is an "ash" script that wstat's the a tape
device with the appropriate command and count strings.

Note that VSTa 1.3.2 has only a small number of DMA map entries
(MAX_WIRED) allocated.  Correspondingly, the SCSI/CAM driver does
I/O in small increments (maximum I/O size currently = 4K).  For disks
this not a problem, since large I/O requests can be broken up into
smaller chunks.  But for tapes, I/O has to be done in a single operation,
so the tape peripheral driver limits the tape I/O size to CAM's maximum
I/O size.  What this means for tar is that the block count (1 tar block =
512 bytes) must be set appropriately.  For example:

	tar tvbf 8 /dev/cam/st4

sets the block size to 4k.


Tape I/O Performance
--------------------

On slower systems (like the one that the SCSI/CAM driver has been
developed on), its hard to get streaming tape drives to stream.  One
solution to this problem is to use a program like "dd" to 1) do disk
and tape I/O concurrently and 2) buffer up blocks before writing them.
For example:

	tar cvbf 256 - files_to_be_tared | dd of=/dev/cam/st4 ibs=128k obs=4k

and

	dd if=/dev/cam/st4 ibs=4k obs=128k | tar xvbf 256 - files_to_be_untared

given that the tape device is /dev/cam/st4 and the tape block size is 4k.


Source File Description
-----------------------

cam.h			- generic CAM definitions
camvsta.h		- VSTa CAM definitions (constants, macros, etc.)
diskpart.h		- disk partition definitions (adapted from
			  "wd/wd.h")
insque.h		- C library insque/remque definitions
scsi.h			- generic SCSI definitions
scsivsta.h		- VSTa SCSI definitions (some typedef's)


camdata.c		- configuration data
camerror.c		- debug/error logging functions
camtimer.c		- timer related functions
camutil.c		- non-server specific CAM utility functions.
camvsta.c		- VSTa CAM utilities (allocate memory, enable_io,
			  enable_isr, page_wire, etc.)
insque.c		- C library insque/remque
main.c			- main entry point and some peripheral driver functions
pdisk.c			- peripheral disk driver code
ptape.c			- peripheral tape driver code
pgen.c			- "generic" peripheral disk driver code
scsicd.c		- functions for formatting CD-ROM CCB's and CDB's.
scsicmds.c		- server SCSI command utilities.
scsicmn.c		- functions for formatting common CCB's and CDB's
scsidir.c		- functions for formatting SCSI DIRECT CCB's and CDB's.
scsiseq.c		- functions for formatting SCSI SEQUENTIAL CCB's and
			  CDB's.
sim.c			- generic CAM SIM code
sim154x.c		- the Adaptec 154x SIM driver
vstasrv.c		- VSTa server functions
vstautil.c		- misc. utility functions (parse a device name, etc.)
xpt.c			- CAM XPT code

@


1.1
log
@Initial revision
@
text
@d16 1
a16 1
    Copyright (C) 1993,1994  Michael A. Larson
d36 12
d175 76
d271 2
a272 1
pdisk.c			- VSTa specific peripheral disk driver code
@
