scsidisk.library Reference

Comprehensive function reference for scsidisk.library, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/AG/scsidisk).

This page documents 20 functions of scsidisk.library. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.

Function index

CMD_READ()

CMD_READ -- read sectors of data from a disk.

Function

This command reads data from the drive to a supplied buffer.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command CMD_READ io_Flags 0 or IOF_QUICK io_Data pointer to the buffer where the data should be put io_Length number of bytes to read, must be a multiple of the drive block size. io_Offset byte offset from the start of the disk describing where to read data from, must be a multiple of the drive block size.

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in

Notes

This command can only reach data below the 4GB barrier. To read data beyond the barrier, use TD_READ64 instead.

Bugs

Some incarnations of the scsi.device, namely those that handle actually IDE devices, were unable to read more than 255 blocks in one go. This bug has been fixed in V47.

CMD_START()

CMD_START -- start a drive, if possible.

Function

This command causes the drive to attempt spinning up the motor and return from an idle operation.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command CMD_START io_Flags 0 or IOF_QUICK

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in

Notes

Drives may or may not react on this command. A possible reaction is that a parked drive spins up its motor and is then ready to take read or write commands.

CMD_STOP()

CMD_STOP -- stop a drive, if possible.

Function

This command causes the drive to attempt spinning down the motor, park the drive heads and enter an idle state.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command CMD_STOP io_Flags 0 or IOF_QUICK

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in

Notes

Drives may or may not react on this command. A possible reaction is that the drive spins down its motor and parks its drive head. A CMD_START is then required to return the drive into an operational stage.

CMD_UPDATE()

CMD_UPDATE -- write out drive cache to the disk.

Function

This command may instruct the connected drive to flush its internal buffers to the disk, and hence complete a write operation. Whether the drive actually has a drive cache, and performs any operation in response of this command is implementation defined.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command CMD_UPDATE or ETD_UPDATE io_Flags 0 or IOF_QUICK

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in

CMD_WRITE()

CMD_WRITE -- write sectors of data to a disk.

Function

This command transfer data from a supplied buffer to a disk.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command CMD_WRITE io_Flags 0 or IOF_QUICK io_Data pointer to the buffer where the data should be put io_Length number of bytes to write, must be a multiple of the disk block size. io_Offset byte offset from the start of the disk describing where to write data to, must be a multiple of the disk block size.

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in

Notes

This command can only reach data below the 4GB barrier. To write data beyond the barrier, use TD_WRITE64 instead.

Bugs

Some incarnations of the scsi.device, namely those that handle actually IDE devices, were unable to write more than 255 blocks in one go. This bug has been fixed in V47.

HD_SCSICMD()

HD_SCSICMD -- issue a SCSI command to the drive

Function

This command issues a SCSI command to the drive, bypassing the translation from trackdisk to SCSI commands.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command HD_SCSICMD io_Data pointer to a struct SCSICmd io_Length sizeof(struct SCSICmd) io_Flags 0 or IOF_QUICK

SCSI COMMAND INPUT scsi_Data word aligned buffer to be filled or transmitted during the data phase of the scsi command. scsi_Length number of bytes to be transfered during the SCSI data phase scsi_Actual filled upon return with the actual number of bytes transmitted scsi_Command pointer to a word aligned buffer containing the bytes to be transmitted during the SCSI command phase. That is, this buffer contains the SCSI commands to be issued. scsi_CmdLength number of bytes to be transmitted during the SCSI command phase, i.e. the byte size of the command. scsi_CmdActual filled upon return with the actual number of bytes transfered during the command phase. scsi_Flags various flags, such as: SCSIF_WRITE: transfer from RAM to disk SCSIF_READ: transfer from disk to RAM SCSIF_AUTOSENSE: automatically sense error status upon failure scsi_Status returned status of the command, see scsi_SenseData pointer to a word aligned buffer that is filled with sense data upon failure if the SCSIF_AUTOSENSE flag is set. scsi_SenseLength size of the autosense buffer scsi_SenseActual actual number of sense bytes returned

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in or

Notes

The scsi.device may actually not be connected to a SCSI bus at all, but may emulate (some) SCSI commands through appropriate IDE commands. If the connected device speaks ATAPI, then the SCSI commands are directly dispatched as ATAPI commands. Note that ATAPI uses the same command set as SCSI.

However, for non-ATAPI devices, the following table lists
which SCSI commands are emulated through ATA commands:

READ(6)     (0x08)
READ(10)    (0x28)
WRITE(6)    (0x0a)
WRITE(10)   (0x2a)
REQUEST_SENSE   (0x03)
FORMAT_UNIT(6)  (0x04)
TEST_UNIT_READY (0x00)
SEEK(6)     (0x0b)
SEEK(10)    (0x2b)
READ_CAPACITY   (0x25)
MODE_SENSE  (0x1a)
INQUIRY     (0x12)
REZERO_UNIT (0x01)
VERIFY      (0x2f)
RESERVE     (0x16)
SEND_DIAGNOSTIC (0x1d)

