.TH SDPARM "8" "April 2021" "sdparm\-1.12" SDPARM
.SH NAME
sdparm \- access SCSI modes pages; read VPD pages; send simple SCSI commands.
.SH SYNOPSIS
.B sdparm
[\fI\-\-all\fR] [\fI\-\-dbd\fR] [\fI\-\-examine\fR] [\fI\-\-flexible\fR]
[\fI\-\-get=STR\fR] [\fI\-\-hex\fR] [\fI\-\-long\fR] [\fI\-\-num\-desc\fR]
[\fI\-\-out\-mask=OM\fR] [\fI\-\-page=PG[,SPG]\fR] [\fI\-\-quiet\fR]
[\fI\-\-readonly\fR] [\fI\-\-six\fR] [\fI\-\-transport=TN\fR]
[\fI\-\-vendor=VN\fR] [\fI\-\-verbose\fR] \fIDEVICE\fR [\fIDEVICE\fR...]
.PP
.B sdparm
[\fI\-\-clear=STR\fR] [\fI\-\-defaults\fR] [\fI\-\-dummy\fR]
[\fI\-\-flexible\fR] [\fI\-\-page=PG[,SPG]\fR] [\fI\-\-quiet\fR]
[\fI\-\-readonly\fR] [\fI\-\-save\fR] [\fI\-\-set=STR\fR]
[\fI\-\-six\fR] [\fI\-\-transport=TN\fR] [\fI\-\-vendor=VN\fR]
[\fI\-\-verbose\fR] \fIDEVICE\fR [\fIDEVICE\fR...]
.PP
.B sdparm
\fI\-\-command=CMD\fR [\fI\-\-hex\fR] [\fI\-\-long\fR] [\fI\-\-readonly\fR]
[\fI\-\-verbose\fR] \fIDEVICE\fR [\fIDEVICE\fR...]
.PP
.B sdparm
\fI\-\-inquiry\fR [\fI\-\-all\fR] [\fI\-\-examine\fR] [\fI\-\-flexible\fR]
[\fI\-\-hex\fR] [\fI\-\-num\-desc\fR] [\fI\-\-page=PG[,SPG]\fR]
[\fI\-\-quiet\fR] [\fI\-\-readonly\fR] [\fI\-\-transport=TN\fR]
[\fI\-\-verbose\fR] \fIDEVICE\fR [\fIDEVICE\fR...]
.PP
.B sdparm
\fI\-\-enumerate\fR [\fI\-\-all\fR] [\fI\-\-inquiry\fR] [\fI\-\-long\fR]
[\fI\-\-page=PG[,SPG]\fR] [\fI\-\-transport=TN\fR] [\fI\-\-vendor=VN\fR]
.PP
.B sdparm
\fI\-\-inhex=FN\fR [\fI\-\-all\fR] [\fI\-\-flexible\fR] [\fI\-\-hex\fR]
[\fI\-\-inquiry\fR] [\fI\-\-long\fR] [\fI\-\-pdt=DT\fR] [\fI\-\-raw\fR]
[\fI\-\-six\fR] [\fI\-\-transport=TN\fR] [\fI\-\-vendor=VN\fR]
[\fI\-\-verbose\fR]
.PP
.B sdparm
\fI\-\-wscan\fR [\fI\-\-verbose\fR]
.PP
.B sdparm
[\fI\-\-help\fR] [\fI\-\-version\fR]
.SH DESCRIPTION
.\" Add any additional description here
.PP
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 functions may also be issued
by this utility.
.PP
The first invocation shown in the synopsis is for accessing (i.e. reading)
mode page fields held on the \fIDEVICE\fR. The second form is for changing
mode page fields held on the \fIDEVICE\fR. The third form is for executing
some simple SCSI commands. The fourth form (i.e.  the '\fI\-\-inquiry\fR ...
\fIDEVICE\fR' form) is for fetching and decoding VPD pages from the given
\fIDEVICE\fR. The \fI\-\-enumerate\fR form is for listing out mode or VPD
field data held by this utility (and if a \fIDEVICE\fR is given then it is
ignored). The \fI\-\-inhex=FN\fR form decodes mode or VPD response data
provided in the named file (or from stdin if \fIFN=\-\fR is given); 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
\fI\-\-wscan\fR. The final form is to provide command line help or the version
number (and date) of this utility.
.PP
If no options (other than \fIDEVICE\fR) are given then a selection of common
mode page fields for that device are listed. If the \fI\-\-long\fR option is
also given then a description of the fields is placed on the right of each
line. If the \fI\-\-all\fR option is given then all known mode page fields
for that device are listed. Individual fields can be displayed with the
\fI\-\-get=STR\fR option (e.g. '\-\-get=WCE' to fetch the state of the
Writeback Cache Enable field).
.PP
This utility completes with an exit status of 0 when successful. For other
values see the EXIT STATUS section below.
.PP
One or more \fIDEVICE\fR arguments can be given. The utility will
essentially apply the given options to each \fIDEVICE\fR in the list. If a
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.
.PP
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 \fI\-\-transport=TN\fR option. See the TRANSPORT section below.
Vendor specific mode pages are selected with the \fI\-\-vendor=VN\fR option.
See the VENDORS section below.
.PP
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.
.PP
When the \fI\-\-inquiry\fR 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 \fI\-\-all\fR option is given then a list of VPD page names (but not
their contents) supported by the \fIDEVICE\fR is output. When both
the \fI\-\-inquiry\fR and \fI\-\-page=PG\fR 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 \fIDEVICE\fR but sdparm cannot decode it or the \fI\-\-hex\fR
option is given then it is output in hex.
.SH 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.
.TP
\fB\-a\fR, \fB\-\-all\fR
output all recognized fields for the device type (e.g. disk) of the
\fIDEVICE\fR. Without this option (or the \fI\-\-page=PG[,SPG]\fR 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
\fI\-\-page=PG[,SPG]\fR 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 \fI\-\-enumerate\fR option see the ENUMERATE section below.
.br
When used together with the \fI\-\-inquiry\fR option and a \fIDEVICE\fR, the
Supported VPD Pages VPD page [0x0] is output. When this option is used
twice (short form: '\-iaa') then all VPD pages (listed in the Supported VPD
Pages VPD page) are output.
.br
By default \fI\-\-inhex=FN\fR will only decode the first mode page found in
\fIFN\fR. With this option, more mode pages will be decoded if present. When
\fI\-\-transport=TN\fR or \fI\-\-vendor=VN\fR is also given then if a given
mode page is not defined for that transport or vendor, then it is decoded
as a generic mode page.
.TP
\fB\-c\fR, \fB\-\-clear\fR=\fISTR\fR
In its simplest form \fISTR\fR 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.
.TP
\fB\-C\fR, \fB\-\-command\fR=\fICMD\fR
Perform given \fICMD\fR. See section below on COMMANDS. To enumerate supported
commands use '\-e \-C x' (using any CMD name, valid or otherwise).
.TP
\fB\-B\fR, \fB\-\-dbd\fR
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.
.TP
\fB\-D\fR, \fB\-\-defaults\fR
sets the given mode page to its default values. Requires the
\fI\-\-page=PG[,SPG]\fR option to be given to specify the mode page. To make
the default mode page values also the saved mode page values, use the
\fI\-\-save\fR option as well.
.br
when this option is used twice, the current values in all modes pages are
reverted to their defaults. If the \fI\-\-save\fR option is given as well,
then the current and saved values in all modes pages are reverted to their
defaults. This feature uses the RTD bit in the MODE SELECT command which
was added in draft SPC\-5 revision 11.
.TP
\fB\-d\fR, \fB\-\-dummy\fR
when set inhibits changes being placed in the \fIDEVICE\fR'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.
.TP
\fB\-e\fR, \fB\-\-enumerate\fR
lists out descriptive information about the pages and fields known to this
utility. Ignores the \fIDEVICE\fR argument and other options apart from
the \fI\-\-all\fR, \fI\-\-inquiry\fR, \fI\-\-long\fR, \fI\-\-page=PG[,SPG]\fR,
\fI\-\-transport=TN\fR and \fI\-\-vendor=VN\fR. If \fI\-\-enumerate\fR is
given without other options then the known (generic) mode pages are listed.
See the ENUMERATE section below.
.TP
\fB\-E\fR, \fB\-\-examine\fR
for mode pages only those with known field names are probed when the
\fI\-\-all\fR option is given. For VPD pages only those pages listed in
"Supported VPD pages page" are decoded. In both cases some pages may be
missed. With this option (i.e. \fI\-\-examine\fR) all mode and VPD pages can
be probed.
.br
For mode pages, this option will probe all mode pages from page number 0x0 to
0x3e. To probe mode subpages give a mode page number with \fI\-\-page=PG\fR
and then all subpages (from 0x0 to 0xfe) are probed.
.br
For VPD pages, use this option with \fI\-\-inquiry\fR. This will cause all VPD
pages from 0x0 to 0xbf to be probed by default. A sequence of VPD pages can
be probed with \fI\-\-page=PG[,SPG]\fR in which case VPD pages from PG (lower
number) to SPG (high number) inclusive are probed. Vendor specific VPD pages
run from 0xc0 to 0xff and can be probed by setting SPG from 0xc0 to 0xff.
.TP
\fB\-f\fR, \fB\-\-flexible\fR
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.
.TP
\fB\-g\fR, \fB\-\-get\fR=\fISTR\fR
In its simplest form \fISTR\fR contains a field acronym_name or a field
numerical descriptor. The field is fetched from mode page. See the PARAMETERS
section below. The \fI\-\-long\fR and \fI\-\-hex\fR 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).
.TP
\fB\-h\fR, \fB\-\-help\fR
output the usage message then exit.
.TP
\fB\-H\fR, \fB\-\-hex\fR
rather than trying to decode mode (or VPD) pages, print them out in
hex. When used with the \fI\-\-get=STR\fR 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 \fI\-\-get=STR\fR
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 \fI\-\-get=STR\fR
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.
.br
Mode page output with the '\-HHH' option is suitable for a later invocation
of sdparm with the \fI\-\-inhex=FN\fR option.
.TP
\fB\-i\fR, \fB\-\-inquiry\fR
output a VPD page which is in the response of a SCSI INQUIRY command sent
to \fIDEVICE\fR. In the absence of this option the default action
is to output mode pages. If the \fI\-\-inquiry\fR option is given without
the \fI\-\-page=PG[,SPG]\fR option then the device identification VPD
page (0x83) is decoded and output. If this option and the \fI\-\-all\fR
option are given then the supported VPD pages page (0x0) is decoded and
output.
.TP
\fB\-I\fR, \fB\-\-inhex\fR=\fIFN\fR
\fIFN\fR is expected to be a file name (or '\-' for stdin) which contains
ASCII hexadecimal (or binary) representing the response to MODE SENSE(10).
If \fI\-\-six\fR is also given then the response from MODE SENSE(6) is
assumed. A MODE SENSE response contains a mode parameter header, then 0
or more block descriptors followed by one or more mode pages. This utility
will only decode the first mode page unless the \fI\-\-all\fR option is
given. In order to decode a mode page the peripheral device type is often
needed and can be supplied with the \fI\-\-pdt=DT\fR option. If the
\fI\-\-pdt=DT\fR is not given then a mode page found in two device type
standards (e.g. SBC and SSC) may be decoded twice.
.br
If \fI\-\-inquiry\fR is given then \fIFN\fR is interpreted as the response
data of a single VPD page.
.br
The hexadecimal in \fIFN\fR should be arranged as 1 or 2 digits representing
a byte each of which is whitespace or comma separated. Anything from and
including a hash mark to the end of line is ignored. If the \fI\-\-raw\fR
option is given then \fIFN\fR is treated as binary.
.TP
\fB\-l\fR, \fB\-\-long\fR
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 \fI\-\-enumerate\fR
see the ENUMERATE section below.
.br
When this option is used along with \fI\-\-command=capacity\fR then the
READ CAPACITY(16) is sent to the \fIDEVICE\fR and if successful its extended
response is output.
.TP
\fB\-n\fR, \fB\-\-num\-desc\fR
for a mode page that can have descriptors, the number of descriptors for the
given page on the \fIDEVICE\fR is output. Otherwise 0 is output.
.TP
\fB\-o\fR, \fB\-\-out\-mask\fR=\fIOM\fR
\fIOM\fR is a bit mask for mode page selections that will be printed/output.
The 0x1 value is for the 'current' values, 0x2 is for the 'changeable'
values, 0x4 is for the 'default' values and 0x8 is for the 'saveable' values.
The default value is 0xf (i.e. the OR of all four values set). The option is
useful for limiting the amount of output with the '\-HHH'.
.TP
\fB\-p\fR, \fB\-\-page\fR=\fIPG[,SPG]\fR
supply the page number (\fIPG\fR) and optionally the sub page
number (\fISPG\fR) 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).
.TP
\fB\-p\fR, \fB\-\-page\fR=\fISTR\fR
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 \fISTR\fR matches a known
VPD page abbreviation then the \fI\-\-inquiry\fR option is assumed. For
usage with \fI\-\-enumerate\fR see the ENUMERATE section below.
.TP
\fB\-P\fR, \fB\-\-pdt\fR=\fIDT\fR
This option is only active when the \fI\-\-inhex=FN\fR option is given.
\fIDT\fR is the peripheral Device Type, a value between 0 and 31 and
can be found in the response to the INQUIRY command. The default value
is \-1 (which may also be given for \fIDT\fR) and it is interpreted as
SPC (i.e. common mode pages) or as a wild card. If available this option
should be supplied with the \fI\-\-inhex=FN\fR option.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
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.
.br
If this option is used twice then additionally mode page output suppresses the
changeable, default and saved values that are usually shown in braces, if
available.
.TP
\fB\-r\fR, \fB\-\-readonly\fR
override other logic to open \fIDEVICE\fR in read\-only mode. The default
setting of the open read\-only/read\-write mode depends on the operation
requested (e.g. a \fI\-\-set=STR\fR operation by default will try a
read\-write mode open on \fIDEVICE\fR). 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.
.TP
\fB\-R\fR, \fB\-\-raw\fR
this option is only active when used with the \fI\-\-inhex=FN\fR option.
When this option is given then the file \fIFN\fR is interpreted as binary;
the default action (i.e. when this option is not given) is to interpret
\fIFN\fR as ASCII hexadecimal.
.TP
\fB\-S\fR, \fB\-\-save\fR
when a mode page is being modified (by using the \fI\-\-clear=STR\fR and/or
\fI\-\-set=STR\fR 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. This option sets the SP field in
the MODE SELECT command. See NOTES section below.
.TP
\fB\-s\fR, \fB\-\-set\fR=\fISTR\fR
in its simplest form \fISTR\fR 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.
.TP
\fB\-6\fR, \fB\-\-six\fR
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.
.br
The SPC\-4 standard (and SPC\-5 drafts) include a note stating that
implementers migrate away from the SCSI MODE SELECT(6) and MODE SENSE(6)
commands in favour of the 10 byte variants (e.g.  MODE SEMSE(10)).
.TP
\fB\-t\fR, \fB\-\-transport\fR=\fITN\fR
Specifies the transport protocol where \fITN\fR is either a number in the
range 0 to 15 (inclusive) or an abbreviation (e.g. "fcp" for the Fibre
Channel Protocol). Some transports accept multiple abbreviations, for example
srp (SCSI RDMA Protocol) and ib (short for InfiniBand) both are accepted for
transport protocol 0x4 . Also both upper and lower case are accepted so iscsi
and iSCSI are accepted for transport protocol 0x5 . One way to list available
transport protocols numbers and their associated abbreviations is to give an
invalid transport protocol name such as '\-t x'; another way is '\-e \-l'.
N.B. The \fI\-\-all\fR option may still be needed to show all available
fields.
.TP
\fB\-M\fR, \fB\-\-vendor\fR=\fIVN\fR
Specifies the vendor (i.e. manufacturer) where \fIVN\fR is either a number (0
or more) or an abbreviation (e.g. "sea" for Seagate disk vendor specific).
For tape drives "lto5" and "lto6" are treated as vendors. One way to list
the available vendor numbers and their associated abbreviations is to give an
invalid vendor number such as '\-M x'; another way is '\-e \-l'.
.br
This option only effects mode page decodes, not VPD pages. For vendor
specific VPD pages see the sg_vpd utility.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
increase the level of verbosity, (i.e. debug output). In some cases
more decoding is done (e.g. fields within a standard INQUIRY response).
.TP
\fB\-V\fR, \fB\-\-version\fR
print the version string and then exit.
.TP
\fB\-w\fR, \fB\-\-wscan\fR
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.
.SH NOTES
The reference document used for interpreting mode and VPD pages (and the
INQUIRY standard response) is T10/BSR INCITS 502 Revision 17 (SPC\-5, 19
September 2017) 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\-5 (SAS transport) and SAT\-4 (SCSI to ATA Translation).
.PP
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'.
.PP
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 \fI\-\-page\fR= either a string or number is expected, so hex
numbers like 'ch' (12) should be prefixed by a zero (e.g. '0ch').
.PP
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 \fI\-\-save\fR option) is _not_ set. In such cases
the \fI\-\-save\fR option needs to be given.
.PP
If the \fI\-\-save\fR option is given but the existing mode page indicates (via
its PS bit) that the page is not saveable, then this utility generates
an error message. That message suggests to try again without the
\fI\-\-save\fR option.
.PP
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".
.PP
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.
.PP
To see all VPD pages supported by a \fIDEVICE\fR use 'sg_vpd \-\-all'.
.PP
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.
.PP
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".
.SH PARAMETERS
In their simplest form the \fI\-\-clear\fR=, \fI\-\-get\fR= and
\fI\-\-set\fR= 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).
.PP
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
\fI\-\-page\fR= option is required to establish which mode page is to be
used.
.PP
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 \fI\-\-clear\fR= is not given an explicit '=<val>'
then the value defaults to zero. When the acronym_name or numeric form
following \fI\-\-set\fR= 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.
.PP
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'.
.PP
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.
.SH ENUMERATE
The \fI\-\-enumerate\fR option essentially dumps out static information held
by this utility. A list of \fI\-\-enumerate\fR variants and their actions
follows. For brevity subsequent examples of options are shown in their
shorter form.
.PP
    \-\-enumerate          list generic mode page information
