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

NAME

6       smp_discover - invoke DISCOVER SMP function
7

SYNOPSIS

9       smp_discover   [--adn]   [--brief]  [--cap]  [--dsn]  [--help]  [--hex]
10       [--ignore]   [--interface=PARAMS]    [--list]    [--multiple]    [--my]
11       [--num=NUM]  [--phy=ID] [--raw] [--sa=SAS_ADDR] [--summary] [--verbose]
12       [--version] [--zero] SMP_DEVICE[,N]
13

DESCRIPTION

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
23       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
31       Rather than supply options and SMP_DEVICE[,N] on every invocation  some
32       can  be supplied via environment variables. See the section on ENVIRON‐
33       MENT VARIABLES below.
34

OPTIONS

36       Mandatory arguments to long options are mandatory for short options  as
37       well.
38
39       -A, --adn
40              causes  the  "attached  device name" field to be output when the
41              --multiple or --summary option is also given.  See  the  section
42              below  on  SINGLE LINE PER PHY FORMAT. Note the "attached device
43              name" field was added is SAS-2.
44
45       -b, --brief
46              reduce the decoded response output. If used twice will  exit  if
47              there  is  no attached device (after outputting that). When used
48              with --multiple, unattached  phys  are  not  listed;  when  used
49              twice, trims attached phys output.
50
51       -c, --cap
52              decode  and  print  phy  capabilities  bits fields (see SNW-3 in
53              draft). Each expander phy has three of these fields: programmed,
54              current  and attached.  By default these fields are only printed
55              out in hex, or not at all if the  --brief  option  is  given  or
56              implied. Of the three the attached phy capability field is prob‐
57              ably the most interesting. If the  --verbose  option  is  given,
58              then  the  various "G" identifiers are expanded (e.g. instead of
59              "G4:" it prints "G4 (12 Gbps):").
60
61       -h, --help
62              output the usage message then exit.
63
64       -D, --dsn
65              outputs the device slot number at the end of each summary  line.
66              In  summary mode one line is output per expander phy. It is out‐
67              put in the form "dsn=<val>" where <val> is decimal in the  range
68              from  0  to 254 inclusive.  It is not output if it is not avail‐
69              able or has the value 255. An expander typically contains a  SES
70              device  which  yields device slot numbers in its Additional Ele‐
71              ment Status diagnostic page.
72
73       -H, --hex
74              output the response (less the CRC field) in hexadecimal.
75
76       -i, --ignore
77              sets the Ignore Zone Group bit  in  the  SMP  Discover  request.
78              Expander  phys  hidden  by  zoning  will  appear as "phy vacant"
79              unless this option is given.
80
81       -I, --interface=PARAMS
82              interface specific parameters. In this case  "interface"  refers
83              to  the  path through the operating system to the SMP initiator.
84              See the smp_utils man page for more information.
85
86       -l, --list
87              list attributes in "name=value" form, one entry per line.
88
89       -m, --multiple
90              loops  over  multiple  phys  within  SMP  target  (typically  an
91              expander)  and  does  a  DISCOVER request and outputs a one line
92              summary. Phy 0 is queried first, then phy 1, continuing until an
93              error  occurs.  The starting phy and the number of phys "discov‐
94              ered" can be controlled by --phy=ID and --num=NUM. If --brief is
95              given then there is no output for phys that indicate there is no
96              attached device. When this option is used twice then  multi-line
97              output is produced for each phy. See the section below on SINGLE
98              LINE PER PHY FORMAT.
99
100       -M, --my
101              outputs my (this expander's) SAS address  in  hex  (prefixed  by
102              "0x").  This  is obtained from the DISCOVER response of phy id 0
103              (unless --phy=ID is given). The expander's SAS address is  typi‐
104              cally available even if a phy is not connected, "vacant" or dis‐
105              abled. This option overrides most other options (e.g.  overrides
106              --multiple and --summary options).
107
108       -n, --num=NUM
109              number  of phys to fetch, starting at --phy=ID when the --multi‐
110              ple option is given. The default value is 0 which is interpreted
111              as "the rest" (i.e. until a "phy does not exist" function result
112              is received). This option is  ignored  in  the  absence  of  the
113              --multiple option.
114
115       -p, --phy=ID
116              phy  identifier. ID is a value between 0 and 254. If this option
117              is not given then the --summary option is assumed.
118
119       -r, --raw
120              send the response (less the CRC field) to stdout in binary.  All
121              error messages are sent to stderr.
122
123       -s, --sa=SAS_ADDR
124              specifies  the  SAS  address of the SMP target device. Typically
125              this is an expander. This  option  may  not  be  needed  if  the
126              SMP_DEVICE  has the target's SAS address within it. The SAS_ADDR
127              is in decimal but most SAS addresses are shown  in  hexadecimal.
128              To  give  a  number in hexadecimal either prefix it with '0x' or
129              put a trailing 'h' on it.
130
131       -S, --summary
132              output a multi line summary,  with  one  line  per  active  phy.
133              Checks all phys (or less is --num=NUM is given), starting at phy
134              0 (unless --phy=ID is given). Equivalent to '--multiple --brief'
135              ('-mb').   See  the section below on SINGLE LINE PER PHY FORMAT.
136              If the --phy=ID is not given then this option is assumed.
137
138       -v, --verbose
139              increase the verbosity of the output. Can be used multiple times
140
141       -V, --version
142              print the version string and then exit.
143
144       -z, --zero
145              zero the Allocated Response Length field in  the  request.  This
146              option  also zeros the Request Length field in the request. This
147              is required for strict SAS-1.1 compliance. However  this  option
148              should  not  be  given  in  SAS-2  and  later; if it is given an
149              abridged response may result.
150

