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), 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  tar-
       get'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. Alterna-
              tively 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  vari-
              ables. PARAMS is of the form: INTF[,force].  If the guess doesn't work then the interface can be specified by giv-
              ing a INTF of either 'mpt', 'sgv4' or 'tpl' ( with 'ai' being a synonym for 'tpl'). Sanity checks are  still  per-
              formed  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  permit-
              ted.

       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  operat-
              ing 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  stan-
       dards,  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 (C) 2006-2008 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
       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)