scdisk SCSI Device Driver

A device can be opened in Diagnostic mode only if the target device is not currently opened. If an attempt is made to open a device in Diagnostic mode and the target device is already open, the subroutine returns a value of -1 and sets the errno global variable to a value of EACCES.

A device can be opened in Exclusive Access mode only if the device is not currently open. If an attempt is made to open a device in Exclusive Access mode and the device is already open, the subroutine returns a value of -1 and sets the errno global variable to a value of EBUSY. If the SC_DIAGNOSTIC flag is specified along with the SC_SINGLE flag, the device is placed in Diagnostic mode.

The DKIOWRSE operation is provided for diagnostic use. It allows the limited use of the target device while operating in an active system environment. The arg parameter to the DKIOWRSE operation contains the address of an sc_rdwrt structure. This structure is defined in the /usr/include/sys/scsi.h file.

The devinfo structure defines the maximum transfer size for a write operation. If an attempt is made to transfer more than the maximum, the subroutine returns a value of -1 and sets the errno global variable to a value of EINVAL. Refer to the Small Computer System Interface (SCSI) Specification for the format of the request-sense data for a particular device.

Provides a means to issue the LOG SENSE command on devices that has been successfully opened. Any application issuing this ioctl operation need to pass the address of the struct sc_log_sense (defined in /usr/include/sys/scsi.h) and the structure is filled as follows:

1. page_code and subpage_code for the requested LOG Page
2. pc set to the value CUMUL_VAL.
3. allocation_length – If this field is set to zero only the log page header consisting of the page code and the log page length is returned. If this field is non zero, this should equal the length of the log page excluding the log page header of size 4 bytes. If the user specifies an allocation length less than the actual log page length, then only the requested length of log data is returned.
4. log_data contains the address of the memory allocated for storing the data returned from the ioctl operation.

If the requested log page is SCSI_BSR_LOG_PAGE (defined in /usr/include/sys/scsi.h) then the log_data points to the struct sc_bsr_log_data allocated by the caller. The caller also allocates the memory for the struct sc_bms_log_data such that total of sizeof struct sc_bsr_log_data and memory allocated for the struct sc_bms_log_data will be equal to the allocation_length.

Otherwise (for log pages other than SCSI_BSR_LOG_PAGE) , it points to a chunk of memory equal to allocation_length.

Following is the example code for filling the sc_log_sense structure:

struct sc_log_sense log_sense;

melog_sense, '\0', sizeof(struct sc_log_sense));
log_sense.page_code = SCSI_BSR_LOG_PAGE ;
log_sense.subpage_code = 0; 
log_sense.pc = CUMUL_VAL;
log_sense.allocation_length = 16; 
if (log_sense.allocation_length) 
 {  
 if (log_sense.page_code == SCSI_BSR_LOG_PAGE)
  {    
   log_sense.log_data = (struct sc_bsr_log_data *) malloc(sizeof(struct sc_bsr_log_data));  
  }
  else 
  { 
   log_sense.log_data = (char *) malloc(log_sense.allocation_length); 
  }      
  if (log_sense.log_data == NULL)   
  exit(-1); 
  if (log_sense.page_code == SCSI_BSR_LOG_PAGE)
  {
   bms_param_len = log_sense.allocation_length - sizeof(struct sc_scan_status);
   ((struct sc_bsr_log_data *)(log_sense.log_data))-> bms_log_data = (struct sc_bms_log_data *)
	 malloc(bms_param_len); 
  if (((struct sc_bsr_log_data *)(log_sense.log_data))-> bms_log_data == NULL)
  exit(-1);
  }
 }
 rc = ioctl(fd, DKLOGSENSE,&log_sense);

Provides a means to issue the LOG SELECT command.

struct sc_log_select log_select;

memset(&log_select, '\0', sizeof(struct sc_log_select));
log_select.page_code = SCSI_BSR_LOG_PAGE;
log_select.subpage_code = 0;
log_select.pcr = 1;
log_select.sp = 0;
log_select.pc = CUMUL_VAL;
log_select.param_length = 0;
if (log_select.param_length) 
{
 log_select.log_data = (char *)malloc(log_select.param_length);
 if (log_select.log_data == NULL) exit(-1);
} 
rc = ioctl(fd, DKLOGSELECT,&log_select);   

If this operation is attempted on a device other than CD-ROM, it is interpreted as a DKIORDSE operation. In this case, the arg parameter is treated as an sc_rdwrt structure.

