SMP_DISCOVER(8)

💖 SMP_DISCOVER(8) — the smp_utils girlies' edition 💖

okay bestie, welcome to smp_discover from the smp_utils collection. this one's a whole vibe, let's get into it 🦋

---

✨ NAME ✨

smp_discover — invoke DISCOVER SMP function

like, it literally invokes the DISCOVER function. that's the whole job. iconic behavior honestly 👑

---

🌸 SYNOPSIS 🌸

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

---

💅 DESCRIPTION 💅

so what this does is send one or more SAS Serial Management Protocol (SMP) DISCOVER function requests over to an SMP target, then it either decodes the responses or just outputs them raw. your SMP target gets identified by the SMP_DEVICE and the SAS_ADDR. and depending on which interface you're using, the SAS_ADDR might just be deduced from the SMP_DEVICE all on its own, no extra work from you 🫶

the mpt interface uses SMP_DEVICE to identify a HBA (which is an SMP initiator, fyi) and it needs that extra ,N on the end to tell the difference between HBAs if there's more than one hanging around. multiple HBAs, one of them is not like the other 💀

now here's a thing to know: if you don't give the --phy=ID option, then --summary is just assumed. no cap. and when --summary is given or assumed, this utility shows you the disposition of every active expander phy in table form. one row per phy, and that's all described down in the SINGLE LINE PER PHY FORMAT section below, don't worry, we get there 📋

for this purpose, disabled expander phys and the ones with errors count as "active" — yeah, messy but that's the rules — and you can suppress those from the output by adding the --brief option. bye bestie 👋

and rather than typing out options and SMP_DEVICE[,N] every single time you invoke this thing (exhausting), some of them can come from environment variables instead. see ENVIRONMENT VARIABLES below, i got you ✨

---

🎀 OPTIONS 🎀

mandatory arguments to long options are mandatory for short options as well. periodt.

