Provided by: smp-utils_0.98-1_amd64 bug

NAME

       smp_discover_list - invoke DISCOVER LIST SMP function

SYNOPSIS

       smp_discover_list  [--adn]  [--brief]  [--cap]  [--descriptor=TY]  [--filter=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  considered
       "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. --descriptor=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 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.
              --descriptor=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  probably  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  descriptors  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 section.

       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 subtractive routing, "T" or "U".  Both  "T"  and  "U"  imply  table  routing,  the
       difference  is  that  if  REPORT  GENERAL indicates "table to table supported" then "U" is
       output to indicate that phy can be part of an enclosure universal port; otherwise  "T"  is
       used.  Next  comes  the  negotiated  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.

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
       summarize  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 © 2006-2014 Douglas Gilbert
       This  software  is distributed under a FreeBSD license. There is NO warranty; not even for
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

       smp_utils, smp_discover, smp_phy_control, smp_conf_zone_phy_info