1SMP_DISCOVER(8) SMP_UTILS SMP_DISCOVER(8)
2
6 smp_discover - invoke DISCOVER SMP function
7
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
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
32 Mandatory arguments to long options are mandatory for short options as
33 well.
34 -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 -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 -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 -h, --help
58 output the usage message then exit.
59 -H, --hex
61 output the response (less the CRC field) in hexadecimal.
62 -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 -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 -l, --list
74 list attributes in "name=value" form, one entry per line.
75 -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 -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 -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 -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 -r, --raw
107 send the response (less the CRC field) to stdout in binary. All
108 error messages are sent to stderr.
109 -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 -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 -v, --verbose
126 increase the verbosity of the output. Can be used multiple times
127 -V, --version
129 print the version string and then exit.
130 -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
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 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 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 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 phy 11:T:attached:[500605b000000afb:00 t(SATA)] 1.5 Gbps
177 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 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
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
202 See "Examples" section in http://sg.danny.cz/sg/smp_utils.html
203
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
212 Written by Douglas Gilbert.
213
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
224 smp_utils, smp_discover_list, smp_phy_control
225smp_utils-0.98 April 2014 SMP_DISCOVER(8)