sdparm - fetch and potentially change SCSI device attributes, send commands

sdparm [--all] [--clear=<str>] [--command=<str>] [--dbd] [--defaults] [--dummy] [--flexible] [--get=<str>] [--help] [--hex] [--inquiry] [--long] [--page=<pg>[,<spg>]] [--quiet] [--save] [--set=<str>] [--six] [--transport=<tn>] [--verbose] [--version] <scsi_device>

sdparm --enumerate [--all] [--inquiry] [--long] [--page=<pg>[,<spg>]] [--transport=<tn>]

This utility fetches and potentially changes SCSI device (e.g. disk) mode pages. Inquiry data including Vital Product Data (VPD) pages can also be displayed. Commands associated with starting and stopping the medium; loading and unloading the medium; and othet housekeeping function may also be issued by this utility.

If no options (other than <scsi_device>) are given then a selection of common mode page attributes for that device are listed. If the '--long' option is also given then a description of the attributes is placed on the right of each line. If the '--all' option is given then all known mode page attributes for that device are listed. Individual attributes can be displayed with the '--get' option (e.g. '--get=WCE' to fetch the state of the Writeback Cache Enable attribute).

By default this utility shows mode pages that a common to all transport protocols. These are termed here as "generic" mode pages. Transport protocol specific mode pages are selected with the '--transport=' option. See the TRANSPORT section below.

Although originally for SCSI disks (or storage devices that appear to the OS as SCSI disks) many of the mode pages are for other SCSI device types. These include CD/DVD players that use the ATAPI (or any other) transport, SCSI tapes drives and SCSI enclosures.

When the '--inquiry' option is given without a page number then the Device Identification VPD page (page number 0x83) is requested and if found it is decoded and output. If no page number is given and the '--all' option is given then a list of VPD page names (but not their contents) supported by the given device is output. When both the '--inquiry' and '--page=' options are given then the VPD page can be specified as an abbreviation (e.g. "sp" for the SCSI ports VPD page) or numerically (e.g. "0x88"). If a VPD page is returned by the device but sdparm cannot decode it or the '-H' option is given then it is output in hex.

--all | -a

output all recognized attributes for the device type (e.g. disk) of the given device. Without this option (or the '--page=' option) the default action is to output a relatively small number of commonly used attributes from different pages. When a specific (mode) page number is given with the '--page=' option then all the attributes of that page are output (irrespective of the setting of this option). For use with the '--enumerate' option see ENUMERATE section below.

--clear=<str> | -c <str>

The <str> contains a comma separated list of attribute acronyms. In the absence of an explicit value argument (e.g. '--clear=WCE=1'), each acronym has its value cleared to zero. Utility exits with process status 0 if successful, else 1. See the PARAMETERS section below.

--command=<cmd> | -C <cmd>

Perform given command. See section below on COMMANDS. If successful then the exit status is 0, else 1. To enumerate supported commands use '-e -C x' (using any command name, valid or otherwise).

--dbd | -B

disable block descriptors. This is a bit in MODE SENSE cdbs that rarely needs to be set. The one known case is a MODE SENSE 6 issued to a Reduced Block Commands (RBC) device where the RBC standard says it shall be set.

--defaults | -D

sets the given mode page to its default values. Requires the '--page=' option to be given to specify the mode page. To make the default mode page values also the saved mode page values use the '--save' option as well.

--dummy | -d

when set inhibits changes being placed in the device's mode page. Instead the mode data that would have been sent to a MODE SELECT command, is output in ASCII hex to the console. This option is mainly for testing.

--enumerate | -e

lists out descriptive information about the pages and attributes known to this utility. Ignores the <scsi_device> argument and other options apart from the '--all', '--inquiry', '--long', '--page=' and '--transport=' options. If '--enumerate' is given without other options then the known (generic) mode pages are listed. See the ENUMERATE section below.

--flexible | -f

Some devices, bridges and/or drivers attempt crude transformations between mode sense 6 and 10 byte commands without correctly rebuilding the response. This will cause the response to be mis-interpreted (usually with an error saying the response is malformed). With this option, the length of the response is checked, and if it looks wrong, various corrections are attempted. This option will also allow mode pages that don't belong to the current device's peripheral type to be listed.

--get=<str> | -g <str>

The <str> contains a comma separated list of attribute acronyms whose values are to be fetched. See the PARAMETERS section below. The '--long' and '--hex' options effect the output format. Also if a value of "1" is given (e.g. '--get=WCE=1') only the current value is output.

--help | -h

output the usage message then exit.

--hex | -H

