rs232.doc

RS232.C was written to provide all of the basic functionality needed to employ serial I/O in any a

                          RS232.C v1.6 User Documentation
                        copyright C. Karcher 1992,93,94,95



    >   About RS232.C:

        RS232.C was written to provide all of the basic functionality needed
        to employ serial I/O in any application written with Borland 'C'
        language compilers.  Some features are:

        1. Ease of use.  No assembly language or library files are used and a
        simple "#include" statement is all that is required to access all of
        the functions provided.

        2. Both input and output are buffered and interrupt driven for
        efficiency.

        3. Serial ports 1 - 4 are supported on PC, AT and PS/2 compatibles.
        Chained interrupts used on port 3 and 4 are allowed for so as not to
        interfere with devices such as a mouse or printer.  Transmission
        speeds of 110 to 115200 baud are available.

        4. Detection and utilization of hardware buffered UARTs (NS16550AF
        etc.) found in some machines is automatic.

        5. Interrupt driven hardware and XON/XOFF flow control is provided for.

        6. All source code is included.  RS232.C can be used with all memory
        models.


        This is user supported software and may be distributed freely in a
        whole and unmodified state.  It may be used in part or wholly, free of
        royalty, to develop any commercial applications provided that the
        developer has registered RS232.C.  Registration entitles the developer
        to any future enhancements or upgrades which may be released.
        Registration also includes technical support as far as can be provided
        via mail, telephone or electronic messaging.  To register RS232.C,
        send a check or money order for $20.00 to (please indicate the
        version level or date of the version you have - if an updated
        version is available, it will be mailed to you):

             Chris A. Karcher
             9537 Evanston Ave. N.
             Seattle WA 98103-3131

        Compuserve members can register RS232.C through Compuserve by
        typing GO SWREG and selecting Register Shareware from the menu.
        The registration ID for RS232.C is 4460.

        The author may be contacted by mail at the above address, by telephone
        at [phone] or via Compuserve EMAIL to user ID 76406,536, or
        by mail on Internet at [e-mail].

        The author of RS232.C makes no expressed or implied warranty of any
        kind with regard to the software or accompanying documentation.  In no
        event shall the author be held liable for incidental or consequential
        damages in connection or arising out of performance or use of any part
        of this software.

        The distribution should include the following files:

            RS232.C   - serial communication routines source code
            RS232.DOC - documentation (this file)
            RS_DEMO.C - sample program demonstrating RS232.C

    >   Why use RS232.C?

        Borland's C compilers (and probably all DOS based C compilers) do
        provide some basic support for serial communications but that support
        makes use of calls to BIOS routines only.  The BIOS serial routines
        are adequate only for the slowest of transmission speeds and do not
        exploit all of the capabilities of the hardware found in PC's.  If
        efficient serial communication is required, the programmer must
        provide all of the low level software.  RS232.C does just that by
        taking care of all the low level details and providing the programmer
        with all the high level functions needed for efficient serial I/O.

    >   How to use RS232.C:

        All that is required to use RS232.C is to include it in your source
        code.  The simplest way to do that is with a compiler '#include'
        directive, treating RS232.C just as you would a header file.  Having
        done that, three basic steps are all that are required to perform
        serial I/0:

             1. Allocate memory for input and output buffers.  (It can be
             pre-allocated at compile time or allocated via some memory
             allocation function like malloc at runtime.)

             2. "Open" the port with the function rs_initport, using the
             desired communication parameters.

                 perform I/O with functions provided
                    .     .    .      .        .
                    .     .    .      .        .
                    .     .    .      .        .

             3. "Close" the port when finished performing I/O with the
             function rs_close before ending the program.

        The file RS_DEMO.C, included with the distribution, is a sample
        terminal program demonstrating most of the functions available with
        RS232.C.

        The following code demonstrates an extremely simple but functional
        program which turns a PC into a dumb terminal capable of communicating
        with a modem or another computer:

         /*
           TERM: a light weight dumb terminal program to demonstrate rs232.c
           C. Karcher
         */

        #include<conio.h>
        #include"src\rs232.c"       /* include rs232 variables and functions */

        main()
        {

           int key = 0;
           char input_buffer[1024],output_buffer[1024]; /* allocate buffers */

           /* open port 1 with 2400 baud, no parity, 8 data bits, 1 stop bit,
              a 1024 byte input buffer and a 1024 byte output buffer */

           if(rs_initport(RS_PORT1,RS_B2400,RS_NOPAR,RS_DBIT8,RS_SBIT1,
                                 1024U,input_buffer,1024U,output_buffer) > 0)
             cprintf("Terminal mode active - press escape to exit\r\n");
           else{
             cprintf("Unable to open COM port\r\n");
             return 0;
             }

          /* turn on Data Terminal Ready */
          rs_modctrl(RS_WRTMCR,RS_MCRDTR,RS_LINON);

              /* display any characters received and send any keystrokes
                 typed until escape is pressed */

              do{
                if(rs_inrcvd())               /* if a character was received */
                  putch(rs_getbyt());         /*    display it */
                if(rs_keyhit())               /* if a key has been pressed */
                  rs_sndbyt((key = getch())); /*    send it */
                }while(key != 27);            /* if the key pressed was ESC,
                                                 end */

              /* turn off Data Terminal Ready */
              rs_modctrl(RS_WRTMCR,RS_MCRDTR,RS_LINOFF);

              /* close the port and exit */
              rs_close();
              return 0;

            } /* end TERM */

    >   RS232.C Functions:

        The following is a list of the functions contained in RS232.C and a
        brief explanation of the purpose of each one.  A detailed description
        of each function and it's use follows:

        rs_initport - Prepares a COM port for use.
        rs_sndbyt   - Sends a single byte.
        rs_sndstr   - Sends a string of bytes.
        rs_getbyt   - Gets a single byte.
        rs_getstr   - Gets a string of bytes.
        rs_inrcvd   - Returns number of bytes which been received.
        rs_peek     - Non-destructive read of next character in input.
        rs_outfre   - Returns amount of free space remaining in output buffer.
        rs_scanin   - Scans buffer for a string and returns offset if found.
        rs_error    - Returns code for last error detected.
        rs_modctrl  - Controls or returns status of modem control lines.
        rs_break    - Sends break to remote equipment.
        rs_clrout   - Clears output buffer.
        rs_clrin    - Clears input buffer.
        rs_keyhit   - Determines if a key has been pressed.
        rs_timer    - Times events or operations.
        rs_setflow  - Establishes or returns status of flow control.
        rs_close    - "Closes" port prepared by rs_initport.

    >   Function Reference: (Note: The pre defined constants shown in
                             parentheses with some of the function argument
                             descriptions or return value descriptions are
                             defined in RS232.C and may be used for
                             convenience.)

      >   rs_initport:

        >   Purpose:
              Prepares a COM port for use.

        >   Prototype:
              int rs_initport(char port, long baud, char parity, char data_bits,
                             char stop_bits, unsigned in_buf_size, char *in_buf,
                             unsigned out_buf_size, char *out_buf);

        >   Arguments:
               port: Character indicating which port to use.  May be one of
                     the following:
                       '1' (RS_PORT1) - COM port 1
                       '2' (RS_PORT2)
                       '3' (RS_PORT3)
                       '4' (RS_PORT4) - COM port 4
                       '0' (RS_USERPORT) - user defined port -- see notes
               baud: The long value indicating the baud rate.  Can be any of
                     the following:
                       110L (RS_B110) - 110 baud
                       300L (RS_B300)
                       600L (RS_B600)
                       1200L (RS_B1200)
                       2400L (RS_B2400)
                       4800L (RS_B4800)
                       9600L (RS_B9600)
                       19200L (RS_B19K)
                       38400L (RS_B38K)
                       57600L (RS_B57K)
                       115200L (RS_B115K) - 115200 baud
             parity: A character indicating the type of parity checking to use
                     as follows:
                       'N' (RS_NOPAR) - no parity
                       'E' (RS_EVPAR) - even parity
                       'O' (RS_ODPAR) - odd parity
                       'S' (RS_SPPAR) - parity bit always space
                       'M' (RS_MKPAR) - parity bit always mark
          data_bits: A character indicating how many data bits to use in each
                     byte:
                       '8' (RS_DBIT8) - 8 data bits
                       '7' (RS_DBIT7) - 7 data bits
          stop_bits: A character indicating the number of stop bits to use:
                       '1' (RS_SBIT1) - 1 stop bit
                       '2' (RS_SBIT2) - 2 stop bits
         in_buf_siz: An unsigned integer between 2 and 32768 indicating the
                     size in bytes of the input buffer.  The value must be a
                     power of 2 (i.e. 2,4,8,16,256,512,1024 etc.).
             in_buf: Character pointer to the input buffer allocated by the
                     application.
        out_buf_siz: The unsigned value between 2 and 32768 indicating the
                     size in bytes of the output buffer.  The value must be a
                     power of 2 (i.e. 2,4,8,16,256,512,1024 etc.).
            out_buf: Character pointer to the output buffer.

             Note: If RS_POLLED_XMIT is defined, the output buffer is not used
             for serial output.  In this case the output buffer size may be 0
             and the output buffer pointer may be NULL.

        >    Return value:
               rs_initport can return the following integer values indicating
               the success or failure of the operation:
                 4 (RS_UART4) Success, UART detected was a 16550 capable of
                   hardware buffering.  This capability is automatically
                   utilized.
                 3 (RS_UART3) Success, UART detected was a 16550 incapable of
                   hardware buffering.
                 2 (RS_UART2) Success, UART detected was an 8250A or 16450.
                 1 (RS_UART1) Success, UART detected was an 8250B
                 0 (RS_NOUART) Failure, no UART detected.
                -1 (RS_BADIBUF) Failure, input buffer size invalid or input
                   buffer pointer is a NULL pointer.
                -2 (RS_BADOBUF) Failure, output buffer size invalid or output
                   buffer pointer is a NULL pointer.
                -3 (RS_BADPORT) Failure, invalid port argument.
                -4 (RS_BADPAR) Failure, invalid parity argument.
                -5 (RS_BADDBIT) Failure, invalid data_bits argument.
                -6 (RS_BADSBIT) Failure, invalid stop_bits argument.
                -7 (RS_BADBAUD) Failure, invalid baud argument.

        >    Examples:

               if(rs_initport(RS_PORT1,RS_B2400,RS_NOPAR,RS_DBIT8,RS_SBIT1,
                              1024U,input_buffer,1024U,output_buffer) > 0)
                 cprintf("Terminal mode active - press escape to exit\r\n");

               port_ok = rs_initport(port,RS_B2400,RS_NOPAR,RS_DBIT8,RS_SBIT1,
                                               BUF_SIZ,in_buf,BUF_SIZ,out_buf);

        >    Notes:

             If a port has already been "opened" with rs_initport, it will
             automatically be closed before another port (or the same port) is
             opened.  Only one port may be opened at any one time although the
             interrupt service routine installed by rs_initport can coexist
             with others sharing the same IRQ (interrupt request).  An example
             of this would be serial mouse installed on COM port 1 and an
             application using rs_initport to prepare access to COM port 3.
             In this case, both the mouse driver and the application would be
             using IRQ4.  Some serial applications "take over" the interrupt
             completely which would disable use of the mouse.  The interrupt
             service routine installed by rs_initport "chains" the interrupt
             so that if it is invoked by other than the targeted device,
             control is passed to the appropriate routine.