async.doc

用C++写的RS232串口异步通讯功能模块

                   int flag;          Set/Reset flag

         Example:

                  ASYNC *port;

                  if (WantToDiscardErrChars)
                      async_ignerr(port, 1);
                  else if (WantToKeepErrChars)
                      async_ignerr(port, 0);


         Returns: No return value

         Remarks: This function sets the bit that determines what hap-
                  pens to received characters that have parity or fram-
                  ing errors.  If the function is called with the flag
                  set to one, incoming characters that have framing or
                  parity errors are discarded -- they do not get put
                  into the receive ring buffer.  If the flag is 0, char-
                  acters with errors are not ignored, they are put into
                  the ring buffer.  The error bits in Stat1 that reflect
                  these error conditions are set regardless of the
                  setting of the discard flag.  When a port is first
                  opened, the flag is set to 0.  This function is imple-
                  mented as a macro.

                  See also async_stat.






         async_msr
         ---------------------------------------------------------------

         Purpose: Get the contents of the Modem Status Register.

         Format:  int async_msr(port);
                   ASYNC *port;       Pointer to ASYNC structure

         Example:

                  ASYNC *port;
                  int MSRcontents;

                  MSRcontents = async_msr(port);


         Returns: The contents of the Modem Status Register.

         Remarks: This function is a macro that returns the port struc-
                  ture member, MSRVal.  This value is initialized when a
                  port is first opened and then updated any time a modem
                  status interrupt occurs.  The reason the MSR is not
                  read directly is to avoid inadvertently intercepting a
                  pending MSR interrupt.  All bits returned except for
                  the delta bits reflect the true current status.






         async_msrflow
         ---------------------------------------------------------------

         Purpose: Enables or disables hardware flow control.

         Format:  void async_msrflow(port, flowmask);
                   ASYNC *port;       Pointer to ASYNC structure
                   int flowmask;      Bit mapped flow control mask

         Example:

                  ASYNC *port;

                  if (enable_RTS_CTS_handshake)
                      async_msrflow(port, B_CTS);
                  else if (disable_handshake)
                      async_msrflow(port, 0);

         Returns: No return value

         Remarks: The flow mask is a bit mapped value of the signal that
                  is monitored by the receiver when performing flow
                  control.  Bits that may be monitored are B_CTS, B_DSR,
                  and B_CD.  This provides capability for RTS/CTS hand-
                  shake, DTR/DSR handshake, and handshaking with the
                  carrier detect line.  To monitor multiple signals, OR
                  the bits together.  Both hardware flow control and
                  XON/XOFF flow control may be enabled at the same time.

                  See async_xflow.






         async_open  <5.40 modified -- see Remarks at end of function>
         ---------------------------------------------------------------

         Purpose: Initializes the hardware, interrupt vector, and ASYNC
                  port structure for interrupt driven operation.

         Format:
                  int async_open(port, base, irqmask, vctrnbr, params);
                   ASYNC *port;   Pointer to ASYNC structure
                   int base;      Base port address of UART chip
                   int irqmask;   8259 mask value for selected IRQ line
                   int vctrnbr;   Number of selected interrupt vector
                   char *params;  Baud, parity, data, & stop bits in
                                   string format

         Entry:   Before calling this function you must allocate ring
                  buffer memory and pre-initialize the following ASYNC
                  structure members:

                   RxSize : the size that you want the receive ring
                      buffer to be.  The memory allocated or set aside
                      for the receive ring buffer must be contiguous
                      with the memory used for the transmit  ring
                      buffer.  In most cases (RxSize + TxSize) bytes
                      will be allocated using some form of malloc.
                      A function to do this is included in the examples.
                      The combined size of RxSize + TxSize can not
                      exceed 32K - 1.

                   TxSize : the size of the transmit buffer in bytes.
                      As stated above, the transmit and receive buffers
                      for each individual port must be allocated as one
                      contiguous block.

                   RingSeg: the segment address of the memory allocated
                      for the receive and transmit buffers.  FAR memory
                      can be used for the receive and transmit buffers
                      by using your compiler library's version of FAR
                      malloc and putting the segment portion (high 16
                      bits) of the returned memory pointer in RingSeg.
                      If you are using a NEAR data model program and
                      want NEAR ring buffers, set RingSeg equal to 0.
                      With RingSeg set to zero, the open function will
                      use the DS segment register for RingSeg.  Using
                      FAR ring buffers causes no loss of performance.

                  RingOfst: the offset address of the memory allocated
                      for the receive and transmit buffers.  This value,
                      in conjunction with the RxSize and TxSize vari-
                      ables, is used to set up the receive and transmit
                      ring buffers.






         async_open
         ---------------------------------------------------------------

                  THE FOLLOWING FUNCTION IS INCLUDED WITH MCOMM5 AND IS
                  RECOMMENDED FOR ALLOCATING RING BUFFER MEMORY AND
                  INITIALIZING THE ABOVE VARIABLES.

         #if defined (__TURBOC__)         /* Turbo C */
            #include <alloc.h>
            #define _fmalloc farmalloc
         #elif defined (__ZTC__)          /* Zortech C */
            #include <dos.h>
            #include <stdlib.h>
            #define _fmalloc farmalloc
         #else                            /* Microsoft C */
            #include <malloc.h>
         #endif

         int AllocRingBuffer(
          ASYNC *port,                  /* pointer to port structure */
          int rxsize,      /* number bytes to use for receive buffer */
          int txsize,     /* number bytes to use for transmit buffer */
          int useFARmem)    /* flag set if using FAR mem for buffers */
         {
            unsigned long memptr;
            int memsize;

            memsize = rxsize + txsize;

            if (useFARmem || sizeof(char *) == 4)/* if FAR Ring bufs */
               memptr = (unsigned long)_fmalloc(memsize);
            else                  /* if Ring buffers use NEAR memory */
               memptr = (unsigned long)(unsigned int)malloc(memsize);

             /* pre-initialize 4 required structure members */
            port->RxSize = rxsize;            /* receive buffer size */
            port->TxSize = txsize;           /* transmit buffer size */
            port->RingSeg = (int)(memptr >> 16);          /* SEG adr */
            port->RingOfst = (int)memptr;            /* OFST address */
            if (memptr == 0L)
               return 0;          /* return 0 if no memory available */
            return 1;                   /* return 1, had some memory */
         }






         async_open
         ---------------------------------------------------------------

         Example 1:

            /*
               Open COM1 at 2400,N,8,1 using FAR ring buffers. COM1 is
               defined in COMM.H as:  0x3f8, 0x10, 12.  It is not
               necessary to check the return value of AllocRingBuffer
               since async_open will return R_NOMEM if the memory
               allocation function fails.
            */

            #include "comm.h"

            ASYNC port;
            int rcode;

            AllocRingBuffer(&port, 24000, 8000, 1);

            rcode = async_open(&port, COM1, "2400N81");
          /**  or
            rcode = async_open(&port, 0x3f8, 0x10, 12, "2400N81");
           **  or
            rcode = async_open(&port, 0x3f8, IRQ4, VCTR4, "2400N81");
           **/

            if (rcode != R_OK)
            {
                printf("\nAsync_open failed, exit code = %d", rcode);
                exit(rcode);
            }






         async_open
         ---------------------------------------------------------------

         Example 2:

            /*
               Open a port located at 0x2e0 that uses IRQ3.  In this
               case NEAR ring buffers are specified and the memory for
               the port structure is obtained using malloc.  See the
               AllocRingBuffer function described previously.
            */

            #include "comm.h"

            ASYNC *port;
            int rcode;

            if ((port = (ASYNC *)malloc(sizeof ASYNC)) == NULL)
            {
                printf("\nNot enough memory");
                exit(R_NOMEM);
            }

            AllocRingBuffer(port, 4096, 1200, 0);

            rcode = async_open(port, 0x2e0, IRQ3, VCTR3, "115200E71");

            if (rcode != R_OK)
            {
                printf("\nAsync_open failed, exit code = %d", rcode);
                exit(rcode);
            }






         async_open
         ---------------------------------------------------------------

         Example 3:

            /*
               Open both COM1 and COM2 at the same time.  You can open
               two ports at once as long as they don't share the same
               IRQ line or interrupt vector.
            */

            #include "comm.h"

            ASYNC ports[2], *port[2];
            int rcode;

            port[0] = &ports[0], port[1] = &ports[1];

            AllocRingBuffer(port[0], 10240, 10240, 1);
            rcode = async_open(port[0], COM1, "9600N81");
            if (rcode != R_OK)
            {
                printf("\nAsync_open failed, exit code = %d", rcode);
                exit(rcode);
            }

            AllocRingBuffer(port[1], 10240, 10240, 1);
            rcode = async_open(port[1], COM2, "1200E71");
            if (rcode != R_OK)
            {
                printf("\nAsync_open failed, exit code = %d", rcode);
                exit(rcode);
            }






         async_open
         ---------------------------------------------------------------

         Example 4:

            /*
               Open COM1 using its current baud, parity, data, and
               stop bit settings.  The port structure member, BPDSstr,
               will reflect those settings after calling async_open.
            */

            #include "comm.h"

            ASYNC *port;
            int rcode;