The Linux sdparm utility

Introduction
SCSI mode pages
VPD pages
sdparm commands
sdparm syntax
linux kernel series
Examples
Downloads
Conclusion

Introduction

The sdparm utility outputs and in some cases modifies SCSI device parameters. When the SCSI device is a disk, sdparm's role is similar to its Linux namesake: hdparm 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.

The information in this page corresponds to sdparm version 0.94 .

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 their 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.

Mode pages are defined in SCSI (draft) standards found at www.t10.org . Mode pages common to all SCSI devices are found in SPC-3 while those specific to block devices are found in SBC-2 and those for CD/DVD drives are found in MMC-5. SCSI device product manuals detail precisely which mode pages (and parts thereof) are supported by a particular model and describe the way 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 20 year old SCSI Parallel Interface), "fcp" and "sas" (Serial Attached SCSI). Mode pages that are not transport protocol specific are sometimes referred to as "generic" in sdparm's documentation.

Mode pages are not the only mechanism in SCSI devices for holding metadata. 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 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 as tabs on a spreadsheet, with each tab containing the same size table. The four 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 manufacturer's 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. At the point when a current value is changed, the user may also choose to change the corresponding saved value (if saved values are supported). A bit of 1 in the changeable values mask indicates the corresponding bit in the current values (and saved 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.

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.

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 cache mode page of SBC-2). For some longer fields the standards "spell out" their names (e.g. "Write Retention Priority" in the cache mode page of SBC-2). In such cases the sdparm utility uses its acronym (e.g. "WRP"). In sdparm acronyms across all generic mode pages are unique (i.e. an acronym matches 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" (since saved values may not be supported). To change saved values as well the "--save" option additionally needs to be given. The current values can be changed back to the manufacturer's defaults with the "--defaults" option (and the "--save" option here will additionally change the saved values back to the manufacturer's defaults).

Changing some mode page fields is a 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 command can be re-executed with the "--save" option added.

VPD pages

Vital Product Data (VPD) pages are associated with the SCSI INQUIRY command. While support for a "standard" INQUIRY response is mandatory, support for VPD page has been optional in the past. The current SPC-3 draft makes support for the Device Identification VPD page mandatory.

VPD pages are read only and in some situations may not be available (e.g. if the media is spun down). They tend to have a variable number of descriptors (rather than a predictable size with parameters in known positions such as most mode pages). A VPD page number can be selected with the '--page=' option; if not given then the Device Identification VPD page (page number 0x83 or abbreviation "di") is assumed. The device identification page has three associations. The SCSI Architectural Model (see SAM-3 at www.t10.org) may help in explaining these associations. Each device identification descriptor belongs to one (and only one) of these associations:

addressed logical unit
target device port that received request
target device containing addressed logical unit

Any descriptors found are grouped in the order of the above list. If there are no descriptors of a given type of association then the heading is not output.

VPD pages that are currently decoded:

Supported VPD pages [page 0x0]; page abbreviation: "sv"
Unit serial number [page 0x80]; page abbreviation: "sn"
Device identification [page 0x83]; default, page abbreviation: "di"
SCSI Ports [page 0x88]; page abbreviation: "sp"

Currently no other VPD pages are decoded. If another VPD page is requested and the device gives a response then that response it output in ASCII hex. VPD page abbreviations can be listed with "sdparm --enumerate --inquiry".

sdparm commands

The "--command=" option allows a command to be sent to the given device. Currently the supported commands may be useful for devices with removable media. Those commands are:

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. This usually means that it is present and spun up.
start: spin up the medium
stop: spin down the medium
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 don't seem to work, adding a verbose flag (i.e. "-v" or "-vv") may provide more information. The "ready" command needs read permissions on the given device, the other commands need both read and write permissions.

sdparm syntax

sdparm is a command line utility which takes zero or more options usually followed by a device name. Only invocations that use the '--enumerate' option do not need a device name. Invocations with a device name and no options will check that device for mode pages in which there are "common" parameters (mode page fields). Common parameters are a somewhat arbitrary subset of the hundreds of parameters available (chosen by the author).

Options have either a long format, as shown in the first column below, or a short format, as shown in the second column. Either format can be used. Note that long options that take an argument (e.g. "--get=WCE") use an equal sign ("=") as a separator while short options use a space as a separator (e.g. "-g WCE").

Table 1. sdparm command line options
long option format	short option format	description
--all	-a	list all known parameters for given device. When this utility is invoked with no options then only common parameters are output.
--clear=<str>	-c <str>	clear (zero) parameter(s) in <str>. The default action to clear can be overridden, see below.
--command=<cmd>	-C <cmd>	perform <cmd> which is one of: eject, load, ready, start, stop or unlock
--dbd	-B	set the DBD (disable block descriptors) bit in each MODE SENSE cdb
--defaults	-D	fetch the default values for the given mode page and use them to overwrite the current values. Note that the saved values are not overwritten unless the "--save" option is also given.
--dummy	-d	when used with '--set' or '--clear' does all the preparation and checks but bypasses the final stage of sending the changes to the device. [It skips the MODE SELECT command.]
--enumerate	-e	fetch information from the sdparm's internal tables. If a SCSI device name is given then it will be ignored. May be used in conjunction with '-all', '--inquiry' and/or '--page='.
--flexible	-f	check mode sense responses for sanity and if broken, try to fix them if possible. Also allows mode pages whose peripheral type mismatches the given device to be listed.
--get=<str>	-g <str>	fetch parameter(s) in <str>
--help	-h	output a usage message then exits
--hex	-H	rather than decode a (mode or VPD) page, it is output in ASCII hex. If used with the '--get' option then the parameter is output in hexadecimal.
--inquiry	-i	fetch a VPD page, decode and output it. If no '--page=' is given then the device identification VPD page is fetched. If this option is not given then this utility defaults to mode page(s).
--long	-l	Add extra information to the output. For example a line showing the setting of the WCE parameter will have "Write cache enable" appended to it.
--page=<pg[,spg]>	-p <pg[,spg]>	page (and optionally subpage) to output or change. Argument may be either a number (assumed to be decimal) or two numbers separated by a comma. If the number are prefixed by "0x" they are assumed to be hexadecimal). Alternatively a two letter (lower case) abbreviation can be given.
--save	-S	also write changes to corresponding "saved" mode page. The default action is to only make changes to the current mode page.
--set=<str>	-s <str>	set parameter(s) in <str>. To set a parameter is to make all its bits one. The default action to set can be overridden, see below.
--six	-6	use 6 byte cdbs for MODE SENSE and MODE SELECT commands for getting and setting mode pages. The default action is to use the 10 byte cdb variants.
--transport=<tn>	-t <tn>	transport protocol identifier; either a number or an abbreviation (e.g. "fcp", "spi" or "sas")
--verbose	-v	increase verbosity of output. May be used multiple times to increase verbosity further.
--version	-V	print out the version and the date of last code change then exits

