sdparm 1.01

sdparm utility outputs and in some cases modifies SCSI device parameters. When the SCSI device is a disk, sdparms role is similar to its namesake: the Linux hdparm utility which is for ATA disks that usually have device names starting with "hd".
More generally sdparm can be used to output and modify parameters on any device that uses a SCSI command set. Apart from SCSI disks, such devices include CD/DVD drives (irrespective of transport), SCSI and ATAPI tape drives and SCSI enclosures. A small set of commands associated with starting and stopping the media, loading and unloading removable media and some other housekeeping functions can also be sent with this utility.
This utility currently contains over 500 entries spread across generic mode pages, transport specific mode pages, vendor specific mode pages, Vital Product Data (VPD) pages and their attributes. Rather than try and document all of these here (or in the man page), another approach is taken. This utilitys internal tables can be searched and output with the --enumerate option. Additional explanatory information is output when the --long option is used (and more if the --long option is used twice).
SCSI mode pages
Mode pages hold meta data about a SCSI device which can, in some cases, be changed by the user. In SCSI parlance the "device" is a logical unit of which there may be several in a SCSI target. In the case of a SCSI disk connected directly to a Host Bus Adapter (HBA) the disk is both a SCSI target and a logical unit. The "user" in this case is the person using sdparm which is a SCSI "application client" and it feeds commands into a SCSI initiator. The SCSI initiator is found in the HBA. At the command level SCSI is a client-server protocol with the logical unit (or target device) being the server that responds to commands sent by the application client via the SCSI initiator.
Mode pages are defined in SCSI (draft) standards found at www.t10.org . Mode pages common to all SCSI devices are found in the SCSI Primary Commands document (SPC-4) while those specific to block devices (e.g. disks) are found in SBC-3 and those for CD/DVD drives are found in MMC-5. This diagram shows how various SCSI and associated standards interrelate. Often device product manuals detail precisely which mode pages (and parts thereof) are supported by a particular model and describe the way that the device will react if the generic description in the SCSI (draft) standard needs amplification. There are also transport protocol specific mode pages for transports such as "spi" (the 25 year old SCSI Parallel Interface), "fcp" (Fibre Channel Protocol) and "sas" (Serial Attached SCSI). There are also vendor specific mode pages. Mode pages that are not transport protocol specific or vendor specific are sometimes referred to as "generic" in sdparms documentation.
To see a list of generic mode page names that sdparm has some information about use: sdparm -e. To see a list of transport specific mode page names that sdparm has some information about use (for example) sdparm -e -t sas. Both lists are sorted alphabetically by mode page abbreviation.
Mode pages are not the only mechanism in SCSI devices for holding meta data. Information which seldom if ever changes for a particular device may be found in the Vital Product Data (VPD) pages which are obtained via the SCSI INQUIRY command. Performance statistics are held in log pages which are obtained via the SCSI LOG SENSE command. Recent CD/DVD drives hold a lot of information in feature and profile descriptors (see MMC-4 and MMC-5) which are accessed via the SCSI GET CONFIGURATION command (see the sg_get_config utility in the sg3_utils package).
Each mode page has up to four tables associated with it. These can be thought of like tabs on a spreadsheet, with each tab containing the same size table. The four tables are:
current values: those values that are active at this time
changeable values: bit masks showing those values that the user may change
default values: the manufacturers default values
saved values: those values that will be active after the next power cycle (or format)
The saved values are optional. If the mask in the changeable values indicates a field can be changed then the corresponding field in the current values may be changed. A bit of 0 in the changeable values mask indicates the corresponding bit in the current values (and saved values) may not be changed. A bit of 1 in the changeable values mask indicates the corresponding bit in the current values (and saved values) may be changed. At the point when a current value is changed, the user may also choose to change the corresponding saved value.
The manufacturer obviously knows a lot about the characteristics of its devices. Hence if a current field value (and saved field value) is different from the default field value then there should be some rationale.
Some current values represent a state within the target device or logical unit. If that state changes so does the current value. Such values are not usually changeable by the user.
The sdparm utility has a --get, --set, --clear type of command line interface in which mode page fields are identified by an acronym. In many cases these acronyms will correspond precisely to the standard (e.g. "WCE" for Writeback Cache Enable in the caching mode page of SBC-3). For some longer fields the standards "spell out" a field name (e.g. "Write Retention Priority" in the caching mode page of SBC-3). In such cases the sdparm utility uses an acronym (e.g. "WRP"). In sdparm, acronyms across all generic mode pages are unique (i.e. an acronym matches at most one field of one generic mode page). Each transport protocol has its own namespace of acronyms so that an acronym is unique within a transport protocol. By default, saved values are not changed by --set and --clear. When changing the current values, the saved values can be changed as well by adding the --save. All the current values in a mode page can be changed back to the manufacturers defaults with the --defaults option (and the --save option here will additionally change the saved values back to the manufacturers defaults).
Changing some mode page fields is like jumping off a cliff holding onto a rope which you are not sure is properly secured. If in doubt, change the current value without using the --save option. That way if the setting is disastrous, power cycling the device will restore the previous setting. Once the new setting is known to be safe, then the sdparm utility can be re-executed with the --save option added.
sdparm commands
The --command= option allows a command to be sent to the given device. The currently supported commands are:
capacity: sends a READ CAPACITY and if successful reports the number of blocks, block length and capacity expressed in MibiBytes (1048576 bytes). Valid for disks and CD/DVD drives with the appropriate media loaded.
eject: stops the medium (if it is spinning) and ejects it from the drive. Note that this may be prevented by software in which case use the unlock command first.
load: loads the medium and then spins it up
ready: reports whether the medium is ready for IO. Ready usually means that it is present and spun up. If the device is not ready then the exit status will be 2 (see exit status section below).
sense: reports sense data (from a REQUEST SENSE SCSI command); can include power condition information, a progress indication for a time consuming command (e.g. format) or a report an informational exception (when MRIE=6)
start: spin up the medium
stop: spin down the medium
sync: send a SYNCHRONIZE CACHE SCSI command to the device.
unlock: instructs the device to allow medium removal (i.e. an eject). Beware, the OS may have had a good reason for preventing removal of the medium (e.g. it contains a mounted file system). Use at your own risk.
These sdparm commands send SCSI commands to the given DEVICE. If they dont seem to work, adding a verbose flag (i.e. -v or -vv) may provide more information. The "ready" and "sense" commands need read permissions on the DEVICE while the other commands need both read and write permissions.
Enhancements:
- Changes to SCSI mode and VPD pages that were introduced by t10.org since the last release were incorporated.
- The pass-through interface was updated, and code which is written in C was made to compile cleanly with C++.