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

PARAMETERS

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.

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

TRANSPORTS

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.

COMMANDS

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.

NOTES

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.

EXAMPLES

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.