Use the open, openx, close, and ioctl subroutines to implement Direct Access Storage Device (DASD) operations. Observe special considerations for using these subroutines:
The openx subroutine is used primarily by diagnostic commands and utilities. Users must have root authority to execute this subroutine. 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 selects the operation to be used for the target controller. The /usr/include/sys/scsi.h file defines the SC_DIAGNOSTIC value for the ext parameter.
The SC_DIAGNOSTIC extended parameter places the selected controller in Diagnostic mode. This mode is singularly entrant. When a controller is in Diagnostic mode, all DASDs on that controller are placed in Diagnostic mode, and error logging is disabled.
Note: If a controller is opened in Diagnostic mode, commands can be addressed to that controller or any DASD on that controller.
The ioctl subroutine can call the IOCINFO, SD_SCSICMD, and SD_RESET operations.
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.
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 following 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 uses the sc_iocmd structure using the following reserved fields:
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.
The SD_RESET operation provides an interface for issuing resets and quiesces to the Serial DASD controller or its storage device. The controller is the /dev/serdasdcN file, where N is 0 or a positive integer. To send a reset or quiesce to a controller, the controller must be opened in SC_DIAGNOSTIC mode. To send a reset or quiesce to a controller's DASD, the controller can be opened with root authority in either SC_DIAGNOSTIC mode or normal 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.
The following fields of the sd_ioctl_parms structure are used with this ioctl command.
| reset_type | Contains one of the following values:
| ||||||||
| status_validity | Indicates either successful completion or the status of the adapter or
controller. This field may have one of the following values:
| ||||||||
| 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. | ||||||||
| resvd1 | Specifies the logical unit number (LUN) of the DASD to be reset if the reset type is SD_DASD_RESET. |
If the SD_RESET operation with a SD_RESET_OP or SD_QUIESCE reset type is issued when the device is not in Diagnostic mode, the operation returns a value of -1 and sets the errno global variable to value of EACCES.
The ioctl subroutine, open, openx subroutine.
Serial DASD Subsystem Device Driver.
Device-Dependent Subroutines for Serial DASD Operations
Device-Dependent Subroutines for Serial DASD Adapter Operations.
Error Conditions for Serial DASD Subroutines.
Reliability, Availability, and Serviceability (RAS) Daemon for the Serial DASD Subsystem.
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.