The arguments given to "--clear=", "--get=" and "--set=" require a "<str>". The <str> argument is a comma separated list of acronyms or numeric descriptors. Each acronym or numeric descriptor can optionally be followed by "=<value>". The "<value>" is assumed to be decimal unless prefixed by "0x". Numeric descriptors are three numbers separated by colons of the form: "<start_byte>:<start_bit>:<num_of_bits> . The <start_byte> begins at zero; the <start_bit> is 7 for the most significant bit (msb) and 0 for the lsb; while the <num_of_bits> should be a value between 1 and 64 inclusive.

For "--clear=" and "--set=" the "<value>" is the unsigned integer value to set that parameter to. The "<value>" of -1 is a special case in which all the bits in the parameter are set to one. For a '"--set=" option the default action (in the absence of "=<value>") is the same as "=-1". For a '"--clear=" option the default action (in the absence of "=<value>") is the same as "=0".

If sdparm is used to change parameters and that operation succeeds (or at least no error is reported) then only INQUIRY device identification information is output and the sdparm process exits with a value of 0. If sdparm is used to change parameters and that operation fails then error information is output (usually to stderr) and the sdparm process exits with a value of 1.

For "--get=" the "<value>" is not normally given. If given then it is interpreted as a formatting instruction for which the value of 0 is the default. For mode pages the default format for "--get=" is the acronym followed by the current value and then the changeable, default and saved values in brackets. If a value of 1 is given then only the acronym followed by the current value are output.

The "--enumerate" option ignores the given device name (if given) and outputs information from the tables within the sdparm utility. With no other options, mode page abbreviations followed by their full names are output. If the "--inquiry" option is also given the VPD page abbreviations followed by their full names are output. If the "--enumerate --page=" options are given then within the selected mode page, the name of each known acronym, its numeric descriptor and its full name is output.

linux kernel series

sdparm is designed for both the linux kernel 2.6 and 2.4 series. There are some slight differences between the two environments.

In the linux kernel 2.6 series sdparm uses the SG_IO ioctl which is implemented for all SCSI devices and many other devices that are not considered as "SCSI" but use a SCSI command set. An example of the latter case is an ATAPI DVD drive which uses MMC (a SCSI command set) and implements the SG_IO ioctl so sdparm will work with it (in the lk 2.6 series).

