[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Kernel and Subsystems Technical Reference, Volume 2

Device-Dependent Subroutines for Serial DASD Adapter Operations

Use the open, openx, close, read, readx, write, writex, and ioctl subroutines to implement Direct Access Storage Device (DASD) operations. Observe the special considerations for using these subroutines:

openx Subroutine

The openx subroutine is intended primarily for use by diagnostic commands and utilities. Appropriate authority is required for execution. Attempting to execute this subroutine without the proper authority results in a return value of -1, with the errno global variable set to EACCES.

The ext parameter passed to the openx subroutine selects the operation to be used for the target adapter. The /usr/include/sys/scsi.h file defines the following possible values for the ext parameter:

SC_DIAGNOSTIC Places the selected adapter in Diagnostic mode. This mode is singularly entrant. When an adapter is in Diagnostic mode, all controllers and DASD on that adapter are placed in Diagnostic mode, and error logging is disabled.
SD_DAEMON Informs the device driver that the serial DASD subsystem daemon is opening the adapter. Only one Daemon-mode open is allowed per adapter, and it must be directed to the /dev/dserdasdan special file.

This mode of operation is transparent to the rest of the system. A diagnostic open does not fail if the only open to an adapter is the daemon open, and the daemon open does not fail if an adapter is in Diagnostic mode. However, when an adapter is placed in Diagnostic mode, all queuing of asynchronous events to the daemon is filtered. The Daemon mode provides the authority needed to perform microcode downloads to the adapter and controller.

ioctl Subroutine

The ioctl subroutine can call the IOCINFO, SD_SCSICMD, and SD_RESET operations.

IOCINFO

The IOCINFO operation is the only operation defined for all device drivers that use the ioctl subroutine. The IOCINFO operation returns the devinfo structure defined in the /usr/include/sys/devinfo.h file. This ioctl operation can be directed to an adapter, controller, or DASD. The device can be opened in normal mode for this ioctl operation.

SD_SCSICMD

When the device has been successfully opened in Diagnostic mode, the SD_SCSICMD operation provides the means for issuing any Serial DASD subsystem command to a specified device. The Serial DASD subsystem commands are modeled after those for SCSI. The following Serial DASD subsystem commands are valid and use the same command descriptor block, including the operation code, as their corresponding SCSI command. The SCSI commands are defined in the /usr/include/sys/scsi.h file:

Format Unit Read Capacity Test Unit Ready
Inquiry Reassign Blocks Verify
Mode Select Release Write
Mode Sense Request Sense Write And Verify
Read (6) Reserve Write Buffer
Read (10) Start Stop Unit Write Sense

The following Serial DASD subsystem commands can be issued when the device is not in Diagnostic mode, but the caller has root authority:

Fence Receive Diagnostics
Inquiry Request Sense
Read Write Buffer
Read Extended

The Serial DASD Fence command does not correspond with any SCSI command. For more information, see "Serial DASD Fence Command" .

If the SD_SCSICMD operation is issued with any other Serial DASD subsystem command and the device is not in Diagnostic mode, the SD_SCSICMD operation returns a value of -1 and sets the errno global variable to a value of EACCES. The device driver performs no error recovery or error logging when this ioctl operation fails. The status_validity byte, scsi_bus_status byte, and the adapter_status byte are returned via the arg parameter. This parameter contains the address of a sc_iocmd structure, which is defined in the /usr/include/sys/scsi.h file.

The devinfo structure, which is returned from the IOCINFO ioctl operation, defines the maximum transfer size for the command. The structure returns a value of -1 and sets the errno global variable to a value of EINVAL if an attempt is made to transfer more than the maximum transfer size. If the Serial DASD subsystem command cannot complete in the time specified in the sc_iocmd structure, a -1 value is returned and the errno global variable is set to a value of ETIMEDOUT.

The SD_SCSICMD operation uses the sc_iocmd structure with the following status validity values:

0x00 Command successful
0x01 Valid scsi_bus_status byte only
0x02 Valid adapter status only
0x04 Valid alert register contents
Note: Except when the adapter status is SC_ADAPTER_HDW_FAILURE, if the adapter status is valid, the alert register contents are also valid. When the device driver fails a command due to internal error recovery without communicating with the adapter, the SC_ADAPTER_HDW_FAILURE adapter status is returned. For all other adapter status values, the adapter status is defined as part of the general card status in the /usr/include/sys/scsi.h file.

The SD_SCSICMD operation also uses the following reserved fields:

resvd1 Returned as the controller status byte of the alert register. The possible values for this field are defined in the "Controller Status Byte Codes" section of the /usr/include/sys/serdasd.h file.
resvd2 Returned as the adapter status byte of the alert register. The possible values for this field are defined in the "Adapter Status Byte Codes" section of the /usr/include/sys/serdasd.h file.
resvd5 Specifies the address of the device. The address is comprised of eight bits
5-7 Target (Controller ID)
4 Direction (0 = DASD, 1 = Controller)
0-3 DASD (LUN)
resvd6 Manipulates the queue control and ordering of the SD_SCSICMD command. The caller must set this field to one of the following values:
0x00 None, unqueued
0x40 Invalid
0x80 Ordered
0xC0 Unordered
resvd7 Specifies an extension to the Serial DASD subsystem command. The caller must set this field to one of the following values:
0x00 No extension
0x20 Split write enabled
0x10 Split read enabled
Note: If the timeout field of the sc_iocmd structure is set to 0, the calling process is responsible for handling timeouts. The device driver will never time out the command if the value of the structure is 0.

SD_RESET

The SD_RESET operation provides an interface for issuing resets and quiesces to the Serial DASD adapter. The adapter is the /dev/serdasdaN file, where N is 0 or a positive integer. To send a reset or quiesce operation to an adapter, the adapter must be opened in SC_DIAGNOSTIC mode. The arg parameter of the ioctl call is a pointer to a sd_ioctl_parms structure, which is defined in the /usr/include/sys/serdasd.h file.

If the SD_RESET ioctl is issued when the device is not in Diagnostic mode, the ioctl returns a value of -1 and sets the errno global variable to a value of EACCES. If the Serial DASD adapter does not respond to the SD_RESET ioctl, a value of -1 is return, and the errno global variable is set to a value of EIO.

The following fields of the sd_ioctl_parms structure are used with this ioctl command.

reset_type Contains one of the following values:
SD_RESET_OP Indicates a full reset.
SD_QUIESCE_OP Indicates a quiesce.
status_validity Indicates either successful completion or the status of the adapter or controller. This field may have one of the following values:
0x00 Command successful
0x01 Valid adapter status
0x02 Valid controller status
0x04 Valid device driver status only
Note: These values are different than the status_validity definitions for pass-through Serial DASD subsystem commands.The valid device driver status is exclusive of the other two valid status conditions. If the value of the status validity field is 0x04, then the adapter_status field contains the device driver status. the only device driver status is SD_DD_PURGED_TAG.
adapter_status Indicates the adapter status, if valid, upon completion of the reset operation. The possible values for this field are defined in the "Adapter Status Byte Codes" section of the /usr/include/sys/serdasd.h file.
controller_status Indicates the controller status, if valid, upon completion of the reset operation. The possible values for this field are defined in the "Controller Status Byte Codes" section of the /usr/include/sys/serdasd.h file.
Note: If the time_out field of the sd_ioctl_parms structure is set to 0, the calling process is responsible for handling timeouts. In this situation, the device driver will never time out the command.

Related Information

The ioctl subroutine, open, openx subroutine.

Serial DASD Subsystem Device Driver.

Device-Dependent Subroutines for Serial DASD Operations.

Device-Dependent Subroutines for Serial DASD Controller Operations.

Error Conditions for Serial DASD Subroutines.

Reliability, Availability, and Serviceability (RAS) Daemon for the Serial DASD Subsystem.

Serial DASD Fence Command.

Serial DASD Concurrent Mode of Operation Interface.

SD Error Identifiers for the Error Log in AIX Problem Solving Guide and Reference.

Serial Direct Access Storage Device (DASD) Overview in AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]