Provided by: sdparm_0.96-1_i386 bug

NAME

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

SYNOPSIS

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

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

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.

AUTHORS

       Written by Douglas Gilbert.

REPORTING BUGS

       Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT

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

SEE ALSO

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