sdparm (8) - Linux Manuals
sdparm: access SCSI modes pages; read VPD pages; send simple SCSI commands.
NAME
sdparm - access SCSI modes pages; read VPD pages; send simple SCSI commands.SYNOPSIS
sdparm [--all] [--clear=STR] [--command=CMD] [--dbd] [--defaults] [--dummy] [--flexible] [--get=STR] [--help] [--hex] [--inquiry] [--long] [--num-desc] [--page=PG[,SPG]] [--quiet] [--readonly] [--save] [--set=STR] [--six] [--transport=TN] [--vendor=VN] [--verbose] [--version] DEVICE [DEVICE...]sdparm --enumerate [--all] [--inquiry] [--long] [--page=PG[,SPG]] [--transport=TN] [--vendor=VN]
DESCRIPTION
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.
Of the three invocations shown in the synopsis, the first is the most general. The second variant that uses --enumerate is for dumping information held in sdparm's internal tables. The last variant is for Windows only and lists the available device names; see the OPTIONS entry for --wscan.
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.
OPTIONS
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.- -a, --all
- output all recognized fields for the device type (e.g. disk) of the DEVICE. Without this option (or the --page=PG[,SPG] option) the default action is to output a relatively small number of commonly used fields from different pages. When a specific (mode) page number is given with the --page=PG[,SPG] option then all the fields of that page are output (irrespective of the setting of this option). For this option's action when used with the --enumerate option see the ENUMERATE section below.
- -c, --clear=STR
- In its simplest form STR contains a field acronym_name or a field numerical descriptor. In the absence of an explicit value argument (e.g. '--clear=WCE=1'), the field has its value cleared to zero. See the PARAMETERS section below.
- -C, --command=CMD
- Perform given CMD. See section below on COMMANDS. To enumerate supported commands use '-e -C x' (using any CMD name, valid or otherwise).
- -B, --dbd
- disable block descriptors. This is a bit in MODE SENSE cdbs that rarely needs to be set. 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.
- -D, --defaults
- sets the given mode page to its default values. Requires the --page=PG[,SPG] 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.
- -d, --dummy
- 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.
- -e, --enumerate
- lists out descriptive information about the pages and fields known to this utility. Ignores the DEVICE argument and other options apart from the --all, --inquiry, --long, --page=PG[,SPG], --transport=TN and --vendor=VN. If --enumerate is given without other options then the known (generic) mode pages are listed. See the ENUMERATE section below.
- -f, --flexible
- 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.
- -g, --get=STR
- In its simplest form STR contains a field acronym_name or a field numerical descriptor. The field is fetched from mode page. 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 (i.e. not the change mask, the default value and the saved value).
- -h, --help
- output the usage message then exit.
- -H, --hex
- rather than trying to decode mode (or VPD) pages, print them out in hex. When used with the --get=STR 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=STR 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=STR option then only the current value is output as a (signed) integer. This option 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.
- -i, --inquiry
- 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=PG[,SPG] 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.
- -l, --long
- output extra information. In the case of mode page fields a description (with units if applicable) is output to the right. If used twice, then for some fields 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.
- -n, --num-desc
- for a mode page that can have descriptors, the number of descriptors for the given page on the DEVICE is output. Otherwise 0 is output.
- -p, --page=PG[,SPG]
- supply the page number (PG) and optionally the sub page number (SPG) of the mode (or VPD) page to fetch. These numbers are interpreted as decimal unless prefixed with "0x" or a trailing. Sub page numbers are only valid for mode pages (not VPD pages). Alternatively an abbreviation for a page can be given (see next entry).
- -p, --page=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.
- -q, --quiet
- 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. Reduces output from the device identification VPD page, typically to one line (or none) for each of di_lu, di_port, di_target and di_asis.
- -r, --readonly
- override other logic to open DEVICE in read-only mode. The default setting of the open read-only/read-write mode depends on the operation requested (e.g. a --set=STR operation by default will try a read-write mode open on DEVICE). This option may be useful if a command is being sent to an ATA disk via a SCSI command set. For example in Linux '-C stop' may require this option to stop an ATA disk being restarted immediately.
- -S, --save
- when a mode page is being modified (by using the --clear=STR and/or --set=STR 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.
- -s, --set=STR
- in its simplest form STR contains a field acronym_name or a field numerical descriptor. In the absence of an explicit value, each acronym_name 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_name or numerical descriptor may be followed by "=<n>" where <n> is the value to set that field to. See the PARAMETERS section below.
- -6, --six
- 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.
- -t, --transport=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'.
- -M, --vendor=VN
- Specifies the vendor (i.e. manufacturer) where VN is either a number (0 or more) or an abbreviation (e.g. "sea" for Seagate disk vendor specific). One way to list available vendor numbers and their associated abbreviations is to give an invalid vendor number such as '-M x'; another way is '-e -l'.
- -v, --verbose
- increase the level of verbosity, (i.e. debug output). In some cases more decoding is done (e.g. fields within a standard INQUIRY response).
- -V, --version
- print the version string and then exit.
- -w, --wscan
- this option is available in Windows only. It lists storage device names and the corresponding volumes, if any. When used twice it adds the "bus type" of the closest transport (e.g. a SATA disk in a USB connected enclosure has bus type Usb). When used three times a SCSI adapter scan is added. When used four times only a SCSI adapter scan is shown. See examples below and the "Win32 port" section in the README file.
NOTES
The reference document used for interpreting mode and VPD pages (and the INQUIRY standard response) is T10/1713-D Revision 36e (SPC-4, 24 August 2012) found at http://www.t10.org . Obsolete and reserved items in the standard INQUIRY response output are displayed in brackets.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.
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.
In the Linux 2.6 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".
PARAMETERS
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.
ENUMERATE
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.