passthru(7) — SPECIAL FILES AND DEVICES
NAME
passthru − passthru support
DESCRIPTION
All Motorola SCSI controllers provide passthru support via the DKPASSTHRU ioctl command. This function permits any scsi command specified by a device manufacturer to be passed directly to the device for processing. This command requires superuser permissions.
IOCTL COMMANDS
All DKPASSTHRU ioctl(2) operations take the form ioctl (fildes, DKPASSTHRU, ∗arg), where ∗arg is a pointer to a scsi_pass structure. The scsi_pass structure is defined in <sys/dk.h>.
You must set up the scsi_pass structure beforeissuing this ioctl. The following is a list of the fields in the scsi_pass structure and their functions:
flags
This field contains the size of the SCSI command descriptor block (CDB) in bits 4-7 (bit four is the low order bit). These bits are defined by the mask SPT_CDB_LEN in <sys/dk.h>. The only valid values for this sub-field are 6, 10, and 12. If this sub-field contains any other value, the ioctl fails, returning -1 and setting errno to ERANGE. Another bit is defined by the SPT_READ mask defined in <sys/dk.h>. This bit must be set if the direction of data transfer for this CDB is from the device to the host system. If this bit is set incorrectly, the ioctl fails, returning -1 and setting errno to EIO and error_info to SPTERR_CTLR (controller error). The SPT_LONG_TIMEOUT bit is defined in <sys/dk.h>. If this bit is set, it tells the driver that the SCSI command takes a long time (e.g., FORMAT UNIT), and so the command timeout should be long enough to compensate. The SPT_ERROR_QUIET bit is defined in <sys/dk.h>. If this bit is set, error’s that occur will not cause a message to be logged. All other flags bits are currently reserved and should be zero. If any reserved bit is set, the ioctl fails, returning EINVAL.
xfer_len
This field contains the number of bytes that are to be transferred to or from the device. The direction of transfer is determined by the SPT_READ bit in the flags field. If this field is zero, no data transfer is attempted. Note that the setting of this field depends on the SCSI command. The xfer_len count must be an even number. If the transfer length in the CDB is an odd number, xfer_len must be rounded up to be even. The buffer must of course be large enough to allow this adjustment. If the transfer count is odd, the ioctl fails, returning -1 and setting errno to EINVAL. If xfer_len is zero when the CDB is set up to transfer data, the ioctl fails, returning -1 and setting errno to EIO and error_info to SPTERR_CTLR (controller error). If xfer_len is not equal to the number of bytes the SCSI command defined by the CDB transfers, it could cause a SCSI bus hang.
data
This field points to a buffer of size xfer_len in the caller’s address space. The buffer must be page-aligned (use the NBPP define in <sys/param.h>). If the SPT_READ bit in the flags field is clear (0), the buffer contains data to be sent as part of the command (for example, a defect list sent as part of a FORMAT UNIT command). If this bit is set (1), it indicates that the buffer will receive the data returned from the device as a result of executing the command.
resid
This field points to an integer in the caller’s address space. This integer is set to the number of bytes that were not transferred as a result of the SCSI command. This is the difference between the value of xfer_len and the number of bytes that were successfully transferred to or from the device. If this integer is set to zero after a command completes, xfer_len bytes were successfully transferred. If it is equal to xfer_len, no bytes were successfully transferred. This field may not be valid if errno is EFAULT. If this field contains a bad pointer (e.g., NULL), the ioctl fails when it attempts to set this field, returning -1 and setting errno to EFAULT.
sense_data
This field is a pointer to a structure of type struct ext_sense in the caller’s address space that is used to accept SCSI sense data in the event of a SCSI error. This structure is defined in <sys/dk.h>. If there is a SCSI error while executing the command, and the status is 0x02 (SCSI Check Condition), the error_info field is set to SPTERR_SCSI and the sense data is copied to this buffer. Note that this buffer is only modified by this command in the event of a SCSI error with Check Condition status.. Therefore, the caller should clear this buffer before executing this ioctl. If this field contains a bad pointer (e.g., NULL) and there is a SCSI Check Condition status while executing the command, the ioctl fails, returning -1 and setting errno to EFAULT.
cdb
This field is an array of 12 bytes that contains the SCSI CDB that is to be passed to the device. Only the number of bytes specified in bits 4-7 of the flags field are actually copied out of this array into the IOPB that is passed to the device. The device driver does no checking of the contents of the CDB. It simply passes it to the device.
status
This field is a pointer to a byte that is used to accept the SCSI status byte in the case of a SCSI error. This field is valid in the case of a SCSI or controller error (when error_info is set to SPTERR_SCSI or SPTERR_CTLR), and it is not updated if the command completes successfully or with a driver error. If this field contains a bad pointer (e.g., NULL) and there is a SCSI error or a controller error while executing the command, the ioctl fails when it tries to copy the status out to the user’s address space, returning -1 and setting errno to EFAULT. Note that some status values are never returned by the device driver because they are handled by the controller (e.g., busy). See the ANSI SCSI specification for a list of status codes.
error_info
This field is a pointer to an unsigned integer in the caller’s address space that is used to indicate the resulting status of the ioctl. This field is always updated, even if no error occurs. If the command fails (ioctl returns -1), this field indicates what type of error occured. The valid values for this field are defined in <sys/dk.h>. If the unsigned integer pointed to by error_info is set to SPTERR_DRIVER, it means that an error occured while setting up the command before sending it to the device. In this case, errno should be examined to determine the cause of the failure. Note that some values of errno can be caused by one of several different error conditions (EINVAL and EFAULT, for instance). If it is set to SPTERR_SCSI or SPTERR_CTLR, then the byte pointed to by the status field contains the SCSI status byte. If this status byte is set to 0x02 (SCSI Check Condition), the sense data for the device is copied into the buffer pointed to by the sense_data field. For this case, errno is set to EIO. If this field contains a bad pointer (e.g., NULL), the ioctl fails, returning -1 and setting errno to EFAULT.
ctlr_code
This field is used to return the controller-specific error code in the case of a SCSI or driver error. This field is only modified if an error occurs and the error_info field is either SPTERR_SCSI or SPTERR_CTLR. If this field contains a bad pointer (e.g., NULL), the ioctl fails, returning -1 and setting errno to EFAULT. See the appropriate hardware users guide for a list of valid controller codes.
ERRORS
If the passthru command can access too may memory regions the command will be terminated and EIO will be returned.
If the passthru command fails for any other reason the error results returned by the driver will be returned to the calling program.
FILES
/usr/include/sys/dk.h