In the linux kernel 2.4 series sdparm will work on all devices that use the SCSI subsystem. Internally it maps the given SCSI device to the corresponding SCSI generic (sg) device which implements the SG_IO ioctl. Hence an ATAPI DVD drive will only be accessible to sdparm if the device is mapped through to the SCSI subsystem with the ide-scsi driver.

Examples

List the common (mode) parameters of a disk:
# sdparm /dev/sda
    /dev/sda: SEAGATE ST336732LC        ABCD
Read write error recovery mode page:
AWRE        1 [cha: y, def: 1, sav: 1]
ARRE        1 [cha: y, def: 1, sav: 1]
PER         0 [cha: y, def: 0, sav: 0]
Caching (SBC) mode page:
WCE         0 [cha: y, def: 0, sav: 0]
RCD         0 [cha: y, def: 0, sav: 0]
Control mode page:
SWP         0 [cha: n, def: 0, sav: 0]
Informational exceptions control mode page:
EWASC       1 [cha: y, def: 1, sav: 1]
DEXCPT      0 [cha: y, def: 0, sav: 0]
MRIE        4 [cha: y, def: 2, sav: 4]

List the descriptors within the device identification VPD page of a disk. [VPD pages are fetched with the SCSI INQUIRY command.]:
# sdparm --inquiry /dev/sda
    /dev/sda: SEAGATE ST336732LC        ABCD
Device identification VPD page:
Addressed logical unit:
    id_type: T10 vendor identification, code_set: ASCII
      vendor id: SEAGATE
      vendor specific: ST336732LC      3ET0D3P4
    id_type: EUI-64 based, code_set: Binary
      [0x0004cffffe73c07b]

See all parameters for the read write error recovery mode page:
# sdparm --page=rw /dev/sda
    /dev/sda: SEAGATE   ST336732LC        ABCD
Read write error recovery mode page:
AWRE        1 [cha: y, def: 1, sav: 1]
ARRE        1 [cha: y, def: 1, sav: 1]
TB          0 [cha: y, def: 0, sav: 0]
RC          0 [cha: y, def: 0, sav: 0]
EER         0 [cha: y, def: 0, sav: 0]
PER         0 [cha: y, def: 0, sav: 0]
DTE         0 [cha: y, def: 0, sav: 0]
DCR         0 [cha: y, def: 0, sav: 0]
RRC        11 [cha: y, def: 11, sav: 11]
WRC         5 [cha: y, def: 5, sav: 5]
RTL        -1 [cha: y, def: -1, sav: -1]

See all parameters for the read write error recovery mode page with acronym descriptions:
# sdparm --page=rw --long /dev/sda
    /dev/sda: SEAGATE ST336732LC        ABCD
Read write error recovery [PS=1] mode page:
AWRE        1 [cha: y, def: 1, sav: 1] Automatic write reallocation enabled
ARRE        1 [cha: y, def: 1, sav: 1] Automatic read reallocation enabled
TB          0 [cha: y, def: 0, sav: 0] Transfer block
RC          0 [cha: y, def: 0, sav: 0] Read continuous
EER         0 [cha: y, def: 0, sav: 0] Enable early recover
PER         0 [cha: y, def: 0, sav: 0] Post error
DTE         0 [cha: y, def: 0, sav: 0] Data terminate on error
DCR         0 [cha: y, def: 0, sav: 0] Disable correction
RRC        11 [cha: y, def: 11, sav: 11] Read retry count
WRC         5 [cha: y, def: 5, sav: 5] Write retry count
RTL        -1 [cha: y, def: -1, sav: -1] Recovery time limit (ms)

Get the Writeback Cache Enable (WCE) values from the caching control mode page:
# sdparm --get=WCE /dev/sdd
    /dev/sdd: SEAGATE ST373453LC        ABCD
WCE         0 [cha: y, def: 0, sav: 0]

Get the Write Cache Enable (WCE) values from the caching control mode page in hex (using short option form). The four values are the current value, the changeable mask, the default value and the saved value respectively:
# sdparm -g WCE -H /dev/sdd
0x00 0x01 0x01 0x00

Get the Write Cache Enable (WCE) current value from the caching control mode page in hex:
# sdparm -g WCE=1 -H /dev/sdd
0x00

Set the "write cache enable" current value in the caching control mode page. Note that only INQUIRY identification information is output; if an error occurs then more information is output (and the sdparm process exits with a non-zero status):
# sdparm --set=WCE /dev/sdd
    /dev/sdd: SEAGATE ST373453LC        ABCD

Check that change occurred:
# sdparm --get=WCE /dev/sdd
    /dev/sdd: SEAGATE ST373453LC        ABCD
WCE         1 [cha: y, def: 1, sav: 0]

Change both the current and saved values of the WCE field:
# sdparm --set=WCE --save /dev/sdd
    /dev/sdd: SEAGATE ST373453LC        ABCD