.br
    \-e \-\-all             list generic mode page contents
.br
                         (i.e. parameters)
.br
    \-e \-\-page=rw         list contents of read write error
.br
                         recovery mode page
.br
    \-e \-\-inquiry         list VPD pages this utility can decode
.br
    \-e \-\-long            list generic mode pages, transport
.br
                         protocols, mode pages for each
.br
                         supported transport protocol and
.br
                         supported commands
.br
    \-e \-l \-\-all          additionally list the contents of
.br
                         each mode page
.br
    \-e \-\-transport=fcp   list mode pages for the fcp
.br
                         transport protocol
.br
    \-e \-t fcp \-\-all      additionally list the contents of
.br
                         each mode page
.br
    \-e \-\-vendor=sea      list vendor specific mode pages for
.br
                         "sea" (Seagate)
.br
    \-e \-M sea \-\-all      additionally list the contents of vendor
.br
                         specific mode pages for "sea" (Seagate)
.br
    \-e \-p pcd \-l         list contents of SAS phy control and
.br
                         discovery mode page plus (due to "\-l")
.br
                         some descfriptor format information
.PP
When known mode pages are listed (via the \fI\-\-enumerate \fR 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.
.PP
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.
.PP
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).
.SH TRANSPORTS
SCSI transport protocols are a relatively specialized area
that can be safely ignored by the majority of users.
.PP
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".
.PP
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
\fI\-\-transport\fR= 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.
.SH VENDORS
SCSI leaves a lot of space for vendor specific information. Often this is
described in product manuals. The \fI\-\-vendor=VN\fR (or \fI\-M=VN\fR)
option allows known vendor specific mode pages to be examined and/or
modified by acronym.
.PP
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).
.SH COMMANDS
The command option sends a SCSI command to the \fIDEVICE\fR. If the
command fails then this is reflected in the non\-zero exit status.
To obtain more information about the error use the \fI\-v\fR option.
.TP
capacity
sends a READ CAPACITY(10) command (valid for disks and cd/dvd media) by
default. If successful yields "blocks: " [the number of
blocks], "block_length: " [typically either 512 or 2048]
and "capacity_mib: " [capacity in MibiBytes (1048576 byte units)].
.PP
If the number of blocks is too large to fit in the 4 byte field provided
by READ CAPACITY(10) or, the \fI\-\-long\fR option is given, then the
READ CAPACITY(16) command is sent. If the \fI\-\-long\fR option is given,
then the extra fields found in the READ CAPACITY(16) response are output.
.TP
eject
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).
.TP
load
loads the medium and starts it (i.e. spins it up). See 'eject' command for
supported device types.
.TP
profile
lists the various formats that a CD/DVD/HD\-DVD/BD drive supports. These are
called "profiles" in the MMC standard. The profiles are listed one per line.
If media is in the drive then the profile that matches the media (if any)
has an "*" to the right of the line.
.TP
ready
sends the "Test Unit Ready" SCSI command to the
\fIDEVICE\fR. 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.
.TP
sense
sends a REQUEST SENSE command. It reports a hardware
threshold exceeded, warning or low power condition if flagged. If a progress
indication is present (e.g. during a format) then it will be output as a
percentage. Yields a process status of 0 if the command succeeds and the
sense key is 0; else yields 1. The \fI\-\-quiet\fR option can be used to
lessen output, and \fI\-\-hex\fR to output sense data in hex.
.TP
speed=SPEED
permits the speed of a CD, DVD, HD_DVD or BD disc in a drive to be set (or
at least influenced). It has this format: \fI\-\-command=speed=SPEED\fR
where SPEED is in kilobytes per second. In this case a kilobyte is 1000
bytes. The "times one" speed for a CD is 176.4 kB/s, for a DVD is
1350 kB/s and for both HD\-DVD and BD it is 4500 kB/s. If SPEED is zero then
the drive is set to the speed that it considers gives optimal performance.
This command sends a SET STREAMING multi\-media command (MMC) to the drive.
The EXACT bit is clear so the drive will round the given SPEED as necessary.
The command is designed to control read speed; setting write speed should
be left to "burning" programs.
.TP
start
starts the medium (i.e. spins it up). Harmless if medium has already been
started. See 'eject' command for supported device types. If the \fIDEVICE\fR
is an ATA disk in Linux the '\-\-readonly' option may be required.
.TP
stop
stops the medium (i.e. spins it down). Harmless if
medium has already been stopped. See 'eject' command for supported device
types. If the \fIDEVICE\fR is an ATA disk in Linux the '\-\-readonly'
option may be required. See the NOTES section above.
.TP
sync
sends a SYNCHRONIZE CACHE command. The device should
flush any data held in its (volatile) buffers to the media.
.TP
unlock
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.
.PP
For loading and ejecting tapes the mt utility should be used (i.e. not
these commands). The 'ready' command is valid for tape devices.
.SH EXAMPLES
To list the common (generic) mode parameters of a disk:
.PP
   sdparm /dev/sda
