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:
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 DASD. The /usr/include/sys/scsi.h file defines possible values for the ext parameter. The parameter can contain any combination of the following flag values logically ORed together:
| SC_DIAGNOSTIC | Places the selected DASD in Diagnostic mode. This mode is singularly entrant. When a DASD is in Diagnostic mode, no Serial DASD subsystem operations are performed during open or close operations, and error logging is disabled. In Diagnostic mode only the close and ioctl operations are accepted. All other DASD-supported subroutines return a value of -1, and the errno global variable is set to EACCES. |
| SC_FORCED_OPEN | Forces a DASD reset regardless of whether another initiator has the DASD reserved, thereby overtaking the reservation. The DASD reset is sent to the DASD before the open sequence begins. Otherwise, the open sequence executes normally. |
| SC_RETAIN_RESERVATION | Retains the reservation of the DASD after a close operation by not issuing the release. This flag prevents other initiators from using the DASD unless they break the host machine's reservation. |
| SD_NO_RESERVE | Prevents the reservation of a DASD during an openx subroutine call to a DASD. This operation is provided so a DASD can be controlled by two processors that synchronize their activity by their own software means. This is defined in the /usr/include/sys/serdasd.h file as the SC_NO_RESERVE flag, which is defined in the /usr/include/sys/scsi.h file. |
The readx and writex subroutines provide additional parameters affecting the raw data transfer. These subroutines pass the ext parameter, which specifies request options. Construct these options by using logical OR with any of the following values:
| WRITEV | Indicates a request for write verification. |
| HWRELOC | Indicates a request for hardware relocation (safe relocation only). |
| UNSAFEREL | Indicates a request for unsafe hardware relocation. |
The ioctl subroutine can call the IOCINFO, SD_SCSICMD, SD_RESET, SD_SET_FENCE, SD_CLEAR_FENCE, DD_CONC_REGISTER, and DD_CONC_UNREGISTER 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 the ioctl subroutine. Information for DASD is returned through the scdk structure within the devinfo structure.
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 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, then 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:
The SD_RESET ioctl provides an interface for issuing resets and quiesces to the DASD. The DASD is the /dev/hdiskN file, where N is 0 or a positive integer. To send a reset or quiesce to a DASD, the DASD 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
| ||||||||
| status_validity | Indicates either successful completion or the status of the adapter or
controller. This field may have one of the following values:
|
Note: If the timeout field of the sc_iocmd 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.
If a 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.
The SD_SET_FENCE ioctl provides an interface for establishing a fence for Serial DASD. The fence is established via the Mask and Swap Fence command with the Force Fence bit off. The DASD is the /dev/hdiskN file, where N is 0 or a positive integer. 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 SD_SET_FENCE ioctl uses the following fields of the sd_ioctl_parms structure:
| resvd1 | Indicates that the caller sets the 16-bit fence mask used by the Mask and Swap
fence command. The fence mask specifies which bits in the fence register to change to the
value specified in the fence data. The bit can have one of the following values:
| ||||
| resvd2 | Indicates that the caller sets the 16-bit fence data used by the Mask and Swap
fence command. The bits in the fence data specify which hosts are fenced out. The bit can
have one of the following values:
| ||||
| status_validity | Indicates either the successful completion of the fence command or the existence of adapter or controller status. | ||||
| adapter_status | Indicates the adapter status, if valid, upon completion of the Fence command. | ||||
| resvd3 | Contains the fence position indicator returned by the Fence command. | ||||
| resvd4 | Contains the old fence value returned by the Fence command. | ||||
| resvd5 | Contains the current fence for the DASD. |
If the SD_SET_FENCE ioctl is successful, the Serial DASD device driver reissues the Fence anytime it detects a power off and subsequent power on of a Serial DASD.
Note: If successive SD_SET_FENCE ioctls are issued without any SD_CLEAR_FENCE ioctls in between, the Serial DASD maintains the fence as a composite of all the uncleared SD_SET_FENCE ioctls.
If the Serial DASD does not support fencing, the SD_SET_FENCE ioctl returns a value of -1 and sets the errno global variable to a value of EINVAL. If the resvd1 and resvd2 fields of the sd_ioctl_parms structure would fence out this host, this ioctl would return a value of -1 and sets the errno global variable to a value of EINVAL.
For more information on the Fence command, see "Serial DASD Fence Command" .
The SD_CLEAR_FENCE ioctl provides an interface for removing the fence established by the SD_SET_FENCE ioctl for a DASD. The DASD is the /dev/hdiskN file, where N is 0 or a positive integer. The DASD can be opened in normal mode for the ioctl subroutine. 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 SD_CLEAR_FENCE ioctl uses the following fields:
| status_validity | Indicates either the successful completion of the Fence command or the existence of adapter or controller status. |
| adapter_status | Indicates the adapter status, if valid, upon completion of the Fence command. |
| controller_status | Indicates the controller status, if valid, upon completion of the Fence command. |
| resvd3 | Contains the fence position indicator returned by the Fence command. |
| resvd4 | Contains the old fence value returned by the Fence command. |
If a fence has not been established with the SD_SET_FENCE ioctl, the SD_CLEAR_FENCE ioctl returns a value of -1 and sets the errno global variable to a value of EINVAL. If the device does not support fencing, a value of -1 is returned, and the errno global variable is set to a value of EINVAL.
Note: If successive SD_SET_FENCE ioctls are issued without any SD_CLEAR_FENCE ioctls in between, the Serial DASD maintains the fence as a composite of all the uncleared SD_SET_FENCE ioctls. The SD_CLEAR_FENCE ioctl clears the composite fence.
The DD_CONC_REGISTER ioctl provides an interface for registering one kernel extension with the Serial DASD device driver for a given DASD. The DASD is the /dev/hdiskN file, where N is 0 or a positive integer. Registration is needed to enable the concurrent mode of operation for Serial DASDS that are shared between hosts. The arg parameter for this ioctl is a pointer to a dd_conc_register structure, which is defined in the /usr/include/sys/ddconc.h file. The kernel extension calling this ioctl must set the conc_intr_addr field of this structure to its special interrupt handler for processing concurrent mode commands. See "Serial DASD Concurrent Mode of Operation Interface" for more information.
If the ioctl returns with a value of 0, the conc_func_addr field of the dd_conc_register structure contains the Serial DASD device driver's special entry point for issuing concurrent mode commands. A value of -1 is returned, and the errno global variable is set to a value of EINVAL for the following occurrences:
The DD_CONC_REGISTER ioctl provides an interface for unregistering one kernel extension with the SERIAL DASD device driver for a given DASD. The DASD is the /dev/hdiskN file, where N is 0 or a positive integer.
A value of -1 is returned, and the errno global variable is set to a value of EINVAL for the following occurrences:
The close subroutine, ioctl subroutine, open or openx subroutine, readx subroutine, writex subroutine.
Device-Dependent Subroutines for Serial DASD Controller 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.
Serial DASD Subsystem Device Driver.
Serial Direct Access Storage Device (DASD) Overview in AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.
SD Error Identifiers for the Error Log in AIX Problem Solving Guide and Reference.