home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / dos / communic / rsdrv / rsdrv.doc < prev    next >
Encoding:
Text File  |  1990-03-26  |  6.5 KB  |  177 lines
  1. rsdrv.doc : last update 1.3. 1990
  2.  
  3. Rsdrv.c contains the source code for the basic functions needed
  4. to perform interrupt driven io on the serial ports of the ibm pc
  5. and compatibles. It is written in Borland turbo C, but it should
  6. be relatively easy to port the code for other compilers, as long 
  7. as they have the interrupt function type and a way to access the
  8. i/o-address space similar to those in turbo C. The code should run 
  9. in all memory models. It has been tested with turbo C 1.0, small 
  10. memory modell. 
  11.  
  12. While the package can be used 'as is', my intention was also to 
  13. provide a template for anyone in need of interrupt driven serial
  14. io in order to reduce the need to 're-invent the wheel'. So, feel
  15. free to use and modify the code as appropriate for your purposes.
  16. If you'd like to give me credit, you can mention the origin of 
  17. the code. This is not required, however. Also, I'd like to point
  18. out that the code can be used even for commercial purposes (or
  19. whatever) without any fee.
  20.  
  21. The code and documentation of rsdrv are provided 'as is' with no
  22. warranty of any kind. Comments, suggestions and bug-fixes are
  23. wellcome.
  24.  
  25.  
  26.                             J. Leppäjärvi / so-jml@stekt.oulu.fi
  27.  
  28.  
  29.  
  30.  
  31.  
  32. General overview
  33. ------------------------------------------------------------------------------
  34.  
  35. The package is initialized with rsinit() for a certain port
  36. and communication parameters. The subsequent operations use
  37. these settings in their operation. When the program using 
  38. the package is about to terminate and return to dos, it 
  39. should call rsend(), which disables the interrupts from the 
  40. serial interface, otherwize some part of the subsequently 
  41. loaded programs might be called as an interrupt service routine
  42. ( = system crash).
  43.  
  44. rsgetc() is used to read the arriving characters. rsputc() 
  45. writes charaters to the port. Actually, the read/write 
  46. operations are buffered : rsgetc() reads characters from a 
  47. buffer filled by the an interrupt routine invoked by the rs 
  48. interface every time a character arrives, while rsputc() 
  49. places characters in a buffer emptied by the interrupt 
  50. routine as the interface is ready to transmit them. 
  51.  
  52. Input buffer overflow causes the oldest character to be lost, 
  53. while output buffer does not actually overflow : rsputc() just 
  54. returns an error condition when the buffer is full. In this case
  55. the call to rsputc() can be repeated as long as the buffer full
  56. condition presists.
  57.  
  58. The input/output buffers are staticly defined in rsdrv.c. By 
  59. default there is a 128 byte buffer both for incoming and outgoing 
  60. data. This can be changed by editing the defines for RXBUF (input 
  61. buffer size) and TXBUF (output buffer size). Optimum buffer sizes 
  62. depend on the nature of the rs-interaction : bigger buffers should 
  63. be allocated if the program spends long times in other actions than 
  64. reading / writing the rs-ports, such as performing disk operations.
  65. On the other hand, the default sizes are quite sufficent (if not 
  66. overkill) for a terminal program that doesn't have other activities 
  67. than copying the incoming data on the display and sending the keyboard 
  68. input out via the rs-line. (In fact the output buffer is rarely, if 
  69. ever needed in this particular case.)
  70.  
  71. The header file rsdrv.h should be included in modules using the
  72. the functions of the package to provide appropriate definitions 
  73. and function prototypes.
  74.  
  75.  
  76.  
  77. Compiling
  78. ------------------------------------------------------------------------------
  79.  
  80. The code is written in a fashion that should enable using it in 
  81. all memory modells. If the package is to be used 'as is' it could
  82. be compliled with the command line version of turbo C as follows :
  83.  
  84.    tcc -c -Z -O rsdrv.c
  85.  
  86. This produces the small model object file rsdrv.obj, which can be 
  87. linked in your programs e.g. by placing it with it's complete path
  88. in the .prj file used in the integrated environment. (Refer to compiler 
  89. documentation for other memory models and other details.)
  90.  
  91.  
  92.  
  93.  
  94. Function descriptions
  95. ------------------------------------------------------------------------------
  96.  
  97.  
  98. rsbreak
  99. ------------------------------------------------------------------------------
  100.  
  101. void rsbreak(int isbreak);
  102.  
  103. rsbreak is used to send a break. It sets/resets the transmit break
  104. bit in the line control register of the 8250. In practice breaks
  105. of various lengths can be send by first calling rsbreak with 1, 
  106. waiting the desired time and calling rsbreak with 0. 
  107.  
  108.  
  109.  
  110. rsgetc
  111. ------------------------------------------------------------------------------
  112.  
  113. int rsgetc(void);
  114.  
  115. rsgetc reads one character from serial port and returns it. If 
  116. none is available rsgetc returns -1. The character codes for 
  117. actual characters vary from 0 - 255.
  118.  
  119.  
  120.  
  121. rsinit
  122. ------------------------------------------------------------------------------
  123.  
  124. int rsinit(int port,int speed,unsigned char pbyte);
  125.  
  126. rsinit initializes the package. It must be called before 
  127. using the other functions in the package. port is the com 
  128. port number to be used (1 - 4), speed is the communication 
  129. speed (baud rate) and pbyte is a value defining the rest of 
  130. the communication parameters, constructed by bitwize ORing 
  131. the following flags :
  132.  
  133.    BITS_7         : 7 data bits
  134.    BITS_8         : 8 data bits
  135.    
  136.    PARITY_NONE    : no parity
  137.    PARITY_ODD     : odd parity
  138.    PARITY_EVEN    : even parity
  139.    
  140.    STOP_1         : one stop bit
  141.    STOP_2         : two stop bits
  142.  
  143.  
  144. In its present state rsinit returns -1 if the port number is 
  145. out of range, zero otherwize.
  146.  
  147.  
  148.  
  149. rsend
  150. ------------------------------------------------------------------------------
  151.  
  152. void rsend(void);
  153.  
  154. rsend terminates the use of interrupt driven rs input/output.
  155. It must be called before returning to DOS to disable interrupts
  156. from the serial interface. Doing otherwize is likely to cause
  157. a system crash.
  158.  
  159.  
  160.  
  161. rsputc
  162. ------------------------------------------------------------------------------
  163.  
  164. int rsputc(unsigned char c);
  165.  
  166. rsputc writes one character to the rs-port. If the character is
  167. successfully written rsputc returns zero. If the character cannot
  168. be written for the moment (output buffer full) rsputc returns -1.
  169.  
  170.  
  171. ------------------------------------------------------------------------------
  172. rsdrv.c was written in Turbo C by J. Lepp{j{rvi (so-jml@stekt.oulu.fi) 
  173. (C) 1990. It and the related documentation may be used, copied and modified 
  174. freely for any purpose. The code and the documentation are provided 'as is' 
  175. without a warranty of any kind.
  176. ------------------------------------------------------------------------------
  177.