home *** CD-ROM | disk | FTP | other *** search
/ Microsoft Programmer's Library 1.3 / Microsoft-Programers-Library-v1.3.iso / drivers / scsi / futrdomn / manual / oemstruc.txt < prev   
Encoding:
Text File  |  1990-08-18  |  9.5 KB  |  201 lines
  1. The key to the operation of the oemscsi routine is the structured data table
  2. which is formatted as follows:
  3.  
  4.     struct oemtable
  5.          {
  6.          unsigned char (far *cmdblock)[ ];
  7.          unsigned char (far *datablock)[ ];
  8.          long expectlen;
  9.          long actuallen;
  10.          int timeout;
  11.          int blkfactora;
  12.          int blkfactorb;
  13.          unsigned char scsistatus;
  14.          unsigned char scsimsg;
  15.          unsigned char scsibits;
  16.          unsigned char scsiaddress;
  17.          unsigned char scsiparity;
  18.          int adaptererr;
  19.          };
  20.  
  21. The following sections explain the parameters that are in the structure. It is
  22. assumed that any routines written in "C" are compiled with the /Zp option in 
  23. the MicroSoft Compiler to specify packed arrays.
  24.  
  25. unsigned char (far *cmdblock)[]
  26.  
  27.     Far pointer to a character array that contains the bytes that are to be 
  28.     sent to the device during the command phase of the SCSI bus operation. 
  29.     Data is sent from this array, one byte at a time, until the SCSI bus 
  30.     phase changes from command phase to another phase.
  31.  
  32. unsigned char (far *datablock)[]
  33.  
  34.     Far pointer to a character array where data from the SCSI bus data phase
  35.     is either to be written into, or read from. The direction of the operation
  36.     is determined automatically by the oemscsi routine by checking the 
  37.     direction specified by the SCSI I/O status line during the data phase.
  38.  
  39. long expectlen
  40.  
  41.     The expected length of the data phase in number of bytes transferred is 
  42.     specified. This is a type "long" variable. This may either be the actual 
  43.     expected length of the transfer, or the size of the buffer into or from 
  44.     which the transfer is to take place. This number should not exceed 
  45.     the length of the actual buffer. If the data phase is longer than the 
  46.     specified buffer size, the extra data is read on an input, or the data 
  47.     phase is filled with unknown data on an output.
  48.  
  49. long actuallen
  50.  
  51.     The actual length of the transfer, in number of bytes transferred, is 
  52.     returned to the caller. This is a type "long" variable. If this exceeds 
  53.     the value expectlen, the data in excess of expectlen has been discarded 
  54.     and is not valid or predictable. If this number is less than expectlen, 
  55.     then only actuallen bytes of data are valid.
  56.  
  57. int timeout
  58.  
  59.     There is an expected length of time that a specific operation should take
  60.     on the SCSI bus. If for some reason the operation exceeds this length of 
  61.     time, there may be a problem and some type of error correction may need to
  62.     take place.  This is the timeout interval in seconds to wait for an 
  63.     operation to complete. 
  64.  
  65.     Timeout value: 1    this value is an indefinite time period.
  66.                    0    this value is no time period.
  67.                 1-65534 is a time period expressed in seconds.
  68.  
  69.     There are two timeouts that are built into the scsioem routine. They are
  70.     the timeout waiting for the device to respond to the assertion of the 
  71.     SCSI Select line with a SCSI Busy, and the timeout waiting for the SCSI
  72.     bus free phase. These timeouts are both 3 seconds.
  73.  
  74. int blkfactora
  75. int blkfactorb
  76.  
  77.     The TMC adapters use a high speed transfer technique that depends on a 
  78.     block of data being transferred in rapid succession with no more than an 
  79.     8 microsec delay between bytes of data. At the end of the block, the 
  80.     software will pause for a maximum of timeout seconds waiting for the 
  81.     device to again assert the SCSI Request line indicating that there is more
  82.     data available.
  83.  
  84.     Two values are provided for the blocking factor. In most cases, both 
  85.     values will be the same. The routine first transfers a block of 
  86.     blkfactora bytes in length and then transfers a block of blkfactorb bytes
  87.     in length. For example, in doing a read from a disk system with 512 byte 
  88.     sectors, both values would be set to 512.
  89.  
  90.     For example, some devices may have a characteristic where the block size 
  91.     may be 4096, but only the first 4095 bytes can be transferred in a burst 
  92.     mode, and the last byte needs to be transferred separately. In this 
  93.     example, blkfactora would be 4095, and blkfactorb would be 1.
  94.     
  95.     Some commands may not block the transfer of their information. An example
  96.     of this might be the Request Sense command or the Mode Select command. The
  97.     data for these commands is often handled in a byte by byte fashion in 
  98.     target controllers. In these situations, both blocking factors should be
  99.     set to 1. This assures that the system will wait for any hardware delays 
  100.     as well as check for any bus phase changes after the transfer of each 
  101.     byte.
  102.  
  103.     Some commands check the incoming data on a byte by byte basis such as the 
  104.     Mode Select command. At any byte, should there be an error, the target 
  105.     device may abort the data phase and go directly to the status message 
  106.     phase. As a result, the length of the data phase in number of bytes  may
  107.     be unknown. If this is true, set both blocking factors to 1. This causes 
  108.     the routine to check the phase of the bus after each byte to see if it has
  109.     changed to the status phase.
  110.  
  111.     There is another class of SCSI devices, normally of low performance such 
  112.     as some of the Optical Disk Drives that may block their data for transfer,
  113.     but not guarantee less than 8 usec between bytes. A blocking factor of 1 
  114.     would handle the device, but because there is complete checking for bus
  115.     phase changes between each byte, the performance is unacceptable. As an
  116.     alternate to this approach, an option is implemented in oemscsi that will 
  117.     check only for the assertion of SCSI Request in a tight loop before doing
  118.     the data read or write. This feature is enabled by setting bit 15 of the
  119.     blocking factor. For example, on a device that has 2048 byte sectors and 
  120.     falls into this performance category, the following code would be used.
  121.  
  122.                     blkfactora= 2048 |0x8000;
  123.                     blkfactorb= 2048 |0x8000;
  124.  
  125.     Note:This method should not be used unless the limitations of the device 
  126.          require it. This  operation is slower for high speed devices that the
  127.          standard block moves.
  128.  
  129. unsigned char scsistatus
  130.  
  131.     The SCSI status byte returned from the device at the conclusion of the 
  132.     transfer is returned here. The format of this byte will be specified in 
  133.     your device manual.
  134.  
  135. unsigned char scsimsg
  136.  
  137.     The SCSI message byte returned from the device at the conclusion of the 
  138.     transfer is returned here. This byte is normally zero. If it is not, 
  139.     refer to your device manual for a discussion of its meaning.
  140.  
  141. unsigned char scsibits
  142.  
  143.     If there is a timeout condition (indicated by the error return status in 
  144.     int adaptererr), the SCSI bus status bits are returned for examination to
  145.     determine what is causing the error. Note that the oemprint routine prints
  146.     out the bus status to indicate the condition of these bits. They are as 
  147.     follows:
  148.  
  149.                     Bit       7-                Not used
  150.                     Bit       6-                Adapter Parity error status
  151.                     Bit       5-                SCSI Select
  152.                     Bit       4-                SCSI Request
  153.                     Bit       3-                SCSI Command/Data
  154.                     Bit       2-                SCSI I/O
  155.                     Bit       1-                SCSI Message
  156.                     Bit       0-                SCSI Busy
  157.  
  158. unsigned char scsiaddress
  159.  
  160.     This is the device's SCSI address. Valid values are 0-7. Check the 
  161.     configuration of your device and your device manual to determine how to 
  162.     set and determine this address. 
  163.  
  164. unsigned char scsiparity
  165.  
  166.     Should parity be checked on the SCSI bus? This is a function of your 
  167.     device and the specific TMC product that is being used. Do not specify 
  168.     parity checking for a device or adapter that does not support parity, as
  169.     each transfer will return an error condition. The summary of adapters in
  170.     section 1 lists which support parity. Set this =0 for no parity checking
  171.     and !=0 for parity checking.
  172.  
  173. int adaptererr
  174.  
  175.     Error status related to the transfer is returned. If there is no error,
  176.     a 0 is returned. Valid error  values are as follows:
  177.  
  178.           -01       Timeout waiting for initial bus free phase
  179.           -02       Timeout during Selection phase
  180.           -03       Timeout during Command phase
  181.           -04       Timeout during Data phase
  182.           -05       Timeout during Status phase
  183.           -06       Timeout during Message phase
  184.           -07       Parity error detected during transfer
  185.           -16       Error locating TMC host adapter
  186.           +01       Buffer overflow, actuallen > expectlen
  187.           +02       Buffer underflow, actuallen < expectlen
  188.  
  189.     Note:For assembly language users of the Tool Kit, the "adaptererr" value
  190.          stored in an oemtable structure by the oemscsi routine is also 
  191.          returned in the [AX] register, and Carry is set if this value of 
  192.          non-zero.
  193.  
  194. In order to execute a SCSI command, full in the command bytes, set the 
  195. pointers to the command array and the buffer, set the expected length, set the
  196. blocking factor terms, set the scsiaddress character to the address of your 
  197. device, set the scsiparity character, and execute the command. An example of 
  198. the operation is included in the attached test routine, oemtest.c. A copy of 
  199. this routine is included on your OEM distribution diskette.
  200.  
  201.