Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SDPARM(8)			    SDPARM			     SDPARM(8)

NAME
       sdparm -	access SCSI modes pages; read VPD pages; send simple SCSI com-
       mands.

SYNOPSIS
       sdparm [--all] [--dbd]  [--examine]  [--flexible]  [--get=STR]  [--hex]
       [--long]	  [--num-desc]	 [--out-mask=OM]  [--page=PG[,SPG]]  [--quiet]
       [--readonly] [--six] [--transport=TN] [--vendor=VN] [--verbose]	DEVICE
       [DEVICE...]

       sdparm	  [--clear=STR]	    [--defaults]     [--dummy]	  [--flexible]
       [--page=PG[,SPG]] [--quiet] [--readonly]	[--save]  [--set=STR]  [--six]
       [--transport=TN]	[--vendor=VN] [--verbose] DEVICE [DEVICE...]

       sdparm  --command=CMD  [--hex] [--long] [--readonly] [--verbose]	DEVICE
       [DEVICE...]

       sdparm --inquiry	[--all]	[--examine] [--flexible] [--hex]  [--num-desc]
       [--page=PG[,SPG]]  [--quiet]  [--readonly] [--transport=TN] [--verbose]
       DEVICE [DEVICE...]

       sdparm  --enumerate  [--all]  [--inquiry]  [--long]   [--page=PG[,SPG]]
       [--transport=TN]	[--vendor=VN]

       sdparm  --inhex=FN  [--all]  [--flexible]  [--hex] [--inquiry] [--long]
       [--pdt=DT] [--raw] [--six] [--transport=TN] [--vendor=VN] [--verbose]

       sdparm --wscan [--verbose]

       sdparm [--help] [--version]

DESCRIPTION
       This utility fetches and	potentially changes SCSI  device  (e.g.	 disk)
       mode  pages.  Inquiry data including Vital Product Data (VPD) pages can
       also be displayed. Commands associated with starting and	 stopping  the
       medium;	loading	and unloading the medium; and other housekeeping func-
       tions may also be issued	by this	utility.

       The first invocation shown in the synopsis is for accessing (i.e. read-
       ing) mode page fields held on the DEVICE. The second form is for	chang-
       ing mode	page fields held on the	DEVICE.	The third form is for  execut-
       ing  some  simple  SCSI commands. The fourth form (i.e.	the '--inquiry
       ...  DEVICE' form) is for fetching and  decoding	 VPD  pages  from  the
       given DEVICE. The --enumerate form is for listing out mode or VPD field
       data held by this utility (and if a DEVICE is  given  then  it  is  ig-
       nored).	The --inhex=FN form decodes mode or VPD	response data provided
       in the named file (or from stdin	if FN=-	is given); that	data  may  ei-
       ther  be	 in hexadecimal	or binary. The second last form	is for Windows
       only and	lists the available storage device names; see the OPTIONS  en-
       try  for	--wscan. The final form	is to provide command line help	or the
       version number (and date) of this utility.

       If no options (other than DEVICE) are given then	a selection of	common
       mode  page  fields  for that device are listed. If the --long option is
       also given then a description of	the fields is placed on	the  right  of
       each line. If the --all option is given then all	known mode page	fields
       for that	device are listed. Individual fields can be displayed with the
       --get=STR  option (e.g. '--get=WCE' to fetch the	state of the Writeback
       Cache Enable field).

       This utility completes with an exit status of 0	when  successful.  For
       other values see	the EXIT STATUS	section	below.

       One or more DEVICE arguments can	be given. The utility will essentially
       apply the given options to each DEVICE in the list. If a	error  is  de-
       tected, it is noted and the utility continues. Error value 5 (file open
       or close	problem) is treated as lower priority when  other  errors  are
       detected.  The  exit  status  is	the most recently detected error value
       (excluding error	value 5	if other errors	have been  detected).  If  all
       actions succeed the exit	status is zero.

       By  default this	utility	shows mode pages that are common to all	trans-
       port protocols. These are termed	as "generic" mode pages. If  there  is
       no match	on a generic mode page name or field then those	pages specific
       to the SAS transport are	checked.   Transport  protocol	specific  mode
       pages  are  selected  with the --transport=TN option. See the TRANSPORT
       section below.  Vendor specific mode pages are selected with the	--ven-
       dor=VN option.  See the VENDORS section below.

       Although	 originally  for SCSI disks (or	storage	devices	that appear to
       the OS as SCSI disks) many of the mode pages are	for other SCSI	device
       types.	These include CD/DVD players that use the ATAPI	(or any	other)
       transport, SCSI tapes drives and	SCSI enclosures.

       When the	--inquiry option is given without a page number	then  the  De-
       vice  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 con-
       tents) supported	by the DEVICE is output. When both the	--inquiry  and
       --page=PG  options  are	given then the VPD page	can be specified as an
       abbreviation (e.g. "sp" for the SCSI ports  VPD	page)  or  numerically
       (e.g.  "0x88"). If a VPD	page is	returned by the	DEVICE but sdparm can-
       not decode it or	the --hex option is given then it is output in hex.

