1SMP_UTILS(8)                       SMP_UTILS                      SMP_UTILS(8)
2
3
4

NAME

6       smp_* - invoke a SAS Serial Management Protocol (SMP) function
7

SYNOPSIS

9       smp_*  [--expected=EX]  [--help]  [--hex]  [--interface=PARAMS] [--raw]
10       [--sa=SAS_ADDR] [--verbose] [--version] SMP_DEVICE[,N]
11

DESCRIPTION

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
22       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
29       If SMP_DEVICE[,N] is not given then the value in the environment  vari‐
30       able SMP_UTILS_DEVICE is used.
31
32       This  package  was  originally written for Linux and has been ported to
33       FreeBSD and Solaris.
34

LINUX INTERFACE

36       Currently there are multiple interfaces that allow SMP functions to  be
37       passed through to an SMP target.
38
39       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
43       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
46       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
50       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
66       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
82       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

FREEBSD INTERFACE

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
107         # smp_discover /dev/ses0
108
109       where /dev/ses0 is a SES device associated with a SAS expander.
110

SOLARIS INTERFACE

112       The USMP pass-through mechanism is used. Invocations look like this:
113
114         # smp_rep_manufacturer /dev/smp/expd0
115

ENVIRONMENT VARIABLES

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
121       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
127       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
135       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

COMMON OPTIONS

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
145       -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
156       -h, --help
157              output the usage message for the utility then exit.
158
159       -H, --hex
160              output the response in hexadecimal. This does  not  include  the
161              trailing CRC field.
162
163       -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
175       -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
179       -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
189       -v, --verbose
190              increase the verbosity of  the  output.  Can  be  used  multiple
191              times.
192
193       -V, --version
194              print the version string and then exit.
195

EXIT STATUS

197       To  aid  scripts  that  call these utilities, the exit status is set to
198       indicate success (0) or failure (1 or more):
199
200       0      success
201
202       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
210       91     syntax error. Either illegal options, options with bad arguments
211              or a combination of options that is not permitted.
212
213       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
218       93     the utility has a resource  problem.  Typically  this  means  an
219              attempt to allocate memory (ram) has failed.
220
221       97     the response to an SMP function failed sanity checks.
222
223       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
227       126    the  utility  was  found  but  could not be executed. That might
228              occur if the executable does not have execute permissions.
229
230       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
235       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
242       255    the utility tried to yield an exit status of 255 or larger. That
243              should not happen; given here for completeness.
244

NOTES

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
251       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
255         # find /sys -name "*expander*"
256
257       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
262       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
267         # sg_logs --page=18h /dev/sdb
268
269       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
277       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
283       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

EXAMPLES

298       See "Examples" section in http://sg.danny.cz/sg/smp_utils.html .
299

CONFORMING TO

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
320       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
327       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
331       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

AUTHORS

338       Written by Douglas Gilbert.
339

REPORTING BUGS

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

SEE ALSO

350       sg_logs, sg_vpd, sg_ses(sg3_utils); sdparm(sdparm); lsscsi(lsscsi)
351
352
353
354smp_utils-0.99                    March 2020                      SMP_UTILS(8)
Impressum