.TH SMP_DISCOVER "8" "May 2011" "smp_utils\-0.96" SMP_UTILS .SH NAME smp_discover \- invoke DISCOVER SMP function .SH SYNOPSIS .B smp_discover [\fI\-\-adn\fR] [\fI\-\-brief\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-ignore\fR] [\fI\-\-interface=PARAMS\fR] [\fI\-\-list\fR] [\fI\-\-multiple\fR] [\fI\-\-my\fR] [\fI\-\-num=NUM\fR] [\fI\-\-phy=ID\fR] [\fI\-\-raw\fR] [\fI\-\-sa=SAS_ADDR\fR] [\fI\-\-summary\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] [\fI\-\-zero\fR] \fISMP_DEVICE[,N]\fR .SH DESCRIPTION .\" Add any additional description here .PP Sends one or more SAS Management Protocol (SMP) DISCOVER function requests to a SMP target and decodes or outputs the responses. The SMP target is identified by the \fISMP_DEVICE\fR and the \fISAS_ADDR\fR. Depending on the interface, the \fISAS_ADDR\fR may be deduced from the \fISMP_DEVICE\fR. The mpt interface uses \fISMP_DEVICE\fR to identify a HBA (an SMP initiator) and needs the additional \fI,N\fR to differentiate between HBAs if there are multiple present. .PP If the \fI\-\-phy=ID\fR option is not given then \fI\-\-summary\fR is assumed. When \fI\-\-summary\fR is given or assumed, this utility shows the disposition of each active expander phy in table form. One row is shown for each phy and is described in the SINGLE LINE PER PHY FORMAT section below. For this purpose disabled and errored expander phys are considered "active" and can be suppressed from the output by adding the \fI\-\-brief\fR option. .SH OPTIONS Mandatory arguments to long options are mandatory for short options as well. .TP \fB\-A\fR, \fB\-\-adn\fR causes the "attached device name" field to be output when the \fI\-\-multiple\fR or \fI\-\-summary\fR option is also given. See the section below on SINGLE LINE PER PHY FORMAT. Note the "attached device name" field was added is SAS\-2. .TP \fB\-b\fR, \fB\-\-brief\fR reduce the decoded response output. If used twice will exit if there is no attached device (after outputting that). When used with \fI\-\-multiple\fR, unattached phys are not listed; when used twice, trims attached phys output. .TP \fB\-h\fR, \fB\-\-help\fR output the usage message then exit. .TP \fB\-H\fR, \fB\-\-hex\fR output the response (less the CRC field) in hexadecimal. .TP \fB\-i\fR, \fB\-\-ignore\fR sets the Ignore Zone Group bit in the SMP Discover request. Expander phys hidden by zoning will appear as "phy vacant" unless this option is given. .TP \fB\-I\fR, \fB\-\-interface\fR=\fIPARAMS\fR interface specific parameters. In this case "interface" refers to the path through the operating system to the SMP initiator. See the smp_utils man page for more information. .TP \fB\-l\fR, \fB\-\-list\fR list attributes in "name=value" form, one entry per line. .TP \fB\-m\fR, \fB\-\-multiple\fR loops over multiple phys within SMP target (typically an expander) and does a DISCOVER request and outputs a one line summary. Phy 0 is queried first, then phy 1, continuing until an error occurs. If \fI\-\-brief\fR is given then there is no output for phys that indicate there is no attached device; when used twice additionally trims the output line of attached phys. See the section below on SINGLE LINE PER PHY FORMAT. .TP \fB\-M\fR, \fB\-\-my\fR outputs my (this expander's) SAS address in hex (prefixed by "0x"). This is obtained from the DISCOVER response of phy id 0 (unless \fI\-\-phy=ID\fR is given). The expander's SAS address is typically available even if a phy is not connected, "vacant" or disabled. This option overrides most other options (e.g. overrides \fI\-\-multiple\fR and \fI\-\-summary\fR options). .TP \fB\-n\fR, \fB\-\-num\fR=\fINUM\fR number of phys to fetch, starting at \fI\-\-phy=ID\fR when the \fI\-\-multiple\fR option is given. The default value is 0 which is interpreted as "the rest" (i.e. until a "phy does not exist" function result is received). This option is ignored in the absence of the \fI\-\-multiple\fR option. .TP \fB\-p\fR, \fB\-\-phy\fR=\fIID\fR phy identifier. \fIID\fR is a value between 0 and 254. If this option is not given then the \fI\-\-summary\fR option is assumed. .TP \fB\-r\fR, \fB\-\-raw\fR send the response (less the CRC field) to stdout in binary. All error messages are sent to stderr. .TP \fB\-s\fR, \fB\-\-sa\fR=\fISAS_ADDR\fR specifies the SAS address of the SMP target device. Typically this is an expander. This option may not be needed if the \fISMP_DEVICE\fR has the target's SAS address within it. The \fISAS_ADDR\fR is in decimal but most SAS addresses are shown in hexadecimal. To give a number in hexadecimal either prefix it with '0x' or put a trailing 'h' on it. .TP \fB\-S\fR, \fB\-\-summary\fR output a multi line summary, with one line per active phy. Checks all phys (or less is \fI\-\-num=NUM\fR is given), starting at phy 0 (unless \fI\-\-phy=ID\fR is given). Equivalent to '\-\-multiple \-\-brief' ('\-mb'). See the section below on SINGLE LINE PER PHY FORMAT. If the \fI\-\-phy=ID\fR is not given then this option is assumed. .TP \fB\-v\fR, \fB\-\-verbose\fR increase the verbosity of the output. Can be used multiple times .TP \fB\-V\fR, \fB\-\-version\fR print the version string and then exit. .TP \fB\-z\fR, \fB\-\-zero\fR zero the Allocated Response Length field in the request. This option also zeros 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 it is given an abridged response may result. .SH SINGLE LINE PER PHY FORMAT The \fI\-\-summary\fR option causes SMP DISCOVER responses to be compressed to a header followed by one line per phy. To save space SAS addresses are shown in hex without a '0x' prefix or 'h' suffix. The header line gives the SAS address of the SMP target itself and assumes it is an expander. .PP Each line starts with " phy :" where is the phy identifier (and they are origin zero). That is followed by the routing attribute represented by a single letter which is either "D" for direct routing, "S" to subtractive routing or "T" for table routing. Then comes the negotiated physical link rate which is either "disabled", "reset problem" or "spinup hold". Other states are mapped to "attached". This includes enabled phys with nothing connected which appear as "attached:[0000000000000000:00]". .PP 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 end device then one of these abbreviations is output: "exp" (for expander), "fex" (for fanout expander) or "res" (for unknown attached device type). If a phy is flagged as "virtual" then the letter "V" appears next. Next are the protocols supported by the attached device which are shown as "i()" for initiator protocols and/or "t()" for target protocols. The is made up of "PORT_SEL", "SSP", "STP", "SMP" and "SATA" with "+" used as a separator. For example a SAS host adapter wi11 most likely appear as: "i(SSP+STP+SMP)". This completes the information about the attached phy, hence the closing right bracket. .PP If appropriate, the negotiated physical link rate is shown in gigabits per second. Here is an example of a line for expander phy identifier 11 connected to a SATA target (or SATA "device" to use the t13.org term): .PP phy 11:T:attached:[500605b000000afb:00 t(SATA)] 1.5 Gbps .PP If the expander supports zoning (i.e. REPORT GENERAL response bit for 'zoning supported' is set) and a phy's zone group is other than zg 1 then the phy's zone group is shown (e.g. "ZG:2"). .PP If the \fI\-\-adn\fR 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 its WWN (if provided, also in NAA-5 format). Also when the \fI\-\-adn\fR option is given the phy speed and zone group are not output in order to keep the line length reasonable. .SH NOTES In SAS\-2 and later both the DISCOVER and DISCOVER LIST functions are available. The DISCOVER LIST function should be favoured for several reasons: its response can hold up to 40 descriptors each describing the state of one expander phy. 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. Other advantages of the DISCOVER LIST function are its "phy filter" and "descriptor type" function request fields. .SH EXAMPLES See "Examples" section in http://sg.danny.cz/sg/smp_utils.html .SH CONFORMING TO The SMP DISCOVER function was introduced in SAS\-1, with small additions in SAS\-1.1 . There have been a large number of additions in SAS\-2 . .SH AUTHORS Written by Douglas Gilbert. .SH "REPORTING BUGS" Report bugs to . .SH COPYRIGHT Copyright \(co 2006\-2011 Douglas Gilbert .br This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. .SH "SEE ALSO" .B smp_utils, smp_discover_list, smp_phy_control