.PP
To list the designators within the device identification VPD page
of a disk:
.PP
   sdparm \-\-inquiry /dev/sda
.PP
To see all parameters for the caching mode page:
.PP
   sdparm \-\-page=ca /dev/sda
.PP
To see all parameters for the caching mode page
with parameter descriptions to the right:
.PP
   sdparm \-\-page=ca \-\-long /dev/sda
.PP
To get the WCE values (current changeable default and saved) in hex:
.PP
   sdparm \-g WCE \-H /dev/sda
.br
0x01 0x00 0x01 0x01
.PP
To get the WCE current value in hex:
.PP
   sdparm \-g WCE=1 \-H /dev/sda
.br
0x01
.PP
To set the "Writeback Cache Enable" bit in the current values page:
.PP
   sdparm \-\-set=WCE /dev/sda
.PP
To set the "Writeback Cache Enable" bit in the current and saved values page:
.PP
   sdparm \-\-set=WCE \-\-save /dev/sda
.PP
To set the "Writeback Cache Enable" and clear "Read Cache Disable":
.PP
   sdparm \-\-set=WCE \-\-clear=RCD \-\-save /dev/sda
.PP
The previous example can also by written as:
.PP
   sdparm \-s WCE=1,RCD=0 \-S /dev/sda
.PP
To re\-establish the manufacturer's defaults in the current and saved
values of the caching mode page:
.PP
   sdparm \-\-page=ca \-\-defaults \-\-save /dev/sda