OPTIONS
       Mandatory arguments to long options are mandatory for short options  as
       well.   If an option takes a numeric argument then that argument	is as-
       sumed to	be decimal unless otherwise indicated  (e.g.  with  a  leading
       "0x"  or	 a trailing "h"). The options are in alphabetical order, based
       on the long option name.

       -a, --all
	      output all recognized fields for the device type (e.g. disk)  of
	      the  DEVICE. Without this	option (or the --page=PG[,SPG] option)
	      the default action is to output a	 relatively  small  number  of
	      commonly	used  fields  from  different  pages.  When a specific
	      (mode) page number is given with the --page=PG[,SPG] option then
	      all the fields of	that page are output (irrespective of the set-
	      ting of this option). For	this option's action  when  used  with
	      the --enumerate option see the ENUMERATE section below.
	      When  used  together with	the --inquiry option and a DEVICE, 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.
	      By default --inhex=FN will only decode the first mode page found
	      in  FN.  With  this  option,  more mode pages will be decoded if
	      present. When --transport=TN or --vendor=VN is also  given  then
	      if  a  given mode	page is	not defined for	that transport or ven-
	      dor, then	it is decoded as a generic mode	page.

       -c, --clear=STR
	      In its simplest form STR contains	 a  field  acronym_name	 or  a
	      field  numerical descriptor. In the absence of an	explicit value
	      argument (e.g. '--clear=WCE=1'), the field has its value cleared
	      to zero.	See the	PARAMETERS section below.

       -C, --command=CMD
	      Perform  given  CMD. See section below on	COMMANDS. To enumerate
	      supported	commands use '-e -C x' (using any CMD name,  valid  or
	      otherwise).

       -B, --dbd
	      disable block descriptors. This is a bit in MODE SENSE cdbs that
	      rarely needs to be set. One known	case is	a MODE SENSE 6	issued
	      to  a Reduced Block Commands (RBC) device	where the RBC standard
	      says it shall be set.

       -D, --defaults
	      sets the given mode page to its  default	values.	 Requires  the
	      --page=PG[,SPG]  option to be given to specify the mode page. To
	      make the default mode page values	also the saved mode page  val-
	      ues, use the --save option as well.
	      when  this option	is used	twice, the current values in all modes
	      pages are	reverted to their defaults. If the  --save  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.

       -d, --dummy
	      when set inhibits	changes	being  placed  in  the	DEVICE's  mode
	      page.  Instead the mode data that	would have been	sent to	a MODE
	      SELECT command, is output	in ASCII hex to	the console. This  op-
	      tion is mainly for testing.

       -e, --enumerate
	      lists  out  descriptive  information  about the pages and	fields
	      known to this utility. Ignores the DEVICE	argument and other op-
	      tions  apart from	the --all, --inquiry, --long, --page=PG[,SPG],
	      --transport=TN and --vendor=VN. If --enumerate is	given  without
	      other  options  then  the	known (generic)	mode pages are listed.
	      See the ENUMERATE	section	below.

       -E, --examine
	      for mode pages only those	with known field names are probed when
	      the --all	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. --examine) all mode
	      and VPD pages can	be probed.
	      For mode pages, this option will probe all mode pages from  page
	      number 0x0 to 0x3e. To probe mode	subpages give a	mode page num-
	      ber with --page=PG and then all subpages (from 0x0 to 0xfe)  are
	      probed.
	      For  VPD	pages, use this	option with --inquiry. This will cause
	      all VPD pages from 0x0 to	0xbf to	be probed by  default.	A  se-
	      quence  of VPD pages can be probed with --page=PG[,SPG] in which
	      case VPD pages from PG (lower number) to SPG (high  number)  in-
	      clusive  are  probed. Vendor specific VPD	pages run from 0xc0 to
	      0xff and can be probed by	setting	SPG from 0xc0 to 0xff.

       -f, --flexible
	      Some devices, bridges and/or drivers attempt  crude  transforma-
	      tions  between  mode  sense  6 and 10 byte commands without cor-
	      rectly 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 at-
	      tempted. This option will	also allow mode	pages that  don't  be-
	      long to the current device's peripheral type to be listed.

       -g, --get=STR
	      In  its  simplest	 form  STR  contains a field acronym_name or a
	      field numerical descriptor. The field is fetched from mode page.
	      See  the	PARAMETERS section below. The --long and --hex options
	      effect the output	format.	Also if	a value	of "1" is given	 (e.g.
	      '--get=WCE=1')  only  the	 current value is output (i.e. not the
	      change mask, the default value and the saved value).

       -h, --help
	      output the usage message then exit.

       -H, --hex
	      rather than trying to decode mode	(or VPD) pages,	print them out
	      in  hex.	When  used with	the --get=STR option the corresponding
	      current, changeable, default and saved values are	output in hex,
	      prefixed by "0x" and space separated. If a value of "1" is given
	      with the --get=STR option	(e.g.  '--get=WCE=1')  then  only  the
	      current  value is	output in hex, prefixed	by "0x". If a value of
	      "2" is given with	the --get=STR option  then  only  the  current
	      value  is	 output	as a (signed) integer. This option can be used
	      multiple times (e.g. '-HH'). Useful with the ATA Information VPD
	      page which usually outputs its IDENTIFY (PACKET) DEVICE response
	      in 16 bit	hex words; with	'-HH' outputs  that  response  in  hex
	      bytes;  with  '-HHH' outputs the same response in	a format suit-
	      able for 'hdparm --Istdin' to decode.
	      Mode page	output with the	'-HHH' option is suitable for a	 later
	      invocation of sdparm with	the --inhex=FN option.

       -i, --inquiry
	      output  a	 VPD  page  which is in	the response of	a SCSI INQUIRY
	      command sent to DEVICE. In the absence of	this  option  the  de-
	      fault action is to output	mode pages. If the --inquiry option is
	      given without the	--page=PG[,SPG]	option then the	device identi-
	      fication	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.

       -I, --inhex=FN
	      FN  is  expected to be a file name (or '-' for stdin) which con-
	      tains ASCII hexadecimal (or binary) representing the response to
	      MODE  SENSE(10).	 If --six 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 --all option	is given. In order to decode a
	      mode page	the peripheral device type is often needed and can  be
	      supplied	with the --pdt=DT option. If the --pdt=DT is not given
	      then a mode page found in	two device type	 standards  (e.g.  SBC
	      and SSC) may be decoded twice.
	      If  --inquiry  is	 given	then FN	is interpreted as the response
	      data of a	single VPD page.
	      The hexadecimal in FN should be arranged as 1 or 2 digits	repre-
	      senting  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 --raw option is given then FN is	treated	as bi-
	      nary.

       -l, --long
	      output extra information.	In the case of mode page fields	a  de-
	      scription	 (with units if	applicable) is output to the right. If
	      used twice, then for some	fields more information	about its val-
	      ues  is given on one or more following lines, each prefixed by a
	      tab character. For usage with --enumerate	see the	ENUMERATE sec-
	      tion below.
	      When  this option	is used	along with --command=capacity then the
	      READ CAPACITY(16)	is sent	to the DEVICE and  if  successful  its
	      extended response	is output.

       -n, --num-desc
	      for  a  mode  page  that can have	descriptors, the number	of de-
	      scriptors	for the	given page on the DEVICE is output.  Otherwise
	      0	is output.

       -o, --out-mask=OM
	      OM  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'.

       -p, --page=PG[,SPG]
	      supply the page number (PG) and optionally the sub  page	number
	      (SPG)  of	the mode (or VPD) page to fetch. These numbers are in-
	      terpreted	as decimal unless prefixed with	"0x"  or  a  trailing.
	      Sub  page	numbers	are only valid for mode	pages (not VPD pages).
	      Alternatively an abbreviation for	a page can be given (see  next
	      entry).

       -p, --page=STR
	      a	 two  or  three	 letter	 abbreviation for a page can be	given.
	      Known mode page abbreviations  are  checked  first  followed  by
	      known  VPD  page abbreviations.  For example '--page=ca' matches
	      the caching mode page. If	no match is found then an error	is is-
	      sued 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 us-
	      age with --enumerate see the ENUMERATE section below.

       -P, --pdt=DT
	      This option is only active when the --inhex=FN option is	given.
	      DT  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 DT) and it is	inter-
	      preted as	SPC (i.e. common mode pages) or	as  a  wild  card.  If
	      available	this option should be supplied with the	--inhex=FN op-
	      tion.

       -q, --quiet
	      suppress output of device	name followed by the  vendor,  product
	      and  revision  strings fetched from an INQUIRY response. Without
	      this option such a line is typically the first  line  output  by
	      sdparm.  Reduces output from the device identification VPD page,
	      typically	to one line (or	none)  for  each  of  di_lu,  di_port,
	      di_target	and di_asis.
	      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.

       -r, --readonly
	      override	other  logic to	open DEVICE in read-only mode. The de-
	      fault setting of the open	read-only/read-write mode  depends  on
	      the  operation  requested	(e.g. a	--set=STR operation by default
	      will try a read-write mode open on DEVICE). This option  may  be
	      useful if	a command is being sent	to an ATA disk via a SCSI com-
	      mand set.	For example in Linux '-C stop' may require this	option
	      to stop an ATA disk being	restarted immediately.

       -R, --raw
	      this option is only active when used with	the --inhex=FN option.
	      When this	option is given	then the file FN is interpreted	as bi-
	      nary; the	default	action (i.e. when this option is not given) is
	      to interpret FN as ASCII hexadecimal.

       -S, --save
	      when a mode page is being	modified  (by  using  the  --clear=STR
	      and/or  --set=STR	 options) then the default action is to	modify
	      only the current values mode page. When  this  option  is	 given
	      then the corresponding value(s) in the saved values mode page is
	      also changed. The	next time the device is	power cycled  (or  re-
	      set)  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.

       -s, --set=STR
	      in  its  simplest	 form  STR  contains a field acronym_name or a
	      field numerical descriptor. In the absence of an explicit	value,
	      each  acronym_name has its value set to (all) ones. This means a
	      16 bit field will	be set to 0xffff which is  65535  in  decimal.
	      Alternatively  each  acronym_name	or numerical descriptor	may be
	      followed by "=<n>" where <n> is the value	to set that field  to.
	      See the PARAMETERS section below.

       -6, --six
	      The  default  action  of this utility is to issue	MODE SENSE and
	      MODE SELECT SCSI commands	with 10	byte cdbs. When	this option is
	      given the	6 byte cdb variants are	used. RBC and old SCSI devices
	      may need this option. This utility outputs a suggestion  to  use
	      this  option  if	the SCSI status	indicates that the 10 byte cdb
	      variant is not supported.
	      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)).

       -t, --transport=TN
	      Specifies	 the transport protocol	where TN is either a number in
	      the range	0 to 15	(inclusive) or an abbreviation (e.g. "fcp" for
	      the Fibre	Channel	Protocol). Some	transports accept multiple ab-
	      breviations, 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	avail-
	      able transport protocols numbers and their associated  abbrevia-
	      tions  is	to give	an invalid transport protocol name such	as '-t
	      x'; another way is '-e -l'.  N.B.	The --all option may still  be
	      needed to	show all available fields.

       -M, --vendor=VN
	      Specifies	 the  vendor  (i.e. manufacturer) where	VN is either a
	      number (0	or more) or an abbreviation (e.g.  "sea"  for  Seagate
	      disk  vendor  specific).	 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'.
	      This option only effects mode page decodes, not VPD  pages.  For
	      vendor specific VPD pages	see the	sg_vpd utility.

       -v, --verbose
	      increase	the  level  of verbosity, (i.e.	debug output). In some
	      cases more decoding is done (e.g.	fields within a	 standard  IN-
	      QUIRY response).

       -V, --version
	      print the	version	string and then	exit.

       -w, --wscan
	      this  option  is available in Windows only. It lists storage de-
	      vice names and the corresponding	volumes,  if  any.  When  used
	      twice  it	 adds  the "bus	type" of the closest transport (e.g. a
	      SATA disk	in a USB connected enclosure has bus type  Usb).  When
	      used  three  times  a SCSI adapter scan is added.	When used four
	      times only a SCSI	adapter	scan is	shown.	See examples below and
	      the "Win32 port" section in the README file.

