Ubuntu Manpage: smp_discover - invoke DISCOVER SMP function

NAME

       smp_discover - invoke DISCOVER SMP function

SYNOPSIS

       smp_discover  [--adn] [--brief] [--cap] [--dsn] [--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.

       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 --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.

-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. An expander
typically contains a SES device which yields device slot numbers in its Additional Element Status
diagnostic page.

-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.

SINGLE LINE PER PHY FORMAT

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.

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.

EXAMPLES

       See "Examples" section in http://sg.danny.cz/sg/smp_utils.html

CONFORMING TO

       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 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.