.TH SMP_DISCOVER_LIST "8" "April 2014" "smp_utils\-0.98" SMP_UTILS
.SH NAME
smp_discover_list \- invoke DISCOVER LIST SMP function
.SH SYNOPSIS
.B smp_discover_list
[\fI\-\-adn\fR] [\fI\-\-brief\fR] [\fI\-\-cap\fR] [\fI\-\-descriptor=TY\fR]
[\fI\-\-filter=FI\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-ignore\fR]
[\fI\-\-interface=PARAMS\fR] [\fI\-\-num=NUM\fR] [\fI\-\-one\fR]
[\fI\-\-phy=ID\fR] [\fI\-\-raw\fR] [\fI\-\-sa=SAS_ADDR\fR]
[\fI\-\-summary\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR]
[\fI\-\-zpi=FN\fR] \fISMP_DEVICE[,N]\fR
.SH DESCRIPTION
.\" Add any additional description here
.PP
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 \fISMP_DEVICE\fR and the \fISAS_ADDR\fR. Depending on
the interface, the \fISAS_ADDR\fR may be deduced from the \fISMP_DEVICE\fR.
The mpt interface uses \fISMP_DEVICE\fR to identify a HBA (an SMP initiator)
and needs the additional \fI,N\fR to differentiate between HBAs if there are
multiple present.
.PP
If the \fI\-\-phy=ID\fR option is not given then \fI\-\-summary\fR is
assumed. When \fI\-\-summary\fR 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
\fI\-\-brief\fR option.
.PP
The DISCOVER LIST response may contain up to 8 descriptors when
the "descriptor type" field in the request is set to
0 (e.g. \fI\-\-descriptor=0\fR). The DISCOVER LIST response may contain up
to 40 descriptors when the "descriptor type" field in the request is set to
1 (e.g. \fI\-\-descriptor=1\fR). Multiple DISCOVER LIST requests will be
made if more descriptors are requested (e.g. \fI\-\-summary\fR requests 254)
and the previous response indicates that more descriptors may be available.
.SH OPTIONS
Mandatory arguments to long options are mandatory for short options as well.
.TP
\fB\-A\fR, \fB\-\-adn\fR
causes the "attached device name" field to be output when the
\fI\-\-one\fR or \fI\-\-summary\fR 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. \fI\-\-descriptor=1\fR).
.TP
\fB\-b\fR, \fB\-\-brief\fR
reduce the decoded response output.
.TP
\fB\-c\fR, \fB\-\-cap\fR
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 \fI\-\-brief\fR option is given or implied. Of the three the attached
phy capability field is probably the most interesting. If the
\fI\-\-verbose\fR option is given, then the various "G" identifiers are
expanded (e.g. instead of "G4:" it prints "G4 (12 Gbps):").
.TP
\fB\-d\fR, \fB\-\-descriptor\fR=\fITY\fR
set the "descriptor type" field in the request. When \fITY\fR 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
\fITY\fR is 1 the short format (i.e. 24 byte per descriptor) information
is placed in the descriptors of this function's response.
.TP
\fB\-f\fR, \fB\-\-filter\fR=\fIFI\fR
set the filter field in the request. When \fIFI\fR is 0 (default) fetch
descriptors for all phys. When \fIFI\fR is 1 only fetch descriptors for
phys attached to (other) expanders. When \fIFI\fR is 2 only fetch
descriptors for phys attached to expanders, SAS or SATA devices. When
\fIFI\fR is 1 or 2, expander phys that would yield "phy vacant" (indicating
they are hidden by zoning) are filtered out.
.TP
\fB\-h\fR, \fB\-\-help\fR
output the usage message then exit.
.TP
\fB\-H\fR, \fB\-\-hex\fR
output the response (less the CRC field) in hexadecimal.
.TP
\fB\-i\fR, \fB\-\-ignore\fR
sets the Ignore Zone Group bit in the SMP Discover list request.
.TP
\fB\-I\fR, \fB\-\-interface\fR=\fIPARAMS\fR
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.
.TP
\fB\-n\fR, \fB\-\-num\fR=\fINUM\fR
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 \fI\-\-phy=ID\fR. 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').
.TP
\fB\-o\fR, \fB\-\-one\fR
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.
.TP
\fB\-p\fR, \fB\-\-phy\fR=\fIID\fR
phy identifier. \fIID\fR 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.
.TP
\fB\-r\fR, \fB\-\-raw\fR
send the response (less the CRC field) to stdout in binary. All error
messages are sent to stderr.
.TP
\fB\-s\fR, \fB\-\-sa\fR=\fISAS_ADDR\fR
specifies the SAS address of the SMP target device. Typically this is an
expander. This option may not be needed if the \fISMP_DEVICE\fR has the
target's SAS address within it. The \fISAS_ADDR\fR 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.
.TP
\fB\-S\fR, \fB\-\-summary\fR
output a multi line summary, with one line per active phy. Checks up
to 254 phys starting at phy identifier \fIID\fR (which defaults to 0).
Equivalent to '\-o \-d 1 \-n 254 \-b' unless the \fI\-\-adn\fR 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.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
increase the verbosity of the output. Can be used multiple times.
.TP
\fB\-V\fR, \fB\-\-version\fR
print the version string and then exit.
.TP
\fB\-Z\fR, \fB\-\-zpi\fR=\fIFN\fR
\fIFN\fR 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 \fI\-\-pconf=FN\fR option. If
\fI\-\-num=NUM\fR is not given it is set to 254. The output will start from
phy_id 0 unless \fI\-\-phy=ID\fR is given.
.SH SINGLE LINE PER PHY FORMAT
The \fI\-\-summary\fR (or \fI\-\-one\fR) 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.
.PP
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
.B 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]".
.PP
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.
.PP
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):
.PP
  phy  11:T:attached:[500605b000000afb:00  t(SATA)]  1.5 Gbps
.PP
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").
.PP
If the \fI\-\-adn\fR 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 \fI\-\-adn\fR option
is given the phy speed and zone group are not output in order to keep the
line length reasonable.
.SH 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.
.SH CONFORMING TO
The SMP DISCOVER LIST function was introduced in SAS\-2 .
.SH AUTHORS
Written by Douglas Gilbert.
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2006\-2014 Douglas Gilbert
.br
This software is distributed under a FreeBSD license. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.B smp_utils, smp_discover, smp_phy_control, smp_conf_zone_phy_info