NOTES
       The  reference  document	 used for interpreting mode and	VPD pages (and
       the INQUIRY standard  response)	is  T10/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).

       A  mode page for	which no abbreviation is known (e.g. a vendor specific
       mode page) can be listed	in hexadecimal by using	the option combination
       '--page=PG --hex'.

       Numbers	input  to  sdparm (e.g.	in the command line arguments) are as-
       sumed to	be in decimal unless there is a	hexadecimal indicator. A hexa-
       decimal indicator is either a leading '0x' or '0X' (i.e.	the C language
       convention) or a	trailing 'h' or	 'H'  (i.e.  the  convention  used  at
       www.t10.org  ). In the case of --page= either a string or number	is ex-
       pected, so hex numbers like 'ch'	(12) should  be	 prefixed  by  a  zero
       (e.g. '0ch').

       The SPC-4 draft (rev 2) says that devices that implement	no distinction
       between current and saved pages can return an error  (ILLEGAL  REQUEST,
       invalid	field  in  cdb)	if the SP bit (which corresponds to the	--save
       option) is _not_	set. In	such cases  the	 --save	 option	 needs	to  be
       given.

       If the --save option is given but the existing mode page	indicates (via
       its PS bit) that	the page is not	saveable, then this utility  generates
       an error	message. That message suggests to try again without the	--save
       option.

       Since the device	identification VPD  page  (acronym_name	 "di")	poten-
       tially  contains	a lot of diverse designators, several associated acro-
       nyms 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	desig-
       nators are grouped by lu, then port and then target device.  To see all
       designators  decoded  in	the order that they appear in the VPD page use
       "di_asis".

       Only those VPD pages defined by t10.org are decoded  by	this  utility.
       SPC-4 sets aside	VPD pages codes	from 0xc0 to 0xff (inclusive) for ven-
       dor specific pages some of which	are decoded in the sg_vpd utility.

       To see all VPD pages supported by a DEVICE use 'sg_vpd --all'.

       In the linux kernel 2.6 and 3 series any	device node that understands a
       SCSI  command set (e.g. SCSI disks and CD/DVD drives) may be specified.
       More precisely the driver that "owns" the device	node must support  the
       SG_IO  ioctl.  In the lk	2.4 series only	SCSI generic (sg) device nodes
       support the SG_IO ioctl.	However	in the lk 2.4 series other SCSI	device
       nodes  are  mapped within this utility to their corresponding sg	device
       nodes. So if there is a SCSI disk at /dev/sda  then  'sdparm  /dev/sda'
       will  work  in both the lk 2.4 series and later.	However	if there is an
       ATAPI cd/dvd drive at /dev/hdc then 'sdparm /dev/hdc' will only work in
       the lk 2.6 series and later.

       In  the Linux 2.6 and 3 series, especially with ATA disks, using	sdparm
       to stop (spin down) a disk may not be sufficient	and  other  mechanisms
       will  start the disk again some time later. The user might additionally
       mark the	disk as	"offline"  with	 'echo	offline	 >  /sys/block/sda/de-
       vice/state'  where  sda	is  the	block name of the disk.	To restart the
       disk "offline" can be replaced with "running".

