/*
 * Copyright (c) 1991-1997, by Sun Microsystems, Inc.
 * All Rights Reserved
 */


	ident	"@(#)README	1.13	97/09/12 SMI"

DRIVER NAME:
	bst.c - Sample Block SCSI Target driver; an example block SCSA target
	   driver for Solaris 2.6

ARCHITECTURES:
	SPARC, x86

DESCRIPTION OF DRIVER:
	This driver is intended as an example of programming a block SCSA
	target driver for SVR4; it is not intended for any particular
	direct access device, although it has been tested on a hard disk drive.

	The sparc version of the driver looks for a Sun-style disk 
	label (struct dk_label, as defined in <sys/dklabel.h>) on sector 
	zero of the device. The label contains the offsets and lengths of 
	each data slice on the device. The driver creates a minor device
	node for each slice, and uses the slice info from the label 
	to calculate the physical block number from the logical block requested.

	The x86 version looks for fdisk and AT386 disk label information.

	This driver also supports the "DKIO" ioctls necessary to format and
	slice the disk (defined in <sys/dkio.h>).

	Note that the label and DKIO ioctl features of the drivers are
	not strictly DDI/DKI-compliant, but also that there is no
	strictly DDI/DKI-compliant means to deal with disk labelling
	and ioctl's.

	The other major difference between this and the character-only driver
	(sst) is that this driver supports I/O request queueing.

	Terminology in this driver:
		"instance" - this device, e.g. the disk drive
		"slice" - the part of the device ("slice") that's being 
		    accessed
	The instance and slice are coded into the minor device number; the
	slice is the low 5 bits (i.e. up to 16 slices and 5 fdisk
	partitions), and the instance is the rest (i.e. bits 5 - 15).

	Source Files
	-------------

	bst.c		driver source
	bst.conf	driver configuration file
	bst_def.h	driver definitions

CAVEATS AND CONSTRAINTS:

	The ARQ uscsi handling is not completely implemented in the driver;
	USCSI_RQENABLE is not checked so request sense data are lost for
	uscsi commands.


NOTE:
	Areas where you may need to change this code or add your own to
	deal with your specific device are marked "Note".
	Other warnings are marked "WARNING"

COMPILING/LOADING:

	To compile and link the driver:

	use the Makefile provided in the driver subdirectory,
	src/driver_dev/bst; the executable files will be built in an
	architecture-specific subdirectory depending on the architecture
	of the build machine (i.e., bst/i386 or bst/sparc)

	to compile and link without using the Makefile:

	% cc -D_KERNEL -c bst.c
	% ld -r bst.o -o bst

	To install:

	1. sh -v Install.sh

	   Copies the module (i386/bst or sparc/bst) and config file
	   (bst.conf) into /kernel/drv

	2. Run add_drv(1M).

		# add_drv bst

	To test:

	Most of the disk and file system utilities (such as newfs, format,
	fsck, mount, etc.) will work with disks running under the bst driver.
	These utilities can be used to test the driver's functionality.

	add_drv causes special files to be created in the /devices 
	subdirectory for the bst disk(s) as described in the drvconfig
	manual page.

	There is a "raw" and "block" special file for each slice
	on the disk.  You should use these names (i.e., provide them
	as arguments to the disk utililites) to access the bst device.

	Setting variables:
	    Variables can be explicitly set from the /etc/system file, by
	    adding an entry of the form

		"set bst:<variable name>=<value>"

	    The /etc/system file is read only once at boot time, if you change
	    it you must reboot for the change to take effect.

	    Alternatively, you can use adb to set variables and debug as
	    follows:

		# adb -kw /dev/ksyms /dev/mem

	    Or, if you booted under kadb, you can set the a variable from the
	    kadb prompt. For example, the following command will set the
	    variable bst_debug to the value 3 (maximum debugging messages):

		kadb[0]: bst_debug:W 3

LOCKLINT:

	To build the LockLint file and run lock_lint:

	use the Makefile.llint provided in the driver subdirectory,
	src/driver_dev/bst, to build bst.ll.
	Then take a look at the DDK LockLint support documentation for
	help an running lock_lint(1).

	% make -f Makefile.llint bst.ll

REFERENCES:
	
        SunOS 5.6 Writing Device Drivers
