Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, July 27, 2022

smp_discover (8)


smp_discover - invoke DISCOVER SMP function


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]


SMP_DISCOVER(8)                    SMP_UTILS                   SMP_DISCOVER(8)

       smp_discover - invoke DISCOVER SMP function

       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]

       Sends one or more SAS Serial Management Protocol (SMP)  DISCOVER  func-
       tion  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  consid-
       ered  "active"  and  can  be  suppressed  from the output by adding the
       --brief option.

       Mandatory arguments to long options are mandatory for short options  as

       -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 prob-
              ably 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 "discov-
              ered" 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  typi-
              cally available even if a phy is not connected, "vacant" or dis-
              abled. 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 --multi-
              ple 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  prob-
       lem"  or  "spinup  hold".  Other  states are mapped to "attached". This
       includes  enabled  phys  with  nothing  connected   which   appear   as

       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

       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.

       See attributes(7) for descriptions of the following attributes:

       |Availability   | system/storage/smp_utils |
       |Stability      | Uncommitted              |

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

       Source  code  for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-

       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source was downloaded from  http://sg.danny.cz/sg/p/smp_utils-0.98.tgz.

       Further information about this software can be found on the open source
       community website at http://sg.danny.cz/sg/smp_utils.html.

       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.

       Written by Douglas Gilbert.

       Report bugs to <dgilbert at interlog dot com>.

       Copyright (C) 2006-2014 Douglas Gilbert
       This software is distributed under a FreeBSD license. There is NO  war-
       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR-

       smp_utils, smp_discover_list, smp_phy_control

smp_utils-0.98                    April 2014                   SMP_DISCOVER(8)