PARAMETERS
       In their	simplest form the --clear=,  --get=  and  --set=  options  (or
       their  short  forms) take an acronym_name such as "WCE".	In the case of
       '--get=WCE' the value of	"Writeback Cache Enable" in the	 caching  mode
       page  will  be fetched. In the case of '--set=WCE' that bit will	be set
       (to one). In the	case of	'--clear=WCE' that bit	will  be  cleared  (to
       zero). When an acronym_name is given then the mode page is imputed from
       that acronym_name (e.g. WCE is in the caching mode page).

       Instead of an acronym_name a field within a mode	page can be  described
       numerically with	a <start_byte>:<start_bit>:<num_bits> tuple. These are
       the <start_byte>	(origin	0) within the mode page, a <start_bit> (0 to 7
       inclusive)  and	<num_bits>  (1	to 64 inclusive). For example, the low
       level representation of the RCD bit (the	"Read Cache Disable bit	in the
       caching mode page) is "2:0:1". The <start_byte> can optionally be given
       in hex (e.g. '--set=0x2:0:1' or '--set=2h:0:1').	 With  this  form  the
       --page= option is required to establish which mode page is to be	used.

       Either form can optionally be followed by "=<val>". By default <val> is
       decimal but can be given	in hex in the normal fashion.  Here  are  some
       examples: '--set=2h:0:1=1h' and '-s MRIE=0x3'. When the acronym_name or
       numeric form following --clear= is not given an explicit	'=<val>'  then
       the  value defaults to zero. When the acronym_name or numeric form fol-
       lowing --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	Write-
       back Cache Enable or, put more simply: turn off the writeback cache.

       Multiple	 fields	 within	 the same mode page can	be changed by giving a
       comma separated list of acronym_names and/or the	 numerical  form.  For
       example:	'--set=TEST,MRIE=6'.

       Some  mode  page	have multiple descriptors. They	typically have a fixed
       header section at the start of the mode page that includes a field con-
       taining	the number of descriptors that follow. Following the header is
       a variable number of descriptors. An example is the SAS Phy Control and
       Discover	 mode  page.  An  acronym_name may include a trailing '.<num>'
       where "<num>" is	a descriptor number (origin 0).	For example '-t	sas -g
       PHID.0' and '-t sas -g PHID' will yield the phy identifier of the first
       descriptor of the above mode page; '-t sas -g PHID.1'  will  yield  the
       phy identifier of the second descriptor.

