1SMP_DISCOVER_LIST(8) SMP_UTILS SMP_DISCOVER_LIST(8)
2
6 smp_discover_list - invoke DISCOVER LIST SMP function
7
9 smp_discover_list [--adn] [--brief] [--cap] [--descriptor=TY] [--dsn]
10 [--filter=FI] [--help] [--hex] [--ignore] [--interface=PARAMS]
11 [--num=NUM] [--one] [--phy=ID] [--raw] [--sa=SAS_ADDR] [--summary]
12 [--verbose] [--version] [--zpi=FN] SMP_DEVICE[,N]
13
15 Sends one or more SAS Serial Management Protocol (SMP) DISCOVER LIST
16 function requests to an SMP target and decodes or outputs the
17 responses. The SMP target is identified by the SMP_DEVICE and the
18 SAS_ADDR. Depending on the interface, the SAS_ADDR may be deduced from
19 the SMP_DEVICE. The mpt interface uses SMP_DEVICE to identify a HBA
20 (an 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 The DISCOVER LIST response may contain up to 8 descriptors when the
32 "descriptor type" field in the request is set to 0 (e.g. --descrip‐
33 tor=0). The DISCOVER LIST response may contain up to 40 descriptors
34 when the "descriptor type" field in the request is set to 1 (e.g.
35 --descriptor=1). Multiple DISCOVER LIST requests will be made if more
36 descriptors are requested (e.g. --summary requests 254) and the previ‐
37 ous response indicates that more descriptors may be available.
38 Rather than supply options and SMP_DEVICE[,N] on every invocation some
40 can be supplied via environment variables. See the section on ENVIRON‐
41 MENT VARIABLES below.
42
44 Mandatory arguments to long options are mandatory for short options as
45 well.
46 -A, --adn
48 causes the "attached device name" field to be output when the
49 --one or --summary option is also given. See the section below
50 on SINGLE LINE PER PHY FORMAT. Note the "attached device name"
51 field is not available in the short format (e.g. --descrip‐
52 tor=1).
53 -b, --brief
55 reduce the decoded response output.
56 -c, --cap
58 decode and print phy capabilities bits fields (see SNW-3 in
59 draft). Each expander phy has three of these fields: programmed,
60 current and attached. By default these fields are only printed
61 out in hex, or not at all if the --brief option is given or
62 implied. Of the three the attached phy capability field is prob‐
63 ably the most interesting. If the --verbose option is given,
64 then the various "G" identifiers are expanded (e.g. instead of
65 "G4:" it prints "G4 (12 Gbps):").
66 -d, --descriptor=TY
68 set the "descriptor type" field in the request. When TY is 0
69 then the 120 byte response defined by the DISCOVER function
70 response (less its CRC field) is placed in the descriptors of
71 this function's response. When TY is 1 the short format (i.e. 24
72 byte per descriptor) information is placed in the descriptors of
73 this function's response.
74 -D, --dsn
76 outputs the device slot number at the end of each summary line.
77 In summary mode one line is output per expander phy. It is out‐
78 put in the form "dsn=<val>" where <val> is decimal in the range
79 from 0 to 254 inclusive. It is not output if it is not avail‐
80 able or has the value 255. The device slot number is not avail‐
81 able in short format, so with this option in summary mode, if
82 the --descriptor=1 is not given, then the longer format is cho‐
83 sen. An expander typically contains a SES device which yields
84 device slot numbers in its Additional Element Status diagnostic
85 page.
86 -f, --filter=FI
88 set the filter field in the request. When FI is 0 (default)
89 fetch descriptors for all phys. When FI is 1 only fetch descrip‐
90 tors for phys attached to (other) expanders. When FI is 2 only
91 fetch descriptors for phys attached to expanders, SAS or SATA
92 devices. When FI is 1 or 2, expander phys that would yield "phy
93 vacant" (indicating they are hidden by zoning) are filtered out.
94 -h, --help
96 output the usage message then exit.
97 -H, --hex
99 output the response (less the CRC field) in hexadecimal.
100 -i, --ignore
102 sets the Ignore Zone Group bit in the SMP Discover list request.
103 -I, --interface=PARAMS
105 interface specific parameters. In this case "interface" refers
106 to the path through the operating system to the SMP initiator.
107 See the smp_utils man page for more information.
108 -n, --num=NUM
110 maximum number of descriptors fetch. If any descriptors are in
111 the response the first phy id will be greater than or equal to
112 the argument of --phy=ID. Note that maximum SMP frame size is
113 1032 bytes (including a trailing 4 byte CRC) which may limit the
114 number of descriptors that can be fetched by a single DISCOVER
115 LIST function (especially when '--descriptor=0').
116 -o, --one
118 use one line (summarized) format for each descriptor in the
119 response. The default action when this option is not given is
120 to output multiple indented lines for each descriptor in the
121 response. See the section below on SINGLE LINE PER PHY FORMAT.
122 -p, --phy=ID
124 phy identifier. ID is a value between 0 and 254. This is the
125 starting (lowest numbered) phy id to fetch in the response.
126 Note that due to the filter field setting, the first phy id in
127 the response may be greater than the argument to this option.
128 -r, --raw
130 send the response (less the CRC field) to stdout in binary. All
131 error messages are sent to stderr.
132 -s, --sa=SAS_ADDR
134 specifies the SAS address of the SMP target device. Typically
135 this is an expander. This option may not be needed if the
136 SMP_DEVICE has the target's SAS address within it. The SAS_ADDR
137 is in decimal but most SAS addresses are shown in hexadecimal.
138 To give a number in hexadecimal either prefix it with '0x' or
139 put a trailing 'h' on it.
140 -S, --summary
142 output a multi line summary, with one line per active phy.
143 Checks up to 254 phys starting at phy identifier ID (which
144 defaults to 0). Equivalent to '-o -d 1 -n 254 -b' unless the
145 --adn option was also given, in which case it is equivalent to
146 '-o -d 0 -n 254 -b' . See the section below on SINGLE LINE PER
147 PHY FORMAT.
148 -v, --verbose
150 increase the verbosity of the output. Can be used multiple
151 times.
152 -V, --version
154 print the version string and then exit.
155 -Z, --zpi=FN
157 FN is a file that will be created or truncated then have zone
158 phy information written to it in a format suitable for input to
159 the smp_conf_zone_phy_info utility's --pconf=FN option. If
160 --num=NUM is not given it is set to 254. The output will start
161 from phy_id 0 unless --phy=ID is given.
162
164 The --summary (or --one) option causes SMP DISCOVER LIST descriptors to
165 be compressed to one line per phy. To save space SAS addresses are
166 shown in hex without a '0x' prefix or 'h' suffix. The header section
167 outputs information found in the DISCOVER LIST response's header sec‐
168 tion.
169 For each descriptor in the DISCOVER LIST response, one line is output
171 starting with " phy <n>:" where <n> is the phy identifier (and they
172 are origin zero). That is followed by the routing attribute represented
173 by a single letter which is either "D" for direct routing, "S" for sub‐
174 tractive routing, "T" or "U". Both "T" and "U" imply table routing, the
175 difference is that if REPORT GENERAL indicates "table to table sup‐
176 ported" then "U" is output to indicate that phy can be part of an
177 enclosure universal port; otherwise "T" is used. Next comes the negoti‐
178 ated physical link rate which is either "disabled", "reset problem" or
179 "spinup hold". Other states are mapped to "attached". This includes
180 enabled phys with nothing connected which appear as
181 "attached:[0000000000000000:00]".
182 Information shown between the brackets is for the attached device. Phys
184 that are connected display something like:
185 "attached:[5000c50000520a2a:01 " where the first number is the attached
186 SAS address (in hex) and the second number is the attached device's phy
187 identifier. If the attached device type is other than an SAS or SATA
188 device then one of these abbreviations is output: "exp" (for expander),
189 "fex" (for fanout expander) or "res" (for unknown attached device
190 type). If a phy is flagged as "virtual" then the letter "V" appears
191 next. Next are the protocols supported by the attached device which are
192 shown as "i(<list>)" for initiator protocols and/or "t(<list>)" for
193 target protocols. The <list> is made up of "PORT_SEL", "SSP", "STP",
194 "SMP" and "SATA" with "+" used as a separator. For example a SAS host
195 adapter will most likely appear as: "i(SSP+STP+SMP)". This completes
196 the information about the attached phy, hence the closing right
197 bracket.
198 If appropriate, the negotiated physical link rate is shown in gigabits
200 per second. Here is an example of a line for expander phy identifier 11
201 connected to a SATA target (or SATA "device" to use the t13.org term):
202 phy 11:T:attached:[500605b000000afb:00 t(SATA)] 1.5 Gbps
204 If the expander has zoning enabled (i.e. REPORT GENERAL response bit
206 for 'zoning enabled' is set) and a phy's zone group is other than zg 1
207 then the phy's zone group is shown (e.g. "ZG:2").
208 If the --adn option is given then after the attached SAS address and
210 the attached device's phy identifier are output an extra field is
211 inserted containing the "attached device name" field. For a SAS disk
212 this should be its target device name (in NAA-5 format) and for a SATA
213 disk its WWN (if provided, also in NAA-5 format). Also when the --adn
214 option is given the phy speed and zone group are not output in order to
215 keep the line length reasonable.
216 If the --dsn option is given and device slot number information is
218 available for the current phy, then "dsn=<num>" is appended to the
219 line. Device slot numbers range from 0 to 254 with 255 meaning there
220 is no corresponding slot so it is not listed.
221
223 If SMP_DEVICE[,N] is not given then the SMP_UTILS_DEVICE environment
224 variable is checked and if present its contents are used instead.
225 If the SAS address (of the SMP target) is not given and it is required
227 (i.e. it is not implicit in SMP_DEVICE[,N]) then the
228 SMP_UTILS_SAS_ADDR environment variable is checked and if present its
229 contents are used as the SAS address. SAS addresses are usually given
230 in hex indicated by a leading '0x' or trailing 'h'.
231 A device slot number (dsn) is important for establishing the relation‐
233 ship between an expander phy and a SES array element. Newer expanders
234 (e.g. SAS-3) support dsn_s in the DISCOVER (and DISCOVER LIST) func‐
235 tions. These can be shown, if available, with the --dsn option to
236 smp_discover and smp_discover_list utilities.. To ease typing that
237 option often, the SMP_UTILS_DSN environment variableriable, if present,
238 has the same effect.
239
241 In SAS-2 and later both the DISCOVER and DISCOVER LIST functions are
242 available. The DISCOVER LIST function should be favoured for several
243 reasons: its response can hold up to 40 descriptors each describing the
244 state of one expander phy. The vast majority of expander chips on the
245 market support 36 phys or less so one DISCOVER LIST response will sum‐
246 marize the states of all its phys. With the DISCOVER function only one
247 expander phy's state is returned in its response. Other advantages of
248 the DISCOVER LIST function are its "phy filter" and "descriptor type"
249 function request fields.
250
252 The SMP DISCOVER LIST function was introduced in SAS-2 . After SAS-2
253 the protocol sections of SAS were split into another document series
254 known as the SAS Protocol Layer (SPL) and it was standardized as SPL
255 ANSI INCITS 476-2011. Next came SPL-2 which was standardized as SPL-2
256 ANSI INCITS 505-2013. Then came SPL-3 which was standardized as SPL-3
257 ANSI INCITS 492-2015. SPL-4 is near standardization and its most recent
258 draft is spl4r13.pdf while SPL-5 work has started and its most recent
259 draft is spl5r03.pdf.
260
262 Written by Douglas Gilbert.
263
265 Report bugs to <dgilbert at interlog dot com>.
266
268 Copyright © 2006-2018 Douglas Gilbert
269 This software is distributed under a FreeBSD license. There is NO war‐
270 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
271 POSE.
272
274 smp_utils, smp_discover, smp_phy_control, smp_conf_zone_phy_info
275smp_utils-0.99 February 2018 SMP_DISCOVER_LIST(8)