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

NAME

6       smp_discover_list - invoke DISCOVER LIST SMP function
7

SYNOPSIS

9       smp_discover_list  [--adn]  [--brief] [--cap] [--descriptor=TY] [--dsn]
10       [--filter=FI]   [--help]   [--hex]   [--ignore]    [--interface=PARAMS]
11       [--num=NUM]  [--one]  [--phy=ID]  [--raw]  [--sa=SAS_ADDR]  [--summary]
12       [--verbose] [--version] [--zpi=FN] SMP_DEVICE[,N]
13

DESCRIPTION

15       Sends one or more SAS Serial Management Protocol  (SMP)  DISCOVER  LIST
16       function  requests  to  an  SMP  target  and  decodes  or  outputs  the
17       responses. The SMP target is  identified  by  the  SMP_DEVICE  and  the
18       SAS_ADDR.  Depending on the interface, the SAS_ADDR may be deduced from
19       the SMP_DEVICE.  The mpt interface uses SMP_DEVICE to  identify  a  HBA
20       (an 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       The DISCOVER LIST response may contain up to  8  descriptors  when  the
32       "descriptor  type"  field  in  the request is set to 0 (e.g. --descrip‐
33       tor=0). The DISCOVER LIST response may contain  up  to  40  descriptors
34       when  the  "descriptor  type"  field  in  the request is set to 1 (e.g.
35       --descriptor=1). Multiple DISCOVER LIST requests will be made  if  more
36       descriptors  are requested (e.g. --summary requests 254) and the previ‐
37       ous response indicates that more descriptors may be available.
38
39       Rather than supply options and SMP_DEVICE[,N] on every invocation  some
40       can  be supplied via environment variables. See the section on ENVIRON‐
41       MENT VARIABLES below.
42

OPTIONS

44       Mandatory arguments to long options are mandatory for short options  as
45       well.
46
47       -A, --adn
48              causes  the  "attached  device name" field to be output when the
49              --one or --summary option is also given. See the  section  below
50              on  SINGLE  LINE PER PHY FORMAT. Note the "attached device name"
51              field is not available in  the  short  format  (e.g.  --descrip‐
52              tor=1).
53
54       -b, --brief
55              reduce the decoded response output.
56
57       -c, --cap
58              decode  and  print  phy  capabilities  bits fields (see SNW-3 in
59              draft). Each expander phy has three of these fields: programmed,
60              current  and attached.  By default these fields are only printed
61              out in hex, or not at all if the  --brief  option  is  given  or
62              implied. Of the three the attached phy capability field is prob‐
63              ably the most interesting. If the  --verbose  option  is  given,
64              then  the  various "G" identifiers are expanded (e.g. instead of
65              "G4:" it prints "G4 (12 Gbps):").
66
67       -d, --descriptor=TY
68              set the "descriptor type" field in the request.  When  TY  is  0
69              then  the  120  byte  response  defined by the DISCOVER function
70              response (less its CRC field) is placed in  the  descriptors  of
71              this function's response. When TY is 1 the short format (i.e. 24
72              byte per descriptor) information is placed in the descriptors of
73              this function's response.
74
75       -D, --dsn
76              outputs  the device slot number at the end of each summary line.
77              In summary mode one line is output per expander phy. It is  out‐
78              put  in the form "dsn=<val>" where <val> is decimal in the range
79              from 0 to 254 inclusive.  It is not output if it is  not  avail‐
80              able  or has the value 255. The device slot number is not avail‐
81              able in short format, so with this option in  summary  mode,  if
82              the  --descriptor=1 is not given, then the longer format is cho‐
83              sen. An expander typically contains a SES  device  which  yields
84              device  slot numbers in its Additional Element Status diagnostic
85              page.
86
87       -f, --filter=FI
88              set the filter field in the request.  When  FI  is  0  (default)
89              fetch descriptors for all phys. When FI is 1 only fetch descrip‐
90              tors for phys attached to (other) expanders. When FI is  2  only
91              fetch  descriptors  for  phys attached to expanders, SAS or SATA
92              devices. When FI is 1 or 2, expander phys that would yield  "phy
93              vacant" (indicating they are hidden by zoning) are filtered out.
94
95       -h, --help
96              output the usage message then exit.
97
98       -H, --hex
99              output the response (less the CRC field) in hexadecimal.
100
101       -i, --ignore
102              sets the Ignore Zone Group bit in the SMP Discover list request.
103
104       -I, --interface=PARAMS
105              interface  specific  parameters. In this case "interface" refers
106              to the path through the operating system to the  SMP  initiator.
107              See the smp_utils man page for more information.
108
109       -n, --num=NUM
110              maximum  number  of descriptors fetch. If any descriptors are in
111              the response the first phy id will be greater than or  equal  to
112              the  argument  of  --phy=ID. Note that maximum SMP frame size is
113              1032 bytes (including a trailing 4 byte CRC) which may limit the
114              number  of  descriptors that can be fetched by a single DISCOVER
115              LIST function (especially when '--descriptor=0').
116
117       -o, --one
118              use one line (summarized) format  for  each  descriptor  in  the
119              response.   The  default action when this option is not given is
120              to output multiple indented lines for  each  descriptor  in  the
121              response. See the section below on SINGLE LINE PER PHY FORMAT.
122
123       -p, --phy=ID
124              phy  identifier.  ID  is a value between 0 and 254.  This is the
125              starting (lowest numbered) phy id  to  fetch  in  the  response.
126              Note  that  due to the filter field setting, the first phy id in
127              the response may be greater than the argument to this option.
128
129       -r, --raw
130              send the response (less the CRC field) to stdout in binary.  All
131              error messages are sent to stderr.
132
133       -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 within it. The SAS_ADDR
137              is in decimal but most SAS addresses are shown  in  hexadecimal.
138              To  give  a  number in hexadecimal either prefix it with '0x' or
139              put a trailing 'h' on it.
140
141       -S, --summary
142              output a multi line summary,  with  one  line  per  active  phy.
143              Checks  up  to  254  phys  starting  at phy identifier ID (which
144              defaults to 0).  Equivalent to '-o -d 1 -n 254  -b'  unless  the
145              --adn  option  was also given, in which case it is equivalent to
146              '-o -d 0 -n 254 -b' . See the section below on SINGLE  LINE  PER
147              PHY FORMAT.
148
149       -v, --verbose
150              increase  the  verbosity  of  the  output.  Can be used multiple
151              times.
152
153       -V, --version
154              print the version string and then exit.
155
156       -Z, --zpi=FN
157              FN is a file that will be created or truncated  then  have  zone
158              phy  information written to it in a format suitable for input to
159              the  smp_conf_zone_phy_info  utility's  --pconf=FN  option.   If
160              --num=NUM  is  not given it is set to 254. The output will start
161              from phy_id 0 unless --phy=ID is given.
162

