scsisesdd SAM Device Driver

Purpose

Supports the Serial Attached SCSI Enclosure Services device.

Syntax

#include <sys/devinfo.h>
#include <sys/scsi.h>
#include <sys/scses.h>

Description

The special files /dev/ses0, /dev/ses1 ... provide I/O access and control functions to the SCSI enclosure devices.

Typical SCSI enclosure services operations are implemented using the open, ioctl, and close subroutines.

The open subroutine places the selected device in Exclusive Access mode. This mode is singularly entrant; that is, only one process at a time can open it. A device can be opened only if it is not currently opened. If an attempt is made to open a device that is already open, a value of -1 is returned and the errno global variable is set to a value of EBUSY.

ioctl Subroutine

The following ioctl operations are available for SCSI Enclosure Services devices:

Operation	Description
IOCINFO	Returns the devinfo structure defined in the /usr/include/sys/devinfo.h file.
SESPASSTHRU	When a device has been successfully opened, this operation provides the means for issuing any SCSI command to the specified enclosure. The device driver performs no error recovery or logging-on failures of this ioctl operation. The SCSI status byte and the adapter status bytes are returned through the arg parameter, which contains the address of an sc_passthru structure (defined in the /usr/include/sys/scsi.h file). If the SESPASSTHRU operation returns a value of -1 and the errno global variable is set to a nonzero value, the requested operation has failed. In this case, the caller must evaluate the returned status bytes to determine why the operation failed and what recovery actions must be taken. The version field of the sc_passthru structure should be set to the value of SCSI_VERSION_1, and SES does not support Variable length CDBs. On completion of the SESPASSTHRU ioctl request, the residual field indicates the leftover data that the device did not fully satisfy for this request. Upon successful completion, the residual field indicates that the device does not have all the data that was requested or the device has less than the amount of data that was requested. Upon failure, the user needs to check the status_validity field to determine if a valid SCSI bus problem exists. In this case, the residual field indicates the number bytes that the device failed to complete for this request. The devinfo structure defines the maximum transfer size for the command. If an attempt is made to transfer more than the maximum transfer size, the subroutine returns a value of -1, sets the errno global variable to a value of EINVAL, and sets the einval_arg field to a value of SC_PASSTHRU_INV_D_LEN (defined in the /usr/include/sys/scsi.h file). Refer to the Small Computer System Interface (SCSI) Specification for the format of the request-sense data for a particular device.

Operation

Description

IOCINFO

Returns the devinfo structure defined in the /usr/include/sys/devinfo.h file.

SESPASSTHRU

When a device has been successfully opened, this operation provides the means for issuing any SCSI command to the specified enclosure. The device driver performs no error recovery or logging-on failures of this ioctl operation.

The SCSI status byte and the adapter status bytes are returned through the arg parameter, which contains the address of an sc_passthru structure (defined in the /usr/include/sys/scsi.h file). If the SESPASSTHRU operation returns a value of -1 and the errno global variable is set to a nonzero value, the requested operation has failed. In this case, the caller must evaluate the returned status bytes to determine why the operation failed and what recovery actions must be taken.

The version field of the sc_passthru structure should be set to the value of SCSI_VERSION_1, and SES does not support Variable length CDBs.

On completion of the SESPASSTHRU ioctl request, the residual field indicates the leftover data that the device did not fully satisfy for this request. Upon successful completion, the residual field indicates that the device does not have all the data that was requested or the device has less than the amount of data that was requested. Upon failure, the user needs to check the status_validity field to determine if a valid SCSI bus problem exists. In this case, the residual field indicates the number bytes that the device failed to complete for this request.

The devinfo structure defines the maximum transfer size for the command. If an attempt is made to transfer more than the maximum transfer size, the subroutine returns a value of -1, sets the errno global variable to a value of EINVAL, and sets the einval_arg field to a value of SC_PASSTHRU_INV_D_LEN (defined in the /usr/include/sys/scsi.h file). Refer to the Small Computer System Interface (SCSI) Specification for the format of the request-sense data for a particular device.

Device Requirements

The following hardware requirements exist for SCSI enclosure services devices:

The device must support the SCSI-3 Enclosure Services Specification Revision 4 or later.
The device can be addressed from an SCSI ID different from the SCSI IDs of the SCSI devices inside the enclosure.
The device must be "well behaved", when receiving SCSI inquiries to page code 0xC7. This means that if the device fails the inquiry to page code C7 with a check condition, then the check condition is cleared by the next SCSI command. An explicit request sense is not required.
If the device reports its ANSI version to be 3 (SCSI-3) in the standard inquiry data, then it must correctly reject all requests that are not valid for luns 8-31 (that is, the device cannot ignore the upper bits in Lun ID and thus cannot treat Lun 8 as being Lun 0, and so on).

Examples

This is the example code for filling the sc_passthru structure for the SESPASSTHRU ioctl to issue Standard Inquiry SCSI CDB:

    struct sc_passthru passthru;
    passthru.version = SCSI_VERSION_1;
    passthru.timeout_value = 30;
    passthru.command_length = 6;
    passthru.q_tag_msg = SC_SIMPLE_Q;
    passthru.flags = B_READ;
    passthru.autosense_length = SENSE_LEN;
    passthru.autosense_buffer_ptr = &sense_data[0];    /* Buffer for Auto Sense Data */
    passthru.data_length = 0xFF;
    passthru.buffer = data;            /* Data buffer address to store inquiry data */
    passthru.scsi_cdb[0] = SCSI_INQUIRY;
    passthru.scsi_cdb[1] = 0x00;
    passthru.scsi_cdb[2] = 00; /* Page Code */
    passthru.scsi_cdb[3] = 00;
    passthru.scsi_cdb[4] = 0xFF;
    passthru.scsi_cdb[5] = 0x00;

Error Conditions

ioctl and open subroutines against this device fail in the following circumstances:

Error	Description
EBUSY	An attempt was made to open a device already opened.
EEXIST	Device already exists in the device table.
ENOMEM	Memory allocation failed.
EFAULT	An illegal user address was entered.
EINVAL	The data buffer length exceeded the maximum defined in the devinfo structure for a SESPASSTHRU ioctl operation.
EINVAL	An unsupported ioctl operation was attempted.
EINVAL	An attempt was made to configure a device that is still open.
EINVAL	An illegal configuration command was given.
EINVAL	The variable_cdb_ptr or variable_cdb_length fields are set in the sc_passthru struct.
EIO	The target device cannot be located or is not responding.
EIO	The target device has indicated an unrecovered hardware error.
EMFILE	An open operation was attempted for an adapter that already has the maximum permissible number of opened devices.
ENODEV	An attempt was made to access a device that was not defined.
ENODEV	An attempt was made to close a device that was not defined.
ENXIO	The parameter or device number supplied by the ioctl subroutine is not valid, or the device is not configured.
EPERM	The attempted subroutine requires appropriate authority.
ETIMEDOUT	An I/O operation has exceeded the given timer value.

Files

Item	Description
/dev/ses0, /dev/ses1... /dev/sesn	Provides an interface to allow SCSI device drivers access to SCSI enclosure services devices.