usmp

- user SMP command interface

Synopsis

#include <sys/scsi/impl/usmp.h>

ioctl(int fildes, int request, struct usmp_cmd *cmd);

Description

The smp driver supports this ioctl(2), which provides a generic user-level interface for sending SMP commands to SMP target devices. SMP target devices are generally SAS switches or expanders. Each usmp call directs the smp(7D) driver to express a specific SMP function, and includes the data transfer to and from the designated SMP target device.

The usmp_cmd structure is defined in <sys/scsi/impl/usmp.h> and includes the following:

caddr_t     usmp_req;         /* address of smp request frame */
caddr_t     usmp_rsp;         /* address of smp response frame */
size_t      usmp_reqsize;     /* byte size of smp request frame */
size_t      usmp_rspsize;     /* byte size of smp response frame */
int         usmp_timeout;     /* command timeout */

The fields of the usmp_cmd structure have the following descriptions:

usmp_req

The address of the buffer containing the smp request frame. The data format should conform to the definition in the Serial Attached SCSI protocol.

usmp_rsp

The address of the buffer used to hold the smp response frame.

usmp_reqsize

The size in byte of the smp request frame buffer.

usmp_rspsize

The size in byte of the smp response frame buffer. The size of the buffer should not be less than eight bytes. If the buffer size is less than eight bytes the smp(7D) driver immediately returns EINVAL. If the buffer size is less than that specified for the specific SMP function in the Serial Attached SCSI protocol definition, the response data might be truncated.

usmp_timeout

The time in seconds to allow for completion of the command. If it is not set in user-level, the default value is 60.

The common headers of smp request and response frames are found in two structures: usmp_req and usmp_rsp, both of which are defined in <sys/scsi/impl/smp_frames.h>.

The structures include the following fields:

struct usmp_req {
  uint8_t smpo_frametype;   /* SMP frame type, should be 0x40 */
  uint8_t smpo_function;    /* SMP function being requested */
  uint8_t smpo_reserved;    /* reserved byte */
  uint8_t smpo_reqsize;     /* number of dwords that follow */
  uint8_t smpo_msgframe[1]  /* request bytes based on SMP function
                                 plus 4-byte CRC code */
}

struct usmp_rsp {
  uint8_t smpi_frametype;   /* SMP frame type, should be 0x41 */
  uint8_t smpi_function;    /* SMP function being requested */
  uint8_t smpi_result;      /* SMP function result */
  uint8_t smpi_rspsize;     /* number of dwords that follow */
  uint8_t smpi_msgframe[1]; /* response bytes based on SMP function */
}

ioctls

The ioctl supported by the SMP target driver through the usmp interface is:

USMPCMD

The argument is a pointer to a usmp_cmd structure.

Errors

EFAULT

One or more of the usmp_cmd, usmp_req or usmp_rsp structures point to an invalid address.

EINVAL

A parameter has an incorrect, or unsupported value.

EIO

An error occurred during the execution of the command.

ENODEV

Device has gone.

ENOMEM

No memory available.

EOVERFLOW

The response buffer is shorter than required, and the data is truncated.

EPERM

A process without PRIV_SYS_DEVICES privilege tried to execute the USMPCMD ioctl.

ETIME

Command timeout.

Attributes

See attributes(5) for a description of the following attributes:

See Also

ioctl(2), attributes(5), smp(7D), mpt(7D)

ANSI Small Computer System Interface – 4 (SCSI-4)

Notes

usmp commands are designed for topology control, device accessibility, and SAS expander and switch configuration. Usage of usmp is restricted to processes running with the PRIV_SYS_DEVICES privilege, regardless of the file permissions on the device node.

User-level applications are not required to fill in the four bytes of SAS CRC code in the SMP request frame. The smp(7D) driver manages this for usmp if the SAS HBA does not.