The following mode pages are emulated through MODE_SENSE:
    Page 3 (Format Device page)
    Page 4 (Rigid Disk page)

TD_ADDCHANGEINT()

TD_ADDCHANGEINT -- add a disk change software interrupt handler.

Function

This command lets you add a software interrupt handler to the scsi.device that gets invoked whenever a disk insertion or removal occurs.

You must pass in a properly initialized Exec Interrupt structure
and be prepared to deal with disk insertions/removals
immediately. From within the interrupt handler, you may only call the
status commands that can use IOF_QUICK.

To set up the handler, an Interrupt structure must be initialized.
This structure is supplied as the io_Data to the TD_ADDCHANGEINT
command. The handler then gets linked into the handler chain and
gets invoked whenever a disk change happens. You must eventually
remove the handler before you exit.

This command only returns when the handler is removed. That is,
the device holds onto the IO request until the TD_REMCHANGEINT command
is executed with that same IO request. Hence, you must use SendIO()
with this command.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command TD_ADDCHANGEINT io_Flags 0 io_Length sizeof(struct Interrupt) io_Data pointer to Interrupt structure

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in

See also

Cause()

TD_CHANGENUM()

TD_CHANGENUM -- return the current value of the disk-change counter.

Function

This command returns the current value of the disk-change counter (as used by the enhanced commands). The disk change counter is incremented each time a disk is inserted or removed from the device unit.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command TD_CHANGENUM io_Flags 0 or IOF_QUICK

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in io_Actual - if io_Error is 0, this contains the current value of the disk-change counter.

TD_CHANGESTATE()

TD_CHANGESTATE -- check if a disk is currently in a device unit.

Function

This command checks to see if there is currently a disk in a unit.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command TD_CHANGESTATE io_Flags 0 or IOF_QUICK

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in io_Actual - if io_Error is 0, this tells you whether a disk is in the drive. 0 means there is a disk, while anything else indicates there is no disk.

TD_EJECT()

TD_EJECT -- eject (or load) the disk in the drive, if possible.

Function

This command causes the drive to attempt to eject the disk in it, if any.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command TD_EJECT io_Flags 0 or IOF_QUICK io_Length 0 (load, if supported) or 1 (eject)

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in

TD_FORMAT()

TD_FORMAT -- write data to disk.

Function

This command is traditionally used to write data to disk that has not yet been formatted or has had a hard error on a standard write command. However, as scsi and ide drives come pre-formatted, these commands are identical to CMD_READ.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command TD_FORMAT io_Flags 0 or IOF_QUICK io_Data points to a buffer containing the data to write to the disk, must be at least as large as io_Length. io_Length number of bytes to format, must be a multiple of the block size of the drive. io_Offset byte offset from the start of the disk for the block to write to, must be a multiple of the drive block size.

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in

Notes

This command can only reach data below the 4GB barrier. To write data beyond the barrier, use TD_FORMAT64 instead.

Bugs

Some incarnations of the scsi.device, namely those that handle actually IDE devices, were unable to write more than 255 blocks in one go. This bug has been fixed in V47.

TD_FORMAT64()

TD_FORMAT64 -- write data to disk, 64 bit extended

Function

This command is traditionally used to write data to disk that has not yet been formatted or has had a hard error on a standard write command. However, as scsi and ide drives come pre-formatted, these commands are identical to TD_WRITE64.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command TD_FORMAT64 io_Flags 0 or IOF_QUICK io_Data points to a buffer containing the data to write to the disk, must be at least as large as io_Length. io_Length number of bytes to format, must be a multiple of the block size of the drive. io_Offset low 32 bits of the byte offset from the start of the disk to the block to write to. io_Actual high 32 bits of the byte offset.

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in

Bugs

Some incarnations of the scsi.device, namely those that handle actually IDE devices, were unable to write more than 255 blocks in one go. This bug has been fixed in V47.

TD_GETGEOMETRY()

TD_GETGEOMETRY -- return the geometry of the drive.

Function

This command returns a full set of information about the layout of the drive. The information is returned in the DriveGeometry structure pointed to by io_Data.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command TD_GETGEOMETRY io_Flags 0 or IOF_QUICK io_Data Pointer to a DriveGeometry structure io_Length sizeof(struct DriveGeometry)

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in

Note

This information may change when a disk in inserted when certain hardware is present.

The information provided with this command may not actually
reflect the true device geometry as hard disk geometries are
more complex than what can be described by the DriveGeometry
structure. However, the size of the medium described by this
structure is "approximately correct" in the sense that the
sector size is correct (or accepted by the drive), and the
number of blocks due to this structure is not larger than
the physical block count of the drive.

