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