SCSI command library for the Linux SG driver
--------------------------------------------


Copyright (c) 2002, 2003, Steve Thompson <stevet010@softhome.net>


This library is a harness for manipulating SCSI devices through the Linux SCSI
Generic driver.  When I started writing this, there were no tools or libraries
designed to embody the logic of the SCSI standard in an abstration layer for
programmers.

Manipulating bits and bit fields in byte arrays to construct a CDB is pretty
much how everyone does it, however that is rather inconvenient and does
nothing to address the multitude of commands which accept or return structured
data.  Additionally, the new SG driver is in itself a neater interface to the
SCSI layer of the kernel than the IOCTL interface ever was.  So, I thought it
would be nice to contrive structures and access methods for the SCSI command
set.  Hence, I wrote this library.  It makes the task of experimenting with
SCSI devices rather simple, and should help one understand the design
philosophy behind the SCSI standard.

Warning: this is alpha-class software containing rudimentary tools and can
severely fuck up your system if used carelessly.  By using this software, you
understand that any risk you assume is your own.  See the file `Licensing' for
detailed terms of use.



Requirements and Configuration:
-------------------------------

You need the SCSI generic driver version 3; it comes standard in 2.4.x and
later kernels.  A patch for 2.2.x series kernels is available at the SG driver
home: http://www.torque.net/sg.

You must be using GCC to compile this code at present.  It should not depend
on any particular version of libc, or any other standard system tools.

If you are not running on ix86, this code may not work.  When I wrote the
include files, I was not aware that structure bit-fields might be arranged
differently on big-endian machines.  I have not investigated this, and so you
may find that you'll have to rewrite some of the include files.

There is at present no install target, so if MCONFIG contains what appear to
you to be reasonable values, type 'make' from the top-level directory.


Library Functions
-----------------

The `opcodes' directory contains functions for the SCSI opcodes which I have
so far written.  Adding new opcodes is a relatively trivial task.  The `lib'
directory contains slightly higher level functions for use with the opcodes
and for doing minimal handling of the data sent from/to SCSI devices.  The
include directory contains defines for much of the SCSI II command set as it
pertains to chapter eight and nine of the SCSI II specification.  I've not yet
added functions for handling tape or ROM devices.

At present, IO is done simply with the SG_IO ioctl.  A queueing, non-blocking
IO model is planned.


Tools
-----

The `test' subdirectory contains a few short programs which are command-line
usable versions of some SCSI commands.  In addition, there is a program which
will scan your disk similarly to badblocks(8) and which will automatically
reassign bad sectors.  I have found this useful in conjunction with the format
command for resurrecting older disks and for making sure that they will work
without immediately failing.  The wrapper for the read_long opcode may be
useful for data recovery purposes.  Elsewhere, I have a disk copying utility
which will be released when it is fixed up and made presentable.


Support
-------

I will answer reasonable questions concerning this software or its use in the
context of non-commercial use free of charge.  If you require extensive
support, I may ask you to make other arrangements.


Plug
----

I am available for contract work to either enhance this library, or for
general consulting services pertaining to data recovery and writing code to
frob SCSI devices and similar.  Contact me via email to discuss specifics.

This code will need a home if it does not end up languishing in infancy; my
time is limited, and so without [financial] support, work on this code will
progress mostly according to my inclinations and the availability of copious
free time.  I am disinclined to avail myself of sourceforge.net and similar,
although I have not investigated alternatives in depth.  Suggestions are
welcome.  At the moment, the primary distribution site is metalab.unc.edu
in the /pub/linux/system/hardware directory, or in the commercial section
according to the inclination of the maintainers.


Politics
--------

In a perfect world, I would be happy to write, release, and maintain code
freely for the benefit of all.  This is not a perfect world.  It is my opinion
that the free software movement is being professionally manipulated and
exploited by corporate and government interests for purposes imnical to the
ideals attributed to the free software movement.  While there are people
working for commercial organisations who are doing honourable work, and who
are supporting free software in good faith, there are many who are not.

Many government and commercial groups are benefitting from the free research
and development efforts of thousands upon thousands of free software
developers while at the same time withholding knowledge gained from their own
R&D efforts.  Proprietary software is one thing.  Proprietary computer science
and engineering is something else altogether.  I believe that military forces
and contractors may be the worst in this regard by a rather large margin.

Thus, commercial use of this software is restricted.  Organisations which
require a license as indicated by the licensing terms of this package will be
considered on a case-by-case basis as to the terms by which I will allow their
use of my code.  My perception of the ethics of any putative licensee will
tend to govern my decisions in this regard.




Release History
---------------

January  2, 2003	First public release.

