NAME¶
smp_discover - invoke DISCOVER SMP function
SYNOPSIS¶
smp_discover [
--adn] [
--brief] [
--cap]
[
--help] [
--hex] [
--ignore] [
--interface=PARAMS]
[
--list] [
--multiple] [
--my] [
--num=NUM] [
--phy=ID] [
--raw] [
--sa=SAS_ADDR] [
--summary]
[
--verbose] [
--version] [
--zero]
SMP_DEVICE[,N]
DESCRIPTION¶
Sends one or more SAS Serial Management Protocol (SMP) DISCOVER 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.
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
--multiple or --summary option is also given. See the
section below on SINGLE LINE PER PHY FORMAT. Note the "attached
device name" field was added is SAS-2.
- -b, --brief
- reduce the decoded response output. If used twice will exit if there is no
attached device (after outputting that). When used with --multiple,
unattached phys are not listed; when used twice, trims attached phys
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):").
- -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 request. Expander phys
hidden by zoning will appear as "phy vacant" unless this option
is given.
- -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.
- -l, --list
- list attributes in "name=value" form, one entry per line.
- -m, --multiple
- loops over multiple phys within SMP target (typically an expander) and
does a DISCOVER request and outputs a one line summary. Phy 0 is queried
first, then phy 1, continuing until an error occurs. The starting phy and
the number of phys "discovered" can be controlled by
--phy=ID and --num=NUM. If --brief is given then
there is no output for phys that indicate there is no attached device.
When this option is used twice then multi-line output is produced for each
phy. See the section below on SINGLE LINE PER PHY FORMAT.
- -M, --my
- outputs my (this expander's) SAS address in hex (prefixed by
"0x"). This is obtained from the DISCOVER response of phy id 0
(unless --phy=ID is given). The expander's SAS address is typically
available even if a phy is not connected, "vacant" or disabled.
This option overrides most other options (e.g. overrides --multiple
and --summary options).
- -n, --num=NUM
- number of phys to fetch, starting at --phy=ID when the
--multiple option is given. The default value is 0 which is
interpreted as "the rest" (i.e. until a "phy does not
exist" function result is received). This option is ignored in the
absence of the --multiple option.
- -p, --phy=ID
- phy identifier. ID is a value between 0 and 254. If this option is
not given then the --summary option is assumed.
- -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 all phys
(or less is --num=NUM is given), starting at phy 0 (unless
--phy=ID is given). Equivalent to '--multiple --brief' ('-mb'). See
the section below on SINGLE LINE PER PHY FORMAT. If the --phy=ID is
not given then this option is assumed.
- -v, --verbose
- increase the verbosity of the output. Can be used multiple times
- -V, --version
- print the version string and then exit.
- -z, --zero
- zero the Allocated Response Length field in the request. This option also
zeros the Request Length field in the request. This is required for strict
SAS-1.1 compliance. However this option should not be given in SAS-2 and
later; if it is given an abridged response may result.
The
--summary option causes SMP DISCOVER responses to be compressed to a
header followed by one line per phy. To save space SAS addresses are shown in
hex without a '0x' prefix or 'h' suffix. The header line gives the SAS address
of the SMP target itself and assumes it is an expander.
Each line starts 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 a 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.
EXAMPLES¶
See "Examples" section in
http://sg.danny.cz/sg/smp_utils.html
The SMP DISCOVER function was introduced in SAS-1, with small additions in
SAS-1.1 . There were a large number of additions in SAS-2 . After SAS-2 the
protocol sections of SAS were split into another document series known as SPL.
Now SPL and SPL-2 are standards and SPL-3 is in the draft stage.
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_list, smp_phy_control