home *** CD-ROM | disk | FTP | other *** search
/ Power Programming / powerprogramming1994.iso / progtool / c / scsidrvr.arc / scsi.doc < prev    next >
Text File  |  1989-02-10  |  7KB  |  197 lines
  1. INTRODUCTION:
  2.  
  3. This package contains three things:
  4.  
  5. 1. A library of routines to interface to an Ampex Megastore PC SCSI
  6. host adapter, written in Turbo C 1.5.
  7.  
  8. 2. A generic MSDOS device driver, written in C and a little assembler.
  9.  
  10. 3. An actual device driver for SCSI disks that uses 1 and 2 above.
  11.  
  12. Feel free to distribute this however you like.
  13.  
  14. THE AMPEX MEGASTORE HOST ADAPTOR:
  15.  
  16. The Ampex Megastore SCSI host adapter is a relatively "dumb" adapter.
  17. Its virtue is that you can get one for $15 or so from Halted Specialities,
  18. in Santa Clara, CA.  It also has supporting software (what you have here)
  19. that will let you use it to talk to SCSI disks, tapes, etc., hooked up to
  20. your PC.  I use one to communicate with two hard disks and a tape drive on
  21. my AT&T PC6300.
  22.  
  23. This board comes with no documentation.  Here is what I have learned:
  24.  
  25. The board uses I/O ports 0x320 to 0x323.  These addresses clash with
  26. the standard PC hard disk adaptor addresses.  However, you can set
  27. a switch or two on the board to relocate these addresses to 0X620 to
  28. 0x623.  You will have to change a #define in scsi.c if you do this.
  29. Unfortunately, I forget which switches on the board change the address.
  30. Try them and find out.
  31.  
  32. The board also uses DMA channel 3, and an interrupt line.  However,
  33. the included code does not use the interrupt, or allow the board to
  34. generate it.  There are jumpers on the board to change the DMA or interrupt
  35. numbers, if necessary.  If the DMA channel is changed, code in scsi.c
  36. will need a little bit of surgery.
  37.  
  38. Remove the EPROM on the board!  The code in it seems to require a special
  39. non-standard SCSI controller to work.
  40.  
  41. Here is a description of what the I/O ports do, as deduced by me:
  42.  
  43.  
  44. Address        Read            Write
  45. ----------------------------------------------------------------------
  46. 0x320:      Data            Data
  47. 0x321:        SCSI Control Lines    Activate SCSI RESET line
  48. 0x322:        Clear SCSI SEL, RESET    Activate SCSI SEL line
  49. 0x323:        XXXXX            Enable DMA
  50.  
  51.  
  52. Here is more info on reading port 321:
  53.  
  54. Bit    Signal
  55. -----------------------------
  56.  
  57. 0    A switch on the board (I forget which)
  58. 1    Another switch
  59. 2    ???
  60. 3    SCSI MSG line
  61. 4    SCSI BSY line
  62. 5    SCSI C/D line
  63. 6    SCSI R/W line
  64. 7    SCSI REQ line
  65.  
  66.  
  67. Writing any value to ports 321 and 322 seems to trigger the desired function.
  68. See the code in scsi.c for how these signals are used.  The functionality
  69. provided in scsi.c should complete enough so that you do not have to worry
  70. about the above information.
  71.  
  72.  
  73.  
  74.  
  75.  
  76. THE SCSI CODE:
  77.  
  78.     Scsi.c contains two routines:
  79.  
  80.     void scsiop(struct scsireq *req);
  81.     void scsiopv(struct scsivreq *req);
  82.  
  83. The first one is passed a pointer to a structure of data describing
  84. a SCSI operation, and does it.  The second one does the same thing,
  85. but allows you to specify multiple data buffers in separate segments.
  86. This allows you to send or receive more than 64K of data in one operation.
  87.  
  88. These is the structure that is passed to scsiop(): 
  89.  
  90.     struct scsireq {
  91.         char far *dptr;
  92.         char far *cptr;
  93.         unsigned dlen;
  94.         char busid;
  95.         int error;
  96.         int timeout;
  97.     };
  98.  
  99.  
  100. Dptr points to your data buffer.  If the command you are executing
  101. reads or writes no data, this can be NULL.
  102.  
  103. Cptr points to  your command bytes for the SCSI operation.
  104. The code will read as many command bytes from here as the SCSI
  105. device asks for.
  106.  
  107. Dlen is the length of the data buffer.  If you have more than 64K-1
  108. bytes of data, use scsiopv() instead.  The code will not read or write
  109. past the end of the buffer.  If the SCSI device tries to, an overrun
  110. error will be generated.
  111.  
  112. Busid is the SCSI bus ID that the command will be sent to.
  113.  
  114. Upon return, error will be filled in with an error code.
  115.  
  116. Timeout is the number of .1 second units that the code should wait
  117. before giving up and generating a timeout error.  Specifying zero
  118. will give a default five-second timeout.  This timing depends on
  119. loops in the code, and will have to be adjusted for extra fast or
  120. slow PCs.  It is correct for a 8 MHz V30.
  121.  
  122.  
  123. Here is the meaning of the error word:
  124.  
  125. The low 8 bits contain the SCSI Status byte generated by the
  126. SCSI device at the end of the transaction.  The upper 8 bits
  127. are as follows:
  128.  
  129.     /* scsireq error bits */
  130.     #define S_BUSERROR        0x8000
  131.     #define S_BADSTATUS        0x4000
  132.     #define S_BADMESSAGE        0x2000
  133.     #define S_NOCONNECT        0x1000
  134.     #define S_TIMEOUT        0x0800
  135.     #define S_OVERRUN        0x0400
  136.     #define S_BADTRANS        0x0200
  137.  
  138. Note that these bits represent hardware errors or errors in the SCSI
  139. protocol itself.  Errors in the device, such as a bad block,
  140. will cause a non-zero Status byte to be generated.  The SCSI
  141. Get Sense command will have to be used to find out more.
  142.  
  143. These are the arguments to scsiopv():
  144.  
  145.     struct scsivreq {
  146.         struct scsibuf far *bufptr;
  147.         char far *cptr;
  148.         char busid;
  149.         int error;
  150.         int timeout;
  151.     };
  152.  
  153.     struct scsibuf {
  154.         char far *dptr;
  155.         unsigned dlen;
  156.     };
  157.  
  158.  
  159. Scsiopv() works the same as scsiop(), except that instead of taking
  160. a single pointer to a data buffer, it takes a pointer to a list
  161. of data buffers of varying lengths.  The last buffer in the list
  162. should have a length of zero and a NULL address.   These buffers
  163. will be read or written in order.
  164.  
  165.  
  166.  
  167. THE MSDOS DEVICE DRIVER CODE:
  168.  
  169. The makefile included describes how to make the SCSI disk device driver
  170. in this package.  The tricky code is generic, and by changing a couple of,
  171. files, you can make your own device driver.
  172.     The files driasm.s, driver.h, and null.c, and they way the makefile
  173. compiles and links them, should not be changed.  The file dheader.s
  174. should have to be modified only if you need to make a character device
  175. instead of a block device.  The file driver3.c should be modified
  176. to do what you need your driver to do.  The only procedure called externally 
  177. in this file is dointr().  It  is passed a pointer to the request header
  178. that describes what should be done.  The current version basically
  179. vectors to a seperate procedure for each request type.  You should probably
  180. keep this arrangement, and change as little code as possible.  The file
  181. scsi.c is part of this driver, but would of course be omitted if you
  182. were not using a SCSI device.  Note that making "dtest" with the makefile
  183. should produce error-free compiles and link if everything is written correctly.
  184. The file dtest.c can be added to to make a program that will test your driver
  185. without having to load it at boot time.
  186.     All of the above assumes you know enough about how device drivers are
  187. supposed to be written.  I recommend the book "Advanced MS-DOS" by Microsoft
  188. Press as a good reference for learning this.
  189.  
  190.  
  191. Good Luck,
  192.  
  193. Doug Braun
  194. 7976 W. Zayante Rd.
  195. Felton, CA 95018
  196.  
  197.