rather than trying to decode mode (or VPD) pages, print them out in hex. When used with the '-get=' option the corresponding current, changeable, default and saved values are output in hex, prefixed by "0x" and space separated. If a value of "1" is given with the '--get=' option (e.g. '--get=WCE=1') then only the current value is output in hex, prefixed by "0x". If a value of "2" is given with the '--get=' option then only the current value is output as a (signed) integer. Can be used multiple times (e.g. '-HH'). Useful with the ATA Information VPD page which usually outputs its IDENTIFY (PACKET) DEVICE response in 16 bit hex words; with '-HH' outputs that response in hex bytes; with -HHH outputs the same response in a format suitable for 'hdparm --Istdin' to decode.

--inquiry | -i

output INQUIRY VPD pages. In the absence of this option the default action is to output mode pages. If the '--inquiry' option is given without the '--page=' option then the device identification VPD page (0x83) is decoded and output. If this option and the '--all' option are given then the supported VPD pages page (0x0) is decoded and output.

--long | -l

output extra information. In the case of mode page attributes a description (with units if applicable) is output to the right. If used twice, then for some attributes more information about its values is given on one or more following lines, each prefixed by a tab character. For usage with '--enumerate' see the ENUMERATE section below.

--page=<pg>[,<spg>] | -p <pg>[,<spg>]

supply the page number and optionally the sub page number of the mode (or VPD) page to fetch. These numbers are interpreted as decimal unless prefixed with "0x". Sub page numbers are only valid for mode pages (not VPD pages). Alternatively an abbreviation for a page can be given (see next entry).

--page=<str> | -p <str>

a two or three letter abbreviation for a page can be given. Known mode page abbreviations are checked first followed by known VPD page abbreviations. For example '--page=ca' matches the caching mode page. If no match is found then an error is issued and a list of possibilities in the current context is given (so '-p x' can be quite useful). If the <str> matches a known VPD page abbreviation then the '--inquiry' option is assumed. For usage with '--enumerate' see the ENUMERATE section below.

--quiet | -q

suppress output of device name followed by the vendor, product and revision strings fetched from an INQUIRY response. Without this option such a line is typically the first line output by sdparm.

--save | -S