If the CDIOCMD operation is attempted on a device not in Diagnostic mode, the subroutine returns a value of -1 and sets the errno global variable to a value of EACCES. Refer to the Small Computer System Interface (SCSI) Specification for the format of the request-sense data for a particular device.

The DKIORDSE operation is provided for diagnostic use. It allows the limited use of the target device while operating in an active system environment. The arg parameter to the DKIORDSE operation contains the address of an sc_rdwrt structure. This structure is defined in the /usr/include/sys/scsi.h file.

The devinfo structure defines the maximum transfer size for a read operation. If an attempt is made to transfer more than the maximum, the subroutine returns a value of -1 and sets the errno global variable to a value of EINVAL. Refer to the Small Computer System Interface (SCSI) Specification for the format of the request-sense data for a particular device.

The SCSI status byte and the adapter status bytes are returned through the arg parameter, which contains the address of a sc_iocmd structure (defined in the /usr/include/sys/scsi.h file). If the DKIOCMD operation fails, the subroutine returns a value of -1 and sets the errno global variable to a nonzero value. In this case, the caller should evaluate the returned status bytes to determine why the operation was unsuccessful 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, the subroutine returns a value of -1 and sets the errno global variable to a value of EINVAL. Refer to the Small Computer System Interface (SCSI) Specification for the format of the request-sense data for a particular device.

