1SMP_DISCOVER(8) SMP_UTILS SMP_DISCOVER(8)
2
6 smp_discover - invoke DISCOVER SMP function
7
9 smp_discover [--adn] [--brief] [--cap] [--dsn] [--help] [--hex]
10 [--ignore] [--interface=PARAMS] [--list] [--multiple] [--my]
11 [--num=NUM] [--phy=ID] [--raw] [--sa=SAS_ADDR] [--summary] [--verbose]
12 [--version] [--zero] SMP_DEVICE[,N]
13
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 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 Rather than supply options and SMP_DEVICE[,N] on every invocation some
32 can be supplied via environment variables. See the section on ENVIRON‐
33 MENT VARIABLES below.
34
36 Mandatory arguments to long options are mandatory for short options as
37 well.
38 -A, --adn
40 causes the "attached device name" field to be output when the
41 --multiple or --summary option is also given. See the section
42 below on SINGLE LINE PER PHY FORMAT. Note the "attached device
43 name" field was added is SAS-2.
44 -b, --brief
46 reduce the decoded response output. If used twice will exit if
47 there is no attached device (after outputting that). When used
48 with --multiple, unattached phys are not listed; when used
49 twice, trims attached phys output.
50 -c, --cap
52 decode and print phy capabilities bits fields (see SNW-3 in
53 draft). Each expander phy has three of these fields: programmed,
54 current and attached. By default these fields are only printed
55 out in hex, or not at all if the --brief option is given or
56 implied. Of the three the attached phy capability field is prob‐
57 ably the most interesting. If the --verbose option is given,
58 then the various "G" identifiers are expanded (e.g. instead of
59 "G4:" it prints "G4 (12 Gbps):").
60 -h, --help
62 output the usage message then exit.
63 -D, --dsn
65 outputs the device slot number at the end of each summary line.
66 In summary mode one line is output per expander phy. It is out‐
67 put in the form "dsn=<val>" where <val> is decimal in the range
68 from 0 to 254 inclusive. It is not output if it is not avail‐
69 able or has the value 255. An expander typically contains a SES
70 device which yields device slot numbers in its Additional Ele‐
71 ment Status diagnostic page.
72 -H, --hex
74 output the response (less the CRC field) in hexadecimal.
75 -i, --ignore
77 sets the Ignore Zone Group bit in the SMP Discover request.
78 Expander phys hidden by zoning will appear as "phy vacant"
79 unless this option is given.
80 -I, --interface=PARAMS
82 interface specific parameters. In this case "interface" refers
83 to the path through the operating system to the SMP initiator.
84 See the smp_utils man page for more information.
85 -l, --list
87 list attributes in "name=value" form, one entry per line.
88 -m, --multiple
90 loops over multiple phys within SMP target (typically an
91 expander) and does a DISCOVER request and outputs a one line
92 summary. Phy 0 is queried first, then phy 1, continuing until an
93 error occurs. The starting phy and the number of phys "discov‐
94 ered" can be controlled by --phy=ID and --num=NUM. If --brief is
95 given then there is no output for phys that indicate there is no
96 attached device. When this option is used twice then multi-line
97 output is produced for each phy. See the section below on SINGLE
98 LINE PER PHY FORMAT.
99 -M, --my
101 outputs my (this expander's) SAS address in hex (prefixed by
102 "0x"). This is obtained from the DISCOVER response of phy id 0
103 (unless --phy=ID is given). The expander's SAS address is typi‐
104 cally available even if a phy is not connected, "vacant" or dis‐
105 abled. This option overrides most other options (e.g. overrides
106 --multiple and --summary options).
107 -n, --num=NUM
109 number of phys to fetch, starting at --phy=ID when the --multi‐
110 ple option is given. The default value is 0 which is interpreted
111 as "the rest" (i.e. until a "phy does not exist" function result
112 is received). This option is ignored in the absence of the
113 --multiple option.
114 -p, --phy=ID
116 phy identifier. ID is a value between 0 and 254. If this option
117 is not given then the --summary option is assumed.
118 -r, --raw
120 send the response (less the CRC field) to stdout in binary. All
121 error messages are sent to stderr.
122 -s, --sa=SAS_ADDR
124 specifies the SAS address of the SMP target device. Typically
125 this is an expander. This option may not be needed if the
126 SMP_DEVICE has the target's SAS address within it. The SAS_ADDR
127 is in decimal but most SAS addresses are shown in hexadecimal.
128 To give a number in hexadecimal either prefix it with '0x' or
129 put a trailing 'h' on it.
130 -S, --summary
132 output a multi line summary, with one line per active phy.
133 Checks all phys (or less is --num=NUM is given), starting at phy
134 0 (unless --phy=ID is given). Equivalent to '--multiple --brief'
135 ('-mb'). See the section below on SINGLE LINE PER PHY FORMAT.
136 If the --phy=ID is not given then this option is assumed.
137 -v, --verbose
139 increase the verbosity of the output. Can be used multiple times
140 -V, --version
142 print the version string and then exit.
143 -z, --zero
145 zero the Allocated Response Length field in the request. This
146 option also zeros the Request Length field in the request. This
147 is required for strict SAS-1.1 compliance. However this option
148 should not be given in SAS-2 and later; if it is given an
149 abridged response may result.
150
152 The --summary option causes SMP DISCOVER responses to be compressed to
153 a header followed by one line per phy. To save space SAS addresses are
154 shown in hex without a '0x' prefix or 'h' suffix. The header line gives
155 the SAS address of the SMP target itself and assumes it is an expander.
156 Each line starts with " phy <n>:" where <n> is the phy identifier
158 (and they are origin zero). That is followed by the routing attribute
159 represented by a single letter which is either "D" for direct routing,
160 "S" for subtractive routing, "T" or "U". Both "T" and "U" imply table
161 routing, the difference is that if REPORT GENERAL indicates "table to
162 table supported" then "U" is output to indicate that phy can be part of
163 an enclosure universal port; otherwise "T" is used. Next comes the
164 negotiated physical link rate which is either "disabled", "reset prob‐
165 lem" or "spinup hold". Other states are mapped to "attached". This
166 includes enabled phys with nothing connected which appear as
167 "attached:[0000000000000000:00]".
168 Information shown between the brackets is for the attached device.
170 Phys that are connected display something like:
171 "attached:[5000c50000520a2a:01 " where the first number is the attached
172 SAS address (in hex) and the second number is the attached device's phy
173 identifier. If the attached device type is other than a SAS or SATA
174 device then one of these abbreviations is output: "exp" (for expander),
175 "fex" (for fanout expander) or "res" (for unknown attached device
176 type). If a phy is flagged as "virtual" then the letter "V" appears
177 next. Next are the protocols supported by the attached device which are
178 shown as "i(<list>)" for initiator protocols and/or "t(<list>)" for
179 target protocols. The <list> is made up of "PORT_SEL", "SSP", "STP",
180 "SMP" and "SATA" with "+" used as a separator. For example a SAS host
181 adapter will most likely appear as: "i(SSP+STP+SMP)". This completes
182 the information about the attached phy, hence the closing right
183 bracket.
184 If appropriate, the negotiated physical link rate is shown in gigabits
186 per second. Here is an example of a line for expander phy identifier 11
187 connected to a SATA target (or SATA "device" to use the t13.org term):
188 phy 11:T:attached:[500605b000000afb:00 t(SATA)] 1.5 Gbps
190 If the expander has zoning enabled (i.e. REPORT GENERAL response bit
192 for 'zoning enabled' is set) and a phy's zone group is other than zg 1
193 then the phy's zone group is shown (e.g. "ZG:2").
194 If the --adn option is given then after the attached SAS address and
196 the attached device's phy identifier are output an extra field is
197 inserted containing the "attached device name" field. For a SAS disk
198 this should be its target device name (in NAA-5 format) and for a SATA
199 disk its WWN (if provided, also in NAA-5 format). Also when the --adn
200 option is given the phy speed and zone group are not output in order to
201 keep the line length reasonable.
202 If the --dsn option is given and device slot number information is
204 available for the current phy, then "dsn=<num>" is appended to the
205 line. Device slot numbers range from 0 to 254 with 255 meaning there
206 is no corresponding slot so it is not listed.
207
209 If SMP_DEVICE[,N] is not given then the SMP_UTILS_DEVICE environment
210 variable is checked and if present its contents are used instead.
211 If the SAS address (of the SMP target) is not given and it is required
213 (i.e. it is not implicit in SMP_DEVICE[,N]) then the
214 SMP_UTILS_SAS_ADDR environment variable is checked and if present its
215 contents are used as the SAS address. SAS addresses are usually given
216 in hex indicated by a leading '0x' or trailing 'h'.
217 A device slot number (dsn) is important for establishing the relation‐
219 ship between an expander phy and a SES array element. Newer expanders
220 (e.g. SAS-3) support dsn_s in the DISCOVER (and DISCOVER LIST) func‐
221 tions. These can be shown, if available, with the --dsn option to
222 smp_discover and smp_discover_list utilities.. To ease typing that
223 option often, the SMP_UTILS_DSN environment variableriable, if present,
224 has the same effect.
225
227 In SAS-2 and later both the DISCOVER and DISCOVER LIST functions are
228 available. The DISCOVER LIST function should be favoured for several
229 reasons: its response can hold up to 40 descriptors each describing the
230 state of one expander phy. The vast majority of expander chips on the
231 market support 36 phys or less so one DISCOVER LIST response will sum‐
232 marize the states of all its phys. With the DISCOVER function only one
233 expander phy's state is returned in its response. Other advantages of
234 the DISCOVER LIST function are its "phy filter" and "descriptor type"
235 function request fields.
236
238 See "Examples" section in http://sg.danny.cz/sg/smp_utils.html
239
241 The SMP DISCOVER function was introduced in SAS-1, with small additions
242 in SAS-1.1 . There were a large number of additions in SAS-2 . After
243 SAS-2 the protocol sections of SAS were split into another document
244 series known as the SAS Protocol Layer (SPL) and it was standardized as
245 SPL ANSI INCITS 476-2011. Next came SPL-2 which was standardized as
246 SPL-2 ANSI INCITS 505-2013. Then came SPL-3 which was standardized as
247 SPL-3 ANSI INCITS 492-2015. SPL-4 is near standardization and its most
248 recent draft is spl4r13.pdf while SPL-5 work has started and its most
249 recent draft is spl5r03.pdf.
250
252 Written by Douglas Gilbert.
253
255 Report bugs to <dgilbert at interlog dot com>.
256
258 Copyright © 2006-2018 Douglas Gilbert
259 This software is distributed under a FreeBSD license. There is NO war‐
260 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
261 POSE.
262
264 smp_utils, smp_discover_list, smp_phy_control
265smp_utils-0.99 February 2018 SMP_DISCOVER(8)