when a mode page is being modified (by using the '--clear=' and/or '--set=" options) then the default action is to modify only the current values mode page. When this option is given then the corresponding value(s) in the saved values mode page is also changed. The next time the device is power cycled (or reset) the saved values mode page becomes (i.e. is copied to) the current values mode page. See NOTES section below.

--set=<str> | -s <str>

The <str> contains a comma separated list of attribute acronyms. In the absence of an explicit value, each acronym has its value set to (all) ones. This means a 16 bit field will be set to 0xffff which is 65535 in decimal. Alternatively each acronym may be followed by "=<n>" where <n> is the value to set that attribute to. This utility exits with process status 0 if successful, else 1. See the PARAMETERS section below.

--six | -6

The default action of this utility is to issue MODE SENSE and MODE SELECT SCSI commands with 10 byte cdbs. When this option is given the 6 byte cdb variants are used. RBC and old SCSI devices may need this option. This utility outputs a suggestion to use this option if the SCSI status indicates that the 10 byte cdb variant is not supported.

--transport=<tn> | -t <tn>

Specifies the transport protocol where <tn> is either a number in the range 0 to 15 (inclusive) or an abbreviation (e.g. "fcp" for the Fibre Channel Protocol). One way to list available transport protocols numbers and their associated abbreviations is to give an invalid transport protocol number such as '-t x'; another way is '-e -l'.

--verbose | -v

increase the level of verbosity, (i.e. debug output). In some cases more decoding is done (e.g. fields within a standard INQUIRY response).

--version | -V

print the version string and then exit.

A mode page for which no abbreviation is known (e.g. a vendor specific mode page) can be listed in hexadecimal by using the option combination '--page=<pn> --hex'.

The '--clear=', '--get=' and '--set=" options can take a string argument which is a comma separated list of attributes. Each attribute can be either an acronym name or a <start_byte>:<start_bit>:<num_bits> tuple. Either form can optionally be followed by "=<val>". Acronyms (e.g. WCE for "Writeback Cache Enable") that this utility supports can be listed with the '--enumerate' option. Alternatively, a mode page attribute to be changed can be described in terms of a <start_byte> (origin 0) within the mode page, a <start_bit> (0 to 7 inclusive) and <num_bits> (1 to 64 inclusive). For example, the low level representation of the RCD bit (in the caching mode page) is "2:0:1". The <start_byte> and the <val> can optionally be given in hex (e.g. '--set=0x2:0:1=0x1').

When the attribute(s) following '--clear=' is not given an explicit '=<val>' then the value defaults to zero. When the attribute(s) following '--set=' is not given an explicit '=<val>' then the value defaults to "all ones" (i.e. as many as <num_bits> permits). For example '--clear=WCE' and '--clear=WCE=0' have the same meaning: clear Writeback Cache Enable or, put more simply: turn off the writeback cache.

When an acronym is given then the mode page is imputed from that acronym (e.g. WCE is in the caching mode page). When only the start_byte:start_bit:num_bits form is used then the '--page=' option must be given to establish which mode page is to be used. A restriction placed on '--clear=' and '--set=' is that if multiple parameters are given, they must all be in the same mode page. Hence an invocation of this utility can only modify one mode page.

The '--enumerate' option essentially dumps out static information held by this utility. A list of '--enumerate' variants and their actions follows. For brevity subsequent examples of options are shown in their shorter form.

--enumerate list generic mode page information

-e --all list generic mode page contents

(i.e. parameters)

-e --page=rw list contents of read write error

recovery mode page

-e --inquiry list VPD pages this utility can decode

-e --long list generic mode pages, transport

protocols, mode pages for each

supported transport protocol and

supported commands

-e -l --all additionally list the contents of

each mode page

-e --transport=fcp list mode pages for the fcp

transport protocol

-e -t fcp --all additionally list the contents of

each mode page

When known mode pages are listed (via the '--enumerate' option) each line starts with a two or three letter abbreviation. This is followed by the page number (in hex prefixed by "0x") optionally followed by a comma and the subpage number. Finally the descriptive name of the mode page (e.g. as found in SPC-4) is output.

When known parameters (fields) of a mode page are listed, each line starts with an acronym (indented a few spaces). This will match (or be an acronym for) the description for that field found in the (draft) standards. Next are three numbers, separated by colons, surrounded by brackets. These are the byte offset (in hex, prefixed by "0x") of the start of the field within the mode page; the starting bit (0 through 7 inclusive) and then the number of bits. The descriptive name of the parameter (field) is then given. If appropriate the descriptive name includes units (e.g. "(ms)" means the units are milliseconds). Adding the '-ll' option will list information about possible field value for selected mode page parameters.

Mode parameters for which the num_bits is greater than 1 can be viewed as unsigned integers. Often 16 and 32 bit fields are set to 0xffff and 0xffffffff respectively (all ones) which usually has a special meaning (see drafts). This utility outputs such values as "-1" to save space (rather than their unsigned integer equivalents). "-1" can also be given as the value to a mode page field acronym (e.g. '--set=INTT=-1' sets the interval timer field in the Informational Exceptions control mode page to 0xffffffff).

SCSI transport protocols are a relatively specialized area that can be safely ignored by the majority of users.

Some transport protocols have protocol specific mode pages. These are usually the disconnect-reconnect (0x2), the protocol specific logical unit (0x18) and the protocol specific port (0x19) mode pages. In some cases the latter mode page has several subpages. The most common transport protocol abbreviations likely to be used are "fcp", "spi" and "sas".

Many of the field names are re-used in the same position so the acronym namespaces have been divided between generic mode pages (i.e. when the '--transport=' option is _not_ given) and a namespace for each transport protocol. A LUPID field from the protocol specific logical unit (0x18) mode page and the PPID field from protocol specific port (0x19) mode page are included in the generic modes pages; this is so the respective (transport) protocol identifiers can be seen. In most cases the user will know what the "port" transport is (i.e. the same transport as the HBA in the computer) but the logical unit's transport could be different.

The logic in sdparm requires acronyms to be unique within a namespace. This becomes difficult if a mode page has multiple descriptors each of which has the same set of acronyms. The SAS phy control and discover page is an example of this. The current solution is to prepend "2_" to the second set of acronyms.

The command option sends a SCSI command to the given device. If the command fails then this is reflected in the process exit status of 1. To obtain more information about the error use the '-v' option.

The 'capacity' command sends a READ CAPACITY command (valid for disks and cd/dvd media). If successful yields "blocks: " [the number of blocks], "block_length: " [typically either 512 or 2048] and "capacity_mib: " [capacity in MibiBytes (1048576 byte units)].

The 'eject' command stops the medium and ejects it from the device. Note that ejection (by command or button) may be prevented in which case the 'unlock' command may be useful in extreme cases. Typically only appropriate for cd/dvd drives and disk drives with removable media. Objects if sent to another peripheral device type (but objection can be overridden with '-f' option).

The 'load' command loads the medium and and starts it (i.e. spins it up). See 'eject' command for supported device types.

The 'ready' command sends the "Test Unit Ready" SCSI command to the given device. No error is reported if the device will respond to data requests (e.g. READ) in a reasonable timescale. For example, if a disk is stopped then it will report "not ready". All devices should respond to this command.

The 'sense' command sends a REQUEST SENSE command. Reports hardware threshold exceeded, warning or low power condition if flagged. If progress indication is present (e.g. during a format) then it will be output as a percentage.

The 'start' command starts the medium (i.e. spins it up). Harmless if medium has already been started. See 'eject' command for supported device types.

The 'stop' command stops the medium (i.e. spins it down). Harmless if medium has already been stopped. See 'eject' command for supported device types.

The 'sync' command sends a SYNCHRONIZE CACHE command. The device should flush any data held in its (volatile) buffers to the media.

The 'unlock' command tells a device to allow medium removal. It uses the SCSI "prevent allow medium removal" command. This is desperation stuff, possibly overriding a prevention applied by the OS on a mounted file system. The "eject" utility (from the "eject" package) is more graceful and should be tried first. This command is only appropriate for devices with removable media.

For loading and ejecting tapes the mt utility should be used (i.e. not these commands). The 'ready' command is valid for tape devices.

The SPC-4 draft (rev 2) says that devices that implement no distinction between current and saved pages can return an error (ILLEGAL REQUEST, invalid field in cdb) if the SP bit (which corresponds to the '--save' option) is _not_ set. In such cases the '--save' option needs to be given.

If the '--save' option is given but the existing mode page indicates (via its PS bit) that the page is not savable, then this utility generates an error message. That message suggests to try again without the '--save' option.

The functionality of this utility overlaps, somewhat, with another utility called blktool. This utility can be considered as more "SCSI-centric". For example, with ATAPI CD/DVD drives this utility will concentrate on the command level as such drives use the Multi Media Command set (MMC) which is a SCSI command set. This utility ignores transport related settings at the ATA(PI) transport level. Such settings can be accessed with blktool (and viewed with 'sg_inq -A').

Since the device identification VPD page (acronym "di") potentially contains a lot of diverse identifiers, three subset acronyms are available. They are "di_lu" for identifiers associated with the addressed logical unit, "di_target" for identifiers associated with the target device and "di_port" for identifiers associated with the target port (which the command arrived via).

In the linux kernel 2.6 series any device node that understands a SCSI command set (e.g. SCSI disks and CD/DVD drives) may be specified. More precisely the driver that "owns" the device node must support the SG_IO ioctl. In the lk 2.4 series only SCSI generic (sg) device nodes support the SG_IO ioctl. However in the lk 2.4 series other SCSI device nodes are mapped within this utility to their corresponding sg device nodes. So if there is a SCSI disk at /dev/sda then 'sdparm /dev/sda' will work in both the lk 2.6 and lk 2.4 series. However if there is an ATAPI cd/dvd drive at /dev/hdc then 'sdparm /dev/hdc' will only work in the lk 2.6 series.

To list the common (generic) mode parameters of a disk:

sdparm /dev/sda

To list the descriptors within the device identification VPD page of a disk:

sdparm --inquiry /dev/sda

To see all parameters for the caching mode page:

sdparm --page=ca /dev/sda

To see all parameters for the caching mode page with parameter descriptions to the right:

sdparm --page=ca --long /dev/sda

To get the WCE values (current changeable default and saved) in hex:

sdparm -g WCE -H /dev/sda

0x01 0x00 0x01 0x01

To get the WCE current value in hex:

sdparm -g WCE=1 -H /dev/sda

0x01

To set the "Writeback Cache Enable" bit in the current values page:

sdparm --set=WCE /dev/sda

To set the "Writeback Cache Enable" bit in the current and saved values page:

sdparm --set=WCE --save /dev/sda

To set the "Writeback Cache Enable" and clear "Read Cache Disable":

sdparm --set=WCE --clear=RCD --save /dev/sda

The previous example can also by written as:

sdparm -s WCE=1,RCD=0 -S /dev/sda

To re-establish the manufacturer's defaults in the current and saved values of the caching mode page:

sdparm --page=ca --defaults --save /dev/sda

If an ATAPI cd/dvd drive is at /dev/hdc then its common (mode) parameters could be listed in the lk 2.6 series with:

sdparm /dev/hdc

If there is a DVD in the drive at /dev/hdc then it could be ejected in the lk 2.6 series with:

sdparm --command=eject /dev/hdc

If the ejection is being prevented by software then that can be overridden with:

sdparm --command=unlock /dev/hdc

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/sda

The resultant change can be viewed in hex with the '--hex' option as there are no acronyms for vendor extensions yet.

Written by Douglas Gilbert.

Report bugs to <dgilbert at interlog dot com>.

Copyright © 2005 Douglas Gilbert

This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

hdparm(hdparm), sg_modes, sg_wr_mode, sginfo, sg_inq(all in sg3_utils), smartmontools(smartmontools.sourceforge.net), mt, eject(eject), blktool(sourceforge.net/projects/gkernel)