If the arg parameter for this operation is null, the format unit sets the format options valid (FOV) bit to 0 (that is, it uses the drive's default setting). If the arg parameter for the DKFORMAT operation is not null, the first byte of the defect list header is set to the value specified in the first byte addressed by the arg parameter. This allows the creation of applications to format a particular type of read/write optical media uniquely.

The driver initially tries to set the FmtData and CmpLst bits to 0. If that fails, the driver tries the remaining three permutations of these bits. If all four permutations fail, this operation fails, and the subroutine sets the errno global variable to a value of EIO.

If the DKFORMAT operation is specified for a fixed disk, the subroutine returns a value of -1 and sets the errno global variable to a value of EINVAL. If the DKFORMAT operation is attempted when the device is not in Exclusive Access mode, the subroutine returns a value of -1 and sets the errno global variable to a value of EACCES. If the media is write-protected, the subroutine returns a value of -1 and sets the errno global variable to a value of EWRPROTECT. If the format unit exceeds its timeout value, the subroutine returns a value of -1 and sets the errno global variable to a value of ETIMEDOUT. For any other failure of this operation, the subroutine returns a value of -1 and sets the errno global variable to a value of EIO.

If DKAUDIO operation is attempted when the device's audio-supported attribute is set to No, the subroutine returns a value of -1 and sets the errno global variable to a value of EINVAL. If the DKAUDIO operation fails, the subroutine returns a value of -1 and sets the errno global variable to a nonzero value. In this case, the caller should evaluate the returned status bytes to determine why the operation failed and what recovery actions should be taken.

CD-ROM Data Mode 1

512-byte block size through both raw (dev/rcd*) and block special (/dev/cd*) files

CD-ROM Data Mode 2 Form 1

2048-byte block size through both raw (dev/rcd*) and block special (/dev/cd*) files

CD-ROM Data Mode 2 Form 2

2336-byte block size through the raw (dev/rcd*) special file only

CD-DA (Compact Disc Digital Audio)

2352-byte block size through the raw (dev/rcd*) special file only

DVD-ROM

2048-byte block size through both raw (/dev/rcd*) and block special (/dev/cd*) files

DVD-RAM

2048-byte block size through both raw (/dev/rcd*) and block special (/dev/cd*) files

DVD-RW

2048-byte block size through both raw (/dev/rcd*) and block special (/dev/cd*) files

The DK_CD_MODE arg parameter contains the address of the mode_form_op structure defined in the /usr/include/sys/scdisk.h file. To have the DK_CD_MODE operation determine or change the CD-ROM data mode, set the action field of the change_mode_form structure to one of the following values:

CD_GET_MODE

Returns the current CD-ROM data mode in the cd_mode_form field of the mode_form_op structure, when the device has been successfully opened.

CD_CHG_MODE

Changes the CD-ROM data mode to the mode specified in the cd_mode_form field of the mode_form_op structure, when the device has been successfully opened in the Exclusive Access mode.

If a CD-ROM has not been configured for different data modes (via mode-select density codes), and an attempt is made to change the CD-ROM data mode (by setting the action field of the change_mode_form structure set to CD_CHG_MODE), the subroutine returns a value of -1 and sets the errno global variable to a value of EINVAL. Attempts to change the CD-ROM mode to any of the DVD modes will also result in a return value of -1 and the errno global variable set to EINVAL.

If the DK_CD_MODE operation for CD_CHG_MODE is attempted when the device is not in Exclusive Access mode, the subroutine returns a value of -1 and sets the errno global variable to a value of EACCES. For any other failure of this operation, the subroutine returns a value of -1 and sets the errno global variable to a value of EIO.

The SCSI status byte and the adapter status bytes are returned through the arg parameter, which contains the address of a sc_passthru structure (defined in the /usr/include/sys/scsi.h file). If the DK_PASSTHRU operation fails, the subroutine returns a value of -1 and sets the errno global variable to a nonzero value. If this happens the caller should evaluate the returned status bytes to determine why the operation was unsuccessful and what recovery actions should be taken.

If a DK_PASSTHRU operation fails because a field in the sc_passthru structure has an invalid value, the subroutine will return a value of -1 and set the errno global variable to EINVAL. The einval_arg field will be set to the field number (starting with 1 for the version field) of the field that had an invalid value. A value of 0 for the einval_arg field indicates no additional information on the failure is available.

DK_PASSTHRU operations are further subdivided into requests which quiesce other I/O prior to issuing the request and requests that do not quiesce I/O. These subdivisions are based on the devflags field of the sc_passthru structure. When the devflags field of the sc_passthru structure has a value of SC_MIX_IO, the DK_PASSTHRU operation will be mixed with other I/O requests. SC_MIX_IO requests that write data to devices are prohibited and will fail. When this happens -1 is returned, and the errno global variable is set to EINVAL. When the devflags field of the sc_passthru structure has a value of SC_QUIESCE_IO, all other I/O requests will be quiesced before the DK_PASSTHRU request is issued to the device. If an SC_QUIESCE_IO request has its timeout_value field set to 0, the DK_PASSTHRU request will be failed with a return code of -1, the errno global variable will be set to EINVAL, and the einval_arg field will be set to a value of SC_PASSTHRU_INV_TO (defined in the /usr/include/sys/scsi.h file). If an SC_QUIESCE_IO request has a nonzero timeout value that is too large for the device, the DK_PASSTHRU request will be failed with a return code of -1, the errno global variable will be set to EINVAL, the einval_arg field will be set to a value of SC_PASSTHRU_INV_TO (defined in the /usr/include/sys/scsi.h file), and the timeout_value will be set to the largest allowed value.

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.

When the device is successfully opened, the DKPRES_READKEYS operation provides a means to read the Persistent Reserve Registration Keys on the device. The arg parameter to the DKPRES_READKEYS contains the address of the dk_pres_in structure. This structure is defined in /usr/include/sys/scdisk.h. The user must provide a buffer area and size for the registered keys to be returned. The returned_length variable sets the number of bytes returned.

In a shared-access or clustered environment, this operation identifies all registered keys for a particular lun.

When the device is successfully opened, the DKPRES_READRES operation provides a means to read the Persistent Reserve Reservation Keys on the device. The arg parameter to the DKPRES_READKEYS contains the address of the dk_pres_in structure. This structure is defined in /usr/include/sys/scdisk.h. The user must provide a buffer area and size for the reservation information to be returned. The returned_length variable sets the number of bytes returned. In a shared-access or clustered environment, this operation identifies the primary initiator that holds the reservation.

When the device is successfully opened, the DKPRES_CLEAR operation provides a means to clear all Persistent Reserve Reservation Keys and Registration Keys on the device. The arg parameter to DKPRES_CLEAR contains the address of the dk_pres_clear structure. This structure is defined in /usr/include/sys/scdisk.h.

When the device is successfully opened, the DKPRES_PREEMPT operation provides a means to preempt a Persistent Reserve Reservation Key or Registration Key on the device. The arg parameter to the DKPRES_PREEMPT contains the address of the dk_pres_preempt structure. This structure is defined in /usr/include/sys/scdisk.h. The user must provide the second party initiator key on the device to be preempted. If the second party initiator holds the reservation to the device, then the initiator that issues the preemption becomes the owner of the reservation. Otherwise, the second party initiator access is revoked.

In order for this operation to succeed, the initiator must be registered with the device first before any preemption can occur. In a shared-access or clustered environment, this operation is used to preempt any operative or inoperative initiator, or any initiator that is not recognized to be part of the shared group.

This operation is the same as the DKPRES_PREEMPT, except the device follows the SCSI Primary Command Specification in aborting tasks that belong to the preempted initiator.

When the device is successfully opened, the DKPRES_REGISTER operation provides a means to register a Key with the device. The Key is extracted from ODM Customize Attribute and passed to the device driver during configuration. The arg parameter to the DKPRES_REGISTER contains the address of the dk_pres_register structure. This structure is defined in /usr/include/sys/scdisk.h.

In a shared-access or clustered environment, this operation attempts a registration with the device, then follows with a read reservation to determine whether the device has been reserved. If the device is not reserved, then a reservation is placed with the device.

The arg parameter contains the address of a sc_rwbuffer structure (defined in the /usr/include/sys/scsi.h file). Before the DK_RWBUFFER ioctl is invoked, the fields of this structure should be set according to the desired behavior. The mode field corresponds to the mode field of the SCSI Command Descriptor Block (CDB) as defined in the SCSI Primary Commands (SPC) Specification. Supported modes are listed in the header file /usr/include/sys/scsi.h.

The device driver will quiesce all other I/O from the initiator issuing the Write Buffer ioctl until the entire operation completes. Once the Write Buffer ioctl completes, all quiesced I/O will be resumed.

The SCSI status byte and the adapter status bytes are returned through the arg parameter, which contains the address of a sc_rwbuffer structure (defined in the /usr/include/sys/scsi.h file). If the DK_RWBUFFER operation fails, the subroutine returns a value of -1 and sets the errno global variable to a nonzero value. In this case, the caller should evaluate the returned status bytes to determine why the operation was unsuccessful and what recovery actions should be taken.

If a DK_RWBUFFER operation fails because a field in the sc_rwbuffer structure has an invalid value, the subroutine will return a value of -1 and set the errno global variable to EINVAL.

The DK_RWBUFFER ioctl allows the user to issue multiple SCSI Write Buffer commands (CDBs) to the device through a single ioctl invocation. This is useful for applications such as microcode download where the user provides a pointer to the entire microcode image, but, due to size restrictions of the device buffer(s), desires that the images be sent in fragments until the entire download is complete.

If the DK_RWBUFFER ioctl is invoked with the fragment_size member of the sc_rwbuffer struct equal to data_length, a single Write Buffer command will be issued to the device with the buffer_offset and buffer_ID of the SCSI CDB set to the values provided in the sc_rwbuffer struct.

If fragment_size is set to zero, an errno of EINVAL will be returned. If the desire is to send the entire buffer with one SCSI Write buffer command, this field should be set equal to data_length. An error of EINVAL will also be returned if the fragment_size is greater than the data_length.

The Parameter List Length (fragment_size) plus the Buffer Offset can not exceed the capacity of the specified buffer of the device. It is the responsibility of the caller of the Write Buffer ioctl to ensure that the fragment_size setting satisfies this requirement. A fragment_size larger than the device can accommodate will result in a SCSI error at the device, and the Write Buffer ioctl will simply report this error but take no action to recover.

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 and sets the errno global variable to a value of EINVAL. Refer to the Small Computer System Interface (SCSI) Specification for the format of the request sense data for a particular device.

• An attempt was made to open a device currently open in Diagnostic or Exclusive Access mode.
• An attempt was made to open a Diagnostic mode session on a device already open.
• The user attempted a subroutine other than an ioctl or close subroutine while in Diagnostic mode.
• A DKIOCMD or CDIOCMD operation was attempted on a device not in Diagnostic mode.
• A DK_CD_MODE ioctl subroutine operation was attempted on a device not in Exclusive Access mode.
• A DKFORMAT operation was attempted on a device not in Exclusive Access mode.

• An attempt was made to open a session in Exclusive Access mode on a device already opened.
• The target device is reserved by another initiator.

• A DKAUDIO (play-audio) operation was attempted for a device that is not configured to use the SCSI-2 play-audio commands.
• The read or write subroutine supplied an nbyte parameter that is not an even multiple of the block size.
• A sense data buffer length of greater than 255 bytes is not valid for a CDIORDSE, DKIOWRSE, or DKIORDSE ioctl subroutine operation.
• The data buffer length exceeded the maximum defined in the devinfo structure for a CDIORDSE, CDIOCMD, DKIORDSE, DKIOWRSE, or DKIOCMD ioctl subroutine operation.
• An unsupported ioctl subroutine operation was attempted.
• A data buffer length greater than that allowed by the CD-ROM drive is not valid for a CDIOCMD ioctl subroutine operation.
• An attempt was made to configure a device that is still open.
• An illegal configuration command has been given.
• A DKPMR (Prevent Media Removal), DKAMR (Allow Media Removal), or DKEJECT (Eject Media) command was sent to a device that does not support removable media.
• A DKEJECT (Eject Media) command was sent to a device that currently has its media locked in the drive.
• The data buffer length exceeded the maximum defined for a strategy operation.

• The target device cannot be located or is not responding.
• The target device has indicated an unrecoverable hardware error.

• The target device has indicated an unrecoverable media error.
• The media was changed.

• An attempt was made to access an undefined device.
• An attempt was made to close an undefined device.

• The ioctl subroutine supplied an invalid parameter.
• A read or write operation was attempted beyond the end of the fixed disk.

• An open operation requesting read/write mode was attempted on read-only media.
• A write operation was attempted to read-only media.

• 0000, which indicates problem-determination procedures should be performed
• 1601, which indicates the removable media should be replaced and retried

• 5000, which indicates a media failure
• 6310, which indicates a disk drive failure

• 0000, which indicates problem-determination procedures should be performed
• 1601, which indicates the removable media should be replaced and retried

Note:

The Detail_Data field in the err_rec structure contains the sc_error_log_df structure. The err_rec structure is defined in the /usr/include/sys/errids.h file. The sc_error_log_df structure is defined in the /usr/include/sys/scsi.h file.

The sc_error_log_df structure contains the following fields:

req_sense_data

Contains the request-sense information from the particular device that had the error, if it is valid.

reserved2

Contains the segment count, which is the number of megabytes read from the device at the time the error occurred.

reserved3

Contains the number of bytes read since the segment count was last increased.

• 6310, which indicates a disk drive failure
• 6330, which indicates a disk drive electronics failure

Note:

The Detail_Data field in the err_rec structure contains the sc_error_log_df structure. The err_rec structure is defined in the /usr/include/sys/errids.h file. The sc_error_log_df structure is defined in the /usr/include/sys/scsi.h file.

The sc_error_log_df structure contains the following fields:

req_sense_data

Contains the request-sense information from the particular device that had the error, if it is valid.

reserved2

Contains the segment count, which is the number of megabytes read from the device at the time the error occurred.

reserved3

Contains the number of bytes read since the segment count was last increased.

• 3452, which indicates a device cable failure
• 6310, which indicates a disk drive failure

• 3452, which indicates a storage device cable failure
• 6310, which indicates a disk drive failure
• 6330, which indicates a disk-drive electronics failure

Note:

The Detail_Data field in the err_rec structure contains the sc_error_log_df structure. The err_rec structure is defined in the /usr/include/sys/errids.h file. The sc_error_log_df structure is defined in the /usr/include/sys/scsi.h file.

The sc_error_log_df structure contains the following fields:

req_sense_data

Contains the request-sense information from the particular device that had the error, if it is valid.

reserved2

Contains the segment count, which is the number of megabytes read from the device at the time the error occurred.

reserved3

Contains the number of bytes read since the segment count was last increased.

• 5000, which indicates a media failure
• 6310, which indicates a disk drive failure

• 0000, which indicates problem-determination procedures should be performed
• 1601, which indicates the removable media should be replaced and retried

• 5000, which indicates a media failure
• 6310, which indicates a disk drive failure

• 0000, which indicates problem-determination procedures should be performed
• 1601, which indicates the removable media should be replaced and retried

Note:

The Detail_Data field in the err_rec structure contains the sc_error_log_df structure. The err_rec structure is defined in the /usr/include/sys/errids.h file. The sc_error_log_df structure is defined in the /usr/include/sys/scsi.h file.

The sc_error_log_df structure contains the following fields:

req_sense_data

Contains the request-sense information from the particular device that had the error, if it is valid.

reserved2

Contains the segment count, which is the number of megabytes read from the device at the time the error occurred.

reserved3

Contains the number of bytes read since the segment count was last increased.

• 3300, which indicates an adapter failure
• 5000, which indicates a media failure
• 6310, which indicates a disk drive failure

• 0000, which indicates problem-determination procedures should be performed
• 1601, which indicates the removable media should be replaced and retried

Note:

The Detail_Data field in the err_rec structure contains the sc_error_log_df structure. The err_rec structure is defined in the /usr/include/sys/errids.h file. The sc_error_log_df structure is defined in the /usr/include/sys/scsi.h file.

The sc_error_log_df structure contains the following fields:

req_sense_data

Contains the request-sense information from the particular device that had the error, if it is valid.

reserved2

Contains the segment count, which is the number of megabytes read from the device at the time the error occurred.

reserved3

Contains the number of bytes read since the segment count was last increased.