Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

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

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
       responses. 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.
       --descriptor=1). Multiple DISCOVER LIST requests will be made  if  more
       descriptors  are requested (e.g. --summary requests 254) and the previ-
       ous 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
              implied. Of the three the attached phy capability field is prob-
              ably 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
              response (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
              response.  The default action when this option is not  given  is
              to  output  multiple  indented  lines for each descriptor in the
              response. 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
              defaults  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
       enclosure 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
       enabled    phys    with    nothing    connected    which    appear   as
       "attached:[0000000000000000:00]".

       Information shown between the brackets is for the attached device. Phys
       that       are       connected       display       something      like:
       "attached:[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
       inserted 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.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+--------------------------+
       |ATTRIBUTE TYPE |     ATTRIBUTE VALUE      |
       +---------------+--------------------------+
       |Availability   | system/storage/smp_utils |
       +---------------+--------------------------+
       |Stability      | Uncommitted              |
       +---------------+--------------------------+
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


       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source was downloaded from  http://sg.danny.cz/sg/p/smp_utils-0.98.tgz

       Further information about this software can be found on the open source
       community website at http://sg.danny.cz/sg/smp_utils.html.



smp_utils-0.98                    April 2014              SMP_DISCOVER_LIST(8)