ENUMERATE
       The --enumerate option essentially dumps	out static information held by
       this utility. A list of --enumerate variants and	their actions follows.
       For  brevity  subsequent	examples of options are	shown in their shorter
       form.

	   --enumerate		list generic mode page information
	   -e --all		list generic mode page contents
				(i.e. parameters)
	   -e --page=rw		list contents of read write error
				recovery mode page
	   -e --inquiry		list VPD pages this utility can	decode
	   -e --long		list generic mode pages, transport
				protocols, mode	pages for each
				supported transport protocol and
				supported commands
	   -e -l --all		additionally list the contents of
				each mode page
	   -e --transport=fcp	list mode pages	for the	fcp
				transport protocol
	   -e -t fcp --all	additionally list the contents of
				each mode page
	   -e --vendor=sea	list vendor specific mode pages	for
				"sea" (Seagate)
	   -e -M sea --all	additionally list the contents of vendor
				specific mode pages for	"sea" (Seagate)
	   -e -p pcd -l		list contents of SAS phy control and
				discovery mode page plus (due to "-l")
				some descfriptor format	information

       When known mode pages are listed	(via  the  --enumerate	 option)  each
       line  starts  with a two	or three letter	abbreviation. This is followed
       by the page number (in hex prefixed by "0x") optionally followed	 by  a
       comma  and the subpage number. Finally the descriptive name of the mode
       page (e.g. as found in SPC-4) is	output.

       When known parameters (fields) of a mode	page  are  listed,  each  line
       starts  with an acronym (indented a few spaces).	This will match	(or be
       an acronym for) the description for that	field  found  in  the  (draft)
       standards.  Next	 are three numbers, separated by colons, surrounded by
       brackets. These are the start byte (in hex, prefixed by	"0x")  of  the
       beginning  of  the  field  within  the  mode  page; the starting	bit (0
       through 7 inclusive) and	then the number	of bits. The descriptive  name
       of  the parameter (field) is then given.	If appropriate the descriptive
       name includes units (e.g. "(ms)"	means  the  units  are	milliseconds).
       Adding the '-ll'	option will list information about possible field val-
       ues 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	trans-
       port 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 acro-
       nym_name	namespaces have	been divided between generic mode pages	 (i.e.
       when  the  --transport= option is _not_ given) and a namespace for each
       transport protocol. A LUPID field from the  protocol  specific  logical
       unit  (0x18)  mode  page	and the	PPID field from	protocol specific port
       (0x19) mode page	are included in	the generic modes pages;  this	is  so
       the  respective	(transport)  protocol identifiers can be seen. In most
       cases the user will know	what the "port"	transport is  (i.e.  the  same
       transport  as the HBA in	the computer) but the logical unit's transport
       could be	different.