TD_MOTOR()

TD_MOTOR/ETD_MOTOR -- control the on/off state of a drive motor or the drive LED.

Function

This command gives control over the disk motor or the drive status LED. The motor/motor light may be turned on or off.

Turning the drive on is not necessary, the device does this
automatically if it receives a request when the motor is off. Some
drives control the drive LED automatically ignoring the TD_MOTOR
command.

In addition, the standard instructions to the user are that it is safe
to remove a disk from a drive if and only if the motor is off (that is,
if the disk light is off).

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command TD_MOTOR or ETD_MOTOR io_Flags 0 or IOF_QUICK io_Length the requested state of the motor, 0 to turn the motor off, and 1 to turn the motor on. iotd_Count (ETD_MOTOR only) maximum allowable change counter value.

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in io_Actual - if io_Error is 0 this contains the previous state of the drive motor.

TD_PROTSTATUS()

TD_PROTSTATUS -- return whether the current disk is write-protected.

Function

This command is used to determine whether the current disk is write-protected.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command TD_PROTSTATUS io_Flags 0 or IOF_QUICK

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in io_Actual - if io_Error is 0, this tells you whether the disk in the drive is write-protected. 0 means the disk is NOT write- protected, while any other value indicates it is.

TD_READ64()

TD_READ64 -- read sectors of data from a disk.

Function

This command reads data from the drive to a supplied buffer.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command CMD_READ io_Flags 0 or IOF_QUICK io_Data pointer to the buffer where the data should be put io_Length number of bytes to read, must be a multiple of the drive block size. io_Offset low 32 bit of the byte offset from the start of the disk describing where to read data from, must be a multiple of the drive block size. io_Actual high 32 bit of the byte offset where to read data from.

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in

Bugs

Some incarnations of the scsi.device, namely those that handle actually IDE devices, were unable to read more than 255 blocks in one go. This bug has been fixed in V47.

TD_REMCHANGEINT()

TD_REMCHANGEINT -- remove a disk change software interrupt handler.

Function

This command removes a disk change software interrupt added by a previous use of TD_ADDCHANGEINT.

IO REQUEST INPUT The same IO request used for TD_ADDCHANGEINT.

io_Device   preset by the call to OpenDevice()
io_Unit     preset by the call to OpenDevice()
io_Command  TD_REMCHANGEINT
io_Flags    0
io_Length   sizeof(struct Interrupt)
io_Data     pointer to Interrupt structure

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in

TD_SEEK()

TD_SEEK -- control positioning of the drive heads with 64 bit offset

Function

This command is currently provided for internal diagnostics, disk repair, and head cleaning only. Drives may or may not implement them.

TD_SEEK move the drive heads to the track specified. The io_Offset
field should be set to the (byte) offset to which the seek is
to occur. TD_SEEK may not verify their position until the next
read. That is, they may only move the heads; they do not actually read
any data. Actually, some drives may do nothing.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command TD_SEEK io_Flags 0 or IOF_QUICK io_Offset byte offset from the start of the disk describing where to move the head to. This shall be a multiple of the drive block size.

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in

TD_SEEK64()

TD_SEEK64 -- control positioning of the drive heads.

Function

These commands are currently provided for internal diagnostics, disk repair, and head cleaning only. Drives may or may not implement them.

TD_SEEK64 move the drive heads to the track specified. The io_Offset
field should be set to the (byte) offset to which the seek is
to occur. TD_SEEK64 may not verify their position until the next
read. That is, they may only move the heads; they do not actually read
any data. Actually, some drives may do nothing.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command TD_SEEK io_Flags 0 or IOF_QUICK io_Offset low 32 bits of the byte offset from the start of the disk describing where to move the head to. This shall be a multiple of the drive block size. io_Actual high 32 bits of the byte offset to seek to.

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in

TD_WRITE64()

CMD_WRITE -- write sectors of data to a disk, with 64 bit offset

Function

This command transfer data from a supplied buffer to a disk.

IO REQUEST INPUT io_Device preset by the call to OpenDevice() io_Unit preset by the call to OpenDevice() io_Command TD_WRITE64 io_Flags 0 or IOF_QUICK io_Data pointer to the buffer where the data should be put io_Length number of bytes to write, must be a multiple of the disk block size. io_Offset low 32 bits of the byte offset from the start of the disk describing where to write data to, must be the disk block size. io_Actual high 32 bits of the byte offset.

IO REQUEST RESULT io_Error - 0 for success, or an error code as defined in

Bugs

Some incarnations of the scsi.device, namely those that handle actually IDE devices, were unable to write more than 255 blocks in one go. This bug has been fixed in V47.