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, Solaris, Tru64, and Windows.

Relationship to sg3_utils
-------------------------
This package shares code with sg3_utils (version 1.26). With the subversion
revision control system this is done by having sdparm's "include/" and "lib/"
subdirectories pointing to the correspondingly named directories in the
sg3_utils package using the "svn:externals" property. These two "external"
directories include more files than sdparm uses. The excess files include
"lib/Makefile.am" and "lib/Makefile.in". The "Makefile.am" in sdparm's "src/"
directory does the main part of the build. When the tarball is generated for
this utility, various files are "exported" out of the subversion repository
and "svn:externals" redirection is no longer visible (but the unused files
are visible).

Currently the shared code is statically compiled into sdparm. 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 utility outputs a usage message when the "--help" (or '-h' or '-?') option
is given. Many syntax errors also result in the usage message being printed.
There is also a man page which is in section 8 (administration and privileged
commands). 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 doc/sdparm.8".

There is a web page about this utility at http://sg.danny.cz/sg/sdparm.html .

Build infrastructure
--------------------
This packages uses the automake and autoconf tools. 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 , sg_lib.c and sg_lib_data.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 ). Vendor specific mode page information is found in the
sdparm_data_vendor.c file and is derived from vendor product manuals.

Notes
-----
Generic information about building this package (i.e. './configure ; make; 
make install') can be found in the INSTALL file. The contents of the COPYING
file is a FreeBSD license (rather than the GPL v2 found in the usual
template).

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. The man page and sg.danny.cz/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".

Solaris port
------------
Currently assumes gcc is present.


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


Win32 port
----------
This port only supports Windows NT, 2000, 2003, XP and Vista (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
a class driver device name and its associated volume name(s). Here are some
examples:
 $ sdparm -w
PD0     [C]     FUJITSU   MHY2160BH         0000
PD1     [DF]    WD        2500BEV External  1.05  WD-WXE90
CDROM0  [E]     MATSHITA DVD/CDRW UJDA775  CB03

Now request bus types as well.

 $ sdparm -ww
PD0     [C]     <Ata  >  FUJITSU   MHY2160BH         0000
PD1     [DF]    <Usb  >  WD        2500BEV External  1.05  WD-WXE90
CDROM0  [E]     <Atapi>  MATSHITA DVD/CDRW UJDA775  CB03

Now request a SCSI adapter scan as well.
 $ sdparm -www
PD0     [C]     <Ata  >  FUJITSU   MHY2160BH         0000
PD1     [DF]    <Usb  >  WD        2500BEV External  1.05  WD-WXE90
CDROM0  [E]     <Atapi>  MATSHITA DVD/CDRW UJDA775  CB03

SCSI0:0,0,0   claimed=1 pdt=0h  FUJITSU   MHY2160BH         0000
SCSI1:0,0,0   claimed=1 pdt=5h  MATSHITA  DVD/CDRW UJDA775  CB03

And finally here is a more interesting example showing disks with no
Windows (2000) volumes, a tape drive and a wierd unclaimed SCSI
pseudo device with BCC (Bridge Controller Commands) peripheral device
type.
 $ sdparm -www
PD0     [C]     <Ata  >  ST380011A  8.01
PD1             <Scsi >  SEAGATE   ST373455SS        2189
PD2             <Scsi >  ATA       ST3160812AS       D
PD3             <Scsi >  SEAGATE   ST336754SS        0003
CDROM0  [F]     <Atapi>  HL-DT-ST DVDRAM GSA-4163B  A103 
TAPE0           <Scsi >  SONY      SDT-7000          0192

SCSI0:0,0,0   claimed=1 pdt=0h dubious  ST380011  A                 8.01
SCSI1:0,0,0   claimed=1 pdt=5h          HL-DT-ST  DVDRAM GSA-4163B  A103
SCSI2:0,6,0   claimed=1 pdt=1h          SONY      SDT-7000          0192
SCSI5:0,17,0  claimed=1 pdt=0h          SEAGATE   ST373455SS        2189
SCSI5:0,19,0  claimed=1 pdt=0h          ATA       ST3160812AS       D
SCSI5:0,21,0  claimed=1 pdt=0h          SEAGATE   ST336754SS        0003
SCSI5:0,112,0 claimed=0 pdt=10h         LSI       PSEUDO DEVICE     2.34


Douglas Gilbert
20th September 2009
