smp_utils (8) - Linux Manuals
smp_utils: invoke a SAS Serial Management Protocol (SMP) function
NAME
smp_* - invoke a SAS Serial Management Protocol (SMP) functionSYNOPSIS
smp_* [--expected=EX] [--help] [--hex] [--interface=PARAMS] [--raw] [--sa=SAS_ADDR] [--verbose] [--version] SMP_DEVICE[,N]DESCRIPTION
Serial Attached SCSI (SAS) is a transport (also known as a interconnect) used by storage systems. A SAS system is made up of Host Bus Adapters (HBAs typically containing SCSI initiators), disks (referred to in SCSI as both targets and logical units) and optionally some switching hardware called "expanders". Expanders are not SCSI devices so a new protocol was required to control and monitor them. Its full name is the SAS Serial Management Protocol which is abbreviated to SMP.
smp_utils is a package of utilities. Each utility sends an SMP function request to a SMP_DEVICE (an SMP target). Some utilities may invoke the same function more than once. 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 the --raw option is given).
If SMP_DEVICE[,N] is not given then the value in the environment variable SMP_UTILS_DEVICE is used.
This package was originally written for Linux and has been ported to FreeBSD and Solaris.
LINUX INTERFACE
Currently there are multiple interfaces that allow SMP functions to be passed through to an 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 the --sa=SAS_ADDR option.
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).
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:
- aac
- This specifies the aacraid SAS pass-through associated with Adaptec/PMC RAID products. The SMP_DEVICE[,N] argument takes the form /dev/aac[N[,E_ID]] where "N" is the raid controller number (typically 0) and "E_ID" is the expander identifier (typically 0); both default to 0 so /dev/aac is equivalent to /dev/aac0 and /dev/aac0,0 . The "N" is the unique_id found in /sys/class/scsi_host<HN>/unique_id . The "HN" is the host number which is the first number to appear on each line in the lsscsi utility which by default uses one line to list each accessible SCSI device (typically SCSI or ATA disks). The "E_ID" is the expander identifier which can be found with the Adaptec/PMC arcconf utility using the form "arcconf expanderlist <ControllerNum>". The <ControllerNum>s start at 1 . If an aac RAID controller is present then the /dev/acc device node will be created by the first smp utility to use this interface.
- mpt
- This specifies the MPT fusion SAS pass-through. The mptsas driver uses the '/dev/mptctl' device node (character device major 10, minor 220) while the mpt2sas driver uses '/dev/mpt2ctl' device node (major 10, minor 221). For the mpt3sas driver the corresponding device node is '/dev/mpt3ctl'. The 'modprobe mptctl' or 'modprobe mpt2ctl' command may be needed. 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 with dmesg after the mptsas driver is registered and appears as a suffix to the driver name (e.g. mpt2sas0). It can also be found in '/sys/class/scsi_host/host<n>/unique_id'. When this interface is used the --sa=SAS_ADDR option must be given to specify the SAS address of the SMP target.
- sgv4 (sg)
- This interface is more generic and supported by several SAS HBA drivers including mptsas (and mpt2sas). It was introduced in the Linux 2.6.24 kernel. The SMP functions are passed to the kernel via the bsg driver 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 (e.g. /sys/class/bsg/expander-6:0 ) or a device node made for the bsg driver (e.g. /dev/bsg/expander-6:0 ). Such device nodes are dynamic (i.e. they don't have fixed major and minor numbers) and should correspond to the major and minor numbers found in the 'sys/class/bsg/<smp_target_device>/dev' file.
FREEBSD INTERFACE
The CAM subsystem has been enhanced in FreeBSD 9 to pass-through SMP requests and return the corresponding responses. However CAM does not directly access expander devices because they are not SCSI devices. It makes the assumption that each SAS expander has an integrated SES (enclosure) device and that is addressed. This assumption seems to be true for SAS-2 expanders but not some SAS-1 expanders. Thus invocations look like this:
where /dev/ses0 is a SES device associated with a SAS expander.
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'.
If either or both environment variables and the corresponding command line
options are given, then the command line options take precedence.
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:
That should show the suffix on any expanders that have been detected. Then
a command like 'cat /sys/class/sas_device/expander-6:0/sas_address' should
show its 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". The sg_logs utility from the sg3_utils
package could be used like this:
Any given "attached SAS address" is either a HBA, an expander or 0 indicating
that port is not connected. An expander is indicated by "attached device
type: expander device". A SAS disk's target port identifiers (also known as
SAS addresses), device name and logical unit name (all NAA 5 format) can be
found with the sg_vpd utility (e.g. 'sg_vpd -i <disk_dev>'). The sdparm
utility can provide the same information (e.g. 'sdparm -i <disk_dev>').
A SAS expander is often associated with a SCSI Enclosure Services (SES)
device sometimes on the same silicon attached via a virtual phy to the
expander. That SES device may be able to access and control an attached
enclosure or backplane via SGPIO or I2C on sideband signals (e.g. in a
SFF-8087 cable). To interact with a SES device, see the sg_ses utility.
Often expander phys are grouped in fours on the same connector (e.g.
SFF-8088). Care needs to be taken when multiple expanders are interconnected.
An enclosure
universal
port is one in which the "table to table supported" attribute is set (in
the REPORT GENERAL response) and the associated phys have the table routing
attribute (in the DISCOVER response). Enclosure
universal
ports were introduced in SAS-2 and have few restrictions when used to
interconnect expanders or connect SAS or SATA devices. An enclosure
out
port is one in which the "table to table supported" attribute is clear and
the associated phys have the table routing attribute. An enclosure
in
port is one in which the associated phys have the subtractive routing
attribute. When
universal
ports are not available, an expander interconnect should be between an
in
port and an
out
port.
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 . "Enhanced" versions of the
corresponding SMP functions have been mentioned in some drafts but no
definitions have been published and the references have been removed in more
recent drafts.
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 a table of all SMP
function names defined in the drafts, the versions of those standards in
which those SMP functions first appeared and the corresponding
smp_utils utility names. A lot of extra SMP functions have been added in
SAS-2 associated with zoning.
SOLARIS INTERFACE
The USMP pass-through mechanism is used. Invocations look like this:
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.
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").
EXIT STATUS
To aid scripts that call these utilities, the exit status is set to
indicate success (0) or failure (1 or more):
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.
EXAMPLES
See "Examples" section in http://sg.danny.cz/sg/smp_utils.html .
CONFORMING TO
SAS has multiple generations. The early standards are: the original
SAS (ANSI INCITS 376-2003), SAS 1.1 (INCITS 417-2006) and SAS-2 (ANSI
INCITS 457-2010) . SAS-2.1 work was split into an electrical and physical
layers document (standardized as SAS-2.1 ANSI INCITS 478-2011) with the
upper level layers placed in a document called the SAS Protocol Layer and
it was standardized as SPL ANSI INCITS 476-2011. Next came SPL-2 which
was standardized as SPL-2 ANSI INCITS 505-2013. SPL-3 is near
standardization and its most recent draft is spl3r07.pdf. To avoid
confusion, the multiple generations of SAS will be referred to in these man
pages as SAS 1, 1.1, 2, 2.1 (SPL) and 3 (SPL-2 and SPL-3). Roughly
speaking SAS-1 runs at 3 Gbps, SAS-2 at 6 Gbps and SAS-3 at 12 Gbps.
Drafts, including those just prior to standardization can be found at the
http://www.t10.org site (e.g. spl-r07.pdf and spl2r04c.pdf). INCITS policy
now requires a registration to view these drafts, a break from t10.org
tradition.
AUTHORS
Written by Douglas Gilbert.
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright © 2006-2014 Douglas Gilbert
This software is distributed under a FreeBSD license. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
SEE ALSO
sg_logs, sg_vpd, sg_ses(sg3_utils); sdparm(sdparm); lsscsi(lsscsi)