async.doc

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

         a new port structure member 'IERVal' to zero as an indicator
         the port is locked up.  Normally 'IERVal' will be set to the
         current value of the Interrupt Enable Register.  If you try to
         open a port that is in a stuck interrupt condition, async_open
         now returns R_UARTERR.  In addition, options were added to open
         a port without enabling Modem Status interrupts or Line Status
         interrupts or both.  ORing the ComBase parameter of async_open
         with 0x2000 disables MSR interrupts.  ORing with 0x1000
         disables LSR interrupts.  So far I have encountered no reason
         for disabling LSR interrupts.  Disabling MSR interrupts
         prevents the lock up problem but has the side effect of causing
         all functions and variables that use Modem Status signals to be
         invalid.  This includes hardware handshake and carrier detect.

         I have probably over emphasized the Modem Status lock up
         problem and my personal opinion is that it is not that serious.
         I considered totally disregarding it since it has a simple
         solution and that is to connect all Modem Status input signals
         to some driving signal (wire the RS232 cable right).  Unused
         signals can be connected to a driving signal on the computer
         end if necessary.  Also it may be isolated to one defective
         chip.  I tested two WD16550s and the problem only showed up on
         one of them during my testing.  Because the computer totally
         locked up when this happened though, I decided to go ahead and
         program for the possibility.  At least control of the computer
         is regained and you can tell the user he needs a properly wired
         RS232 cable or his UART is broke and then exit gracefully.
         This will probably show up very very rarely so don't be too
         concerned about it.  In closing, I would like to point out
         again that these problems are a fault of the WD16550 and are
         not unique to MCOMM.






         async_16550
         ---------------------------------------------------------------

         Purpose: Check if 16550 UART was detected in system.

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

         Example:

                  ASYNC *port;
                  int is_16550;

                  is_16550 = async_16550(port);

         Returns: Returns zero if a 16550 is not in the system or the
                  'ignore 16550 bit' was set when async_open was called.
                  Returns NZ if a 16550 was found.  Async_open must be
                  called before this function is valid.  If a 16550 is
                  found, it will be placed in the FIFO mode of operation
                  by async_open unless '16550 detect' was overridden or
                  the force FIFOs off option was selected.

         Remarks: This function is implemented as a macro.

                  See async_open.






         async_breakrxd
         ---------------------------------------------------------------

         Purpose: Checks if a break signal has been received.

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

         Example:

                  ASYNC *port;
                  int break_status;

                  break_status = async_breakrxd(port);


         Returns: If a break signal has been received the function
                  returns a non-zero value.  If a break has not been
                  detected, zero is returned.

         Remarks: Once a break signal has been detected, this function
                  continually returns non-zero values until async_reset
                  is called.  If a break is received, a line status
                  register interrupt is generated.  The interrupt
                  handler sets a bit in the Stat1 port structure member.
                  The async_breakrxd function is a macro that checks the
                  status of this bit.

                  See also async_reset, async_rx, async_stat,
                  async_sndbrk.






         async_carrier
         ---------------------------------------------------------------

         Purpose: Check for the presence of a carrier.

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

         Example:

                  ASYNC *port;
                  int carrier_status;

                  carrier_status = async_carrier(port);


         Returns: A non-zero value is returned if a carrier is present.
                  If the carrier detect line is LOW, zero is returned.

         Remarks: This function is implemented as a macro.  See also
                  async_rx and async_stat.






         async_close
         ---------------------------------------------------------------

         Purpose: Closes a port opened by async_open.

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

         Example:

                  ASYNC port;
                  async_close(&port);

         Returns: No return value

         Remarks: Do not attempt to close an unopened port.  Some
                  minimal checking is done internally by async_close in
                  an attempt to detect whether or not the specified port
                  is actually opened.  If an unopened port makes it past
                  those checks and the main close routine is entered,
                  the system may lock up (immediately, 2 hours later, or
                  never).  When a port is closed the UART registers,
                  interrupt controller mask, and interrupt vectors are
                  restored to the value they had when async_open was
                  called.  It is possible to close the port and leave
                  various signals (DTR for one) in the state you desire
                  rather than in their initial state.  See async_dtr and
                  async_rts for some examples on how to do this.

                  The B_ORGFIFO bit in the ASYNC 'Stat3' structure
                  member is used by async_close to return the 16550 --
                  if present -- to the mode it was in when async_open
                  was called.  FIFOs may be 'forced' to remain enabled
                  or 'forced' to be disabled when closing the port by
                  first setting or resetting this bit.  Ex:

                    Force off:    port->Stat3 &= ~B_ORGFIFO;
                                  async_close(port);

                    Force on:     port->Stat3 |= B_ORGFIFO;
                                  async_close(port);






         async_cts
         ---------------------------------------------------------------

         Purpose: Check status of the Clear to Send signal.

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

         Example:

                  ASYNC *port;
                  int cts_status;

                  cts_status = async_cts(port);

         Returns: Returns zero if Clear To Send is LOW.  If CTS is HIGH,
                  a non-zero value is returned.

         Remarks: This function is implemented as a macro.






         async_dsr
         ---------------------------------------------------------------

         Purpose: Check status of the Data Set Ready signal.

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

         Example:

                  ASYNC *port;
                  int dsr_status;

                  dsr_status = async_dsr(port);

         Returns: Returns zero if Data Set Ready is LOW.  If DSR is
                  HIGH, a non-zero value is returned.

         Remarks: This function is implemented as a macro.






         async_dtr
         ---------------------------------------------------------------

         Purpose: Set or reset the Data Terminal Ready signal.

         Format:  void async_dtr(port, DTRflag);
                   ASYNC *port;       Pointer to ASYNC structure
                   int DTRflag;       Set/Reset DTR flag

         Example:

                  ASYNC *port;

                  if (WantToDropDTR)
                      async_dtr(port, 0);
                  else if (WantDTRhigh)
                      async_dtr(port, 1);


         Returns: No return value

         Remarks: This signal is set HIGH when a port is first opened.
                  When the port is closed, it is restored to the cond-
                  ition it was in when the port was opened.  To force
                  DTR low when a port is closed, regardless of its state
                  when the port was opened, AND the port member, OldMCR,
                  with NOT B_DTR.  To force DTR to remain high when the
                  port is closed, OR OldMCR with B_DTR.

                    Force low:    port->OldMCR &= ~B_DTR;
                                  async_close(port);

                    Force high:   port->OldMCR |= B_DTR;
                                  async_close(port);






         async_FIFOrxlvl  <5.20 addition>
         ---------------------------------------------------------------

         Purpose: Set the 16550 UART's receive trigger level.

         Format:  void async_FIFOrxlvl(port, trigger_lvl);
                   ASYNC *port;       Pointer to ASYNC structure
                   int trigger_lvl;   Rx FIFO interrupt trigger level

         Example:

                  ASYNC *port;

                   /* set the receiver trigger level to 8 bytes */
                  async_FIFOrxlvl(port, 8);

         Returns: No return value

         Remarks: Valid values for 'trigger_lvl' are 1, 4, 8, and 14
                  bytes.  When a port with a 16550 UART is first opened,
                  the trigger level is set to 1 byte.  See the
                  discussion on 'Use of receiver FIFOs' at the beginning
                  of this document.  This function has no effect if the
                  FIFOs were not enabled when async_open was called.






         async_FIFOtxlvl  <5.20 addition>
         ---------------------------------------------------------------

         Purpose: Set the number of bytes loaded into the 16550 UART's
                  transmit FIFOs when a transmit interrupt occurs.

         Format:  void async_FIFOtxlvl(port, bytes);
                   ASYNC *port;       Pointer to ASYNC structure
                   int bytes;         # of bytes to load into tx FIFOs

         Example:

                  ASYNC *port;

                   /* set the transmit FIFO byte level to 16 bytes */
                  async_FIFOrxlvl(port, 16);

         Returns: No return value

         Remarks: Valid values for 'bytes' are 1 through 16 bytes.  When
                  a port with a 16550 UART is first opened, the transmit
                  level byte count is set to 3 bytes.  See the
                  discussion on 'Use of transmit FIFOs' at the beginning
                  of this document.  This function has no effect if the
                  FIFOs were not enabled when async_open was called.






         async_ignerr
         ---------------------------------------------------------------

         Purpose: Set or reset 'ignore characters with errors' bit

         Format:  void async_ignerr(port, flag);
                   ASYNC *port;       Pointer to ASYNC structure