Topic       : A system-global SCSI-driver SCSI-Driver
Author      : Steffen Engel
Version     : Text-Release 1.10e
Subject     : Documentation/Utilities
Nodes       : 31
Index Size  : 708
HCP-Version : 3
Compiled on : Atari
@charset    : atarist
@lang       : en
@default    : Title
@help       : 
@options    : -i +zz -t2
@width      : 70
View Ref-File3.8  In                                                    SCSI-Driver

Sends a SCSI command and receives the incoming data.

A pointer to a SCSI command structure that contains all the required 
information about the desired accesds is passed as a parameter.

Remember: Parms is not a const *, so the contents of the 
parameterblock may be changed by the driver!

  LONG  cdecl (*In)           (tpSCSICmd  Parms);

  typedef struct
  {  tHandle Handle;              /* Handle for bus and device */
    BYTE  *Cmd;                   /* Pointer to CmdBlock */
    UWORD CmdLen;                 /* Length of Cmd-Block */
    void  *Buffer;                /* Data buffer */
    ULONG TransferLen;            /* Transfer length */
    BYTE  *SenseBuffer;           /* Buffer for ReqSense (18 Bytes) */
    ULONG Timeout;                /* Timeout in 1/200 sec */
    UWORD Flags;                  /* Bit-vector for desired sequence
                                     of transfer */
      #define Disconnect 0x10     /* Try to disconnect */

  }tSCSICmd;
  typedef tSCSICmd *tpSCSICmd;

 Handle:        The handle of the addressed device.

 Cmd:           Pointer to the command block to be passed.

 CmdLen:        Length of the command block.  (The command length is 
                actually not needed for a SCSI driver. But since ACSI 
                cannot operate target controlled, some hard disk 
                drivers do not use this feature even on true SCSI 
                ports and future device drivers for clones 
                (Mac/Gemulator/STOnX) may also require this value, it 
                must always be included.)

 Buffer:        Pointer to the transfer buffer.

 TransferLen:   Number of bytes to be transferred.

 SenseBuffer:   Buffer for RequestSense data.

                This is filled automatically when the device reports 
                CheckCondition.

 Timeout:       Maximum wait-state for executing the command in 1/200 
                sec.

 Flags:         Bit-vector with additional information/requests.

Note: The length of the command block is really necessary only for 
ACSI, or for drivers that cannot be controlled from the target. Hence 
it must always be passed correctly.  ( According to the SCSI standards
the addressed target controls the bus phases. This means that the 
target continues to request command bytes until it has received the 
number of bytes belonging to that command.

Hence it is not necessary for the SCSI routines to know the length of 
the command.

With ACSI the bus phase cannot be interrogated, hence the command 
length must be specified in every case. )

Returns:

  NOSCSIERROR     0L /* No error */
  SELECTERROR    -1L /* Error during selection */
  STATUSERROR    -2L /* Default error */
  PHASEERROR     -3L /* Invalid phase */
  BSYERROR       -4L /* BSY lost */
  BUSERROR       -5L /* Bus error during DMA transfer */
  TRANSERROR     -6L /* Error during DMA-transfer (nothing
                      * transferred)*/
  FREEERROR      -7L /* Bus not freed */
  TIMEOUTERROR   -8L /* Timeout error */
  DATATOOLONG    -9L /* Data for ACSI Soft-transfer too long */
  LINKERROR     -10L /* Error while sending the Linked command (ACSI)
                      */
  TIMEOUTARBIT  -11L /* Timeout during arbitration */
  PENDINGERROR  -12L /* Error noted on this handle */
  PARITIYERROR  -13L /* Transfer caused parity errors */

  Value greater than zero: Status byte of the SCSI device, for
                           Status 2 (CheckCondition) the RequestSense
                           data are present in the sense-buffer.


EXAMPLE:

Calling Inquiry

WORD Inquiry(tHandle handle, char *inqdata)
{
  tScsiCmd ScsiCmd;
  BYTE CmdBlock[6]={0x12,0,0,0,36,0};   /* Command 18, 36 bytes */
  BYTE ReqBuff[18];

  ScsiCmd.Handle      = handle;       /* Device handle */
  ScsiCmd.Cmd         = CmdBlock;     /* The command */
  ScsiCmd.CmdLen      = 6;            /* 6-byte command */
  ScsiCmd.Buffer      = inqdata;      /* Data buffer */
  ScsiCmd.TransLen    = 36;           /* 36 bytes expected */
  ScsiCmd.SenseBuffer = ReqBuff;      /* For errors go there */
  ScsiCmd.Timeout     = 1000;         /* 5 sec */
  ScsiCmd.Flags       = 0;            /* No special requirements */

  return (ScsiCall->In((tpScsiCmd)&ScsiCmd));
}

ATTENTION: With virtual RAM you must take care of transfer via ST-RAM 
yourself (see section VIRTUAL RAM)