.PP
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:
.PP
   sdparm /dev/hdc
.PP
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:
.PP
   sdparm \-\-command=eject /dev/hdc
.PP
If the ejection is being prevented by software then that can be
overridden with:
.PP
   sdparm \-\-command=unlock /dev/hdc
.PP
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:
.PP
   sdparm \-\-page=0 \-\-set=2:7:1=1 \-\-save /dev/sda
.PP
The resultant change can be viewed in hex with the \fI\-\-hex\fR 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:
.PP
   sdparm \-\-vendor=sea \-\-set=PM \-\-save /dev/sda
.PP
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.
.PP
  # sdparm \-\-wscan
.br
PD0     [C]     FUJITSU   MHY2160BH         0000
.br
PD1     [DF]    WD        2500BEV External  1.05  WD\-WXE90
.br
CDROM0  [E]     MATSHITA DVD/CDRW UJDA775  CB03
.PP
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 '\-\-wscan' option twice,
the bus type (as seen by the OS) is added to the output:
.PP
  # sdparm \-ww
.br
PD0     [C]     <Ata  >  FUJITSU   MHY2160BH         0000
.br
PD1     [DF]    <Usb  >  WD        2500BEV External  1.05  WD\-WXE90
.br
CDROM0  [E]     <Atapi>  MATSHITA DVD/CDRW UJDA775  CB03
.PP
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.
.PP
  # sdparm \-www
