Category : Tutorials + Patches
Archive   : NAT_UART.ZIP
Filename : PROGUIDE.LBT

 
Output of file : PROGUIDE.LBT contained in archive : NAT_UART.ZIP
27 October 1988


Programmer's Guide for the NS16450 UART Loop Back Test Rev 1.1
==============================================================

Developed by Brian A. Berg
BERG SOFTWARE DESIGN
P.O. Box 3488
Saratoga, CA 95070
408.741.5704 / 741.5010


Summary of Delivered Files
--------------------------

LBT.C C source code: main program, subroutines and interrupt handler
SERIO.H header file containing UART definitions for C code use
STDHDR.H header file containing "standard" definitions for C code use
LBT.MK LBT "make" file to compile C code and create executable LBT
LBT.OBJ compiled object file from LBT.C
LBT.EXE executable LBT program; only this file is needed to run the LBT
LBT.MAP "map" file of LBT.EXE
PROGUIDE.LBT Programmer's Guide for LBT (this file)
USRGUIDE.LBT User's Guide for LBT


Help Screen for LBT
-------------------

NOTE: The following is displayed if any incorrect arguments are supplied
to the LBT (this includes entering "lbt help")


**** HELP Screen for NS16450 UART Loop Back Test Rev 1.1 ****

USAGE: lbt [ [ []]]
arg1 arg2 arg3
('lbt' may be followed by no args, arg1, arg1+2 or arg1+2+3)

ARGUMENT MINIMUM VALUE MAXIMUM VALUE DEFAULT VALUE
============ =============== =============== ==============
COM-number 1 (for COM1) 2 (for COM2) 1
(serial line 0) (serial line 1) (COM1)

term-err-cnt 0 (infinite) 30000 1
(data errors before stopping) (1 error)

baudrate- 2 (56000 baud) 2304 (50 baud) 12
divisor (based on 1.8432 MHz crystal) (9600 baud)
* Sample baudrate divisors: for baud= 1200, use 96 *
* 2400 48 *
* 4800 24 *
* 9600 12 *
* 19200 6 *

27 October 1988

Page 2 of 4


Programmer's Guide for the NS16450 UART Loop Back Test Rev 1.1
==============================================================


Summary of LBT.C Subroutines
----------------------------

NOTE: As the code itself is heavily commented, it should be inspected if
further clarification is necessary.

The following subroutines are contained in this file:

void main(int, char **); /* main program */
void interrupt far serint(void); /* serial interrupt handler */
void procarg(int, char **); /* process invocation arguments */
void savepar(void); /* save our environment parameters */
void rstrpar(void); /* restore our environment parameters */
void dspstr(UCHAR *); /* display a string on the console */
void usage(void); /* display usage info and exit */


1. main(): main program

The main program processes invocation arguments by calling procarg(),
saves environment parameters by calling savepar(),
sets the requested (or default) baud rate,
sets up the MCR and LCR registers,
uses the CLEAR_REGS() macro to clear the RBR, LSR and IIR registers,
and prompts the operator to "Hit any non-control key to stop" the program.
It then starts the loop back operation by setting up the IER register,
and continually waits for either the global variable "finit" to change from
FALSE to TRUE, or for the operator to strike any non-control keyboard key,
before exiting this loop. The finit variable is set by the interrupt handler
as described for serint().
While this loop is active, the global variable "tick" is inspected. If it is
non-zero, either "|" or "_" is displayed at one place on the screen in order
to inform the operator that the program is active. This is facilitated by
use of a flip-flop variable to index one of two ASCII strings.
After exiting this loop, the program waits for the TEMT bit in the LSR to be
set to indicate the quiescence of the UART. The CLEAR_REGS() macro is again
invoked. If any data or status errors were discovered by the interrupt
handler, the number found is displayed. Then the rstrpar() routine is
called to restore the environment parameters, and the program terminates.

27 October 1988

Page 3 of 4


Programmer's Guide for the NS16450 UART Loop Back Test Rev 1.1
==============================================================


Summary of LBT.C Subroutines (continued)
----------------------------------------

2. serint(): serial port interrupt handler

The interrupt handler first checks if the global "finit" flag is TRUE. If so,
the interrupt is ignored by simply sending the PIC an EOI and exiting.
Then the IIR is read and each interrupt type is handled:
NO Interrupt Pending:
the status error count (sec) is incremented

Receiver Line STatus interrupt:
Received Data AVailable (RDAV):
the LSR is read
if PE or FE is set in the LSR, sec is incremented
if OE or BI is set in the LSR, the data error count (dec)
is incremented
if DR is set, a data byte is read and verified
if it is bad, dec is incremented
after every 2560 bytes are read, the global "tick"
is set to TRUE for use by main()
else if the interrupt type is RDAV, sec is incremented
since DR should have been set

Transmitter Holding Register Empty:
the LSR is read
if THRE is set in the LSR, a data byte is written
else sec is incremented since THRE should have been set

any other value for the IIR:
sec is incremented since this shouldn't happen

If sec is non-zero or if dec is at least as great as the termination
error count (an invocation parameter), "finit" is set to TRUE for
use in terminating the program (see documentation for main())

An EOI is sent to the PIC.
(NOTE: an IRET instruction is automatically generated to exit this int. handler)

27 October 1988

Page 4 of 4


Programmer's Guide for the NS16450 UART Loop Back Test Rev 1.1
==============================================================


Summary of LBT.C Subroutines (concluded)
----------------------------------------

3. procarg(): process invocation arguments

The invocation arguments as defined in the help screen are validated
by this routine. The help screen itself is displayed by calling
usage() if any illegal arguments are found.
Based on the COM argument (or its default), the interrupt vector number
and UART base address are set up for global use. The existence of
the requested COM port is verified; its non-existence causes program
termination.


4. savepar(): save our environment parameters

This routine saves the original interrupt vector, ctrl-break/ctrl-c
status and PIC mask, and then sets these up as required for LBT use.
It also saves some of the UART register values.


5. rstrpar(): restore our environment parameters

This routine is the complement for savepar(): it restores the saved
registers, interrupt vector, ctrl-break/ctrl-c status and PIC mask.


6. dspstr(): display a string of characters on the console

This routine uses the INT 10H software interrupt to display a string a
character at a time.


7. usage(): display program usage information and terminate (never return)

This routine displays the help screen and terminates the program.


  3 Responses to “Category : Tutorials + Patches
Archive   : NAT_UART.ZIP
Filename : PROGUIDE.LBT

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/