Introduction
------------
sdparm is a utility for listing and potentially changing SCSI disk
parameters. More generally it can be used on any device that uses
a SCSI command set. Apart form SCSI disks, examples of devices that
use SCSI command sets are ATAPI CD/DVD drives, SCSI and ATAPI tape
drives and SCSI enclosures.

This utility was originally written for Linux. It has been ported
to FreeBSD, Tru64, and Windows.

Relationship to sg3_utils
-------------------------
This package shares code with sg3_utils (version 1.24).
sg3_utils is a package of utilities that typically act at the SCSI
command level. sg3_utils is written by the same author. The shared code
(sg_lib.[hc] and sg_cmds_basic.[hc]) includes tables of SCSI command
names and additional sense code descriptions as well as functions for
issuing common SCSI commands.

Currently the shared code is statically compiled in to each package.
It is the intention of the author to make a common library called
libsgutils.so in a separate package that both sdparm and sg3_utils
will depend on at some point in the future.

Documentation
-------------
The executable outputs a usage message when the "--help" (or '-h)
option is given. Many syntax errors also result in the usage message
being printed. There is also a man page which is in chapter 8. It
can be accessed with "man sdparm" once this package is installed. Prior
to installation the man page can be viewed from this package's
main directory with "man ./sdparm.8".

There is a web page at http://www.torque.net/sg/sdparm.html and
a copy of that html file is placed in the "doc" directory.

Build infrastructure
--------------------
This is the first time the author has used the automake and autoconf
tools. So anybody who has problems or suggestions please contact the
author. The generating files (scripts) are configure.ac, Makefile.am,
src/Makefile.am and autogen.sh . The autogen.sh script only needs
to be executed if one of the other generating files in the above list
is changed.

There is a rpm "spec" file in the main directory: sdparm.spec .
There are debian build files in the "debian" directory and a
script called build_debian.sh in the main directory.

License
-------
This utility is covered by a FreeBSD license. The intention of the author
is that both open source and commercial entities can re-use this code.
Naturally credit and improvement/bug feedback are encouraged. The part
of this code that others may be able to re-use is the information in
the tables in sdparm_data.c and sg_lib.c . This is information garnered
from "SCSI" drafts and standards at http://www.t10.org (plus some
information from the ATA drafts and standards at http://www.t13.org ).

Notes
-----
The following files were symlinks to /usr/share/automake-1.9 generic
files on the author's system. That doesn't seem useful to put in
a tarball so versions were copied. Former symlinks:
   - config.guess
   - config.sub
   - depcomp
   - install-sh
   - missing
The above file copies have been updated to match with automake version
1.9.5 as found in Fedora Core 4 (linux).
The contents of INSTALL have been replaced by more specific instructions.
The contents of COPYING is a FreeBSD license (rather than the GPL v2).

Linux port
----------
The utility can be used on any device that supports the SG_IO ioctl. In
the linux 2.4 series that is only the scsi generic (i.e. /dev/sg* )
device nodes. In the linux 2.6 series the supported device nodes has
expanded to all other SCSI device nodes (e.g. /dev/sd* and /dev/sr*)
plus block devices such as /dev/hdc when the associated device is a
DVD drive. Most man page and www.torque.net/sg/sdparm.html web page
examples use linux device node names.

FreeBSD port
------------
Virtually all of sdparm's features work with FreeBSD. SCSI commands are
routed through the CAM pass through interface. The author tested sdparm
with FreeBSD version 5.3 and found SCSI disks worked with the "da" device
(e.g. 'sdparm  /dev/da0'). SCSI tape drives can be accessed via the "sa"
device via /dev nodes starting with "esa", "nsa" and "sa". To access cd/dvd
drives, the kernel needs to be build with the "atapicam" device after which
access is via the "cd" device. Other SCSI devices are "ses" (for enclosure
services), "ch" (media changer (for tapes)), and "pr" for processor device
type (e.g. SAF-TE devices). All these device may also be accessed via
the "pass" device. To see the mapping between the "pass" device name and
the corresponding higher level device node try "camcontrol devlist".


Tru64 (osf) port
----------------
??


Win32 port
----------
This port only supports Windows NT, 2000, 2003 and XP (not 95, 98, ME or
earlier). It uses the Microsoft SCSI Pass Through "Direct" (SPTD) rather
than ASPI32 which requires a dll from Adaptec.

The source can be built in a cygwin environment and can run in a cygwin
bash shell. It can also run in a DOS shell if the cygwin1.dll is put in an
appropriate place.
Alternatively the source can be built with the MinGW compiler using its
MSYS shell. This removes the dependence on the cygwin1.dll file.

The device naming schemes attempt to follow what DOS does, with a few short
cuts. If volume "D:" is an ATAPI DVD drive then the actual file opened
is "\\.\D:". All device nodes of interest to sdparm have a leading "\\.\"
so if the user doesn't supply it, sdparm will. Thus 'sdparm d:' should work.
Note that volume names map to Windows partitions so there can be multiple
volume names per disk. SCSI devices (or those that use a SCSI command set)
can also be accessed via their "class" driver. These have names
like "PhysicalDrive<n>", "CDROM<n>" and "TAPE<n>" where <n> is a number
starting at 0. Since "PhysicalDrive" is tedious to type, a shortened
form "PD" is accepted.  So if "PD3" is a SCSI disk (or a SATA disk behind
a SAT layer) then 'sdparm pd3' should work.

Finally there is a lower level "SCSI<n>:" interface that addresses a SCSI
adapter. The device needs further sub-addressing in the form of a bus
number (also called a PathId), a target identifier and a lun (logical
unit number). sdparm uses this notation: "SCSI<n>:<bus>,<target>,<lun>".
The trailing ",<lun>" may be omitted in which case a lun of 0 is assumed.
Once a device has been "claimed" by an upper level "class" driver the
OS will not allow it to be accessed via the "SCSI<n>:" interface. Hence
this is only needed for special devices (e.g. with processor or SES
peripheral device type) that are not claimed by the class drivers.

The '--wscan' (or '-w') option has been added to show the mapping between
the volume name(s), class driver name and the "SCSI<n>:" name. It attempts
to place all device names for the same device on the same line followed
by its INQUIRY string. Unfortunately each USB or IEEE 1394 device may
appear on two lines. Here is an example of the output:

# sdparm -w
SCSI0:0,0,0       C:    PD0      IC25N040ATCS05-0        CS4O  *
SCSI1:0,0,0       D:    CDROM0   HITACHI DVD-ROM GD-S200 0034
SCSI2:0,0,0       I: +  PD5      QUANTUM LPS525S         3110
SCSI2:0,6,0             TAPE0    SONY    SDT-7000        0192
                  E:             Generic USB SD Reader   1.00  pdt=0
                        PD1      Generic USB SD Reader   1.00

The last two lines are actually one device. The "*" at the end of
the first line flags that the SCSI-2 INQUIRY response is not quite
correct, usually indicative of an ATA disk. The "+" after the "I:"
indicates that several volume names (letters) map to that device.
That usually means there are two or more partitions which Windows
recognizes. Devices for which no class device name is found
(e.g. the column that starts with "PD0" above) have their SCSI
"peripheral device type" (pdt) value placed at the end of the line.
The longer "PhysicalDrive" name, shown in Windows documentation,
may be used but "PD" is obviously quicker to type.


Douglas Gilbert
5th April 2007
