1SMP_UTILS(8) SMP_UTILS SMP_UTILS(8)
2
6 smp_* - invoke a SAS Serial Management Protocol (SMP) function
7
9 smp_* [--expected=EX] [--help] [--hex] [--interface=PARAMS] [--raw]
10 [--sa=SAS_ADDR] [--verbose] [--version] SMP_DEVICE[,N]
11
13 Serial Attached SCSI (SAS) is a transport (also known as a intercon‐
14 nect) used by storage systems. A SAS system is made up of Host Bus
15 Adapters (HBAs typically containing SCSI initiators), disks (referred
16 to in SCSI as both targets and logical units) and optionally some
17 switching hardware called "expanders". Expanders are not SCSI devices
18 so a new protocol was required to control and monitor them. The proto‐
19 col's full name is the SAS Serial Management Protocol which is abbrevi‐
20 ated to SMP.
21 smp_utils is a package of utilities. Each utility sends an SMP function
23 request to a SMP_DEVICE (an SMP target). Some utilities may invoke the
24 same function more than once. If an error occurs then an error message
25 is sent to stderr. If no error occurs, the response is decoded (the
26 default), output in ASCII hex (when --hex is given) or output in binary
27 to stdout (when the --raw option is given).
28 If SMP_DEVICE[,N] is not given then the value in the environment vari‐
30 able SMP_UTILS_DEVICE is used.
31 This package was originally written for Linux and has been ported to
33 FreeBSD and Solaris.
34
36 Currently there are multiple interfaces that allow SMP functions to be
37 passed through to an SMP target.
38 One method is to have a SMP_DEVICE which is actually the SMP initiator
40 (e.g. '/dev/mptctl,0'). In this case the SMP target's SAS address must
41 be supplied with the --sa=SAS_ADDR option.
42 Another method is to have a SMP_DEVICE which represents the SMP target.
44 In this case no SAS_ADDRESS needs to be given (since it is implicit).
45 Each utility in smp_utils attempts to work out which interface it has
47 been given by examining the SMP_DEVICE file. There are three interfaces
48 supported currently:
49 aac This specifies the aacraid SAS pass-through associated with
51 Adaptec/PMC RAID products. The SMP_DEVICE[,N] argument takes the
52 form /dev/aac[N[,E_ID]] where "N" is the raid controller number
53 (typically 0) and "E_ID" is the expander identifier (typically
54 0); both default to 0 so /dev/aac is equivalent to /dev/aac0 and
55 /dev/aac0,0 . The "N" is the unique_id found in
56 /sys/class/scsi_host<HN>/unique_id . The "HN" is the host num‐
57 ber which is the first number to appear on each line in the lss‐
58 csi utility which by default uses one line to list each accessi‐
59 ble SCSI device (typically SCSI or ATA disks). The "E_ID" is the
60 expander identifier which can be found with the Adaptec/PMC arc‐
61 conf utility using the form "arcconf expanderlist <Controller‐
62 Num>". The <ControllerNum>s start at 1 . If an aac RAID con‐
63 troller is present then the /dev/acc device node will be created
64 by the first smp utility to use this interface.
65 mpt This specifies the MPT fusion SAS pass-through. The mptsas
67 driver uses the '/dev/mptctl' device node (character device
68 major 10, minor 220) while the mpt2sas driver uses
69 '/dev/mpt2ctl' device node (major 10, minor 221). For the
70 mpt3sas driver the corresponding device node is '/dev/mpt3ctl'.
71 The 'modprobe mptctl' or 'modprobe mpt2ctl' command may be
72 needed. If there are multiple mpt fusion controllers (HBAs) in
73 the computer, then the user will need to specify which one to
74 use with the syntax: '/dev/mptctl,<n>' where <n> is the
75 "ioc_num". This number can be found with dmesg after the mptsas
76 driver is registered and appears as a suffix to the driver name
77 (e.g. mpt2sas0). It can also be found in
78 '/sys/class/scsi_host/host<n>/unique_id'. When this interface
79 is used the --sa=SAS_ADDR option must be given to specify the
80 SAS address of the SMP target.
81 sgv4 (sg)
83 This interface is more generic and supported by several SAS HBA
84 drivers including mptsas (and mpt2sas). It was introduced in the
85 Linux 2.6.24 kernel. The SMP functions are passed to the kernel
86 via the bsg driver using a format known as "SCSI Generic Version
87 4" which gives this interface its name: "sgv4" or just "sg". The
88 SAS transport layer within the SCSI sub-system unpacks the SMP
89 requests and forwards them to SAS low level drivers that support
90 this interface. The SMP_DEVICE is either a member of the
91 '/sys/class/bsg' directory (e.g. /sys/class/bsg/expander-6:0 )
92 or a device node made for the bsg driver (e.g.
93 /dev/bsg/expander-6:0 ). Such device nodes are dynamic (i.e.
94 they don't have fixed major and minor numbers) and should corre‐
95 spond to the major and minor numbers found in the
96 'sys/class/bsg/<smp_target_device>/dev' file.
97
99 The CAM subsystem has been enhanced in FreeBSD 9 to pass-through SMP
100 requests and return the corresponding responses. However CAM does not
101 directly access expander devices because they are not SCSI devices. It
102 makes the assumption that each SAS expander has an integrated SES
103 (enclosure) device and that is addressed. This assumption seems to be
104 true for SAS-2 expanders but not some SAS-1 expanders. Thus invocations
105 look like this:
106 # smp_discover /dev/ses0
108 where /dev/ses0 is a SES device associated with a SAS expander.
110
112 The USMP pass-through mechanism is used. Invocations look like this:
113 # smp_rep_manufacturer /dev/smp/expd0
115
117 If the device name is not given then the SMP_UTILS_DEVICE environment
118 variable is checked and if present its contents are used as the device
119 name.
120 If the SAS address (of the SMP target) is not given and it is required
122 (i.e. it is not implicit in the device name) then the
123 SMP_UTILS_SAS_ADDR environment variable is checked and if present its
124 contents are used as the SAS address. SAS addresses are usually given
125 in hex indicated by a leading '0x' or trailing 'h'.
126 A device slot number (dsn) is important for establishing the relation‐
128 ship between an expander phy and a SES array element. Newer expanders
129 (e.g. SAS-3) support dsn_s in the DISCOVER (and DISCOVER LIST) func‐
130 tions. These can be shown, if available, with the --dsn option to
131 smp_discover and smp_discover_list utilities.. To ease typing that
132 option often, the SMP_UTILS_DSN environment variable, if present, has
133 the same effect.
134 If both an environment variable and the corresponding command line
136 option is given and contradict, then the command line options take
137 precedence.
138
140 Mandatory arguments to long options are mandatory for short options as
141 well. If an option takes a numeric argument then that argument is
142 assumed to be decimal unless otherwise indicated (e.g. with a leading
143 "0x" or a trailing "h").
144 -E, --expected=EX
146 revision 4a of the SAS-2 draft introduced an 'expected expander
147 change count' field in some SMP requests. The idea is to detect
148 other SMP initiators trying to change the state of an expander.
149 The value EX is from 0 to 65535 inclusive with 0 being the
150 default value. When EX is greater than zero then if the value
151 doesn't match the expander change count of the SMP target (i.e.
152 the expander) when the request arrives then the target ignores
153 the request and sets a function result of "invalid expander
154 change count" in the response.
155 -h, --help
157 output the usage message for the utility then exit.
158 -H, --hex
160 output the response in hexadecimal. This does not include the
161 trailing CRC field.
162 -I, --interface=PARAMS
164 interface specific parameters. This option is usually not needed
165 since the interface type is guessed by a utility based on the
166 characteristics of the given SMP_DEVICE argument or what is in
167 the corresponding environment variables. PARAMS is of the form:
168 INTF[,force]. If the guess doesn't work then the interface can
169 be specified by giving a INTF of either 'mpt' or 'sgv4'. Sanity
170 checks are still performed and a utility may refuse if it
171 doesn't agree with the given INTF. If the user is really sure
172 then adding a ',force' will force the utility to use the given
173 interface.
174 -r, --raw
176 send the response to stdout in binary. This does not include the
177 trailing CRC field. All error messages are sent to stderr.
178 -s, --sa=SAS_ADDR
180 specifies the SAS address of the SMP target device. Typically
181 this is an expander. This option may not be needed if the
182 SMP_DEVICE has the target's SAS address associated with it. The
183 SAS_ADDR is in decimal but most SAS addresses are shown in hexa‐
184 decimal. To give a number in hexadecimal either prefix it with
185 '0x' or put a trailing 'h' on it. If this option is not given
186 then the value in the environment variable SMP_UTILS_SAS_ADDR is
187 used.
188 -v, --verbose
190 increase the verbosity of the output. Can be used multiple
191 times.
192 -V, --version
194 print the version string and then exit.
195
197 To aid scripts that call these utilities, the exit status is set to
198 indicate success (0) or failure (1 or more):
199 0 success
201 1 - 63 reserved for SMP function result codes. See the SAS-2 (or later)
203 draft, in the section on the application layer, drilling down
204 further: management application layer then SMP functions. Here
205 are some common function result codes: 1 [unknown SMP function],
206 2 [SMP function failed], 16 [phy does not exist], 17 [index does
207 not exist], 18 [phy does not support SATA], 19 [unknown phy
208 operation], 22 [phy vacant] and 35 [zone lock violation].
209 91 syntax error. Either illegal options, options with bad arguments
211 or a combination of options that is not permitted.
212 92 the utility is unable to open, close or use the given
214 SMP_DEVICE. The given file name could be incorrect or there may
215 be file permission problems. Adding the --verbose option may
216 give more information.
217 93 the utility has a resource problem. Typically this means an
219 attempt to allocate memory (ram) has failed.
220 97 the response to an SMP function failed sanity checks.
222 99 any error that can't be categorized into values 1 to 97 may
224 yield this value. This includes transport and operating system
225 errors.
226 126 the utility was found but could not be executed. That might
228 occur if the executable does not have execute permissions.
229 127 This is the exit status for utility not found. That might occur
231 when a script calls a utility in this package but the PATH envi‐
232 ronment variable has not been properly set up, so the script
233 cannot find the executable.
234 128 + <signum>
236 If a signal kills a utility then the exit status is 128 plus the
237 signal number. For example if a segmentation fault occurs then a
238 utility is typically killed by SIGSEGV which according to 'man 7
239 signal' has an associated signal number of 11; so the exit sta‐
240 tus will be 139 .
241 255 the utility tried to yield an exit status of 255 or larger. That
243 should not happen; given here for completeness.
244
246 Finding the SAS address of an expander can be a challenge in some envi‐
247 ronments. An enclosure containing one or more expanders may have the
248 expander SAS address(es) printed on the back of the device, a bit like
249 Ethernet MAC addresses.
250 In the Linux 2.6 kernel series the expander SAS address may well be in
252 the sysfs tree but it is not always easy to find. Doing this search may
253 help:
254 # find /sys -name "*expander*"
256 That should show the suffix on any expanders that have been detected.
258 Then a command like 'cat
259 /sys/class/sas_device/expander-6:0/sas_address' should show its SAS
260 address.
261 Another approach is to work backwards from SCSI devices (i.e. logical
263 units). The protocol specific port log page (log page 18h) contains
264 fields for the "attached SAS address". The sg_logs utility from the
265 sg3_utils package could be used like this:
266 # sg_logs --page=18h /dev/sdb
268 Any given "attached SAS address" is either a HBA, an expander or 0
270 indicating that port is not connected. An expander is indicated by
271 "attached device type: expander device". A SAS disk's target port iden‐
272 tifiers (also known as SAS addresses), device name and logical unit
273 name (all NAA 5 format) can be found with the sg_vpd utility (e.g.
274 'sg_vpd -i <disk_dev>'). The sdparm utility can provide the same infor‐
275 mation (e.g. 'sdparm -i <disk_dev>').
276 A SAS expander is often associated with a SCSI Enclosure Services (SES)
278 device sometimes on the same silicon attached via a virtual phy to the
279 expander. That SES device may be able to access and control an attached
280 enclosure or backplane via SGPIO or I2C on sideband signals (e.g. in a
281 SFF-8087 cable). To interact with a SES device, see the sg_ses utility.
282 Often expander phys are grouped in fours on the same connector (e.g.
284 SFF-8088). Care needs to be taken when multiple expanders are intercon‐
285 nected. An enclosure universal port is one in which the "table to ta‐
286 ble supported" attribute is set (in the REPORT GENERAL response) and
287 the associated phys have the table routing attribute (in the DISCOVER
288 response). Enclosure universal ports were introduced in SAS-2 and have
289 few restrictions when used to interconnect expanders or connect SAS or
290 SATA devices. An enclosure out port is one in which the "table to table
291 supported" attribute is clear and the associated phys have the table
292 routing attribute. An enclosure in port is one in which the associated
293 phys have the subtractive routing attribute. When universal ports are
294 not available, an expander interconnect should be between an in port
295 and an out port.
296
298 See "Examples" section in http://sg.danny.cz/sg/smp_utils.html .
299
301 SAS has multiple generations. The early standards are: the original SAS
302 (ANSI INCITS 376-2003), SAS 1.1 (INCITS 417-2006) and SAS-2 (ANSI
303 INCITS 457-2010) . SAS-2.1 work was split into an electrical and physi‐
304 cal layers document (standardized as SAS-2.1 ANSI INCITS 478-2011) with
305 the upper level layers placed in a document called the SAS Protocol
306 Layer and it was standardized as SPL ANSI INCITS 476-2011. Next came
307 SPL-2 which was standardized as SPL-2 ANSI INCITS 505-2013. Then came
308 SPL-3 which was standardized as SPL-3 ANSI INCITS 492-2015. SPL-4 is
309 near standardization and its most recent draft is spl4r13.pdf while
310 SPL-5 work has started and its most recent draft is spl5r03.pdf. To
311 lessen confusion, the multiple generations of SAS will be referred to
312 in these man pages as SAS 1, 1.1, 2, 2.1 (SPL), 3 (SPL-2 and SPL-3), 4
313 (SPL-4) and 5 (SPL-5). Roughly speaking for the electrical and physi‐
314 cal layers standards SAS-1 runs at 3 Gbps, SAS-2 at 6 Gbps, SAS-3 at 12
315 Gbps and SAS-4 at 22.5 Gbps. Drafts, including those just prior to
316 standardization can be found at the http://www.t10.org site (e.g.
317 spl-r07.pdf and spl2r04c.pdf). INCITS policy now requires a registra‐
318 tion to view these drafts, a break from t10.org tradition.
319 The two utilities for reading and writing to GPIO registers,
321 smp_read_gpio and smp_write_gpio, are defined in the Small Form Factor
322 document SFF-8485 found at http://www.sffcommittee.com . "Enhanced"
323 versions of the corresponding SMP functions have been mentioned in some
324 drafts but no definitions have been published and the references have
325 been removed in more recent drafts.
326 In this section of each utility's man page is the first standard in
328 which the associated SMP function appeared and whether there have been
329 significant additions in later standards.
330 The COVERAGE file in the smp_utils source tarball shows a table of all
332 SMP function names defined in the drafts, the versions of those stan‐
333 dards in which those SMP functions first appeared and the corresponding
334 smp_utils utility names. A lot of extra SMP functions have been added
335 in SAS-2 associated with zoning.
336
338 Written by Douglas Gilbert.
339
341 Report bugs to <dgilbert at interlog dot com>.
342
344 Copyright © 2006-2020 Douglas Gilbert
345 This software is distributed under a FreeBSD license. There is NO war‐
346 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
347 POSE.
348
350 sg_logs, sg_vpd, sg_ses(sg3_utils); sdparm(sdparm); lsscsi(lsscsi)
351smp_utils-0.99 March 2020 SMP_UTILS(8)