smp_utils man page on SuSE
[printable version]
SMP_UTILS(8) SMP_UTILS SMP_UTILS(8)
NAME
smp_* - invoke a Serial Attached SCSI Management (SMP) function
SYNOPSIS
smp_* [--expected=EX] [--help] [--hex] [--interface=PARAMS] [--raw]
[--sa=SAS_ADDR] [--verbose] [--version] SMP_DEVICE[,N]
DESCRIPTION
smp_utils is a package of utilities. Each utility sends a Serial
Attached SCSI (SAS) Management Protocol (SMP) request to a SMP_DEVICE
(a SMP target). If an error occurs then an error message is sent to
stderr. If no error occurs, the response is decoded (the default), out‐
put in ASCII hex (when --hex is given) or output in binary to stdout
(when --raw is given).
If SMP_DEVICE[,N] is not given then the value in the environment vari‐
able SMP_UTILS_DEVICE is used.
INTERFACE
Currently there are multiple interfaces that allow SMP functions to be
passed through to a SMP target.
One method is to have a SMP_DEVICE which is actually the SMP initiator
(e.g. '/dev/mptctl,0'). In this case the SMP target's SAS address must
be supplied with --sa=SAS_ADDR.
Another method is to have a SMP_DEVICE which represents the SMP target.
In this case no SAS_ADDRESS needs to be given (since it is implicit).
This method may be simpler but it has some limitations (e.g. it assumes
the SMP target has already been discovered which may not be the case
for the initial discovery process).
Each utility in smp_utils attempts to work out which interface it has
been given by examining the SMP_DEVICE file. There are three interfaces
supported currently:
mpt This specifies the MPT fusion SAS pass-through which uses the
'/dev/mptctl' or '/dev/mpt2ctl' device node. If mpt drivers are
loaded but '/dev/mptctl' or '/dev/mpt2ctl' are not present then
a 'modprobe mptctl' command may be needed in Linux. If there are
multiple mpt fusion controllers (HBAs) in the computer, then the
user will need to specify which one to use with the syntax:
'/dev/mptctl,<n>' where <n> is the "ioc_num". This number can be
found in the log where the mptsas driver is registered. In Linux
it can be found in '/proc/scsi/mptsas/<host_no>' in the 2.4
series and additionally in
'/sys/class/scsi_host/host<n>/unique_id' in the 2.6 series. When
this interface is used the --sa=SAS_ADDR option must be given to
specify the SAS address of the SMP target. When the mptctl
driver is loaded in Linux there should be a character device
node at '/dev/mptctl' with major 10 and minor 220. Alternatively
there may be a character device node at '/dev/mpt2ctl' with
major 10 and minor 221.
sgv4 (sg)
This interface is more generic and supported in the linux 2.6.24
kernel and beyond. The SMP functions are passed to the kernel
using a format known as "SCSI Generic Version 4" which gives
this interface its name: "sgv4" or just "sg". The SAS transport
layer within the SCSI sub-system unpacks the SMP requests and
forwards them to SAS low level drivers that support this inter‐
face. The SMP_DEVICE is either a member of the '/sys/class/bsg'
directory or a device node made by the bsg driver. Such device
nodes are dynamic (i.e. they don't have a fixed major number)
and should correspond to the major and minor numbers found in
the 'sys/class/bsg/<smp_target_device>/dev' file.
tpl (ai)
This interface is currently used by one adaptec 94xx driver. The
"device" name will usually be "smp_portal" and it will be found
within the sysfs file system (typically mounted under "/sys").
The target SMP SAS address is implicit (as is the SMP initia‐
tor). Either 'tpl' or 'ai' can be used to specify this inter‐
face.
ENVIRONMENT VARIABLES
If the device name is not given then the SMP_UTILS_DEVICE environment
variable is checked and if present its contents are used as the device
name.
If the SAS address (of the SMP target) is not given and it is required
(i.e. it is not implicit in the device name) then the
SMP_UTILS_SAS_ADDR environment variable is checked and if present its
contents are used as the SAS address. SAS addresses are usually given
in hex indicated by a leading '0x' or trailing 'h'.
In both cases command line options override the corresponding environ‐
ment variable.
COMMON OPTIONS
Mandatory arguments to long options are mandatory for short options as
well. If an option takes a numeric argument then that argument is
assumed to be decimal unless otherwise indicated (e.g. with a leading
"0x" or a trailing "h").
-E, --expected=EX
revision 4a of the SAS-2 draft introduced an 'expected expander
change count' field in some SMP requests. The idea is to detect
other SMP initiators trying to change the state of an expander.
The value EX is from 0 to 65535 inclusive with 0 being the
default value. When EX is greater than zero then if the value
doesn't match the expander change count of the SMP target (i.e.
the expander) when the request arrives then the target ignores
the request and sets a function result of "invalid expander
change count" in the response.
-h, --help
output the usage message for the utility then exit.
-H, --hex
output the response in hexadecimal.
-I, --interface=PARAMS
interface specific parameters. This option is usually not needed
since the interface type is guessed by a utility based on the
characteristics of the given SMP_DEVICE argument or what is in
the corresponding environment variables. PARAMS is of the form:
INTF[,force]. If the guess doesn't work then the interface can
be specified by giving a INTF of either 'mpt', 'sgv4' or 'tpl' (
with 'ai' being a synonym for 'tpl'). Sanity checks are still
performed and a utility may refuse if it doesn't agree with the
given INTF. If the user is really sure then adding a ',force'
will force the utility to use the given interface.
-r, --raw
send the response to stdout in binary. All error messages are
sent to stderr.
-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 associated with it. The
SAS_ADDR is in decimal but most SAS addresses are shown in hexa‐
decimal. To give a number in hexadecimal either prefix it with
'0x' or put a trailing 'h' on it. If this option is not given
then the value in the environment variable SMP_UTILS_SAS_ADDR is
used.
-v, --verbose
increase the verbosity of the output. Can be used multiple
times.
-V, --version
print the version string and then exit.
EXIT STATUS
To aid scripts that call these utilities, the exit status is set to
indicate success (0) or failure (1 or more):
0 success
1 - 63 reserved for SMP function result codes. See SAS draft or stan‐
dard, application layer, management application layer, SMP func‐
tions. Here are some common function result codes: 1 [unknown
SMP function], 2 [SMP function failed], 16 [phy does not exist],
17 [index does not exist], 18 [phy does not support SATA] and 19
[unknown phy operation].
91 syntax error. Either illegal options, options with bad arguments
or a combination of options that is not permitted.
92 the utility is unable to open, close or use the given
SMP_DEVICE. The given file name could be incorrect or there may
be permission problems. Adding the --verbose option may give
more information.
97 the response to a SMP function failed sanity checks.
99 any error that can't be categorized into values 1 to 97 may
yield this value. This includes transport and operating system
errors.
NOTES
Finding the SAS address of an expander can be a challenge in some envi‐
ronments. An enclosure containing one or more expanders may have the
expander SAS address(es) printed on the back of the device, a bit like
ethernet MAC addresses.
In the Linux 2.6 kernel series the expander SAS address may well be in
the sysfs tree but it is not always easy to find. Doing this search may
help:
# find /sys -name "sas_device:expander*"
Then change directory to any path found and call 'cat sas_address'
Another approach is to work backwards from SCSI devices (i.e. logical
units). The protocol specific port log page (log page 18h) contains
fields for the "attached SAS address". sg_logs from the sg3_utils pack‐
age could be used like this:
# sg_logs --page=18h /dev/sdb
Any given "attached SAS address" is either a HBA, an expander or 0
indicating that port is not connected.
CONFORMING TO
To date SAS has three generations. The first two generations are
approved standards: the original SAS (SAS ANSI INCITS 376-2003) and SAS
1.1 (INCITS 417-2006). SAS-2 technical work is ongoing and at the time
of writing the most recent draft is sas2r15.pdf (see section 10.4.3 for
SMP functions). To avoid confusion, the three generations of SAS will
be referred to in these man pages as SAS 1, 1.1 and 2 . Drafts, includ‐
ing those just prior to standardization can be found at the
http://www.t10.org site.
The two utilities for reading and writing to GPIO registers,
smp_read_gpio and smp_write_gpio, are defined in the Small Form Factor
document SFF-8485 found at http://www.sffcommittee.com .
In this section of each utility's man page is the first standard in
which the associated SMP function appeared and whether there have been
significant additions in later standards.
The COVERAGE file in the smp_utils source tarball shows the mapping
between all SMP function names defined in the standards, the versions
of those standards in which those SMP functions are defined and the
corresponding smp_utils utility names. A lot of extra SMP functions
have been added in SAS-2 and many do not have corresponding utilities
at this time.
AUTHORS
Written by Douglas Gilbert.
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright © 2006-2008 Douglas Gilbert
This software is distributed under a FreeBSD license. There is NO war‐
ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
POSE.
SEE ALSO
smp_conf_general, smp_conf_route_info, smp_discover, smp_discover_list,
smp_phy_control, smp_phy_test, smp_read_gpio, smp_rep_exp_route_tbl,
smp_rep_general, smp_rep_manufacturer, smp_rep_phy_err_log,
smp_rep_phy_sata, smp_rep_route_info, smp_write_gpio,
sg_logs(sg3_utils)
smp_utils-0.94 December 2008 SMP_UTILS(8)
[top]
List of man pages available for SuSE
Copyright (c) for man pages and the logo by the respective OS vendor.
For those who want to learn more, the polarhome community provides shell access and support.
[legal]
[privacy]
[GNU]
[policy]
[cookies]
[netiquette]
[sponsors]
[FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
|
|
Vote for polarhome
|
