NAME¶
smp_discover_list - invoke DISCOVER LIST SMP function
SYNOPSIS¶
smp_discover_list [
--adn] [
--brief]
[
--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 Management Protocol (SMP) DISCOVER LIST function requests
to a 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 and errored expander phys 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.
- -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 or end 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.
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" to subtractive routing or "T" for table routing. Then
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 end 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 wi11 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 supports zoning (i.e. REPORT GENERAL response bit for 'zoning
supported' 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.
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-2011 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