Provided by: smp-utils_0.98-1_amd64 bug

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.

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.

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