SDPARM(8) | SDPARM | SDPARM(8) |
sdparm - access SCSI modes pages; read VPD pages; send simple SCSI commands.
sdparm [--all] [--dbd] [--flexible] [--get=STR] [--hex] [--long] [--num-desc] [--page=PG[,SPG]] [--quiet] [--readonly] [--six] [--transport=TN] [--vendor=VN] [--verbose] DEVICE [DEVICE...]
sdparm [--clear=STR] [--defaults] [--dummy] [--flexible] [--page=PG[,SPG]] [--quiet] [--readonly] [--save] [--set=STR] [--six] [--transport=TN] [--vendor=VN] [--verbose] DEVICE [DEVICE...]
sdparm --command=CMD [--hex] [--readonly] [--verbose] DEVICE [DEVICE...]
sdparm --inquiry [--all] [--flexible] [--hex] [--num-desc] [--page=PG[,SPG]] [--quiet] [--readonly] [--transport=TN] [--vendor=VN] [--verbose] DEVICE [DEVICE...]
sdparm --enumerate [--all] [--inquiry] [--long] [--page=PG[,SPG]] [--transport=TN] [--vendor=VN]
sdparm --inhex=FN [--all] [--flexible] [--hex] [--inquiry] [--long] [--pdt=DT] [--raw] [--six] [--transport=TN] [--vendor=VN]
sdparm --wscan [--verbose]
sdparm [--help] [--version]
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 other housekeeping function may also be issued by this utility.
The first invocation shown in the synopsis is for accessing (reading) mode page fields held on the DEVICE. The second form is for changing mode page fields held on the DEVICE. The third form is for executing some simple SCSI commands. The fourth form (i.e. the '--inquiry ... DEVICE' form) is for fetching and decoding VPD pages from the given DEVICE. The --enumerate form is for listing out mode or VPD field data held by this utility (and if a DEVICE is given then it is ignored). The --inhex=FN form decodes mode or VPD response data provided in the named file (or from stdin if FN is '-'); that data may either be in hexadecimal or binary. The second last form is for Windows only and lists the available storage device names; see the OPTIONS entry for --wscan. The final form is to provide command line help or the version number (and date).
If no options (other than DEVICE) are given then a selection of common mode page fields for that device are listed. If the --long option is also given then a description of the fields is placed on the right of each line. If the --all option is given then all known mode page fields for that device are listed. Individual fields can be displayed with the --get=STR option (e.g. '--get=WCE' to fetch the state of the Writeback Cache Enable field).
This utility completes with an exit status of 0 when successful. For other values see the EXIT STATUS section below.
One or more DEVICE arguments can be given. The utility will essentially apply the given options to each DEVICE in the list. If an error is detected, it is noted and the utility continues. Error value 5 (file open or close problem) is treated as lower priority when other errors are detected. The exit status is the most recently detected error value (excluding error value 5 if other errors have been detected). If all actions succeed the exit status is zero.
By default this utility shows mode pages that are common to all transport protocols. These are termed as "generic" mode pages. If there is no match on a generic mode page name or field then those pages specific to the SAS transport are checked. Transport protocol specific mode pages are selected with the --transport=TN option. See the TRANSPORT section below. Vendor specific mode pages are selected with the --vendor=VN option. See the VENDORS 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 DEVICE is output. When both the --inquiry and --page=PG 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 --hex option is given then it is output in hex.
Mandatory arguments to long options are mandatory for short options as well. If an option takes a numeric argument then that argument is assumed to be decimal unless otherwise indicated (e.g. with a leading "0x" or a trailing "h"). The options are in alphabetical order, based on the long option name.
The reference document used for interpreting mode and VPD pages (and the INQUIRY standard response) is T10/BSR INCITS 502 Revision 02 (SPC-5, 3 January 2015) found at http://www.t10.org . Obsolete and reserved items in the standard INQUIRY response output are displayed in brackets. Recent drafts of other T10 documents are also used: SBC-4 (disks), SSC-5 (tapes), SPL-4 (SAS transport) and SAT-4 (SCSI to ATA Translation).
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=PG --hex'.
Numbers input to sdparm (e.g. in the command line arguments) are assumed to be in decimal unless there is a hexadecimal indicator. A hexadecimal indicator is either a leading '0x' or '0X' (i.e. the C language convention) or a trailing 'h' or 'H' (i.e. the convention used at www.t10.org ). In the case of --page= either a string or number is expected, so hex numbers like 'ch' (12) should be prefixed by a zero (e.g. '0ch').
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.
Since the device identification VPD page (acronym_name "di") potentially contains a lot of diverse designators, several associated acronyms are available. They are "di_lu" for designators associated with the addressed logical unit, "di_port" for designators associated with the target port (which the command arrived via) and "di_target" for designators associated with the target device. When "di" is used designators are grouped by lu, then port and then target device. To see all designators decoded in the order that they appear in the VPD page use "di_asis".
Only those VPD pages defined by t10.org are decoded by this utility. SPC-4 sets aside VPD pages codes from 0xc0 to 0xff (inclusive) for vendor specific pages some of which are decoded in the sg_vpd utility.
To see all VPD pages supported by a DEVICE use 'sg_vpd --all'.
In the linux kernel 2.6 and 3 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.4 series and later. 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 and later.
In the Linux 2.6 and 3 series, especially with ATA disks, using sdparm to stop (spin down) a disk may not be sufficient and other mechanisms will start the disk again some time later. The user might additionally mark the disk as "offline" with 'echo offline > /sys/block/sda/device/state' where sda is the block name of the disk. To restart the disk "offline" can be replaced with "running".
In their simplest form the --clear=, --get= and --set= options (or their short forms) take an acronym_name such as "WCE". In the case of '--get=WCE' the value of "Writeback Cache Enable" in the caching mode page will be fetched. In the case of '--set=WCE' that bit will be set (to one). In the case of '--clear=WCE' that bit will be cleared (to zero). When an acronym_name is given then the mode page is imputed from that acronym_name (e.g. WCE is in the caching mode page).
Instead of an acronym_name a field within a mode page can be described numerically with a <start_byte>:<start_bit>:<num_bits> tuple. These are the <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 (the "Read Cache Disable bit in the caching mode page) is "2:0:1". The <start_byte> can optionally be given in hex (e.g. '--set=0x2:0:1' or '--set=2h:0:1'). With this form the --page= option is required to establish which mode page is to be used.
Either form can optionally be followed by "=<val>". By default <val> is decimal but can be given in hex in the normal fashion. Here are some examples: '--set=2h:0:1=1h' and '-s MRIE=0x3'. When the acronym_name or numeric form following --clear= is not given an explicit '=<val>' then the value defaults to zero. When the acronym_name or numeric form 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.
Multiple fields within the same mode page can be changed by giving a comma separated list of acronym_names and/or the numerical form. For example: '--set=TEST,MRIE=6'.
Some mode page have multiple descriptors. They typically have a fixed header section at the start of the mode page that includes a field containing the number of descriptors that follow. Following the header is a variable number of descriptors. An example is the SAS Phy Control and Discover mode page. An acronym_name may include a trailing '.<num>' where "<num>" is a descriptor number (origin 0). For example '-t sas -g PHID.0' and '-t sas -g PHID' will yield the phy identifier of the first descriptor of the above mode page; '-t sas -g PHID.1' will yield the phy identifier of the second descriptor.
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
-e --vendor=sea list vendor specific mode pages for
"sea" (Seagate)
-e -M sea --all additionally list the contents of vendor
specific mode pages for "sea" (Seagate)
-e -p pcd -l list contents of SAS phy control and
discovery mode page plus (due to "-l")
some descfriptor format information
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 start byte (in hex, prefixed by "0x") of the beginning 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 values 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_name 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.
SCSI leaves a lot of space for vendor specific information. Often this is described in product manuals. The --vendor=VN (or -M=VN) option allows known vendor specific mode pages to be examined and/or modified by acronym.
In this utility the syntax and semantics of vendor specific mode pages is very similar to those of transport protocol specific mode pages. Both cannot be specified together. Vendor specific modes pages can still be accessed numerically (as shown at the end of the EXAMPLES section).
The command option sends a SCSI command to the DEVICE. If the command fails then this is reflected in the non-zero exit status. To obtain more information about the error use the -v option.
For loading and ejecting tapes the mt utility should be used (i.e. not these commands). The 'ready' command is valid for tape devices.
To list the common (generic) mode parameters of a disk:
sdparm /dev/sda
To list the designators 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 and 3 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 and 3 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. The PM bit is now covered by vendor specific mode pages and the above can also be accomplished with:
sdparm --vendor=sea --set=PM --save /dev/sda
What follows are some examples from Windows using the '--wscan' option. The idea is to list the storage device names on the system that might be invoked by other uses of sdparm.
# sdparm --wscan
PD0 [C] FUJITSU MHY2160BH 0000
PD1 [DF] WD 2500BEV External 1.05 WD-WXE90
CDROM0 [E] MATSHITA DVD/CDRW UJDA775 CB03
So 'sdparm -a CDROM0' and 'sdparm -a E' will show all the (known) mode page fields for the Matshita DVD/CD drive. By using the '--wsacan' option twice, the bus type (as seen by the OS) is added to the output:
# 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
And the pattern continues to add a SCSI adapter scan. This may be useful if there are specialized storage related devices (e.g. a SES device in an enclosure) but does add much extra information in this case.
# 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
To aid scripts that call sdparm, the exit status is set to indicate success (0) or failure (1 or more). Note that some of the lower values correspond to the SCSI sense key values. The exit status values are:
Most of the error conditions reported above will be repeatable (an example of one that is not is "unit attention") so the utility can be run again with the -v option (or several) to obtain more information.
Written by Douglas Gilbert.
Report bugs to <dgilbert at interlog dot com>.
Copyright © 2005-2016 Douglas Gilbert
This software is distributed under a FreeBSD license. There is NO warranty;
not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
There is a web page discussing this package at http://sg.danny.cz/sg/sdparm.html .
hdparm(hdparm), sg_modes, sg_wr_mode, sginfo, sg_inq, sg_vpd(all in sg3_utils), smartmontools(smartmontools.sourceforge.net), mt, eject(eject),
February 2016 | sdparm-1.10 |