• -A, --adn — makes the "attached device name" field get output when the --multiple or --summary option is also given. go look at SINGLE LINE PER PHY FORMAT below. also heads up, the "attached device name" field was added in SAS-2, so it's giving newer-generation energy.
• -b, --brief — reduces the decoded response output. if you use it twice, it will exit if there's no attached device (after outputting that info first). when it's used with --multiple, unattached phys don't get listed at all; when used twice, it trims the attached phys output. double tap = extra aggressive 🫣
• -c, --cap — decodes and prints the phy capabilities bits fields (see SNW-3 in the 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 one ngl. and if --verbose is given, then the various "G" identifiers get expanded — so instead of "G4:" it prints "G4 (12 Gbps):". cute right? 💅
• -h, --help — outputs the usage message, then exits. the classic.
• -D, --dsn — outputs the device slot number at the end of each summary line. in summary mode it's one line per expander phy. it comes out in the form "dsn=<val>" where <val> is decimal and in the range from 0 to 254 inclusive. it is not output if it's not available or if it has the value 255. an expander typically contains a SES device which yields device slot numbers in its Additional Element Status diagnostic page, so that's where the numbers come from 🍓
• -H, --hex — outputs the response (less the CRC field) in hexadecimal.
• -i, --ignore — sets the Ignore Zone Group bit in the SMP Discover request. expander phys that are hidden by zoning will show up as "phy vacant" unless you give this option. sneaky zoning 🙈
• -I, --interface=PARAMS — interface specific parameters. in this case "interface" means the path through the operating system to the SMP initiator. go read the smp_utils man page for more, there's more.
• -l, --list — lists attributes in "name=value" form, one entry per line. very organized of it.
• -m, --multiple — loops over multiple phys within the SMP target (typically an expander) and does a DISCOVER request for each, outputting a one line summary. phy 0 gets queried first, then phy 1, and it keeps going until an error happens. the starting phy and the number of phys that get "discovered" can be controlled with --phy=ID and --num=NUM. if --brief is given then there's no output for phys that indicate there's no attached device. and when this option is used twice, you get multi-line output for each phy. glow up ✨ see SINGLE LINE PER PHY FORMAT below.
• -M, --my — outputs my (this expander's) SAS address in hex (prefixed by "0x"). this comes from the DISCOVER response of phy id 0 (unless --phy=ID is given). the expander's SAS address is typically available even if a phy isn't connected, or is "vacant", or disabled. this option overrides most other options (like, it overrides --multiple and --summary). main character option, honestly 👑
• -n, --num=NUM — the number of phys to fetch, starting at --phy=ID when the --multiple option is given. the default value is 0 which is interpreted as "the rest" — i.e. until a "phy does not exist" function result comes back. this option is ignored if --multiple isn't there. it simply does not care.
• -p, --phy=ID — phy identifier. ID is a value between 0 and 254. if this option isn't given, then --summary is assumed.
• -r, --raw — sends the response (less the CRC field) to stdout in binary. all error messages go to stderr. keep your streams separated bestie 🫶
• -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 already has the target's SAS address inside it. the SAS_ADDR is in decimal, but most SAS addresses get shown in hexadecimal, so to give a number in hex either prefix it with '0x' or slap a trailing 'h' on it.
• -S, --summary — outputs a multi line summary, with one line per active phy. it checks all phys (or fewer if --num=NUM is given), starting at phy 0 (unless --phy=ID is given). this is equivalent to '--multiple --brief' ('-mb'). see SINGLE LINE PER PHY FORMAT below. and if --phy=ID isn't given, this option is assumed. it's basically the default personality of this program 💖
• -v, --verbose — increases the verbosity of the output. can be used multiple times. stack it up.
• -V, --version — prints the version string and then exits.
• -z, --zero — zeroes the Allocated Response Length field in the request. this option also zeroes the Request Length field in the request. this is required for strict SAS-1.1 compliance. however, this option should not be given in SAS-2 and later; if you do give it, an abridged response may result. so like, only if you're on old SAS-1.1, okay? don't be reckless 🔥

---

🦋 SINGLE LINE PER PHY FORMAT 🦋

the --summary option makes SMP DISCOVER responses get compressed down into a header followed by one line per phy. to save space, SAS addresses are shown in hex with no '0x' prefix and no 'h' suffix. the header line gives you the SAS address of the SMP target itself, and it assumes that target is an expander.

every line starts with " phy <n>:" where <n> is the phy identifier (and yes, they're origin zero, so the counting starts at 0, as it should 😌).

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

• "D" for direct routing
• "S" for subtractive routing
• "T" or "U"

both "T" and "U" imply table routing — the difference is that if REPORT GENERAL indicates "table to table supported" then "U" is output to indicate that phy can be part of an enclosure universal port; otherwise "T" gets used. so basically "U" is the special case 🌈

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]". yes, an attached nothing. we've all been there 💀

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 anything other than a SAS or SATA device, then one of these abbreviations gets output:

• "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)". that completes the info about the attached phy, hence the closing right bracket 🫶

if appropriate, the negotiated physical link rate gets 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 anything other than zg 1, then that phy's zone group gets shown (e.g. "ZG:2"). zone group two, living its life ✨

if the --adn option is given, then after the attached SAS address and the attached device's phy identifier are output, an extra field gets 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 should be its WWN (if provided, also in NAA-5 format). also, when --adn is given, the phy speed and zone group are not output, in order to keep the line length reasonable. tradeoffs, bestie 💅

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

---

💜 ENVIRONMENT VARIABLES 💜

if SMP_DEVICE[,N] isn't given, then the SMP_UTILS_DEVICE environment variable gets checked, and if it's present, its contents are used instead. auto-fill, love that for us 🎀

if the SAS address (of the SMP target) isn't given and it's actually required (i.e. it isn't implicit in SMP_DEVICE[,N]), then the SMP_UTILS_SAS_ADDR environment variable gets checked, and if it's present its contents are used as the SAS address. SAS addresses are usually given in hex, indicated by a leading '0x' or a trailing 'h'.

a device slot number (dsn) is important for establishing the relationship between an expander phy and a SES array element. newer expanders (e.g. SAS-3) support dsn_s in the DISCOVER (and DISCOVER LIST) functions. these can be shown, if available, with the --dsn option to the smp_discover and smp_discover_list utilities. to ease typing that option all the time, the SMP_UTILS_DSN environment variable, if present, has the same effect. set it once, thank yourself later 🫶

💭 NOTES 💭

Okay so bestie, in SAS-2 and later, both the DISCOVER and DISCOVER LIST functions are available. But the DISCOVER LIST function should be favoured, and honestly? For several very good reasons. Its response can hold up to 40 descriptors, each one describing the state of one expander phy. And the vast majority of expander chips on the market support 36 phys or less, so one DISCOVER LIST response will summarize the states of all its phys. With the DISCOVER function, only one expander phy's state is returned in its response. Not the vibe we're going for. Other advantages of the DISCOVER LIST function are its "phy filter" and "descriptor type" function request fields. periodt.

---

🌸 EXAMPLES 🌸

See the "Examples" section in http://sg.danny.cz/sg/smp_utils.html. That's the whole thing, bestie. Go click, it's giving helpful. 💖

---

📜 CONFORMING TO 📜

The SMP DISCOVER function was introduced in SAS-1, with small additions in SAS-1.1. Then there were a large number of additions in SAS-2. After SAS-2, the protocol sections of SAS were split into another document series known as the SAS Protocol Layer (SPL), and it was standardized as SPL ANSI INCITS 476-2011. Next came SPL-2, which was standardized as SPL-2 ANSI INCITS 505-2013. Then came SPL-3, which was 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. Look at all those glow-ups. ✨

---

👑 AUTHORS 👑

Written by Douglas Gilbert. King behavior, no cap. 💅

---

🐛 REPORTING BUGS 🐛

Report bugs to <dgilbert at interlog dot com>. Please be nice, bestie. 🫶

---

©️ 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. Read that again. 😭

---

🔗 SEE ALSO 🔗

• smp_utils
• smp_discover_list
• smp_phy_control

---

This page came from smp_utils-0.99 back in February 2018, and it's the SMP_DISCOVER(8) manual. Stay slay, bestie. 💅✨