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

FreeBSD Manual Pages

  
 
  

home | help
SMP_DISCOVER_LIST(8)		   SMP_UTILS		  SMP_DISCOVER_LIST(8)

NAME
       smp_discover_list - invoke DISCOVER LIST	SMP function

SYNOPSIS
       smp_discover_list  [--adn]  [--brief] [--cap] [--descriptor=TY] [--fil-
       ter=FI] [--help]	[--hex]	 [--ignore]  [--interface=PARAMS]  [--num=NUM]
       [--one]	[--phy=ID]  [--raw]  [--sa=SAS_ADDR]  [--summary]  [--verbose]
       [--version] [--zpi=FN] SMP_DEVICE[,N]

DESCRIPTION
       Sends one or more SAS Serial Management Protocol	 (SMP)	DISCOVER  LIST
       function	 requests  to  an  SMP	target	and decodes or outputs the re-
       sponses.	The SMP	 target	 is  identified	 by  the  SMP_DEVICE  and  the
       SAS_ADDR.  Depending on the interface, the SAS_ADDR may be deduced from
       the SMP_DEVICE.	The mpt	interface uses SMP_DEVICE to  identify	a  HBA
       (an SMP initiator) and needs the	additional ,N to differentiate between
       HBAs if there are multiple present.

       If the --phy=ID option is not given then	 --summary  is	assumed.  When
       --summary  is  given  or	assumed, this utility shows the	disposition of
       each active expander phy	in table form. One row is shown	for  each  phy
       and  is	described in the SINGLE	LINE PER PHY FORMAT section below. For
       this purpose disabled expander phys and those with errors  are  consid-
       ered  "active"  and  can	 be  suppressed	 from the output by adding the
       --brief option.

       The DISCOVER LIST response may contain up to  8	descriptors  when  the
       "descriptor  type"  field  in  the request is set to 0 (e.g. --descrip-
       tor=0). The DISCOVER LIST response may contain  up  to  40  descriptors
       when the	"descriptor type" field	in the request is set to 1 (e.g. --de-
       scriptor=1). Multiple DISCOVER LIST requests will be made if  more  de-
       scriptors  are requested	(e.g. --summary	requests 254) and the previous
       response	indicates that more descriptors	may be available.

OPTIONS
       Mandatory arguments to long options are mandatory for short options  as
       well.

       -A, --adn
	      causes  the  "attached  device name" field to be output when the
	      --one or --summary option	is also	given. See the	section	 below
	      on  SINGLE  LINE PER PHY FORMAT. Note the	"attached device name"
	      field is not available in	 the  short  format  (e.g.  --descrip-
	      tor=1).

       -b, --brief
	      reduce the decoded response output.

       -c, --cap
	      decode  and  print  phy  capabilities  bits fields (see SNW-3 in
	      draft). Each expander phy	has three of these fields: programmed,
	      current  and attached.  By default these fields are only printed
	      out in hex, or not at all	if the --brief option is given or  im-
	      plied.  Of the three the attached	phy capability field is	proba-
	      bly the most interesting.	If the --verbose option	is given, then
	      the  various "G" identifiers are expanded	(e.g. instead of "G4:"
	      it prints	"G4 (12	Gbps):").

       -d, --descriptor=TY
	      set the "descriptor type"	field in the request.  When  TY	 is  0
	      then  the	120 byte response defined by the DISCOVER function re-
	      sponse (less its CRC field) is placed in the descriptors of this
	      function's response. When	TY is 1	the short format (i.e. 24 byte
	      per descriptor) information is placed in the descriptors of this
	      function's response.

       -f, --filter=FI
	      set  the	filter	field  in  the request.	When FI	is 0 (default)
	      fetch descriptors	for all	phys. When FI is 1 only	fetch descrip-
	      tors  for	 phys attached to (other) expanders. When FI is	2 only
	      fetch descriptors	for phys attached to expanders,	 SAS  or  SATA
	      devices.	When FI	is 1 or	2, expander phys that would yield "phy
	      vacant" (indicating they are hidden by zoning) are filtered out.

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

       -H, --hex
	      output the response (less	the CRC	field) in hexadecimal.

       -i, --ignore
	      sets the Ignore Zone Group bit in	the SMP	Discover list request.

       -I, --interface=PARAMS
	      interface	specific parameters. In	this case  "interface"	refers
	      to  the  path through the	operating system to the	SMP initiator.
	      See the smp_utils	man page for more information.

       -n, --num=NUM
	      maximum number of	descriptors fetch. If any descriptors  are  in
	      the  response  the first phy id will be greater than or equal to
	      the argument of --phy=ID.	Note that maximum SMP  frame  size  is
	      1032 bytes (including a trailing 4 byte CRC) which may limit the
	      number of	descriptors that can be	fetched	by a  single  DISCOVER
	      LIST function (especially	when '--descriptor=0').

       -o, --one
	      use  one line (summarized) format	for each descriptor in the re-
	      sponse.  The default action when this option is not given	is  to
	      output  multiple	indented  lines	for each descriptor in the re-
	      sponse. See the section below on SINGLE LINE PER PHY FORMAT.

       -p, --phy=ID
	      phy identifier. ID is a value between 0 and 254.	 This  is  the
	      starting	(lowest	 numbered)  phy	 id  to	fetch in the response.
	      Note that	due to the filter field	setting, the first phy	id  in
	      the response may be greater than the argument to this option.

       -r, --raw
	      send  the	response (less the CRC field) to stdout	in binary. 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 within it. The  SAS_ADDR
	      is  in  decimal but most SAS addresses are shown in hexadecimal.
	      To give a	number in hexadecimal either prefix it	with  '0x'  or
	      put a trailing 'h' on it.

       -S, --summary
	      output  a	 multi	line  summary,	with  one line per active phy.
	      Checks up	to 254 phys starting at	phy identifier ID  (which  de-
	      faults  to  0).	Equivalent  to	'-o -d 1 -n 254	-b' unless the
	      --adn option was also given, in which case it is	equivalent  to
	      '-o  -d  0 -n 254	-b' . See the section below on SINGLE LINE PER
	      PHY FORMAT.

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

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

       -Z, --zpi=FN
	      FN  is  a	 file that will	be created or truncated	then have zone
	      phy information written to it in a format	suitable for input  to
	      the   smp_conf_zone_phy_info  utility's  --pconf=FN  option.  If
	      --num=NUM	is not given it	is set to 254. The output  will	 start
	      from phy_id 0 unless --phy=ID is given.

