Provided by: smp-utils_0.99-1_amd64 
NAME
smp_discover_list - invoke DISCOVER LIST SMP function
SYNOPSIS
smp_discover_list [--adn] [--brief] [--cap] [--descriptor=TY] [--dsn] [--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.
Rather than supply options and SMP_DEVICE[,N] on every invocation some can be supplied via environment
variables. See the section on ENVIRONMENT VARIABLES below.
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.
-D, --dsn
outputs the device slot number at the end of each summary line. In summary mode one line is output
per expander phy. It is output in the form "dsn=<val>" where <val> is decimal in the range from 0
to 254 inclusive. It is not output if it is not available or has the value 255. The device slot
number is not available in short format, so with this option in summary mode, if the
--descriptor=1 is not given, then the longer format is chosen. An expander typically contains a
SES device which yields device slot numbers in its Additional Element Status diagnostic page.
-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.
If the --dsn option is given and device slot number information is available for the current phy, then
"dsn=<num>" is appended to the line. Device slot numbers range from 0 to 254 with 255 meaning there is
no corresponding slot so it is not listed.
ENVIRONMENT VARIABLES
If SMP_DEVICE[,N] is not given then the SMP_UTILS_DEVICE environment variable is checked and if present
its contents are used instead.
If the SAS address (of the SMP target) is not given and it is required (i.e. it is not implicit in
SMP_DEVICE[,N]) 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 relationship between an expander phy and a
SES array element. Newer expanders (e.g. SAS-3) support dsn_s in the DISCOVER (and DISCOVER LIST)
functions. These can be shown, if available, with the --dsn option to smp_discover and smp_discover_list
utilities.. To ease typing that option often, the SMP_UTILS_DSN environment variableriable, if present,
has the same effect.
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 . After SAS-2 the protocol sections of SAS were
split into another document series known as the SAS Protocol Layer (SPL) 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.
AUTHORS
Written by Douglas Gilbert.
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright © 2006-2018 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
smp_utils-0.99 February 2018 SMP_DISCOVER_LIST(8)