SINGLE LINE PER PHY FORMAT

152       The --summary option causes SMP DISCOVER responses to be compressed  to
153       a  header followed by one line per phy. To save space SAS addresses are
154       shown in hex without a '0x' prefix or 'h' suffix. The header line gives
155       the SAS address of the SMP target itself and assumes it is an expander.
156
157       Each  line  starts  with  "  phy  <n>:" where <n> is the phy identifier
158       (and they are origin zero). That is followed by the  routing  attribute
159       represented  by a single letter which is either "D" for direct routing,
160       "S" for subtractive routing, "T" or "U". Both "T" and "U"  imply  table
161       routing,  the  difference is that if REPORT GENERAL indicates "table to
162       table supported" then "U" is output to indicate that phy can be part of
163       an  enclosure  universal  port;  otherwise  "T" is used. Next comes the
164       negotiated physical link rate which is either "disabled", "reset  prob‐
165       lem"  or  "spinup  hold".  Other  states are mapped to "attached". This
166       includes  enabled  phys  with  nothing  connected   which   appear   as
167       "attached:[0000000000000000:00]".
168
169       Information  shown  between  the  brackets  is for the attached device.
170       Phys     that     are     connected     display     something     like:
171       "attached:[5000c50000520a2a:01 " where the first number is the attached
172       SAS address (in hex) and the second number is the attached device's phy
173       identifier.  If  the  attached  device type is other than a SAS or SATA
174       device then one of these abbreviations is output: "exp" (for expander),
175       "fex"  (for  fanout  expander)  or  "res"  (for unknown attached device
176       type). If a phy is flagged as "virtual" then  the  letter  "V"  appears
177       next. Next are the protocols supported by the attached device which are
178       shown as "i(<list>)" for initiator  protocols  and/or  "t(<list>)"  for
179       target  protocols.  The  <list> is made up of "PORT_SEL", "SSP", "STP",
180       "SMP" and "SATA" with "+" used as a separator. For example a  SAS  host
181       adapter  will  most  likely appear as: "i(SSP+STP+SMP)". This completes
182       the information  about  the  attached  phy,  hence  the  closing  right
183       bracket.
184
185       If  appropriate, the negotiated physical link rate is shown in gigabits
186       per second. Here is an example of a line for expander phy identifier 11
187       connected to a SATA target (or SATA "device" to use the t13.org term):
188
189         phy  11:T:attached:[500605b000000afb:00  t(SATA)]  1.5 Gbps
190
191       If  the  expander  has zoning enabled (i.e. REPORT GENERAL response bit
192       for 'zoning enabled' is set) and a phy's zone group is other than zg  1
193       then the phy's zone group is shown (e.g. "ZG:2").
194
195       If  the  --adn  option is given then after the attached SAS address and
196       the attached device's phy identifier  are  output  an  extra  field  is
197       inserted  containing  the  "attached device name" field. For a SAS disk
198       this should be its target device name (in NAA-5 format) and for a  SATA
199       disk  its  WWN (if provided, also in NAA-5 format). Also when the --adn
200       option is given the phy speed and zone group are not output in order to
201       keep the line length reasonable.
202
203       If  the  --dsn  option  is  given and device slot number information is
204       available for the current phy, then  "dsn=<num>"  is  appended  to  the
205       line.   Device  slot numbers range from 0 to 254 with 255 meaning there
206       is no corresponding slot so it is not listed.
207