SINGLE LINE PER PHY FORMAT

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

ENVIRONMENT VARIABLES

223       If SMP_DEVICE[,N] is not given then  the  SMP_UTILS_DEVICE  environment
224       variable is checked and if present its contents are used instead.
225
226       If  the SAS address (of the SMP target) is not given and it is required
227       (i.e.    it   is   not   implicit   in   SMP_DEVICE[,N])    then    the
228       SMP_UTILS_SAS_ADDR  environment  variable is checked and if present its
229       contents are used as the SAS address. SAS addresses are  usually  given
230       in hex indicated by a leading '0x' or trailing 'h'.
231
232       A  device slot number (dsn) is important for establishing the relation‐
233       ship between an expander phy and a SES array element.  Newer  expanders
234       (e.g.  SAS-3)  support  dsn_s in the DISCOVER (and DISCOVER LIST) func‐
235       tions. These can be shown, if  available,  with  the  --dsn  option  to
236       smp_discover  and  smp_discover_list  utilities..  To  ease typing that
237       option often, the SMP_UTILS_DSN environment variableriable, if present,
238       has the same effect.
239

NOTES

241       In  SAS-2  and  later both the DISCOVER and DISCOVER LIST functions are
242       available. The DISCOVER LIST function should be  favoured  for  several
243       reasons: its response can hold up to 40 descriptors each describing the
244       state of one expander phy. The vast majority of expander chips  on  the
245       market  support 36 phys or less so one DISCOVER LIST response will sum‐
246       marize the states of all its phys. With the DISCOVER function only  one
247       expander  phy's  state is returned in its response. Other advantages of
248       the DISCOVER LIST function are its "phy filter" and  "descriptor  type"
249       function request fields.
250

CONFORMING TO

252       The  SMP  DISCOVER  LIST function was introduced in SAS-2 . After SAS-2
253       the protocol sections of SAS were split into  another  document  series
254       known  as  the  SAS Protocol Layer (SPL) and it was standardized as SPL
255       ANSI INCITS 476-2011. Next came SPL-2 which was standardized  as  SPL-2
256       ANSI  INCITS 505-2013.  Then came SPL-3 which was standardized as SPL-3
257       ANSI INCITS 492-2015. SPL-4 is near standardization and its most recent
258       draft  is  spl4r13.pdf while SPL-5 work has started and its most recent
259       draft is spl5r03.pdf.
260

AUTHORS

262       Written by Douglas Gilbert.
263

REPORTING BUGS

265       Report bugs to <dgilbert at interlog dot com>.
266
268       Copyright © 2006-2018 Douglas Gilbert
269       This software is distributed under a FreeBSD license. There is NO  war‐
270       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
271       POSE.
272

SEE ALSO

274       smp_utils, smp_discover, smp_phy_control, smp_conf_zone_phy_info
275
276
277
278smp_utils-0.99                   February 2018            SMP_DISCOVER_LIST(8)
Impressum