SMP_UTILS

Section: SMP_UTILS (8)
Updated: December 2008
Index Return to Main Contents

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), output 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 variable 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 interface. 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 initiator). Either 'tpl' or 'ai' can be used to specify this interface.

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 environment 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 hexadecimal. 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 standard, application layer, management application layer, SMP functions. 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 environments. 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 package 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, including 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

This document was created by man2html, using the manual pages.
Time: 05:34:30 GMT, December 24, 2015