ENVIRONMENT VARIABLES

209       If SMP_DEVICE[,N] is not given then  the  SMP_UTILS_DEVICE  environment
210       variable is checked and if present its contents are used instead.
211
212       If  the SAS address (of the SMP target) is not given and it is required
213       (i.e.    it   is   not   implicit   in   SMP_DEVICE[,N])    then    the
214       SMP_UTILS_SAS_ADDR  environment  variable is checked and if present its
215       contents are used as the SAS address. SAS addresses are  usually  given
216       in hex indicated by a leading '0x' or trailing 'h'.
217
218       A  device slot number (dsn) is important for establishing the relation‐
219       ship between an expander phy and a SES array element.  Newer  expanders
220       (e.g.  SAS-3)  support  dsn_s in the DISCOVER (and DISCOVER LIST) func‐
221       tions. These can be shown, if  available,  with  the  --dsn  option  to
222       smp_discover  and  smp_discover_list  utilities..  To  ease typing that
223       option often, the SMP_UTILS_DSN environment variableriable, if present,
224       has the same effect.
225

NOTES

227       In  SAS-2  and  later both the DISCOVER and DISCOVER LIST functions are
228       available. The DISCOVER LIST function should be  favoured  for  several
229       reasons: its response can hold up to 40 descriptors each describing the
230       state of one expander phy. The vast majority of expander chips  on  the
231       market  support 36 phys or less so one DISCOVER LIST response will sum‐
232       marize the states of all its phys. With the DISCOVER function only  one
233       expander  phy's  state is returned in its response. Other advantages of
234       the DISCOVER LIST function are its "phy filter" and  "descriptor  type"
235       function request fields.
236

EXAMPLES

238       See "Examples" section in http://sg.danny.cz/sg/smp_utils.html
239

CONFORMING TO

241       The SMP DISCOVER function was introduced in SAS-1, with small additions
242       in SAS-1.1 . There were a large number of additions in  SAS-2  .  After
243       SAS-2  the  protocol  sections  of SAS were split into another document
244       series known as the SAS Protocol Layer (SPL) and it was standardized as
245       SPL  ANSI  INCITS  476-2011.  Next came SPL-2 which was standardized as
246       SPL-2 ANSI INCITS 505-2013.  Then came SPL-3 which was standardized  as
247       SPL-3  ANSI INCITS 492-2015. SPL-4 is near standardization and its most
248       recent draft is spl4r13.pdf while SPL-5 work has started and  its  most
249       recent draft is spl5r03.pdf.
250

AUTHORS

252       Written by Douglas Gilbert.
253

REPORTING BUGS

255       Report bugs to <dgilbert at interlog dot com>.
256
258       Copyright © 2006-2018 Douglas Gilbert
259       This  software is distributed under a FreeBSD license. There is NO war‐
260       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR‐
261       POSE.
262

SEE ALSO

264       smp_utils, smp_discover_list, smp_phy_control
265
266
267
268smp_utils-0.99                   February 2018                 SMP_DISCOVER(8)
Impressum