SINGLE LINE PER	PHY FORMAT
       The --summary (or --one)	option causes SMP DISCOVER LIST	descriptors to
       be compressed to	one line per phy. To  save  space  SAS	addresses  are
       shown  in  hex without a	'0x' prefix or 'h' suffix.  The	header section
       outputs information found in the	DISCOVER LIST response's  header  sec-
       tion.

       For  each  descriptor in	the DISCOVER LIST response, one	line is	output
       starting	with "	phy  <n>:" where <n> is	the phy	identifier  (and  they
       are origin zero). That is followed by the routing attribute represented
       by a single letter which	is either "D" for direct routing, "S" for sub-
       tractive	routing, "T" or	"U". Both "T" and "U" imply table routing, the
       difference is that if REPORT GENERAL indicates  "table  to  table  sup-
       ported"	then  "U" is output to indicate	that phy can be	part of	an en-
       closure universal port; otherwise "T" is	used. Next comes  the  negoti-
       ated  physical link rate	which is either	"disabled", "reset problem" or
       "spinup hold". Other states are mapped to "attached". This includes en-
       abled	phys   with   nothing	connected   which   appear   as	  "at-
       tached:[0000000000000000:00]".

       Information shown between the brackets is for the attached device. Phys
       that	are	connected     display	  something	like:	  "at-
       tached:[5000c50000520a2a:01 " where the first number  is	 the  attached
       SAS address (in hex) and	the second number is the attached device's phy
       identifier. If the attached device type is other	than an	 SAS  or  SATA
       device then one of these	abbreviations is output: "exp" (for expander),
       "fex" (for fanout expander)  or	"res"  (for  unknown  attached	device
       type).  If  a  phy  is flagged as "virtual" then	the letter "V" appears
       next. Next are the protocols supported by the attached device which are
       shown  as  "i(<list>)"  for  initiator protocols	and/or "t(<list>)" for
       target protocols. The <list> is made up of  "PORT_SEL",	"SSP",	"STP",
       "SMP"  and "SATA" with "+" used as a separator.	For example a SAS host
       adapter will most likely	appear as: "i(SSP+STP+SMP)".   This  completes
       the  information	 about	the  attached  phy,  hence  the	 closing right
       bracket.

       If appropriate, the negotiated physical link rate is shown in  gigabits
       per second. Here	is an example of a line	for expander phy identifier 11
       connected to a SATA target (or SATA "device" to use the t13.org term):

	 phy  11:T:attached:[500605b000000afb:00  t(SATA)]  1.5	Gbps

       If the expander has zoning enabled (i.e.	REPORT	GENERAL	 response  bit
       for  'zoning enabled' is	set) and a phy's zone group is other than zg 1
       then the	phy's zone group is shown (e.g.	"ZG:2").

       If the --adn option is given then after the attached  SAS  address  and
       the  attached  device's phy identifier are output an extra field	is in-
       serted containing the "attached device name" field. For a SAS disk this
       should  be its target device name (in NAA-5 format) and for a SATA disk
       its WWN (if provided, also in NAA-5 format). Also when the --adn	option
       is  given  the phy speed	and zone group are not output in order to keep
       the line	length reasonable.

NOTES
       In SAS-2	and later both the DISCOVER and	DISCOVER  LIST	functions  are
       available.  The	DISCOVER  LIST function	should be favoured for several
       reasons:	its response can hold up to 40 descriptors each	describing the
       state  of  one expander phy. The	vast majority of expander chips	on the
       market support 36 phys or less so one DISCOVER LIST response will  sum-
       marize  the states of all its phys. With	the DISCOVER function only one
       expander	phy's state is returned	in its response. Other	advantages  of
       the  DISCOVER  LIST function are	its "phy filter" and "descriptor type"
       function	request	fields.

CONFORMING TO
       The SMP DISCOVER	LIST function was introduced in	SAS-2 .

AUTHORS
       Written by Douglas Gilbert.

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

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

SEE ALSO
       smp_utils, smp_discover,	smp_phy_control, smp_conf_zone_phy_info

smp_utils-0.98			  April	2014		  SMP_DISCOVER_LIST(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | SINGLE LINE PER PHY FORMAT | NOTES | CONFORMING TO | AUTHORS | REPORTING BUGS | COPYRIGHT | SEE ALSO

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

home | help