1SMP_UTILS(8) SMP_UTILS SMP_UTILS(8)
2
6 smp_* - invoke a Serial Attached SCSI Management (SMP) function
7
9 smp_* [--expected=EX] [--help] [--hex] [--interface=PARAMS] [--raw]
10 [--sa=SAS_ADDR] [--verbose] [--version] SMP_DEVICE[,N]
11
13 smp_utils is a package of utilities. Each utility sends a Serial
14 Attached SCSI (SAS) Management Protocol (SMP) request to a SMP_DEVICE
15 (a SMP target). If an error occurs then an error message is sent to
16 stderr. If no error occurs, the response is decoded (the default), out‐
17 put in ASCII hex (when --hex is given) or output in binary to stdout
18 (when --raw is given).
19 If SMP_DEVICE[,N] is not given then the value in the environment vari‐
21 able SMP_UTILS_DEVICE is used.
22
24 Currently there are multiple interfaces that allow SMP functions to be
25 passed through to a SMP target.
26 One method is to have a SMP_DEVICE which is actually the SMP initiator
28 (e.g. '/dev/mptctl,0'). In this case the SMP target's SAS address must
29 be supplied with --sa=SAS_ADDR.
30 Another method is to have a SMP_DEVICE which represents the SMP target.
32 In this case no SAS_ADDRESS needs to be given (since it is implicit).
33 This method may be simpler but it has some limitations (e.g. it assumes
34 the SMP target has already been discovered which may not be the case
35 for the initial discovery process).
36 Each utility in smp_utils attempts to work out which interface it has
38 been given by examining the SMP_DEVICE file. There are three interfaces
39 supported currently:
40 mpt This specifies the MPT fusion SAS pass-through which uses the
42 '/dev/mptctl' or '/dev/mpt2ctl' device node. If mpt drivers are
43 loaded but '/dev/mptctl' or '/dev/mpt2ctl' are not present then
44 a 'modprobe mptctl' command may be needed in Linux. If there are
45 multiple mpt fusion controllers (HBAs) in the computer, then the
46 user will need to specify which one to use with the syntax:
47 '/dev/mptctl,<n>' where <n> is the "ioc_num". This number can be
48 found in the log where the mptsas driver is registered. In Linux
49 it can be found in '/proc/scsi/mptsas/<host_no>' in the 2.4
50 series and additionally in
51 '/sys/class/scsi_host/host<n>/unique_id' in the 2.6 series. When
52 this interface is used the --sa=SAS_ADDR option must be given to
53 specify the SAS address of the SMP target. When the mptctl
54 driver is loaded in Linux there should be a character device
55 node at '/dev/mptctl' with major 10 and minor 220. Alternatively
56 there may be a character device node at '/dev/mpt2ctl' with
57 major 10 and minor 221.
58 sgv4 (sg)
60 This interface is more generic and supported in the linux 2.6.24
61 kernel and beyond. The SMP functions are passed to the kernel
62 using a format known as "SCSI Generic Version 4" which gives
63 this interface its name: "sgv4" or just "sg". The SAS transport
64 layer within the SCSI sub-system unpacks the SMP requests and
65 forwards them to SAS low level drivers that support this inter‐
66 face. The SMP_DEVICE is either a member of the '/sys/class/bsg'
67 directory or a device node made by the bsg driver. Such device
68 nodes are dynamic (i.e. they don't have a fixed major number)
69 and should correspond to the major and minor numbers found in
70 the 'sys/class/bsg/<smp_target_device>/dev' file.
71 tpl (ai)
73 This interface is currently used by one adaptec 94xx driver. The
74 "device" name will usually be "smp_portal" and it will be found
75 within the sysfs file system (typically mounted under "/sys").
76 The target SMP SAS address is implicit (as is the SMP initia‐
77 tor). Either 'tpl' or 'ai' can be used to specify this inter‐
78 face.
79
81 If the device name is not given then the SMP_UTILS_DEVICE environment
82 variable is checked and if present its contents are used as the device
83 name.
84 If the SAS address (of the SMP target) is not given and it is required
86 (i.e. it is not implicit in the device name) then the
87 SMP_UTILS_SAS_ADDR environment variable is checked and if present its
88 contents are used as the SAS address. SAS addresses are usually given
89 in hex indicated by a leading '0x' or trailing 'h'.
90 In both cases command line options override the corresponding environ‐
92 ment variable.
93
95 Mandatory arguments to long options are mandatory for short options as
96 well. If an option takes a numeric argument then that argument is
97 assumed to be decimal unless otherwise indicated (e.g. with a leading
98 "0x" or a trailing "h").
99 -E, --expected=EX
101 revision 4a of the SAS-2 draft introduced an 'expected expander
102 change count' field in some SMP requests. The idea is to detect
103 other SMP initiators trying to change the state of an expander.
104 The value EX is from 0 to 65535 inclusive with 0 being the
105 default value. When EX is greater than zero then if the value
106 doesn't match the expander change count of the SMP target (i.e.
107 the expander) when the request arrives then the target ignores
108 the request and sets a function result of "invalid expander
109 change count" in the response.
110 -h, --help
112 output the usage message for the utility then exit.
113 -H, --hex
115 output the response in hexadecimal.
116 -I, --interface=PARAMS
118 interface specific parameters. This option is usually not needed
119 since the interface type is guessed by a utility based on the
120 characteristics of the given SMP_DEVICE argument or what is in
121 the corresponding environment variables. PARAMS is of the form:
122 INTF[,force]. If the guess doesn't work then the interface can
123 be specified by giving a INTF of either 'mpt', 'sgv4' or 'tpl' (
124 with 'ai' being a synonym for 'tpl'). Sanity checks are still
125 performed and a utility may refuse if it doesn't agree with the
126 given INTF. If the user is really sure then adding a ',force'
127 will force the utility to use the given interface.
128 -r, --raw
130 send the response to stdout in binary. All error messages are
131 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 associated with it. The
137 SAS_ADDR is in decimal but most SAS addresses are shown in hexa‐
138 decimal. To give a number in hexadecimal either prefix it with
139 '0x' or put a trailing 'h' on it. If this option is not given
140 then the value in the environment variable SMP_UTILS_SAS_ADDR is
141 used.
142 -v, --verbose
144 increase the verbosity of the output. Can be used multiple
145 times.
146 -V, --version
148 print the version string and then exit.
149
151 To aid scripts that call these utilities, the exit status is set to
152 indicate success (0) or failure (1 or more):
153 0 success
155 1 - 63 reserved for SMP function result codes. See SAS draft or stan‐
157 dard, application layer, management application layer, SMP func‐
158 tions. Here are some common function result codes: 1 [unknown
159 SMP function], 2 [SMP function failed], 16 [phy does not exist],
160 17 [index does not exist], 18 [phy does not support SATA] and 19
161 [unknown phy operation].
162 91 syntax error. Either illegal options, options with bad arguments
164 or a combination of options that is not permitted.
165 92 the utility is unable to open, close or use the given
167 SMP_DEVICE. The given file name could be incorrect or there may
168 be permission problems. Adding the --verbose option may give
169 more information.
170 97 the response to a SMP function failed sanity checks.
172 99 any error that can't be categorized into values 1 to 97 may
174 yield this value. This includes transport and operating system
175 errors.
176
178 Finding the SAS address of an expander can be a challenge in some envi‐
179 ronments. An enclosure containing one or more expanders may have the
180 expander SAS address(es) printed on the back of the device, a bit like
181 ethernet MAC addresses.
182 In the Linux 2.6 kernel series the expander SAS address may well be in
184 the sysfs tree but it is not always easy to find. Doing this search may
185 help:
186 # find /sys -name "sas_device:expander*"
188 Then change directory to any path found and call 'cat sas_address'
190 Another approach is to work backwards from SCSI devices (i.e. logical
192 units). The protocol specific port log page (log page 18h) contains
193 fields for the "attached SAS address". sg_logs from the sg3_utils pack‐
194 age could be used like this:
195 # sg_logs --page=18h /dev/sdb
197 Any given "attached SAS address" is either a HBA, an expander or 0
199 indicating that port is not connected.
200
202 To date SAS has three generations. The first two generations are
203 approved standards: the original SAS (SAS ANSI INCITS 376-2003) and SAS
204 1.1 (INCITS 417-2006). SAS-2 technical work is ongoing and at the time
205 of writing the most recent draft is sas2r15.pdf (see section 10.4.3 for
206 SMP functions). To avoid confusion, the three generations of SAS will
207 be referred to in these man pages as SAS 1, 1.1 and 2 . Drafts, includ‐
208 ing those just prior to standardization can be found at the
209 http://www.t10.org site.
210 The two utilities for reading and writing to GPIO registers,
212 smp_read_gpio and smp_write_gpio, are defined in the Small Form Factor
213 document SFF-8485 found at http://www.sffcommittee.com .
214 In this section of each utility's man page is the first standard in
216 which the associated SMP function appeared and whether there have been
217 significant additions in later standards.
218 The COVERAGE file in the smp_utils source tarball shows the mapping
220 between all SMP function names defined in the standards, the versions
221 of those standards in which those SMP functions are defined and the
222 corresponding smp_utils utility names. A lot of extra SMP functions
223 have been added in SAS-2 and many do not have corresponding utilities
224 at this time.
225
227 Written by Douglas Gilbert.
228
230 Report bugs to <dgilbert at interlog dot com>.
231
233 Copyright © 2006-2008 Douglas Gilbert
234 This software is distributed under a FreeBSD license. There is NO war‐
235 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
236 POSE.
237
239 smp_conf_general, smp_conf_route_info, smp_discover, smp_discover_list,
240 smp_phy_control, smp_phy_test, smp_read_gpio, smp_rep_exp_route_tbl,
241 smp_rep_general, smp_rep_manufacturer, smp_rep_phy_err_log,
242 smp_rep_phy_sata, smp_rep_route_info, smp_write_gpio,
243 sg_logs(sg3_utils)
244smp_utils-0.94 December 2008 SMP_UTILS(8)