SMP_DISCOVER_LIST(8)

💅 SMP_DISCOVER_LIST(8) — it's giving smp_utils, bestie

okay so. this is a page from the SMP_UTILS manual set (that's the family it lives in, section 8, system admin realness) and it's about the smp_discover_list utility. pull up a chair, we're going in. 🦋

---

✨ NAME ✨

smpl_discover_list — wait no, let me not do that. it's smp_discover_list, and it's the tool that invokes the DISCOVER LIST SMP function. that's the whole vibe of the name, no notes. 💅

---

🌸 SYNOPSIS 🌸

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

---

💖 DESCRIPTION 💖

so basically? this thing sends one or more SAS Serial Management Protocol (SMP) DISCOVER LIST function requests at an SMP target, and then decodes the responses or just hands them over raw. 🫶

the SMP target is identified by SMP_DEVICE and the SAS_ADDR. depending on the interface, the SAS_ADDR may be deduced from the SMP_DEVICE — like, it might already be in there, no need to repeat yourself. but the mpt interface is built different: it uses SMP_DEVICE to identify a HBA (that's an SMP initiator, periodt) and it needs the extra ,N to tell HBAs apart if you've got multiple of them hanging around. 👑

lowkey important: if you do not give the --phy=ID option, then --summary is just assumed. like, that's the default, bestie.

when --summary is given or assumed, this utility shows the disposition of each active expander phy in table form. one row per phy, and each row is described down in the SINGLE LINE PER PHY FORMAT section (yes it's below, keep scrolling 💀). and for this purpose, disabled expander phys and phys with errors still count as "active" — which is kind of a lot of energy tbh. you can suppress them from the output by adding the --brief option. ✨

the DISCOVER LIST response can hold up to 8 descriptors when the "descriptor type" field in the request is set to 0 (like, --descriptor=0). it can hold up to 40 descriptors when that same "descriptor type" field is set to 1 (e.g. --descriptor=1). and if you ask for more descriptors than fit, multiple DISCOVER LIST requests get made — --summary asks for 254, for instance — and that keeps happening as long as the previous response says more descriptors may be available. 🔥

also! rather than typing out options and SMP_DEVICE[,N] every single time like some kind of unpaid intern, some of them can be supplied via environment variables. the ENVIRONMENT VARIABLES section below has the tea. 🍓

---

🎀 OPTIONS 🎀

quick note before we go off: mandatory arguments to long options are mandatory for short options as well. no shortcuts, sorry not sorry. 🙈

• -A, --adn — makes the "attached device name" field get output when the --one or --summary option is also given. the SINGLE LINE PER PHY FORMAT section below spills the details. heads up tho: the "attached device name" field is not available in the short format (e.g. --descriptor=1). 😭
• -b, --brief — reduce the decoded response output. less yapping, more data. ✂️
• -c, --cap — decode and print the phy capabilities bits fields (see SNW-3 in draft, iykyk). every expander phy has three of these fields: programmed, current and attached. by default these fields are only printed out in hex, or not at all if --brief is given or implied. of the three, the attached phy capability field is probably the most interesting — that's the main character right there 👑. and if you also pass --verbose, the various "G" identifiers get expanded, so instead of "G4:" it prints "G4 (12 Gbps):". slay.
• -d, --descriptor=TY — sets the "descriptor type" field in the request. when TY is 0, the 120 byte response defined by the DISCOVER function response (minus its CRC field) gets placed in the descriptors of this function's response. when TY is 1, it's the short format (i.e. 24 byte per descriptor) information that goes in there instead. pick your fighter. ⭐
• -D, --dsn — outputs the device slot number at the end of each summary line. in summary mode, one line comes out per expander phy. it's output in the form "dsn=<val>" where <val> is decimal in the range from 0 to 254 inclusive. it is not output if it's not available, or if it has the value 255. the device slot number is not available in short format, so in summary mode with this option, if --descriptor=1 is not given, the longer format gets chosen instead. an expander typically contains a SES device, and that's what yields device slot numbers in its Additional Element Status diagnostic page. ✨
• -f, --filter=FI — sets the filter field in the request. when FI is 0 (default) it fetches descriptors for all phys. when FI is 1 it only fetches descriptors for phys attached to (other) expanders. when FI is 2 it only fetches descriptors for phys attached to expanders, SAS or SATA devices. and when FI is 1 or 2, expander phys that would yield "phy vacant" — which means they're hidden by zoning, sneaky — get filtered out. 🧚
• -h, --help — output the usage message, then exit. classic.
• -H, --hex — output the response (less the CRC field) in hexadecimal. 💜
• -i, --ignore — sets the Ignore Zone Group bit in the SMP Discover list request.
• -I, --interface=PARAMS — interface specific parameters. and just so we're clear, "interface" here means the path through the operating system to the SMP initiator. the smp_utils man page has more on that if you wanna go deeper. 🌈
• -n, --num=NUM — maximum number of descriptors to fetch. if any descriptors are in the response, the first phy id will be greater than or equal to the argument of --phy=ID. also, real talk: the maximum SMP frame size is 1032 bytes (including a trailing 4 byte CRC), which may limit how many descriptors a single DISCOVER LIST function can fetch — especially when you're doing '--descriptor=0'. 💀
• -o, --one — use one line (summarized) format for each descriptor in the response. the default action when this option is not given is to output multiple indented lines for each descriptor in the response. see the SINGLE LINE PER PHY FORMAT section below. 📏
• -p, --phy=ID — phy identifier. ID is a value between 0 and 254. this is the starting (lowest numbered) phy id to fetch in the response. and note — because of the filter field setting, the first phy id in the response may be greater than the argument you gave to this option. not me being surprised by that every time 😭
• -r, --raw — send the response (less the CRC field) to stdout in binary. all error messages go to stderr instead. clean separation, we love to see it. 🫶
• -s, --sa=SAS_ADDR — specifies the SAS address of the SMP target device. typically this is an expander. this option may not be needed if the SMP_DEVICE has the target's SAS address within it. the SAS_ADDR is in decimal, but most SAS addresses are shown in hexadecimal — so to give a number in hex, either prefix it with '0x' or put a trailing 'h' on it. pick your lil formatting moment. 💅
• -S, --summary — output a multi line summary, with one line per active phy. checks up to 254 phys starting at phy identifier ID (which defaults to 0). equivalent to '-o -d 1 -n 254 -b' unless the --adn option was also given, in which case it's equivalent to '-o -d 0 -n 254 -b'. see the SINGLE LINE PER PHY FORMAT section below. 👑
• -v, --verbose — increase the verbosity of the output. can be used multiple times. stack 'em, bestie. 📚
• -V, --version — print the version string and then exit. ⭐
• -Z, --zpi=FN — FN is a file that will be created or truncated and then have zone phy information written to it, in a format suitable for input to the smp_conf_zone_phy_info utility's --pconf=FN option. if --num=NUM is not given it is set to 254. the output will start from phy_id 0 unless --phy=ID is given. 🎀

---

🦋 SINGLE LINE PER PHY FORMAT 🦋

the --summary (or --one) option causes SMP DISCOVER LIST descriptors to be compressed down to one line per phy. and to save space, SAS addresses are shown in hex without a '0x' prefix or 'h' suffix. the header section outputs information found in the DISCOVER LIST response's header section.

for each descriptor in the DISCOVER LIST response, one line gets output starting with " phy <n>:" where <n> is the phy identifier — and yes, they are origin zero, because of course they are. 💀

after that comes the routing attribute, represented by a single letter:

• "D" — direct routing
• "S" — subtractive routing
• "T" or "U" — both of these imply table routing. the difference: if REPORT GENERAL indicates "table to table supported", then "U" is output to show that the phy can be part of an enclosure universal port; otherwise "T" is used.

next comes the negotiated physical link rate, which is either "disabled", "reset problem" or "spinup hold". other states get mapped to "attached". and that includes enabled phys with nothing connected, which show up as "attached:[0000000000000000:00]". iconic honestly. 🫠

information shown between the brackets is for the attached device. phys that are connected display something like "attached:[5000c50000520a2a:01 " where the first number is the attached SAS address (in hex) and the second number is the attached device's phy identifier. if the attached device type is other than an SAS or SATA device, then one of these abbreviations gets output instead:

• "exp" — for expander
• "fex" — for fanout expander
• "res" — for unknown attached device type

if a phy is flagged as "virtual" then the letter "V" appears next. next up are the protocols supported by the attached device, shown as "i(<list>)" for initiator protocols and/or "t(<list>)" for target protocols. the <list> is made up of "PORT_SEL", "SSP", "STP", "SMP" and "SATA", with "+" used as a separator. for example a SAS host adapter will most likely appear as "i(SSP+STP+SMP)". and that completes the info about the attached phy — hence the closing right bracket. 🎀

if appropriate, the negotiated physical link rate is shown in gigabits per second. here's an example of a line for expander phy identifier 11 connected to a SATA target (or SATA "device", to use the t13.org term):

  phy  11:T:attached:[500605b000000afb:00  t(SATA)]  1.5 Gbps

if the expander has zoning enabled (i.e. the REPORT GENERAL response bit for 'zoning enabled' is set) and a phy's zone group is other than zg 1, then the phy's zone group is shown — like "ZG:2". ✨

if the --adn option is given, then after the attached SAS address and the attached device's phy identifier are output, an extra field is inserted containing the "attached device name" field. for a SAS disk this should be its target device name (in NAA-5 format), and for a SATA disk it's its WWN (if provided, also in NAA-5 format). also, when --adn is given, the phy speed and zone group are not output — all in the name of keeping the line length reasonable. we respect the line length in this house. 📏

if the --dsn option is given and device slot number information is available for the current phy, then "dsn=<num>" is appended to the line. device slot numbers range from 0 to 254, with 255 meaning there is no corresponding slot — so it's not listed. 💅

🌸 ENVIRONMENT VARIABLES 🌸

okay bestie, so if you don't pass SMP_DEVICE[,N] yourself, the utils go looking for a lil backup plan — they check the SMP_UTILS_DEVICE environment variable, and if it's there, its contents get used instead. slay, delegation 💅

And if the SAS address (of the SMP target, obvs) isn't given but it's needed — like, it's not already implicit in SMP_DEVICE[,N] — then it peeks at the SMP_UTILS_SAS_ADDR environment variable, and if that's present its contents become your SAS address. SAS addresses are usually written in hex, marked by a leading 0x or a trailing h. ✨

Now, a device slot number (dsn) is super important for connecting the dots between an expander phy and a SES array element. Newer expanders (SAS-3 girlies, hi 💖) support dsn_s in the DISCOVER (and DISCOVER LIST) functions. If they're available, you can show them with the --dsn option on the smp_discover and smp_discover_list utilities. And because typing that option over and over is giving carpal tunnel, the SMP_UTILS_DSN environment variableriable — if present — has the exact same effect. 🫶

---

👑 NOTES 👑

In SAS-2 and later, both the DISCOVER and DISCOVER LIST functions are available. But like… DISCOVER LIST is the main character for several reasons, bestie:

• Its response can hold up to 40 descriptors, each one describing the state of one expander phy. 🌈
• The vast majority of expander chips on the market support 36 phys or less, so one single DISCOVER LIST response will summarize the states of all its phys. Iconic, no notes. 💅
• With the DISCOVER function? Only one expander phy's state comes back in its response. one. single. phy. 💀

Other advantages of the DISCOVER LIST function are its "phy filter" and "descriptor type" function request fields. lowkey the range on this function is unmatched.

---

📜 CONFORMING TO 📜

The SMP DISCOVER LIST function was introduced in SAS-2. After SAS-2, the protocol sections of SAS got split off into a whole other document series known as the SAS Protocol Layer (SPL), and it was standardized as SPL ANSI INCITS 476-2011. ✨

Then came SPL-2, standardized as SPL-2 ANSI INCITS 505-2013. Then came SPL-3, standardized as SPL-3 ANSI INCITS 492-2015. SPL-4 is near standardization and its most recent draft is spl4r13.pdf, while SPL-5 work has started and its most recent draft is spl5r03.pdf. the lore goes deep fr fr 📚

---

💖 AUTHORS 💖

Written by Douglas Gilbert. (we love a legend ✨)

---

🐛 REPORTING BUGS 🐛

Found a bug? Report it to <dgilbert at interlog dot com>. don't be shy bestie, they wanna know 🙈

---

🎀 COPYRIGHT 🎀

Copyright © 2006-2018 Douglas Gilbert

This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

no cap, that's the real legal text — no warranty, none, not even the merchantability kind 💀

---

🦋 SEE ALSO 🦋

• smp_utils
• smp_discover
• smp_phy_control
• smp_conf_zone_phy_info

---

okay that's the whole page bestie, you ate it 💅✨ this one's from smp_utils-0.99, dated February 2018, and it lives at SMP_DISCOVER_LIST(8) — go forth and list those phys, queen 👑🌸