1SMP_DISCOVER(8)                    SMP_UTILS                   SMP_DISCOVER(8)
2
3
4

NAME

6       smp_discover - invoke DISCOVER SMP function
7

SYNOPSIS

9       smp_discover  [--adn]  [--brief]  [--cap]  [--help]  [--hex] [--ignore]
10       [--interface=PARAMS]   [--list]   [--multiple]    [--my]    [--num=NUM]
11       [--phy=ID]  [--raw] [--sa=SAS_ADDR] [--summary] [--verbose] [--version]
12       [--zero] SMP_DEVICE[,N]
13

DESCRIPTION

15       Sends one or more SAS Serial Management Protocol (SMP)  DISCOVER  func‐
16       tion  requests  to  an SMP target and decodes or outputs the responses.
17       The SMP target is  identified  by  the  SMP_DEVICE  and  the  SAS_ADDR.
18       Depending  on  the  interface,  the  SAS_ADDR  may  be deduced from the
19       SMP_DEVICE.  The mpt interface uses SMP_DEVICE to identify  a  HBA  (an
20       SMP  initiator)  and  needs  the additional ,N to differentiate between
21       HBAs if there are multiple present.
22
23       If the --phy=ID option is not given then  --summary  is  assumed.  When
24       --summary  is  given  or assumed, this utility shows the disposition of
25       each active expander phy in table form. One row is shown for  each  phy
26       and  is  described in the SINGLE LINE PER PHY FORMAT section below. For
27       this purpose disabled expander phys and those with errors  are  consid‐
28       ered  "active"  and  can  be  suppressed  from the output by adding the
29       --brief option.
30

OPTIONS

32       Mandatory arguments to long options are mandatory for short options  as
33       well.
34
35       -A, --adn
36              causes  the  "attached  device name" field to be output when the
37              --multiple or --summary option is also given.  See  the  section
38              below  on  SINGLE LINE PER PHY FORMAT. Note the "attached device
39              name" field was added is SAS-2.
40
41       -b, --brief
42              reduce the decoded response output. If used twice will  exit  if
43              there  is  no attached device (after outputting that). When used
44              with --multiple, unattached  phys  are  not  listed;  when  used
45              twice, trims attached phys output.
46
47       -c, --cap
48              decode  and  print  phy  capabilities  bits fields (see SNW-3 in
49              draft). Each expander phy has three of these fields: programmed,
50              current  and attached.  By default these fields are only printed
51              out in hex, or not at all if the  --brief  option  is  given  or
52              implied. Of the three the attached phy capability field is prob‐
53              ably the most interesting. If the  --verbose  option  is  given,
54              then  the  various "G" identifiers are expanded (e.g. instead of
55              "G4:" it prints "G4 (12 Gbps):").
56
57       -h, --help
58              output the usage message then exit.
59
60       -H, --hex
61              output the response (less the CRC field) in hexadecimal.
62
63       -i, --ignore
64              sets the Ignore Zone Group bit  in  the  SMP  Discover  request.
65              Expander  phys  hidden  by  zoning  will  appear as "phy vacant"
66              unless this option is given.
67
68       -I, --interface=PARAMS
69              interface specific parameters. In this case  "interface"  refers
70              to  the  path through the operating system to the SMP initiator.
71              See the smp_utils man page for more information.
72
73       -l, --list
74              list attributes in "name=value" form, one entry per line.
75
76       -m, --multiple
77              loops  over  multiple  phys  within  SMP  target  (typically  an
78              expander)  and  does  a  DISCOVER request and outputs a one line
79              summary. Phy 0 is queried first, then phy 1, continuing until an
80              error  occurs.  The starting phy and the number of phys "discov‐
81              ered" can be controlled by --phy=ID and --num=NUM. If --brief is
82              given then there is no output for phys that indicate there is no
83              attached device. When this option is used twice then  multi-line
84              output is produced for each phy. See the section below on SINGLE
85              LINE PER PHY FORMAT.
86
87       -M, --my
88              outputs my (this expander's) SAS address  in  hex  (prefixed  by
89              "0x").  This  is obtained from the DISCOVER response of phy id 0
90              (unless --phy=ID is given). The expander's SAS address is  typi‐
91              cally available even if a phy is not connected, "vacant" or dis‐
92              abled. This option overrides most other options (e.g.  overrides
93              --multiple and --summary options).
94
95       -n, --num=NUM
96              number  of phys to fetch, starting at --phy=ID when the --multi‐
97              ple option is given. The default value is 0 which is interpreted
98              as "the rest" (i.e. until a "phy does not exist" function result
99              is received). This option is  ignored  in  the  absence  of  the
100              --multiple option.
101
102       -p, --phy=ID
103              phy  identifier. ID is a value between 0 and 254. If this option
104              is not given then the --summary option is assumed.
105
106       -r, --raw
107              send the response (less the CRC field) to stdout in binary.  All
108              error messages are sent to stderr.
109
110       -s, --sa=SAS_ADDR
111              specifies  the  SAS  address of the SMP target device. Typically
112              this is an expander. This  option  may  not  be  needed  if  the
113              SMP_DEVICE  has the target's SAS address within it. The SAS_ADDR
114              is in decimal but most SAS addresses are shown  in  hexadecimal.
115              To  give  a  number in hexadecimal either prefix it with '0x' or
116              put a trailing 'h' on it.
117
118       -S, --summary
119              output a multi line summary,  with  one  line  per  active  phy.
120              Checks all phys (or less is --num=NUM is given), starting at phy
121              0 (unless --phy=ID is given). Equivalent to '--multiple --brief'
122              ('-mb').   See  the section below on SINGLE LINE PER PHY FORMAT.
123              If the --phy=ID is not given then this option is assumed.
124
125       -v, --verbose
126              increase the verbosity of the output. Can be used multiple times
127
128       -V, --version
129              print the version string and then exit.
130
131       -z, --zero
132              zero the Allocated Response Length field in  the  request.  This
133              option  also zeros the Request Length field in the request. This
134              is required for strict SAS-1.1 compliance. However  this  option
135              should  not  be  given  in  SAS-2  and  later; if it is given an
136              abridged response may result.
137

