Technical Reference: Kernel and Subsystems, Volume 2

scsesdd SCSI Device Driver

Purpose

Device driver supporting the 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.

Open 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 the device is not currently opened. If an attempt is made to open a device and the device 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.
SESIOCMD	When the 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 via the arg parameter, which contains the address of a sc_iocmd structure (defined in the /usr/include/sys/scsi.h file). If the SESIOCMD 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 should evaluate the returned status bytes to determine why the operation failed and what recovery actions should be taken. The devinfo structure defines the maximum transfer size for the command. If an attempt is made to transfer more than the maximum, a value of -1 is returned and the errno global variable set to a value of EINVAL. Refer to the Small Computer System Interface (SCSI) Specification for the applicable device to get request sense information.

Operation

Description

IOCINFO

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

SESIOCMD

When the 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 via the arg parameter, which contains the address of a sc_iocmd structure (defined in the /usr/include/sys/scsi.h file). If the SESIOCMD 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 should evaluate the returned status bytes to determine why the operation failed and what recovery actions should be taken.

The devinfo structure defines the maximum transfer size for the command. If an attempt is made to transfer more than the maximum, a value of -1 is returned and the errno global variable set to a value of EINVAL. Refer to the Small Computer System Interface (SCSI) Specification for the applicable device to get request sense information.

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 a SCSI id different from the SCSI ids of the 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 will be 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 invalid requests 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, etc).

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.
EFAULT	An illegal user address was entered.
EINVAL	The data buffer length exceeded the maximum defined in the devinfo structure for a SESIOCMD 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 has been given.
EIO	The target device cannot be located or is not responding.
EIO	The target device has indicated an unrecovered hardware error.
EMFILE	An open 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 is not defined.
ENODEV	An attempt was made to close a device that has not been defined.
ENXIO	The ioctl subroutine supplied an invalid parameter.
EPERM	The attempted subroutine requires appropriate authority.
ETIMEDOUT	An I/O operation has exceeded the given timer value.

Reliability and Serviceability Information

The following errors are returned from SCSI enclosure services devices:

Error	Description
ABORTED COMMAN	The device cancelled the command.
ADAPTER ERRORS	The adapter returned an error.
GOOD COMPLETION	The command completed successfully.
HARDWARE ERROR	An unrecoverable hardware failure occurred during command execution or during a self test.
ILLEGAL REQUEST	An illegal command or command parameter.
MEDIUM ERROR	The command terminated with a unrecovered media error condition.
NOT READY	The logical unit is off-line or media is missing.
RECOVERED ERROR	The command was successful after some recovery applied.
UNIT ATTENTION	The device has been reset or the power has been turned on.

Files

/dev/ses0,/dev/ses1...,/dev/sesn

Provides an interface to allow SCSI device drivers access to SCSI enclosure services devices.

Related Information

SCSI Subsystem Overview in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.

A Typical Initiator-Mode SCSI Driver Transaction Sequence in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.

Required SCSI Adapter Device Driver ioctl Commands in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.

Understanding the Execution of Initiator I/O Requests in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.

SCSI Error Recovery in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.

Understanding the sc_buf Structure in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.

SCSI Adapter Device Driver.