Check that saved value has also changed:
# sdparm --get=WCE /dev/sdd
    /dev/sdd: SEAGATE ST373453LC        ABCD
WCE         1 [cha: y, def: 1, sav: 1]

Multiple fields in the same mode page can be changed (set WCE and clear RCD):
# sdparm --set=WCE --clear=RCD --save /dev/sdd
    /dev/sdd: SEAGATE ST373453LC        ABCD

The previous example can also be written as:
# sdparm -s WCE=1,RCD=0 -S /dev/sdd
    /dev/sdd: SEAGATE ST373453LC        ABCD

Set the caching mode page to its default values (copy defaults into current and saved values):
# sdparm --page=ca --defaults --save /dev/sdd
    /dev/sdd: SEAGATE ST373453LC        ABCD

One disk vendor has a "performance mode" bit (PM) in the vendor specific unit attention mode page [0x0,0x0]. PM=0 is server mode (the default) while PM=1 is desktop mode. Desktop mode can be set (both current and saved values) with:
# sdparm --page=0 --set=2:7:1=1 --save /dev/sdd
    /dev/sdd: SEAGATE ST373453LC        ABCD

Since there are no acronyms defined for the unit attention mode page, its fields can be viewed in hex. The above command causes the top bit in byte 2 of the current and saved values to be set:
# sdparm --page=0 --hex /dev/sdd
mode page 0x0:
    Current:
00     80 06 80 00 0f 00 00 00
    Changeable:
00     80 06 f7 40 0f 00 00 00
    Default:
00     80 06 00 00 0f 00 00 00
    Saved:
00     80 06 80 00 0f 00 00 00

So where acronyms are available, values can be fetched and set in a relatively straight forward manner. In the absence of acronyms, the lower level numeric descriptors can be used.

Here is an example of common parameters fetched from a SAS disk:
# sdparm --transport=sas /dev/sdb
    /dev/sdb: TESTING   XY777701SS        ABCD
Disconnect-reconnect (SAS) mode page:
BITL        0 [cha: n, def: 0, sav: 0]
MCTL        0 [cha: n, def: 0, sav: 0]
MBS       164 [cha: y, def:164, sav:164]
lu: SSP short format (SAS) mode page:
LUPID       6 [cha: n, def: 6, sav: 6]
port: SSP short format (SAS) mode page:
PPID        6 [cha: n, def: 6, sav: 6]
RLM         0 [cha: y, def: 0, sav: 0]
ITNLT     2000 [cha: y, def:2000, sav:2000]
IRT         0 [cha: y, def: 0, sav: 0]
port: phy control and discover (SAS) mode page:
NOP         2 [cha: n, def: 2, sav: 2]

Here is a command example; ejecting a CD:
$ sdparm --command=eject /dev/hdc
    /dev/hdc: HITACHI   DVD-ROM GD-S200   0034 [pdt=0x5]
$ echo $?
0

The process status of 0 indicates that the eject command worked.

Downloads

The initial version of sdparm was 0.90 .

**Table 2. sdparm tarballs, rpm + deb packages**
	tarball	source rpm	i386 rpm binary	debian package
version 0.90	sdparm-0.90.tgz	sdparm-0.90-1.src.rpm	sdparm-0.90-1.i386.rpm	sdparm_0.90-2_i386.deb
version 0.91	sdparm-0.91.tgz	sdparm-0.91-1.src.rpm	sdparm-0.91-1.i386.rpm	sdparm_0.91-2_i386.deb
version 0.92	sdparm-0.92.tgz	sdparm-0.92-1.src.rpm	sdparm-0.92-1.i386.rpm	sdparm_0.92-2_i386.deb
version 0.93	sdparm-0.93.tgz	sdparm-0.93-1.src.rpm	sdparm-0.93-1.i386.rpm	sdparm_0.93-2_i386.deb
version 0.94	sdparm-0.94.tgz	sdparm-0.94-1.src.rpm	sdparm-0.94-1.i386.rpm	sdparm_0.94-2_i386.deb

The tarball contains an "rpm" spec file which is used to build source rpm and the i386 binary rpm. The alien utility is used to build the "deb" package from the i386 binary rpm. Here is the ChangeLog .

Conclusion

This command line utility attempts to simplify getting and in some cases setting device parameters. These device parameters number more than 300 and are accessed via transport, page and/or parameter acronym. The sdparm package includes a man page (in chapter 8) for online access and outputs a usage message if the '--help' option is given.

The author hopes a GUI wrapping this utility (or using it as a library) will soon emerge. SCSI mode pages especially lend themselves to a GUI representation similar to the table representations found in the SCSI (draft) standards and vendor's product manuals.

Return to main page.

Last updated: 28th July 2005