SINGLE LINE PER PHY FORMAT

139       The --summary option causes SMP DISCOVER responses to be compressed  to
140       a  header followed by one line per phy. To save space SAS addresses are
141       shown in hex without a '0x' prefix or 'h' suffix. The header line gives
142       the SAS address of the SMP target itself and assumes it is an expander.
143
144       Each  line  starts  with  "  phy  <n>:" where <n> is the phy identifier
145       (and they are origin zero). That is followed by the  routing  attribute
146       represented  by a single letter which is either "D" for direct routing,
147       "S" for subtractive routing, "T" or "U". Both "T" and "U"  imply  table
148       routing,  the  difference is that if REPORT GENERAL indicates "table to
149       table supported" then "U" is output to indicate that phy can be part of
150       an  enclosure  universal  port;  otherwise  "T" is used. Next comes the
151       negotiated physical link rate which is either "disabled", "reset  prob‐
152       lem"  or  "spinup  hold".  Other  states are mapped to "attached". This
153       includes  enabled  phys  with  nothing  connected   which   appear   as
154       "attached:[0000000000000000:00]".
155
156       Information  shown  between  the  brackets  is for the attached device.
157       Phys     that     are     connected     display     something     like:
158       "attached:[5000c50000520a2a:01 " where the first number is the attached
159       SAS address (in hex) and the second number is the attached device's phy
160       identifier.  If  the  attached  device type is other than a SAS or SATA
161       device then one of these abbreviations is output: "exp" (for expander),
162       "fex"  (for  fanout  expander)  or  "res"  (for unknown attached device
163       type). If a phy is flagged as "virtual" then  the  letter  "V"  appears
164       next. Next are the protocols supported by the attached device which are
165       shown as "i(<list>)" for initiator  protocols  and/or  "t(<list>)"  for
166       target  protocols.  The  <list> is made up of "PORT_SEL", "SSP", "STP",
167       "SMP" and "SATA" with "+" used as a separator. For example a  SAS  host
168       adapter  will  most  likely appear as: "i(SSP+STP+SMP)". This completes
169       the information  about  the  attached  phy,  hence  the  closing  right
170       bracket.
171
172       If  appropriate, the negotiated physical link rate is shown in gigabits
173       per second. Here is an example of a line for expander phy identifier 11
174       connected to a SATA target (or SATA "device" to use the t13.org term):
175
176         phy  11:T:attached:[500605b000000afb:00  t(SATA)]  1.5 Gbps
177
178       If  the  expander  has zoning enabled (i.e. REPORT GENERAL response bit
179       for 'zoning enabled' is set) and a phy's zone group is other than zg  1
180       then the phy's zone group is shown (e.g. "ZG:2").
181
182       If  the  --adn  option is given then after the attached SAS address and
183       the attached device's phy identifier  are  output  an  extra  field  is
184       inserted  containing  the  "attached device name" field. For a SAS disk
185       this should be its target device name (in NAA-5 format) and for a  SATA
186       disk  its  WWN (if provided, also in NAA-5 format). Also when the --adn
187       option is given the phy speed and zone group are not output in order to
188       keep the line length reasonable.
189

NOTES

191       In  SAS-2  and  later both the DISCOVER and DISCOVER LIST functions are
192       available. The DISCOVER LIST function should be  favoured  for  several
193       reasons: its response can hold up to 40 descriptors each describing the
194       state of one expander phy. The vast majority of expander chips  on  the
195       market  support 36 phys or less so one DISCOVER LIST response will sum‐
196       marize the states of all its phys. With the DISCOVER function only  one
197       expander  phy's  state is returned in its response. Other advantages of
198       the DISCOVER LIST function are its "phy filter" and  "descriptor  type"
199       function request fields.
200

EXAMPLES

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

CONFORMING TO

205       The SMP DISCOVER function was introduced in SAS-1, with small additions
206       in SAS-1.1 . There were a large number of additions in  SAS-2  .  After
207       SAS-2  the  protocol  sections  of SAS were split into another document
208       series known as SPL. Now SPL and SPL-2 are standards and  SPL-3  is  in
209       the draft stage.
210

AUTHORS

212       Written by Douglas Gilbert.
213

REPORTING BUGS

215       Report bugs to <dgilbert at interlog dot com>.
216
218       Copyright © 2006-2014 Douglas Gilbert
219       This  software is distributed under a FreeBSD license. There is NO war‐
220       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR‐
221       POSE.
222

SEE ALSO

224       smp_utils, smp_discover_list, smp_phy_control
225
226
227
228smp_utils-0.98                    April 2014                   SMP_DISCOVER(8)
Impressum