Copyright ã1994 by Christopher Wolf
($Id: DriveSCSI.rtf,v 0.4 94/12/07 02:01:31 chris Exp $)

DriveSCSI

Inherits From:	SCSI : Object

Declared In:	SCSI2_Class/Source/DriveSCSI.h 

Class Description

DriveSCSI is a subclass of SCSI class used to send SCSI commands which are specific to disk type devices.  DriveSCSI currently contains methods for determining if a device is a disk-type device, formatting a disk-type device, seeking to a specific location on a disk-type device, and reading data from a specific location on a disk-type device.  The DriveSCSI class is intended as an example of how to implement other SCSI sub-classes for issuing commands to specific device types.

Instance Variables

none

Method Types

Checking if a device is a disk  	±  isDevice

Sending disk commands 	- formatUnit
- seekExtended:
±  readExtended:numBytes:numBlocks:from:
±  read:numBytes:numBlocks:from:

Instance Methods

isDevice
- (BOOL)isDevice

Returns TRUE if the current target device is a disk-type SCSI device, FALSE if the device is of a different type or if there is no device present.  This method must be implemented by all SCSI sub-classes in order to over-ride the generic isDevice method provided by SCSI class.  This is necessary so that the findDevice and findDevice: methods in SCSI class will work to properly locate and return the target ID of disk-type devices on the SCSI bus.  The source code for this method should be used as an example of how to correctly implement this method for other SCSI sub-classes. 

formatUnitInterleave:clearGList:cert:immed:
- (int)formatUnitInterleave:(u_int)interleave clearGList:(BOOL)clearGList cert:(BOOL)mediaCert 

This is a pre-packaged SCSI command method which sends the SCSI Format Unit command to the current target device.  This command erases all data on the target and so should be used with the utmost caution.   The format command will use the interleave value specified in interleave.  A value of 0 for this parameter tells the drive to use its default interleave.  If clearGList is TRUE the drive's grown defect list will be erased.  If mediaCert is TRUE the drive will be instructed to perform its media certification and error-remapping procedures, if supported, while formatting.  The grown defect list should not be erased unless media certification or some other form of defect remapping is going to be performed to reestablish a new grown defect list.  This method will return as soon as the drive has acknowledged receiving the Format Unit command if immediate mode has been enabled with the SCSI.m setImmediate: method.  Otherwise this method will not return until the drive has finished formatting.  Note that if the command returns immediately additional precautions will have to be taken by the programmer to check that the format completed without errors.  This method will return 0 if successful or non-zero if there was an error.  Additional error information can be retrieved using the standard methods provided in the SCSI class.

Since this is a pre-packaged command method it takes care of all the messy low-level details of building and sending the SCSI request.  It is not necessary for the SCSI device to be open before calling this method.  If the SCSI device was open when this method was called the device will remain open after the method exits.     The source code for this method is a good example of how to correctly implement other pre-packaged SCSI command methods for this or other SCSI sub-classes.

readExtended:numBytes:numBlocks:from:
- (int)readExtended: (char *)destBuffer numBytes:(u_int)numBytes numBlocks:(u_int)numBlocks from: (u_int)lba

This is a pre-packaged SCSI command method which sends the Read Extended(10) command to the current target device.  This command will cause the disk to seek to the specified logical block address (lba) and read the amount of data specified in numBytes and numBlocks into a sufficiently large memory buffer at destBuffer.  The amount of data to be read must be specified in both numBytes and numBlocks - behavior is undefined if these values do not agree.   (To calculate the number of blocks take the length of data and divide by the length of the block, which can be found via a Read Capacity command, and round the resulting value up.  No error checking is performed to make sure that the destination buffer is large enough to hold all the data being read.  This method will return 0 if successful or non-zero if there was an error.  Additional error information can be retrieved using the standard methods provided in the SCSI class.

Since this is a pre-packaged command method it takes care of all the messy low-level details of building and sending the SCSI request.  It is not necessary for the SCSI device to be open before calling this method.  If the SCSI device was open when this method was called the device will remain open after the method exits.   The source code for this method  is a good example of how to correctly implement other pre-packaged SCSI command methods for this or other SCSI sub-classes.

read:to:numBytes:numBlocks:from:
- (int)read:(char *)destBuffer numBytes:(u_int)numBytes numBlocks:(u_int)numBlocks from: (u_int)lba

This is a pre-packaged SCSI command method which sends the Read(6) command to the current target device.  This command will cause the disk to seek to the specified logical block address (lba) and read the amount of data specified in numBytes and numBlocks into a sufficiently large memory buffer at destBuffer.  The amount of data to be read must be specified in both numBytes and numBlocks - behavior is undefined if these values do not agree.   (To calculate the number of blocks take the length of data and divide by the length of the block, which can be found via a Read Capacity command, and round the resulting value up.  No error checking is performed to make sure that the destination buffer is large enough to hold all the data being read.  This method will return 0 if successful or non-zero if there was an error.  Additional error information can be retrieved using the standard methods provided in the SCSI class.

Since this is a pre-packaged command method it takes care of all the messy low-level details of building and sending the SCSI request.  It is not necessary for the SCSI device to be open before calling this method.  If the SCSI device was open when this method was called the device will remain open after the method exits.   The source code for this method  is a good example of how to correctly implement other pre-packaged SCSI command methods for this or other SCSI sub-classes.

seekExtended:
- (int)seekExtended:(u_int)logicalBlockAddress

This is a pre-packaged SCSI command method which sends the Seek Extended command to the current target device.  This command will cause the disk to seek to the specified logicalBlockAddress.  This method will return 0 if successful or non-zero if there was an error.  Additional error information can be retrieved using the standard methods provided in the SCSI class.

Since this is a pre-packaged command method it takes care of all the messy low-level details of building and sending the SCSI request.  It is not necessary for the SCSI device to be open before calling this method.  If the SCSI device was open when this method was called the device will remain open after the method exits.   The source code for this method  is a good example of how to correctly implement other pre-packaged SCSI command methods for this or other SCSI sub-classes.