.br
PD0     [C]     <Ata  >  FUJITSU   MHY2160BH         0000
.br
PD1     [DF]    <Usb  >  WD        2500BEV External  1.05  WD\-WXE90
.br
CDROM0  [E]     <Atapi>  MATSHITA DVD/CDRW UJDA775  CB03
.br

.br
SCSI0:0,0,0   claimed=1 pdt=0h  FUJITSU   MHY2160BH         0000
.br
SCSI1:0,0,0   claimed=1 pdt=5h  MATSHITA  DVD/CDRW UJDA775  CB03
.PP
.SH EXIT STATUS
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:
.TP
.B 0
success
.TP
.B 1
syntax error. Either illegal command line options, options with bad
arguments or a combination of options that is not permitted.
.TP
.B 2
the \fIDEVICE\fR reports that it is not ready for the operation
requested. The device may be in the process of becoming ready (e.g.
spinning up but not at speed) so the utility may work after a wait.
.TP
.B 3
the \fIDEVICE\fR reports a medium or hardware error (or a blank
check). For example an attempt to read a corrupted block on a disk
will yield this value.
.TP
.B 5
the \fIDEVICE\fR reports an "illegal request" with an additional
sense code other than "invalid operation code". This is often a
supported command with a field set requesting an unsupported
capability. For commands that require a "service action" field
this value can indicate that the command is not supported.
.TP
.B 6
the \fIDEVICE\fR reports a "unit attention" condition. This usually
indicates that something unrelated to the requested command has
occurred (e.g. a device reset) potentially before the current SCSI
command was sent. The requested command has not been executed by the
device. Note that unit attention conditions are usually only reported
once by a device.
.TP
.B 7
the \fIDEVICE\fR reports a "data protect" sense key. This implies some
mechanism has blocked writes (or possibly all access to the media).
.TP
.B 9
the \fIDEVICE\fR reports an illegal request with an additional
sense code of "invalid operation code" which means that it doesn't
support the requested command.
.TP
.B 10
the \fIDEVICE\fR reports a "copy aborted". This implies another command or
device problem has stopped a copy operation. The EXTENDED COPY family of
commands (including WRITE USING TOKEN) may return this sense key.
.TP
.B 11
the \fIDEVICE\fR reports an aborted command. In some cases aborted
commands can be retried immediately (e.g. if the transport aborted
the command due to congestion).
.TP
.B 14
the \fIDEVICE\fR reports a miscompare sense key. VERIFY and COMPARE AND
WRITE commands may report this.
.TP
.B 15
the utility is unable to open, close or use the given \fIDEVICE\fR.
The given file name could be incorrect or there may be permission
problems. Adding the \fI\-v\fR option may give more information.
.TP
.B 20
the \fIDEVICE\fR reports it has a check condition but "no sense".
Some polling commands (e.g. REQUEST SENSE) can react this way.
It is unlikely that this value will occur as an exit status.
.TP
.B 21
the \fIDEVICE\fR reports a "recovered error". The requested command
was successful. Most likely a utility will report a recovered error
to stderr and continue, probably leaving the utility with an exit
status of 0 .
.TP
.B 22
the \fIDEVICE\fR reports that the current command or its parameters imply
a logical block address (LBA) that is out of range.
.TP
.B 24
the \fIDEVICE\fR reports a SCSI status of "reservation conflict". This
means access to the \fIDEVICE\fR with the current command has been blocked
because another machine (HBA or SCSI "initiator") holds a reservation on
this \fIDEVICE\fR. On modern SCSI systems this is related to the use of
the PERSISTENT RESERVATION family of commands.
.TP
.B 25
the \fIDEVICE\fR reports a SCSI status of "condition met". Currently only
the PRE\-FETCH command (see SBC\-4) yields this status.
.TP
.B 26
the \fIDEVICE\fR reports a SCSI status of "busy". SAM\-5 defines this
status as the logical unit is temporarily unable to process a command.
It is recommended to re\-issue the command.
.TP
.B 27
the \fIDEVICE\fR reports a SCSI status of "task set full".
.TP
.B 28
the \fIDEVICE\fR reports a SCSI status of "ACA active". ACA is "auto
contingent allegiance" and is seldom used.
.TP
.B 29
the \fIDEVICE\fR reports a SCSI status of "task aborted". SAM\-5 says:
"This status shall be returned if a command is aborted by a command or task
management function on another I_T nexus and the Control mode page TAS bit
is set to one".
.TP
.B 33
the command sent to \fIDEVICE\fR has timed out. This occurs in Linux
only; in other ports a command timeout will appear as a transport (or OS)
error.
.TP
.B 40
the command sent to \fIDEVICE\fR has received an "aborted command" sense
key with an additional sense code of 0x10. This value is related to
problems with protection information (PI or DIF). For example this error
may occur when reading a block on a drive that has never been written (or
is unmapped) if that drive was formatted with type 1, 2 or 3 protection.
.TP
.B 48
this is an internal message indicating a NVMe status field (SF) is other
than zero after a command has been executed (i.e. something went wrong).
Work in this area is currently experimental.
.TP
.B 49
low level driver reports a response's residual count (i.e. number of bytes
actually received by HBA is 'requested_bytes \- residual_count') that is
too high. So no useful processing can be done with that response.
.TP
.B 50 + <os_error_number>
OS system calls that fail often return a small integer number to help
indicate what the error is. For example in Unix the inability of a system
call to allocate memory returns (in 'errno') ENOMEM which often is
associated with the integer 12. So 62 (i.e. '50 + 12') may be returned
by a utility in this case.
.TP
.B 97
the response to a SCSI command failed sanity checks.
.TP
.B 98
the \fIDEVICE\fR reports it has a check condition but the error
doesn't fit into any of the above categories.
.TP
.B 99
any errors that can't be categorized into values 1 to 98 may yield
this value. This includes transport and operating system errors
after the command has been sent to the device.
.TP
.B 126
the utility was found but could not be executed. That might occur if the
executable does not have execute permissions.
.TP
.B 127
This is the exit status for utility not found. That might occur when a
script calls a utility in this package but the PATH environment variable
has not been properly set up, so the script cannot find the executable.
.TP
.B 128 + <signum>
If a signal kills a utility then the exit status is 128 plus the signal
number. For example if a segmentation fault occurs then a utility is
typically killed by SIGSEGV which according to 'man 7 signal' has an
associated signal number of 11; so the exit status will be 139 .
.TP
.B 255
the utility tried to yield an exit status of 255 or larger. That should
not happen; given here for completeness.
.PP
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 \fI\-v\fR option (or several) to obtain more
information.
.SH AUTHORS
Written by Douglas Gilbert.
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2005\-2021 Douglas Gilbert
.br
This software is distributed under a FreeBSD license. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH WEB SITE
There is a web page discussing this package at
https://sg.danny.cz/sg/sdparm.html .
.SH "SEE ALSO"
.B hdparm(hdparm),
.B sg_modes, sg_wr_mode, sginfo, sg_inq, sg_vpd(all in sg3_utils),
.B smartmontools(smartmontools.sourceforge.net), mt, eject(eject),