VENDORS
       SCSI leaves a lot of space for vendor specific information. Often  this
       is  described in	product	manuals. The --vendor=VN (or -M=VN) option al-
       lows known vendor specific mode pages to	be examined and/or modified by
       acronym.

       In  this	utility	the syntax and semantics of vendor specific mode pages
       is very similar to those	of transport  protocol	specific  mode	pages.
       Both  cannot  be	 specified  together.  Vendor specific modes pages can
       still be	accessed numerically (as shown at the end of the EXAMPLES sec-
       tion).

COMMANDS
       The  command  option sends a SCSI command to the	DEVICE.	If the command
       fails then this is reflected in the non-zero exit  status.   To	obtain
       more information	about the error	use the	-v option.

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

       If the number of	blocks is too large to fit in the 4  byte  field  pro-
       vided  by  READ	CAPACITY(10)  or, the --long option is given, then the
       READ CAPACITY(16) command is sent. If the --long	option is given,  then
       the extra fields	found in the READ CAPACITY(16) response	are output.

       eject  stops the	medium and ejects it from the device.  Note that ejec-
	      tion (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 me-
	      dia.  Objects if sent to another peripheral device type (but ob-
	      jection can be overridden	with '-f' option).

       load   loads the	medium and starts it (i.e. spins it up).  See  'eject'
	      command for supported device types.

       profile
	      lists  the  various  formats  that a CD/DVD/HD-DVD/BD drive sup-
	      ports. These are called "profiles" in the	MMC standard. The pro-
	      files  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.

       ready  sends the	"Test Unit Ready" SCSI command to the 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  re-
	      spond to this command.

       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
	      --quiet option can be used to lessen output, and --hex to	output
	      sense data in hex.

       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:	--com-
	      mand=speed=SPEED 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.

       start  starts the medium	(i.e. spins it up). Harmless if	medium has al-
	      ready been started. See 'eject'  command	for  supported	device
	      types.  If  the  DEVICE is an ATA	disk in	Linux the '--readonly'
	      option may be required.

       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 DEVICE is an ATA disk in  Linux  the  '--readonly'
	      option may be required. See the NOTES section above.

       sync   sends  a	SYNCHRONIZE CACHE command. The device should flush any
	      data held	in its (volatile) buffers to the media.

       unlock tells a device to	allow medium removal. It uses the  SCSI	 "pre-
	      vent  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.

EXAMPLES
       To list the common (generic) mode parameters of a disk:

	  sdparm /dev/sda

       To list the designators within the device identification	VPD page of  a
       disk:

	  sdparm --inquiry /dev/sda

       To see all parameters for the caching mode page:

	  sdparm --page=ca /dev/sda

       To see all parameters for the caching mode page with parameter descrip-
       tions 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)  parame-
       ters could be listed in the lk 2.6 and 3	series with:

	  sdparm /dev/hdc

       If  there is a DVD in the drive at /dev/hdc then	it could be ejected in
       the lk 2.6 and 3	series with:

	  sdparm --command=eject /dev/hdc

       If the ejection is being	prevented by software then that	can  be	 over-
       ridden with:

	  sdparm --command=unlock /dev/hdc

       One  disk  vendor  has a	"Performance Mode" bit (PM) in the vendor spe-
       cific unit attention mode page [0x0,0x0]. PM=0 is server	mode (the  de-
       fault)  while  PM=1 is desktop mode. Desktop mode can be	set (both cur-
       rent and	saved values) with:

	  sdparm --page=0 --set=2:7:1=1	--save /dev/sda

       The resultant change can	be viewed in hex  with	the  --hex  option  as
       there are no acronyms for vendor	extensions yet.	The PM bit is now cov-
       ered by vendor specific mode pages and the above	 can  also  be	accom-
       plished with:

	  sdparm --vendor=sea --set=PM --save /dev/sda

       What follows are	some examples from Windows using the '--wscan' option.
       The idea	is to list the storage device names on the system  that	 might
       be invoked by other uses	of sdparm.

	 # sdparm --wscan
       PD0     [C]     FUJITSU	 MHY2160BH	   0000
       PD1     [DF]    WD	 2500BEV External  1.05	 WD-WXE90
       CDROM0  [E]     MATSHITA	DVD/CDRW UJDA775  CB03

       So  'sdparm -a CDROM0' and 'sdparm -a E'	will show all the (known) mode
       page fields for the Matshita DVD/CD drive. By using the	'--wscan'  op-
       tion twice, the bus type	(as seen by the	OS) is added to	the output:

	 # sdparm -ww
       PD0     [C]     <Ata  >	FUJITSU	  MHY2160BH	    0000
       PD1     [DF]    <Usb  >	WD	  2500BEV External  1.05  WD-WXE90
       CDROM0  [E]     <Atapi>	MATSHITA DVD/CDRW UJDA775  CB03

       And  the	pattern	continues to add a SCSI	adapter	scan. This may be use-
       ful if there are	specialized storage related devices (e.g. a SES	device
       in an enclosure)	but does add much extra	information in this case.

	 # sdparm -www
       PD0     [C]     <Ata  >	FUJITSU	  MHY2160BH	    0000
       PD1     [DF]    <Usb  >	WD	  2500BEV External  1.05  WD-WXE90
       CDROM0  [E]     <Atapi>	MATSHITA DVD/CDRW UJDA775  CB03

       SCSI0:0,0,0   claimed=1 pdt=0h  FUJITSU	 MHY2160BH	   0000
       SCSI1:0,0,0   claimed=1 pdt=5h  MATSHITA	 DVD/CDRW UJDA775  CB03

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:

       0      success

       1      syntax  error. Either illegal command line options, options with
	      bad arguments or a combination of	options	that is	not permitted.

       2      the DEVICE reports that it is not	ready for  the	operation  re-
	      quested.	The  device  may  be  in the process of	becoming ready
	      (e.g.  spinning up but not at speed) so the utility may work af-
	      ter a wait.

       3      the  DEVICE  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.

       5      the DEVICE reports an "illegal request" with an additional sense
	      code other than "invalid operation code".	This is	often  a  sup-
	      ported  command with a field set requesting an unsupported capa-
	      bility. For commands that	require	a "service action" field  this
	      value can	indicate that the command is not supported.

       6      the  DEVICE  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  exe-
	      cuted  by	 the  device.  Note that unit attention	conditions are
	      usually only reported once by a device.

       7      the DEVICE reports a "data protect" sense	key. This implies some
	      mechanism	 has blocked writes (or	possibly all access to the me-
	      dia).

       9      the DEVICE reports an illegal request with an  additional	 sense
	      code  of	"invalid  operation  code" which means that it doesn't
	      support the requested command.

       10     the DEVICE reports a "copy aborted". This	implies	 another  com-
	      mand  or	device	problem	 has stopped a copy operation. The EX-
	      TENDED COPY family of commands (including	WRITE USING TOKEN) may
	      return this sense	key.

       11     the  DEVICE  reports  an	aborted	command. In some cases aborted
	      commands can be  retried	immediately  (e.g.  if	the  transport
	      aborted the command due to congestion).

       14     the  DEVICE  reports  a miscompare sense key. VERIFY and COMPARE
	      AND WRITE	commands may report this.

       15     the utility is unable to open, close or use  the	given  DEVICE.
	      The  given  file name could be incorrect or there	may be permis-
	      sion problems. Adding the	-v option may give more	information.

       20     the DEVICE 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.

       21     the DEVICE 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 .

       22     the  DEVICE  reports  that the current command or	its parameters
	      imply a logical block address (LBA) that is out of range.

       24     the DEVICE reports a SCSI	status of "reservation conflict". This
	      means  access  to	 the  DEVICE with the current command has been
	      blocked because another machine (HBA or SCSI "initiator")	 holds
	      a	reservation on this DEVICE. On modern SCSI systems this	is re-
	      lated to the use of the PERSISTENT RESERVATION  family  of  com-
	      mands.

       25     the  DEVICE  reports a SCSI status of "condition met". Currently
	      only the PRE-FETCH command (see SBC-4) yields this status.

       26     the DEVICE 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.

       27     the DEVICE reports a SCSI	status of "task	set full".

       28     the DEVICE reports a SCSI	status of "ACA active".	ACA  is	 "auto
	      contingent allegiance" and is seldom used.

       29     the  DEVICE reports a SCSI status	of "task aborted". SAM-5 says:
	      "This status shall be returned if	a command is aborted by	a com-
	      mand  or	task  management function on another I_T nexus and the
	      Control mode page	TAS bit	is set to one".

       33     the command sent to DEVICE has timed out.	This occurs  in	 Linux
	      only;  in	 other ports a command timeout will appear as a	trans-
	      port (or OS) error.

       40     the command sent to DEVICE has  received	an  "aborted  command"
	      sense  key  with an additional sense code	of 0x10. This group 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.

       48     this  is an internal message indicating a	NVMe status field (SF)
	      is other than zero after a command has been executed (i.e. some-
	      thing went wrong).  Work in this area is currently experimental.

       49     low  level driver	reports	a response's residual count (i.e. num-
	      ber 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.

       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 inabil-
	      ity 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.

       97     the response to a	SCSI command failed sanity checks.

       98     the DEVICE reports it  has  a  check  condition  but  the	 error
	      doesn't fit into any of the above	categories.

       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.

       126    the  utility was found but could not be executed.	That might oc-
	      cur if the executable does not have execute permissions.

       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 envi-
	      ronment variable has not been properly set  up,  so  the	script
	      cannot find the executable.

       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  sta-
	      tus will be 139 .

       255    the utility tried	to yield an exit status	of 255 or larger. That
	      should not happen; given here for	completeness.

       Most of the error conditions reported above will	be repeatable (an  ex-
       ample of	one that is not	is "unit attention") so	the utility can	be run
       again with the -v option	(or several) to	obtain more information.

AUTHORS
       Written by Douglas Gilbert.

REPORTING BUGS
       Report bugs to <dgilbert	at interlog dot	com>.

COPYRIGHT
       Copyright (C) 2005-2020 Douglas Gilbert
       This software is	distributed under a FreeBSD license. There is NO  war-
       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR-
       POSE.

WEB SITE
       There	is    a	   web	  page	  discussing	this	package	    at
       http://sg.danny.cz/sg/sdparm.html .

SEE ALSO
       hdparm(hdparm),	sg_modes,  sg_wr_mode,	sginfo,	 sg_inq, sg_vpd(all in
       sg3_utils),	smartmontools(smartmontools.sourceforge.net),	   mt,
       eject(eject),

sdparm-1.11			  March	2020			     SDPARM(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | NOTES | PARAMETERS | ENUMERATE | TRANSPORTS | VENDORS | COMMANDS | EXAMPLES | EXIT STATUS | AUTHORS | REPORTING BUGS | COPYRIGHT | WEB SITE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sdparm&sektion=8&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help