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

FreeBSD Manual Pages


home | help

       smp_* - invoke a	SAS Serial Management Protocol (SMP) function

       smp_*  [--expected=EX]  [--help]	 [--hex]  [--interface=PARAMS] [--raw]
       [--sa=SAS_ADDR] [--verbose] [--version] SMP_DEVICE[,N]

       Serial Attached SCSI (SAS) is a transport (also known  as  a  intercon-
       nect)  used  by	storage	 systems.  A SAS system	is made	up of Host Bus
       Adapters	(HBAs typically	containing SCSI	initiators),  disks  (referred
       to  in  SCSI  as	 both  targets	and logical units) and optionally some
       switching hardware called "expanders". Expanders	are not	 SCSI  devices
       so  a new protocol was required to control and monitor them. The	proto-
       col's full name is the SAS Serial Management Protocol which is abbrevi-
       ated to SMP.

       smp_utils is a package of utilities. Each utility sends an SMP function
       request to a SMP_DEVICE (an SMP target).	Some utilities may invoke  the
       same  function more than	once. If an error occurs then an error message
       is sent to stderr. If no	error occurs, the response is decoded (the de-
       fault),	output	in ASCII hex (when --hex is given) or output in	binary
       to stdout (when the --raw option	is given).

       If SMP_DEVICE[,N] is not	given then the value in	the environment	 vari-
       able SMP_UTILS_DEVICE is	used.

       This  package  was  originally written for Linux	and has	been ported to
       FreeBSD and Solaris.

       Currently there are multiple interfaces that allow SMP functions	to  be
       passed through to an SMP	target.

       One  method is to have a	SMP_DEVICE which is actually the SMP initiator
       (e.g. '/dev/mptctl,0'). In this case the	SMP target's SAS address  must
       be supplied with	the --sa=SAS_ADDR option.

       Another method is to have a SMP_DEVICE which represents the SMP target.
       In this case no SAS_ADDRESS needs to be given (since it is implicit).

       Each utility in smp_utils attempts to work out which interface  it  has
       been given by examining the SMP_DEVICE file. There are three interfaces
       supported currently:

       aac    This specifies the  aacraid  SAS	pass-through  associated  with
	      Adaptec/PMC RAID products. The SMP_DEVICE[,N] argument takes the
	      form /dev/aac[N[,E_ID]] where "N"	is the raid controller	number
	      (typically  0)  and "E_ID" is the	expander identifier (typically
	      0); both default to 0 so /dev/aac	is equivalent to /dev/aac0 and
	      /dev/aac0,0   .	 The   "N"   is	  the	unique_id   found   in
	      /sys/class/scsi_host<HN>/unique_id .  The	"HN" is	the host  num-
	      ber which	is the first number to appear on each line in the lss-
	      csi utility which	by default uses	one line to list each accessi-
	      ble SCSI device (typically SCSI or ATA disks). The "E_ID"	is the
	      expander identifier which	can be found with the Adaptec/PMC arc-
	      conf  utility  using the form "arcconf expanderlist <Controller-
	      Num>". The <ControllerNum>s start	at 1 . If  an  aac  RAID  con-
	      troller is present then the /dev/acc device node will be created
	      by the first smp utility to use this interface.

       mpt    This specifies the  MPT  fusion  SAS  pass-through.  The	mptsas
	      driver  uses the '/dev/mptctl' device node (character device ma-
	      jor 10, minor 220) while the mpt2sas driver uses	'/dev/mpt2ctl'
	      device  node  (major 10, minor 221).  For	the mpt3sas driver the
	      corresponding device  node  is  '/dev/mpt3ctl'.	The  'modprobe
	      mptctl'  or  'modprobe  mpt2ctl' command may be needed. If there
	      are multiple mpt fusion controllers (HBAs) in the	computer, then
	      the  user	will need to specify which one to use with the syntax:
	      '/dev/mptctl,<n>'	where <n> is the "ioc_num". This number	can be
	      found  with  dmesg after the mptsas driver is registered and ap-
	      pears as a suffix	to the driver name (e.g.   mpt2sas0).  It  can
	      also be found in '/sys/class/scsi_host/host<n>/unique_id'.  When
	      this interface is	used the --sa=SAS_ADDR option must be given to
	      specify the SAS address of the SMP target.

       sgv4 (sg)
	      This  interface is more generic and supported by several SAS HBA
	      drivers including	mptsas (and mpt2sas). It was introduced	in the
	      Linux  2.6.24 kernel. The	SMP functions are passed to the	kernel
	      via the bsg driver using a format	known as "SCSI Generic Version
	      4" which gives this interface its	name: "sgv4" or	just "sg". The
	      SAS transport layer within the SCSI sub-system unpacks  the  SMP
	      requests and forwards them to SAS	low level drivers that support
	      this interface.  The  SMP_DEVICE	is  either  a  member  of  the
	      '/sys/class/bsg'	directory  (e.g. /sys/class/bsg/expander-6:0 )
	      or a device node made for	 the  bsg  driver  (e.g.  /dev/bsg/ex-
	      pander-6:0  ).  Such  device  nodes are dynamic (i.e. they don't
	      have fixed major and minor numbers) and should correspond	to the
	      major  and  minor	 numbers found in the 'sys/class/bsg/<smp_tar-
	      get_device>/dev' file.

       The CAM subsystem has been enhanced in FreeBSD 9	 to  pass-through  SMP
       requests	 and  return the corresponding responses. However CAM does not
       directly	access expander	devices	because	they are not SCSI devices.  It
       makes  the assumption that each SAS expander has	an integrated SES (en-
       closure)	device and that	is addressed. This assumption seems to be true
       for SAS-2 expanders but not some	SAS-1 expanders. Thus invocations look
       like this:

	 # smp_discover	/dev/ses0

       where /dev/ses0 is a SES	device associated with a SAS expander.

       The USMP	pass-through mechanism is used.	Invocations look like this:

	 # smp_rep_manufacturer	/dev/smp/expd0

       If the device name is not given then the	 SMP_UTILS_DEVICE  environment
       variable	 is checked and	if present its contents	are used as the	device

       If the SAS address (of the SMP target) is not given and it is  required
       (i.e.	it   is	  not	implicit   in	the   device  name)  then  the
       SMP_UTILS_SAS_ADDR environment variable is checked and if  present  its
       contents	 are  used as the SAS address. SAS addresses are usually given
       in hex indicated	by a leading '0x' or trailing 'h'.

       A device	slot number (dsn) is important for establishing	the  relation-
       ship  between  an expander phy and a SES	array element. Newer expanders
       (e.g. SAS-3) support dsn_s in the DISCOVER (and	DISCOVER  LIST)	 func-
       tions.  These  can  be  shown,  if  available, with the --dsn option to
       smp_discover and	smp_discover_list utilities.. To ease typing that  op-
       tion often, the SMP_UTILS_DSN environment variable, if present, has the
       same effect.

       If both an environment variable and the corresponding command line  op-
       tion is given and contradict, then the command line options take	prece-

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

       -E, --expected=EX
	      revision	4a of the SAS-2	draft introduced an 'expected expander
	      change count' field in some SMP requests.	The idea is to	detect
	      other  SMP initiators trying to change the state of an expander.
	      The value	EX is from 0 to	65535 inclusive	with 0 being  the  de-
	      fault  value.  When  EX  is  greater than	zero then if the value
	      doesn't match the	expander change	count of the SMP target	 (i.e.
	      the  expander)  when the request arrives then the	target ignores
	      the request and sets a  function	result	of  "invalid  expander
	      change count" in the response.

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

       -H, --hex
	      output  the  response  in	hexadecimal. This does not include the
	      trailing CRC field.

       -I, --interface=PARAMS
	      interface	specific parameters. This option is usually not	needed
	      since  the  interface  type is guessed by	a utility based	on the
	      characteristics of the given SMP_DEVICE argument or what	is  in
	      the  corresponding environment variables.	PARAMS is of the form:
	      INTF[,force].  If	the guess doesn't work then the	interface  can
	      be specified by giving a INTF of either 'mpt' or 'sgv4'.	Sanity
	      checks are still performed  and  a  utility  may	refuse	if  it
	      doesn't  agree  with  the	given INTF. If the user	is really sure
	      then adding a ',force' will force	the utility to use  the	 given

       -r, --raw
	      send the response	to stdout in binary. This does not include the
	      trailing CRC field. All error messages are sent to stderr.

       -s, --sa=SAS_ADDR
	      specifies	the SAS	address	of the SMP  target  device.  Typically
	      this  is	an  expander.  This  option  may  not be needed	if the
	      SMP_DEVICE has the target's SAS address associated with it.  The
	      SAS_ADDR is in decimal but most SAS addresses are	shown in hexa-
	      decimal. To give a number	in hexadecimal either prefix  it  with
	      '0x'  or	put  a trailing	'h' on it. If this option is not given
	      then the value in	the environment	variable SMP_UTILS_SAS_ADDR is

       -v, --verbose
	      increase	the  verbosity	of  the	 output.  Can be used multiple

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

       To aid scripts that call	these utilities, the exit status is set	to in-
       dicate success (0) or failure (1	or more):

       0      success

       1 - 63 reserved for SMP function	result codes. See the SAS-2 (or	later)
	      draft, in	the section on the application	layer,	drilling  down
	      further:	management  application	layer then SMP functions. Here
	      are some common function result codes: 1 [unknown	SMP function],
	      2	[SMP function failed], 16 [phy does not	exist],	17 [index does
	      not exist], 18 [phy does not support SATA], 19 [unknown phy  op-
	      eration],	22 [phy	vacant]	and 35 [zone lock violation].

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

       92     the utility is unable to open, close or use  the	given  SMP_DE-
	      VICE.   The  given  file name could be incorrect or there	may be
	      file permission problems.	Adding the --verbose option  may  give
	      more information.

       93     the  utility has a resource problem. Typically this means	an at-
	      tempt to allocate	memory (ram) has failed.

       97     the response to an SMP function failed sanity checks.

       99     any error	that can't be categorized into	values	1  to  97  may
	      yield  this value.  This includes	transport and operating	system

       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.

       Finding the SAS address of an expander can be a challenge in some envi-
       ronments. An enclosure containing one or	more expanders	may  have  the
       expander	 SAS address(es) printed on the	back of	the device, a bit like
       Ethernet	MAC addresses.

       In the Linux 2.6	kernel series the expander SAS address may well	be  in
       the sysfs tree but it is	not always easy	to find. Doing this search may

	 # find	/sys -name "*expander*"

       That should show	the suffix on any expanders that have  been  detected.
       Then  a	command	 like  'cat /sys/class/sas_device/expander-6:0/sas_ad-
       dress' should show its SAS address.

       Another approach	is to work backwards from SCSI devices	(i.e.  logical
       units).	The  protocol  specific	 port log page (log page 18h) contains
       fields for the "attached	SAS address". The  sg_logs  utility  from  the
       sg3_utils package could be used like this:

	 # sg_logs --page=18h /dev/sdb

       Any  given "attached SAS	address" is either a HBA, an expander or 0 in-
       dicating	that port is not connected. An expander	is indicated  by  "at-
       tached  device type: expander device". A	SAS disk's target port identi-
       fiers (also known as SAS	addresses), device name	and logical unit  name
       (all  NAA  5 format) can	be found with the sg_vpd utility (e.g. 'sg_vpd
       -i <disk_dev>').	The sdparm utility can provide	the  same  information
       (e.g. 'sdparm -i	<disk_dev>').

       A SAS expander is often associated with a SCSI Enclosure	Services (SES)
       device sometimes	on the same silicon attached via a virtual phy to  the
       expander. That SES device may be	able to	access and control an attached
       enclosure or backplane via SGPIO	or I2C on sideband signals (e.g. in  a
       SFF-8087	cable).	To interact with a SES device, see the sg_ses utility.

       Often  expander	phys  are grouped in fours on the same connector (e.g.
       SFF-8088). Care needs to	be taken when multiple expanders are intercon-
       nected.	 An enclosure universal	port is	one in which the "table	to ta-
       ble supported" attribute	is set (in the REPORT  GENERAL	response)  and
       the  associated	phys have the table routing attribute (in the DISCOVER
       response). Enclosure universal ports were introduced in SAS-2 and  have
       few  restrictions when used to interconnect expanders or	connect	SAS or
       SATA devices. An	enclosure out port is one in which the "table to table
       supported"  attribute  is  clear	and the	associated phys	have the table
       routing attribute. An enclosure in port is one in which the  associated
       phys  have  the subtractive routing attribute. When universal ports are
       not available, an expander interconnect should be between  an  in  port
       and an out port.

       See "Examples" section in .

       SAS has multiple	generations. The early standards are: the original SAS
       (ANSI INCITS 376-2003), SAS 1.1 (INCITS 417-2006) and SAS-2  (ANSI  IN-
       CITS 457-2010) .	SAS-2.1	work was split into an electrical and physical
       layers document (standardized as	SAS-2.1	ANSI INCITS 478-2011) with the
       upper  level  layers placed in a	document called	the SAS	Protocol Layer
       and it was standardized as SPL ANSI INCITS 476-2011.  Next  came	 SPL-2
       which  was  standardized	as SPL-2 ANSI INCITS 505-2013. Then came SPL-3
       which was standardized as SPL-3 ANSI INCITS  492-2015.  SPL-4  is  near
       standardization	and  its  most recent draft is spl4r13.pdf while SPL-5
       work has	started	and its	most recent draft is  spl5r03.pdf.  To	lessen
       confusion, the multiple generations of SAS will be referred to in these
       man pages as SAS	1, 1.1,	2, 2.1 (SPL), 3	(SPL-2 and SPL-3),  4  (SPL-4)
       and 5 (SPL-5).  Roughly speaking	for the	electrical and physical	layers
       standards SAS-1 runs at 3 Gbps, SAS-2 at	6 Gbps,	SAS-3 at 12  Gbps  and
       SAS-4 at	22.5 Gbps.  Drafts, including those just prior to standardiza-
       tion can	be found at the site	(e.g. spl-r07.pdf  and
       spl2r04c.pdf).  INCITS policy now requires a registration to view these
       drafts, a break from tradition.

       The  two	 utilities  for	 reading  and  writing	to   GPIO   registers,
       smp_read_gpio  and smp_write_gpio, are defined in the Small Form	Factor
       document	SFF-8485 found	at	 .  "Enhanced"
       versions	of the corresponding SMP functions have	been mentioned in some
       drafts but no definitions have been published and the  references  have
       been removed in more recent drafts.

       In  this	 section  of  each utility's man page is the first standard in
       which the associated SMP	function appeared and whether there have  been
       significant additions in	later standards.

       The  COVERAGE file in the smp_utils source tarball shows	a table	of all
       SMP function names defined in the drafts, the versions of  those	 stan-
       dards in	which those SMP	functions first	appeared and the corresponding
       smp_utils utility names.	A lot of extra SMP functions have  been	 added
       in SAS-2	associated with	zoning.

       Written by Douglas Gilbert.

       Report bugs to <dgilbert	at interlog dot	com>.

       Copyright (C) 2006-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-

       sg_logs,	sg_vpd,	sg_ses(sg3_utils); sdparm(sdparm); lsscsi(lsscsi)

smp_utils-0.99			  March	2020			  SMP_UTILS(8)


Want to link to this manual page? Use this URL:

home | help