Windows users who need a command line connection to another system via telnet or SSH are big fans of PuTTY. It's free, it has every feature you need, and it's reliable.

One thing many people would like to do is use PuTTY as a component in their program. Apparently this comes up so often enough that there is a FAQ entry dedicated to the topic. Alas, PuTTY does not have any sort of automation interface, so this goal has always been out of reach.

In this article I will show you how to work around this minor shortcoming. Creating a version of PuTTY that can be driven from a Windows program turns out to be an easy task. I'll demonstrate this with a small C++ program that shows exactly how to get this versatile program to do your bidding. My solution works for C++, but the changes I make should work well with any Windows software that can properly process a few messages.

Putting Together the Project

I'm using Visual Studio 2010 to build both my program and the modified version of Putty. I created the basic outline as follows:

1. Use the File|New|Project menu item to bring up the list of available project wizards.
2. Select MFC project, and enter a project name (I used the uninspired name PuttyDriver.)
3. I don't want the default MFC settings, so in the MFC App Wizard, select the Next button.
4. On the Application Type page of the wizard, change the Application Type to Dialog Based.
5. The project is ready to go at this point, you can click the Finish button and then build your initial project.

My driver program is only going to do one thing: direct putty to connect to the host of my choice, then log in using canned credentials. The resulting UI is shown below, and I am going to leave the very minor details of creating it up to the reader.

The driver program - a simple dialog-based MFC app

Adding Putty to the Project

The next step in this process is to add the Putty components to the project. I downloaded version 0.61 of the PuTTY source from the download page and extracted it to a separate folder. I then used Visual Studio's File|Add|Existing Project to add the compatible project file, Putty.dsp, found in /Windows/MSVC/Putty. Visual Studio has to convert this project to a version 10 project file, but it should do so with no problems.

I then right-clicked on the Putty project in Solution Explorer and renamed it to AutoPutty. Since this version of PuTTY will have some slightly different behavior, I don't want to confuse the executable I am creating with the real thing.

From Project|Project Dependencies, I set the PuttyDriver project to depend on AutoPutty - this insures that both projects get built when I build the entire solution.

My final change to the project is to modify the output directory for both Debug and Release versions of AutoPutty. I set the project to build the executable in the root directory of my PuttyDriver project - this will make it easy to find the executable when I need to launch it. I had to make this change in two places: Properties|Configuration Properties|General|Output Directory and Properties|Linker|Outuput File.

When you finally build the project, you'll find that current version of Microsoft's C++ compiler complain quite a bit about the use of functions like strcpy - Microsoft would like you to use safer replacement functions. You may choose to turn those errors off by defining _CRT_SECURE_NO_WARNINGS in the project file. While you are there, you should define SECURITY_WIN32 as well - it is required by Windows header sspi.h.

After a successful build you should find a copy of AutoPutty.exe in the root directory of your project, and it should run on your system and behave just like PuTTY.

Launching AutoPutty

If I'm going to have a PuTTY component in my PuttyDriver program, one of the first things I need is to be able to start and stop AutoPutty. So my first step in this project is to create the code that launches the program from PuttyDriver. The code below is inserted into the handler for the Start button:

UpdateData( true );
char path[MAX_PATH];
GetCurrentDirectory(MAX_PATH, path);
if ( path[ strlen(path) - 1 ] != '\\' )
    strcat_s( path, MAX_PATH, "\\" );
strcat_s( path, MAX_PATH, "AutoPutty.exe -ssh " );
strcat_s( path, MAX_PATH, m_HostName.GetBuffer() );
PROCESS_INFORMATION pi;
ZeroMemory(&pi, sizeof(pi) );
STARTUPINFO si;
ZeroMemory(&si, sizeof(si) );
si.cb = sizeof(si);
if ( CreateProcess( NULL, path, NULL, NULL, NULL, NULL, NULL, NULL, &si, &pi ) )
{
    Sleep( 1000 );
    BringWindowToTop();
}

This code assumes that AutoPutty.exe is in the current directory, and launches it with a command line telling it to connect to the host named in the dialog using ssh. Assuming that you have the project set up properly, pushing the start button should now start an independent copy of AutoPutty, which will behave identically to classic PuTTY.

Taking Ownership of AutoPutty

At this point I can successfully launch AutoPutty, but I can't really start calling this an integrated part of my main program, PuttyDriver. All I have done is set up a launcher for a separate executable.

The next step in the integration process is to establish PuttyDriver as the owner of AutoPutty's main window. Most Windows programmers are familiar with the traditional parent/child relationship between windows. That relationship is well understood, but I can't use it here - it doesn't work for two top level windows.

Setting PuttyDriver to be the owner (as opposed to the parent) of AutoPutty has the following effects, as explained here by Microsoft:

• The owned window will always be above its owner in the z-order.
• The system automatically destroys the owned window when the owner is destroyed.
• The owned window is hidden when the owner is minimized.

The most straightforward way to set ownership of the window is to pass the owner's handle in the call to CreateWindow(), which means I will now make my first modifications to the PuTTY source code.

There are a number of ways to pass the owner handle to AutoPutty for use in the call to CreateWindow(), with the most obvious being to pass it on the command line. In the interest of minimizing changes to the existing PuTTY code base, I elected to pass it by creating an environment variable that holds the owner window handle. Since a child process inherits the parent's environment, this is a no-fuss way to get the data to AutoPutty.

I added the following code to the end of InitDialog() in PuttyDriver:

CString hwnd_text;
hwnd_text.Format( "%d", m_hWnd );
SetEnvironmentVariable("PUTTY_OWNER", hwnd_text );

This sets the environment variable for AutoPutty to find when it gets launched.

Now I come to the point where I am actually making changes to the PuTTY code. Fortunately, all of the changes needed for this program are confined to two files: terminal.c and windows/window.c. My first change is to window.c. This file contains the WndProc for the PuTTY window, and thus most of the rendering and control code for the GUI.

In order to establish the Owner/Owned relationship, I need to modify the code that calls CreateWindow(). I hoisted the function call into a block, added code to get the owner window handle, and inserted the handle into the call to CreateWindow():

{
    HWND owner_hwnd = 0;
    char buffer[ 132 ];
    if ( GetEnvironmentVariable( "PUTTY_OWNER", buffer, 132 ) )
        sscanf( buffer, "%d", &owner_hwnd );
    if ( owner_hwnd == 0 )
        MessageBox( NULL,
                    "AutoPutty did not find the handle for the "
                    "owner window, this is not going to work",
                    "Fail",
                    MB_OK );
    hwnd = CreateWindowEx(exwinmode, appname, appname,
                          winmode, CW_USEDEFAULT, CW_USEDEFAULT,
                          guess_width, guess_height,
                          owner_hwnd, NULL, inst, NULL);
}

At this point I've only modified one small block of code in the PuTTY source, but I'm well on my way to having it behave more like a component of PuttyDriver and less like an independent program. The ownership status means that the two programs only appear once on the taskbar, and will only appear once when you are pressing ALT-TAB to select a new active process. And they only produce a single entry in the Applications Tab of Task Manager.

The Communications Link

In order to achieve the automation that I am seeking, I also need to have two way communications between AutoPutty and the driver program. Since this is Windows, a natural choice for communications is to use native Windows messages. In order to do this, both programs need the Window handle of their opposite number.

I've already solved half of that problem through the ownership relationship established when I created the main window for AutoPutty. Now that it has set PuttyDriver as its owner window, I can get this window handle any place in the program through a simple function call:

HWND parent = GetWindow(hwnd, GW_OWNER);

But the reverse is not true - PuttyDriver does not know have a copy of the window handle for AutoPutty.

To remedy this situation, I added code to window.c that notifies its owner when it s created, and when it is destroyed. First I add this statement immediately after the call to CreateWindow():

if ( owner_hwnd )
   PostMessage( owner_hwnd, WM_APP, 0, (LPARAM) hwnd );

This tells PuttyDriver that the window is created, and gives it the handle to use for communications.

I also need to know when the window is closed, and I have to add that code two places in window.c - because Putty can be shut down two different ways.

Normally AutoPutty will shut down in response to a windows message. When this happens, I can count on a WM_CLOSE message being sent to the Windows Procedure. I add this code the existing handler for WM_CLOSE:

if (!cfg.warn_on_close || session_closed ||
    MessageBox(hwnd,
               "Are you sure you want to close this session?",
               str, MB_ICONWARNING | MB_OKCANCEL | MB_DEFBUTTON1)
    == IDOK) {
    HWND parent = GetWindow(hwnd, GW_OWNER);
    if ( parent )
        SendMessage( parent, WM_APP, 0, 0 );
    DestroyWindow(hwnd);
}

This lets PuttyDriver know that the window has been destroyed.

The original PuTTY code has an alternative method of shutdown. When it receives one of several possible network events, such as a telnet connection being broken, it calls PostQuitMessage(). When a program shuts down this way, it doesn't issue messages to destroys its windows - it relies on the O/S to destroy the windows when the process exists. As a result, I have to make a change in WinMain(), the main window procedure for PuTTY. This procedure extracts the messages sent to it using PeekMessage, and I add some code to handle the processing when a WM_QUIT message is sent:

if (msg.message == WM_QUIT) {
    HWND parent = GetWindow(hwnd, GW_OWNER);
    if ( parent )
        SendMessage( parent, WM_APP, 0, 0 );
    goto finished;	       /* two-level break */
}

Handling the AutoPutty Lifecycle Events

To keep track of the state of AutoPutty, I have to add a handler for WM_APP to PuttyDriver. It does two things when handling the incoming WM_APP event.

First, then handler stores the handle of the AutoPutty window - or sets the value to 0 when the window has been destroyed.

Second, it either enables or disables the button used to start up AutoPutty. Since this program can only manage one window at a time, I don't want to allow any inadvertent button pushes:

afx_msg LRESULT CPuttyDriverDlg::OnWmApp(WPARAM wParam, LPARAM lParam)
{
    m_PuttyWindow = (HWND) lParam;
    m_StartButton.EnableWindow( !m_PuttyWindow );
    return 0;
}

One final piece of bookkeeping is to make sure that the AutoPutty window is shut down when PuttyDriver shuts down. (The Windows documentation claims this happens automatically to owned windows, but it doesn't seem to be the case.)

void CPuttyDriverDlg::OnDestroy()
{
    CDialogEx::OnDestroy();
    if ( m_PuttyWindow )
        ::SendMessage( m_PuttyWindow, WM_CLOSE, 0, 0 );
}

Monitoring Input Traffic

Now that I have control over the lifetime of my AutoPutty window, it's time to take the next step in automation. My driver program needs to watch all the data coming in from the remote end so that it can take action on various types of input.

Depending on how you set up your connection, PuTTY can receive input data from a serial port, a Telnet connection, or an SSH connection. Fortunately the Windows version of PuTTY uses a standard handle-based interface to all three types of connections. The routine term_data() in terminal.c is called as data arrives, regardless of the source.

Since we are using the Windows API to communicate between processes, it makes sense to use the WM_COPYDATA message to send data to the parent program as it arrives. WM_COPYDATA is a good choice, as it takes care of marshalling the data between the two processes, which can add some complication to other solutions. The modified routine is shown below:

int term_data(Terminal *term, int is_stderr, const char *data, int len)
{
    HWND parent = GetWindow(hwnd, GW_OWNER);
    if ( parent ) {
        COPYDATASTRUCT cd;
        cd.dwData = (ULONG_PTR) 0xDEADBEEF;
        cd.cbData = len;
        cd.lpData = (PVOID) data;
        SendMessage( parent, WM_COPYDATA, (WPARAM) hwnd, (LPARAM) &cd );
    }

Receiving the Data

To receive this messages in PuttyDriver, I simply create a handler for WM_COPYDATA and start grabbing the data as it arrives. One important thing to note is that because AutoPutty has to use SendMessage() to send the data to its parent, it has to wait for PuttyDriver to finish processing the data until it can continue. This dictates a certain style of behavior on my part.

There are quite a few ways to skin this cat, and I'm keeping it very simple here. I'm using a deque<char> container to hold the last 64 characters I've received. After each WM_COPYDATA message I received, I check to see if the current output snapshot ends in one of my trigger messages. If it does, I post the message number to myself for later processing, then return so that AutoPutty can continue its work.

The code I'm using here is doing something fairly simple: automating the login process by using the credentials that I've entered into the dialog box. That means the two strings I'm looking for are the login and password prompts. The resulting code is shown here:

BOOL CPuttyDriverDlg::OnCopyData(CWnd* pWnd, COPYDATASTRUCT* pCopyDataStruct)
{
    char *p = (char *) pCopyDataStruct->lpData;
    int len = pCopyDataStruct->cbData;
    if ( len >= 64 ) {
        p += len - 64;
        len = 64;
        m_Snapshot.clear();
    }
    while ( len-- )
        m_Snapshot.push_front(*p++);
    m_Snapshot.resize(64);
    static const char *needles[2] = { "login as: ", "password: " };
    for ( int i = 0 ; i < 2 ; i++ ) {
        int len = strlen( needles[i] );
        int j;
        for ( j = 0 ; j < len ; j++ ) {
            if ( needles[i][j] != m_Snapshot[len-1-j] )
                break;
        }
        if ( j == len )
            PostMessage( WM_APP+1, i, 0 );
    }
    return TRUE;
}

There is plenty of room for improvement in this routine, much of it depending on what type of automation you are going to be using in your program. Some obvious items would include the ability to add and remove triggers as the program progresses, and regular expression matching for triggers.

Driving PuTTY

This login program is now complete save for one detail: I need a way to send my responses back to AutoPutty.

The first part of this is pretty obvious - I just need to read the data from the dialog box and post it to AutoPutty with my useful WM_COPYDATA command. This happens in my WM_APP+1 handler:

afx_msg LRESULT CPuttyDriverDlg::OnWmAppPlusOne(WPARAM wParam, LPARAM lParam)
{
    UpdateData(TRUE);
    CString msg;
    switch ( wParam ) {
    case 0 :
        msg = this->m_UserId + '\r'; break;
    case 1:
        msg = this->m_Password + '\r'; break;
    }
    if ( this->m_PuttyWindow ) {
        COPYDATASTRUCT cd;
        cd.dwData = (ULONG_PTR) 0xF00DFACE;
        cd.cbData = msg.GetLength();
        cd.lpData = (PVOID) (const char *) msg;
        ::SendMessage( this->m_PuttyWindow,
                       WM_COPYDATA,
                       (WPARAM) this->m_hWnd,
                       (LPARAM) &cd );
    }
    return 0;
}

Sending this data to AutoPutty is fine, but right now the program doesn't do anything with that message. The final piece of work is to add a WM_COPYDATA handler to window.c.

Simply grabbing the data is easy enough - the data structure that accompanies the message contains a pointer to the data and a value indicating its length. However, I have two problems I have to solve before the data is actually sent out to the to whatever device AutoPutty is connected to.

First, I have to take into account the fact that PuTTY was written to use wide characters. My driver program was built using MultiByte characters, so we have a mismatch. This means I have to do a conversion of the data from one domain to the other. This is a two step process - I call MultiByteToWideChar() once to determine how much space I need, then I allocate a buffer and call it again.

The second thing I need to do is determine what to do with the data once I've converted it. PuTTY takes all terminal input and eventually passes through a function called luni_send(). Calling this function directly from the Windows procedure seems to work just fine.

The WM_COPYDATA handler I created looks like this:

case WM_COPYDATA :
{
    COPYDATASTRUCT *cd = (COPYDATASTRUCT *) lParam;
    int wsize = MultiByteToWideChar( CP_ACP,
                                     MB_PRECOMPOSED,
                                     (LPCSTR) cd->lpData,
                                     cd->dwData,
                                     NULL,
                                     0 );
    wchar_t *buf = (wchar_t *) calloc( wsize+1, sizeof(wchar_t) );
    MultiByteToWideChar( CP_ACP,
                         MB_PRECOMPOSED,
                         (LPCSTR) cd->lpData,
                         cd->dwData,
                         buf,
                         wsize + 1 );
    if (term->ldisc)
        luni_send(term->ldisc, buf, wsize, 0);
    free( buf );
}

At this point I have a working program - it connects to my designated host, and sends the username and password of my choice to the host, connecting me to the system.

I should add a note of caution here. Automating logins is a tempting time saver, but in general this is a really bad idea. Any time you hard code credentials into a program, you open the door to all sorts of new attacks on your system.

In my demo program, the user has to enter a name and password, so nothing is hardcoded, but even this adds security holes to a system. I encourage you to think of this as a demonstration only.

Source Code

I've included the complete source code for PuttyDriver, the MFC project that controls AutoPutty. It was built with Visual Studio 2010, so you may have a little work to do if you backport it to earlier versions. My use of language features and classes should be compatible with much earlier versions - this is all very simple code.

Because PuTTY is always changing, I am not redistributing a snapshot of the version I used. Instead, I'm including before and after copies of the two source files I modified: window.c and terminal.c. If you build with Putty 0.61, you should be able to drop these two files right on top of the files included with the distribution and be on your way. With later versions of PuTTY you will have to perform an intelligent merge of the changes, which I hope will be a fairly effortless process.

Downloads

• PuttyDriver.zip. The PuttyDriver source and project. You will need to add the PuTTY project to this solution as described in the article.
• putty.zip. This contains the two PuTTY source files modified for this project. Both the original 0.61 source and my modified source are supplied. Executables are supplied as well, which may or may not work on your system.

I spent a pretty big chunk of the 80's and 90's toiling away on Greenl af Commlib, a C/C++ library that provided support for RS-232 communications on MS-DOS and Windows machines. Despite the fact that serial communications ports were standard issue on IBM-compatible PCs, Microsoft provide little or no support for their use under MS-DOS or 16-bit versions of Windows. Which allowed Greenleaf to carve out a healthy little business, taking me along with them.

Even with our library, working with RS-232 ports could be pretty tough. C/C++ programmers in this environment didn't have good options for writing code that dealt with asynchronous events, so programs tended to be difficult to both develop and maintain. We tried a lot of approaches to improving the situation, but one thing we never pursued was the idea of developing a Domain-specific Language.

In retrospect, I think we might have missed a real opportunity here. A couple of weeks ago I received an email from Orhan Alby, announcing the launch of Any Serial Port, a language specifically devoted to developing RS-232 applications. Having a language dedicated to RS-232 programming is a big plus, but Alby took it one step further by providing an IDE that really makes it easy to debug the entire process.

The language is nicely crafted for this kind of work - at the high level it takes the approach of developing a state machine, which is driven by RS-232 events. It's a very natural paradigm for communications work.

Fortunately, the entire project is available on SourceForge under GPLv3. Next time you have a need to dust off your RS-232 knowledge, I encourage you to give a try to Any Serial Port and see if it cuts your development time down. And if you like it, dig in and help improve it!

In the mini and microcomputer world, RS-232 links provide what is likely the most heavily used form of communications. RS-232 is versatile and relatively inexpensive. It is possible to connect computers that are considered otherwise to be completely incompatible. RS-232 is also used by computers to talk to devices such as modems, dumb terminals, bar code readers, printers, lab equipment, and more. So it made sense that IBM defined a standard RS-232 interface card for their PC. Up to two of the cards could be installed in a PC, and were referred to as COM1 and COM2.

Unfortunately, each COM card installed in a PC needed its own interrupt line. The original IBM PC had only eight interrupt lines, of which just two were available for use by RS-232 ports. Some third party COM cards could be configured to operate at other addresses on other interrupt lines, so it was in theory possible to operate three ports at once, but this required using interrupt lines that were allocated for other devices. And a user who wanted to operate as many as 8 RS-232 ports simultaneously was essentially out of luck.

The solution to this problem comes in the form of the Multiple Port Shared Interrupt (Multiport) board. These are boards that are set up so that multiple communication ports can share a single interrupt on the PC bus. This article discusses how the programmer can use these boards in MS-DOS applications.
What is a Multiple Port Shared Interrupt Board?

There is no such thing as a standard Multiport RS-232 board. There are many different manufacturers of these boards, and each of them has implemented their board in a different fashion. However, most of the boards have enough in common so that the same programming techniques, and even the same code, can be used to operate them.

The boards discussed in this article all have several things in common. First of all, each of them uses a Universal Asynchronous Receiver/Transmitter (UART) for the 8250 family. The 8250 family of UARTs include the 8250, 16450, and 16550 manufactured by National Semiconductor. These are the same UARTs used by IBM in the standard COM1 and COM2. This means that the actual programming of the registers on the UART of a Multiport board can be done using essentially the same code as already exists for standard RS-232 ports. Most of the boards support 4 or 8 UARTs on a single board, although there are some 16 port boards available.

In addition, the manufacturers of multiport boards all support the same I/O pins used on the IBM PC COM1 and COM2. These are:

The Multiport board designers use various techniques to bring these signal lines out to multiple 9 or 25 pin D connectors. The DB-25 connector is an industry standard, but IBM began using a nine pin connector as an alternative when the AT series was introduced. For the most part, the board manufacturers seem to be adhering to the 25 pin standard. The nine pin connector used by IBM may have been implemented to save space on a card edge for more connectors, but the multiport vendors don't attempt to mount their connectors on the card edge anyway, so geographical considerations are of less importance.

What makes a Multiport board work on a PC is the shared interrupt logic. This is special hardware that takes the interrupts from all 4, 8 or 16 UARTs on the board and manages them to produce interrupts on a single line on the PC bus. This is not as simple as just ORing them all together to produce an interrupt signal. The IBM PC bus interrupt lines are edge-triggered, which means that a low to high transition needs to take place in order to create a new interrupt. This causes a problem for the hardware designer. In an ORed logic scheme with two UARTS, the following sequence of events could hang the board up:

1. UART 2 generates an interrupt, bringing PC IRQ high
2. The interrupt service routine (ISR) is invoked
3. The ISR checks UART 1, which is idle
4. The ISR checks UART 2, sees that it is active
5. UART 1 receives a character, generates an interrupt
6. The ISR services UART 2
7. UART 2 drops its interrupt line, PC IRQ remains high because of UART 1
8. The ISR exits

At this point, the IRQ line on the PC is still high, but a new interrupt will not be generated. This is because it did not go low after UART 2 was serviced, so an edge was not generated.

The Multiport boards have to intelligently manage the interrupt output going on to the PC bus. The exact method varies from board to board, but the final outcome is the same: an edge needs to be generated for each interrupt that needs to be serviced by the CPU. This implies circuitry somewhat more sophisticated than just a giant OR gate, but doesn't require revolutionary new designs. This allows the board designers to keep the prices at a reasonable level.

All the boards that will be discussed in this article manage the interrupts in this manner. Each of the boards also incorporates an additional feature that helps the programmer: a status register. When the board generates an interrupt, there is a special register on the board that can be read by the interrupt service routine. This register indicates which port(s) are presently in need of servicing. Without this register, the interrupt service routine would have to poll each UART on the board for its current interrupt activity. The status register makes that job a little easier.

The multiport boards discussed in this article differ somewhat from RS-232 interface boards that readers may have seen on various other system. First of all, the 8250 family of UARTs are not considered to be high performance parts. Boards designed for systems such as DEC's VAX line of minicomputers can select the optimum UART for the job, since all system access goes through a device driver. PC board designers don't have this luxury, and must stick to the compatible family of parts, for better or worse.

An even more important distinction between PC multiport boards and those found on other systems is the requirement of processor intervention on every single character event. Higher powered boards relieve the system CPU of "character juggling" through many different mechanisms.

Generally these boards will have a dedicated processor that takes care of processing individual interrupts, buffering data, and transferring it to the main CPU memory via DMA or shared memory. Even if a slave processor is not available, many UARTs have FIFOs that can drastically reduce the number of interrupts required when processing data.

These intelligent boards suffer from only two problems: they cost an arm and a leg, and they are for the most part incompatible with the existing PC code base. So when an application requires support for 4 or more RS-232 lines, it makes sense to look at the lower cost, dumb-but-compatible multi-port boards.

When to Select an 8250 Family Multiport Board

When you have an application that needs to be able to service 4 or more RS-232 ports, you have several choices, including intelligent boards, networked systems, and multiport boards. The decision making process on which board to choose is fairly simple. As long as cost is an important factor, the multiport board board is your first choice. The end user price of under $100/port is well below the price of an intelligent board.

The primary drawback to the multiport board is one of throughput. As was discussed earlier, the CPU in your PC will have to individually transfer each byte from the UART to PC memory, or vice versa. By adding up the number of cycles needed to process each character, you can quickly get an idea of the maximum throughput on a PC. Even with carefully crafted assembly code, a 10 Mhz 80286 machine will only be able to keep up with perhaps 4-6 ports running continuously at 9600 baud. At that rate the CPU will be receiving a new interrupt about once every 250 microseconds, which is barely enough time to save and restore all the registers.

Fortunately, RS-232 throughput for most applications tends to be "bursty". An AT machine will have no trouble managing 8 or even 16 ports in an application where data is being sent only periodically. Think of a typical Point-of-Sale terminal application. Most terminals attached to the PC will be idle most of the time. As long as the processor can send the 2000 or so characters needed to redraw a screen in a second or so, it will have plenty of breathing room to catch up while the clerk runs the customer's Visa card through the imprinting machine.

One additional advantage to consider when selecting a type of board is the availability of library software. Most of the multiport boards discussed in this article have support available from several C and Pascal library vendors. The intelligent boards for the most part are limited to device drivers supplied by the vendor. These device drivers generally implement a basic feature set, but are short on bells and whistles. The competitive environment in the third-party library arena has created a buyer's market, with extensive feature lists available for library purchasers. Sources for these libraries are discussed at the end of this article.

The Software

Given that you now have an application that needs one of these multiport boards, and you have purchased one and installed it in your computer, what do you do next? Just having the board itself is not enough, you now need an interface to control and communicate with the RS-232 ports resident on it. The code to do this breaks down into three major sections:

• The control interface, used to open and close ports, and set and change parameters, such as the baud rate.
• The Input/Output interface, used by the programmer to read and write single characters, or blocks of characters.
• The device interface code, used to handle the physical level interface with the multiport board.

The conventional way to talk to a piece of hardware in the computer world is through a device driver, which is either part of or closely linked to the operating system of the computer. In the MS-DOS world, if you are talking to a device driver you can generally use the standard I/O routines that are supplied with your programming language.

Unfortunately, for various reasons, device drivers on MS-DOS machines will frequently not perform as well as we would like. This leads programmers to use shortcuts that talk directly to the hardware. Serial communications software is no exception to this.

The device driver built into the IBM PC BIOS for the RS-232 ports is of very little value. Since it is a polled mode interface, about the only thing it can reasonably be used for is an output-only interface, such as to a printer. In addition, multiport boards are unknown to the BIOS, so any device driver to support these boards must be added in as a separate program. Most manufacturers of multiport boards do in fact supply device drivers for their boards. Some are true device drivers which are installed via modification of the MS-DOS CONFIG.SYS configuration files. Others are TSR programs which can be installed and removed at any time on a running system.

Using the vendor supplied software can be a good or bad idea. The true MS-DOS device drivers allow you to open ports in C with standard fopen() commands, and read and write with putc() and getc(). Other vendors require you to learn new commands and link in their library routines. At the most inconvenient end of the scale, some vendors emulate the INT 14 BIOS service calls for their COM ports, requiring you to learn the arcane syntax of your particular compiler's version of the int86() function.

All of these are reasonable solutions, but they generally suffer from one or more disadvantages. First of all, the device drivers tend to be somewhat inflexible. MS-DOS does not support loading or unloading device drivers, so they usually have to be left in at all times, imposing an unwelcome burden on applications that don't need them.

Communicating with devices via system interrupts is usually slower than direct function calls. And most importantly, there are a lot of times when you want to have the source to your device interface code, and you don't usually get that from a board vendor.

Fortunately, it is not that difficult to implement your own code to talk to a multiport board. Most C compilers being sold today have the capability to implement a complete interface without having to resort to any assembly code, and still achieve satisfactory performance. As an example, I have supplied some sample code with this article that does just that, and all in only a little more than a hundred lines of C code.

The Sample Device Interface

The code for interfacing to the multiport board is contained in the file called COM.C. For the most part, this code glosses over the details of programming the 8250 UART. Various computer magazines have published many good articles over the past few years detailing how this part works, and the reader unfamiliar with the part can refer to these. In addition, I would recommend ordering the data sheets from National Semiconductor.

The code in COM.C is compatible with Microsoft C, Quick C, and Turbo C. The major difference to be handled between the two dialects of C is their implementation of the I/O port input and output routines, and the get and set interrupt routines. These differences are managed through the use of macros conditionally defined in the COM.H header file.

In order to understand how to use this code, you need to look at the procedural interface to the code. The data structures remain mostly hidden from view. In order to understand how the code works, you need to look at those data structures, and examine how they interface with the code.
Data Structures

There are two major types of data structures in this program, and once you understand how they work, the rest of the program's operation quickly makes sense. The two data structures are the BOARD structure and the PORT structure. The PORT structure is very similar to the structure you might use in a conventional single port program. The definition of type PORT in COM.H is shown below:

typedef struct {
    unsigned int   address;     /* Address of the 8250                */
    char           buffer[256]; /* The receive buffer.                */
    unsigned char  head;        /* Offset for insertion into the buff.*/
    unsigned char  tail;        /* Offset for removal from the buffer.*/
    unsigned char  match;       /* The status register match value    */
} PORT ;

The structure elements are as follows:

The only structure element that wouldn't normally be used in a single port operation is the "match" element. Depending on the board type, the match can either indicate which bit is set for the given port in the board status register, or what value in the status register will indicate the port is active. (Digiboard is the only board using the latter algorithm).

The BOARD data structure is a little different. A BOARD structure is what is attached to a particular interrupt line, and it in turn has to keep track of the PORT structures that are owned by a particular board.

The structure elements for BOARD are described here:

The Code

There are only eight routines in the COM.C file, and they implement a complete interface to a multiport board. In this case, the code was written to support a Stargate Technologies Plus-8 board, but it only requires changing a line or two in the interrupt service routine to support other boards. The routines are described below:

board_open( address, number ) :

This routine is called to perform the logical connection between a multiport board and an interrupt line on the PC. The address parameter is the address of the status register on the board. The number is the interrupt number to be used on the PC. For the first 8 interrupts on the ISA bus, the interrupt number is 8+IRQn, so IRQ3 and IRQ4 will have interrupt number 11 and 12. This routine initializes the BOARD data structure and returns a pointer to that structure. It saves the old interrupt vector, sets up a new interrupt vector, and enables interrupts on the specified line.

board_close( board ) :

This routine is called to shut down a given board, specified by the "board" parameter. board_close() takes care of disabling interrupts on the correct interrupt line, then restoring the interrupt vector that was in place before the board was opened. It also takes care of closing any of the ports attached to it that have not been closed with an explicit call to port_close().

port_open( board, address, match ) :

This routine is called to open a single port up, and attach it to the board it belongs with. The board parameter is a pointer to the BOARD structure, which should have already been opened. The address parameter is the base address of the UART, and the match parameter is used in the interrupt service routine to check for the status register bit indicating that this particular UART has an interrupt pending.

port_set( port, speed, parity, data, stopbits ) :

This routine is called after the port has been opened. It sets up the baud rate, parity, number of data bits, and number of stop bits for the port specified in the port parameter. After the parameters are set up for the port, receiver interrupts on that port are enabled.

port_close( port ) :

port_close is called to shut down the UART. All it does is disable interrupts on the selected UART, then free up the space that had been allocated for the port structure. The way the routines are presently written, board_close() will call this routine for each open port, so it doesn't need to be called by the application.

port_putc( port, c ) :

This routine is analagous to the fputc() routine in the C standard i/o run time library. It is passed a character and a pointer to a port data structure. It sits in a loop and waits for the UART to have space available in its transmit holding register. When the UART is ready to send another character, this routine stuffs it into the holding register and returns.

port_getc( port ) :

port_getc() is analagous to the fgetc() routine in the standard i/o library. It doesn't have to talk directly to the UART, since incoming characters are being stored in the circular buffer. It checks to see if there are any characters in the buffer, and extracts and returns one if there are. If no characters are available, an error code is returned.

interrupt_service_routine() :

The final routine found in COM.C is interrupt_service_routine(), which is not called by any routines outside of the COM.C file. It is the routine that is branched to when an interrupt is generated by the board. Its job is to service any and all interrupts pending on the multiport board. The way the routine determines which ports need servicing is by reading the status register. Once the status register has been read in, the ISR can loop through the list of open ports, looking for ports that have bits set in the status register.

The device dependent portion of the code is found in the interrupt service routine. The way the ISR decides whether to service a port on the Stargate board is by executing the following lines:

for ( i = 0 ; i < board.port_count ; i++ )
{
    if ( board.ports[i]->match & status_reg) {
                     .
                     .
                     .

The match value in each port structure has been set up in my sample program for the Stargate status register, where each port has a single bit in the status register. Other boards may expect the bit to be cleared for the given port. The Digiboard products don't use a bit pattern in the status register, they actually put a single port number in the register. These differing cases would only require a minor change to if line of code in the ISR.

The Test Program

In order to test this interface code, I wrote a short program called MULTTERM. This program creates four windows on the screen which each have an independent terminal session taking place concurrently. The way I wrote the program allows the user to switch the keyboard between the four windows by pressing Function keys 1 through 4. Even though keyboard input can only be directed to one port at a time, all four ports are actively receiving input characters at all times, and displaying them on the screen as they arrive.

The program consists of four modules that can be compiled separately and linked together. There are also three header files. The files are listed below:

The operation of MULTTERM.C is relatively simple. The program consists of only three sections. In the first section, four non-overlapping windows are opened up. In the second section of code, the board and the four ports are opened up. My test board was set up with a status register at address 0x580, and the UARTs spaced 8 addresses apart starting at 0x180. The Stargate Plus board uses a single bit in the status register to indicate that a port needs servicing, so the port parameters look like this:

Finally, after the ports are opened, the main terminal emulation loop is entered. This main loop has two sections. In the first section, the input buffers for all four ports are emptied out, with all the characters being written out to the appropriate display window. Once this is done, the second section is entered. This is where the keyboard is read. An Escape key causes an immediate exit, a Function key causes a switch to a particular window, and any other key is output to the appropriate communications port.

To test the operation of this system, I ran it on a standard 10Mhz XT, and connected it to Xenix system on four different ports. A sample screen capture is shown here:

----------------------------------------------------------------------------
|                                    ||23%                                 |
|17%                                 ||23% w -t                            |
|17% tty                             ||  3:24pm  up 1 day, 21:08,  5 users,|
|/dev/ttyi1a                         || load average: 0.00, 0.00, 0.00     |
|18% cat > /dev/ttyi1b               ||24%                                 |
|Message...                          ||24% tty                             |
|Message line two...                 ||/dev/ttyi1b                         |
|19%                                 ||25% Message...                      |
|                                    ||Message line two...                 |
|                                    ||                                    |
----------------------------------------------------------------------------
----------------------------------------------------------------------------
|Message  1:                         ||                                    |
|From nelson Sun Mar 18 15:22:48 1990||4% mail nelson                      |
|To: nelson                          ||Subject: Stargate                   |
|Subject: Stargate                   ||This message is being sent          |
|Date: Sun Mar 18 15:22:48 1990      ||through a Stargate board.           |
|                                    ||(end of message)                    |
|This message is being sent          ||5%                                  |
|through a Stargate board.           ||                                    |
|                                    ||                                    |
|d                                   ||                                    |
----------------------------------------------------------------------------

The sample program was built using the following QuickC 2.0 command line:

QCL /W3 MULTTERM.C VIDEO.C COM.C KEYS.C

If you are using Borland's Turbo C 2.0, use this line:

TCC -w MULTTERM.C VIDEO.C COM.C KEYS.C

The only differences between the two versions of the program are the names of the routines to get and set interrupt vectors, and the routines to input and output bytes to I/O ports. These differences are handled by #define statements in COM.H. Note that this program can be ported easily to any MS- DOS compiler that supports interrupt service routines written in C.

The test program operated fine on the XT, although I didn't subject it to heavy data traffic. It was able to receive data simultaneously on all four windows without losing any characters. However, if I want to keep up with continuous data on multiple ports I would either need to upgrade to a faster machine or optimize both my Com port and display I/O routines.

Software Improvements

If you wanted to develop the routines shown here into a production quality library, there are quite a few areas that would benefit from attention. Most of the refinements can be done one at a time, allowing for a steady evolutionary improvement in your library. Some of the most beneficial improvements would be:

• Allowing for adjustable buffer sizes. 256 bytes may prove to be far to small for some applications.
• Interrupt driven transmission, as well as reception. This requires modification of the ISR to check for the type of interrupt.
• Hardware and software handshaking, including XON/XOFF, RTS/CTS, and DTR/DSR.
• Support of more than one board operating at a time.
• Hand coding of the interrupt service routine in assembly language for maximum optimization.
• Break detection on the incoming line.
• Adding lines to check the status of the incoming modem status lines.
• Detection of parity errors, overrun errors, etc.
• Protection from uncontrolled exit of your program without disabling interrupts.

Hardware Sources

There are quite a few different companies making multiport boards for the PC bus family of machines. A few of the names and phone numbers of companies whose hardware I have used are shown below. The biggest demand for these types of boards has in the past come from users of multitasking operating systems, so the manufacturers have tended to advertise in Unix oriented magazines. If you want to do more research, this would be a good place to look. This is not intended to be a comprehensive list, and any time you spend doing research in area will probably be worthwhile.

Commtech, Inc.
Wichita, KS
316-651-0077

Contec U.S.A
San Jose, CA
800-888-8884

Digiboard, Inc.
St. Louis Park, MN
612-922-8055

Quadram
Norcross, GA
404-923-6666

Quatech, Inc.
Akron, Ohio
800-553-1170

Stargate Technologies, Inc.
Solon, Ohio
216-349-1860
Software Sources

It is relatively easy to go into business selling C libraries. All you need is a few months of time to develop a product, and a little seed money for advertising. This fact, combined with the high demand for quality libraries, has resulted in there being at least a dozen companies selling C libraries for serial communications. With this many entrants in the market, a "features war" has developed, resulting in a good buyers market. For less than $300, you can buy libraries that have an enormous amount of functionality. Most of these library vendors have ads in the pages of this magazine, so the research job is relatively simple. Armed with the list of functions you need, you should be able to estimate the amount of effort required to write your own code. Given this, you are ready to make a build or buy decision.

In addition to the commercial market, there are a few public domain and shareware serial communications libraries available. However, I am not aware of any that offer support for multiport boards. Of course, it could be practical to modify one of these libraries to suit your particular needs.

Conclusion

In order to use more than two RS-232 ports on a PC, you need to purchase a multiport board. While this does mean you have to either build or buy some non-standard device interface software, this can be done without too much new code. So if you have an application that demands communication with multiple source of information in the real world, this can provide an economical means of accomplishing your goal.

This article first appeared in the May, 1990 issue of Tech Specialist

The COM ports on an IBM compatible PC provide MS-DOS users with an extremely versatile avenue for communications with other devices. Yet experienced PC programmers find that the operating system and their compiler libraries offer them with very little in the way of useful tools for using these COM ports. Fortunately, C compiler technology has advanced to the point where it is now practical to implement an interrupt driven communications system entirely in C. This article discusses some of the techniques for accomplishing this.

A Brief History of COM

The original design for the IBM PC included provisions in the hardware and the BIOS for the support of RS-232 communications ports. The BIOS supports up to four COM ports, but both MS-DOS and the hardware design reduced the number of ports that could practically be used to two. These ports are referred to by their MS-DOS device names, COM1 and COM2. The designers chose the 8250 series of UARTs from National Semiconductor, and implemented a single port communications card that supported the following items:

• Interrupt or polled input and output.
• Modem control output lines RTS, DTR.
• Modem control input lines CTS, DSR, RI and CD.
• Baud rates up to 115200 bps.

Unfortunately the BIOS implementation for the COM ports restricted these capabilities somewhat. The BIOS functions for the COM port do not support interrupt driven I/O, and only allow eight discrete baud rate settings which range up to 9600 bps. MS-DOS uses the BIOS for all of its COM port functions, so the BIOS provides the limits on what functions programmers have available using the operating system.

Using the COM port for output-only applications, such as for spooling to a printer, works fairly well using this built-in support. The application operates in a somewhat inefficient mode, since it is effectively idled for the duration of its output, but it is able to get maximum throughput out of the port, even at higher baud rates.

But when MS-DOS programmers try to use the COM ports for applications that require both input and output, they are quickly stymied. Even at rates as low as 1200 baud, polled mode software has to sample the input port at rates that create incredible scheduling problems within programs. At the highest BIOS supported rate of 9600 baud, a program would have to sample the UART once every millisecond without fail. This is essentially impossible.

This leaves the programmer with only one option for programs that need to make full use of the COM port: using interrupt driven communications. This allows the program to go off and do some work while characters are being read into a buffer and/or being pulled out of a buffer and passed through the UART. The idea behind this sounds attractive, but most programmers feel that implementing this type of code is extremely difficult.

At one time this was certainly true, but advances in C compiler implementation have reduced the level of effort needed to solve this problem. Unlike four or five years ago, it is now relatively easy to implement an interrupt service routine that manages the UART without ever having to leave the comfort of your C compiler. This is a marked change from the days where this type of code had to be developed from assembly language. This article will demonstrate how to write this type of code using both Microsoft C & Borland's Turbo C.

The UART

Writing device interface code requires that you understand the hardware. In this case, the hardware to interface with is the 8250/16450/16550 family. The original PC was equipped with 8250 UARTs. The AT began using the 16450 UARTs, and some of the newest machines are now being equipped with 16550s. The two newer members of this UART family are completely downward compatible with the 8250, so code written for it will run without modification on newer machines.

The 8250 has 11 internal registers that the programmer can access. On the IBM compatible PC, these registers are laid out on the I/O bus, rather than being mapped into memory. This means that the C programmer needs to access the registers using the inp() and outp() library routines. The register definitions are accessed through eight consecutive port locations. The function of each of the 11 registers is discussed in detail in this section.the following offsets and conventional mnemonics

RBR: Receiver Buffer Register (Offset 0)

This is the holding register that receives a character after the UART has finished reading it in from the RS-232 line. Since the UART is double buffered, the receive can be working on reading in the next character while at the same time waiting for the CPU to read the character out of the RBR. This give the programmer approximately one character time to respond the character being read in. This is a read-only register.

THR: Transmit Holding Register (Offset 0)

This is a write-only register that accepts a character to be sent out of the UART. As soon as the UART transmitter is available, the character is moved out of the holding register and into the transmitter and starts going out on the RS-232 line.

IER: Interrupt Enable Register (Offset 1)

This register has four bits that individually enable each of the four different types of interrupts that the 8250 family can generate. The bit masks and the interrupt types are:

IIR: Interrupt Identification Register (Offset 2)

When an interrupt occurs, the Interrupt Service Routine (ISR) reads this register to determine what caused the interrupt. The register contains one of five values, four for the four different interrupt types, with one more for "no interrupt pending". The values read out of the IIR are:

LCR: The Line Control Register (Offset 3)

This register has control over how the UART sends and receives characters. All eight bits of this register are used, with the following definitions and bit masks:

MCR: The Modem Control Register (Offset 4)

The Modem Control Register has five bits that can be set or cleared by a program. They are listed here, along with the bit masks used to set or clear the bits:

LSR: The Line Status Register (Offset 5)

The Line Status Register has seven bits that contain various status indicators relating to the actual transmission of data. The error bits and the break indicator can be read directly from this register. They will also generate an interrupt when they are set, so they can be read from inside an interrupt service routine to eliminate the need to poll this register. The bits and masks that can be set in this register are:

MSR: The Modem Status Register (Offset 6)

For each of the incoming four modem status lines, there are two bits in this register. One of the bits is used to detect the state of the line. This line can be polled at any time to determine what the state of a particular line is. The other bit is used when a Modem Status interrupt occurs. This bit, called the delta bit, indicates which lines have changed state, causing the interrupt. If modem status interrupts are being used, the delta bits can be examined to determine which line caused the interrupt. The bits in the MSR are defined as follows:

SCR: The Scratch Register (Offset 7)

There is a spare register in the 8250 that can be used as a storage area. It is generally not used for anything in the IBM PC compatible development environment.

DLL & DLM: Divisor Latch LSB and MSB (Offset 0 and 1, DLAB=1)

The Baud Rate at which the 8250 transmits and receives data is established by dividing a master clock by a 16 bit divider. The master clock on the IBM PC COM card is operating at an effective rate of 115,200 Hz. Thus, a divider of 12 yields a baud rate of 9600. Since the UART has an 8 bit wide data path, the divider has to be loaded in two registers. On the 8250, the least significant byte of the divisor is loaded into register 0, and the most significant byte is loaded into register 1.

The problem with these two registers is that the designers of the 8250 found that they came up a couple short on registers in their address map. They could either expand the address space to 10 registers, or play some tricks with they space they had. They opted for the tricks. In order to access the baud rate divisor registers, there is a bit in the Line Control Register that must be set. This bit, the Divisor Latch Access Bit, temporarily changes the function of registers 0 and 1 while it is set. So to load the baud rate, the code normally sets DLAB to 1, writes to register 0 and 1, then restores DLAB to its normal setting of 0.

Writing The Interface Code

Despite the fact that there are so many registers, control lines, bits and bytes to keep track of on this UART, it is still relatively easy to develop a fully featured communications interface to it. The sample program developed here only uses 6 routines, none of which take up more than a screenful of code.

The code presented here uses interrupts for both input and output. While this adds some complexity to the software, it should also increase the overall performance of a program by relieving the processor of the dead time incurred during polled output. It also makes the code much easier to modify for support of hardware handshaking, which requires the use of Modem Status Interrupts. An ISR supporting multiple interrupt types will also make it easy to add interrupt based detection of line errors to this code.

The interface to a device of any kind has five basic types of functions that are needed in order to operate the device:

• An open function, to establish a link with the device.
• A control function, to manipulate device parameters.
• An input function, to receive data from the device.
• An output function, to send data to the device.
• A close function, to break the link with the device.

In a comprehensive library, there will be multiple functions in many of the five categories, but the basic five provide a platform on which to start building.

The Port Structure

Before looking at the interface functions to the COM port, it is a good idea to understand what is stored in the PORT structure. The PORT structure is analogous to the FILE structure used by the C standard I/O library. When a COM port is opened, the PORT structure is returned, and all future access to the COM port is done through the structure. The definition of the PORT structure, found in Listing 2, COM.H is:

typedef struct {
    void (interrupt far * old_vector)();
    int  uart_base;
    int  irq_mask;
    int  interrupt_number;
    BUFFER  in;
    BUFFER  out;
} PORT ;

The buffer structure is defined previously in the COM.H file as:

typedef struct {
    char buffer[256];
    unsigned char write_index;
    unsigned char read_index;
} BUFFER;

Once a COM port is opened, the information in the PORT structure can be used to perform any of the functions needed to manipulate it. The structure members have the following definitions:

The structure of the input and output buffers in this program is fairly simple. They are implemented as 256 byte circular buffers with each one having a read index and a write index. For both the input and the output, only one process is allowed to modify the write_index, and only one process is allowed to modify the read index. This simplifies the code, since interrupts do not have to be disabled during the routines that insert and delete characters from the buffer. For example, on the input buffer, the port_getc() routine is allowed to increment the read_index when extracting a character, and the interrupt service routine is allowed to increment the write_index when inserting a character. An additional simplifying factor with these buffers is their size, 256 bytes. This means that the indices for the buffers can be one byte, and the increment procedure will inherently roll the pointers over when they reach their maximum. In point of fact, most applications will find 256 bytes to be too small for both the input and output buffers, and will have to increase the size. The code for managing the indices in this case will also get a little larger.

The Open Function

The open function needs to establish a logical link with a particular device. In the case of a COM port on a PC, the minimum amount of information to establish the connection would be the COM port number, 1 or 2. In order to provide a little more versatility, I had my routine require as parameters the UART base address and the CPU interrupt number. The function prototype is:

PORT *port_open( int address,
                 int int_number )

This requires an extra parameter beyond what would be needed for just using COM1 or COM2, but it does allow the routine the flexibility to deal with non-standard COM port implementations. There are quite a few variations of COM3 and COM4 that are circulating about, and this routine should be able to handle all of them. Note that like its counterpart in the C standard I/O library, fopen(), port_open() returns a pointer to a structure. The PORT structure contains all of the information needed for future operations on the port.

The actual code for port_open is shown in Listing 3. The space for the PORT structure is allocated with a call to malloc. The input and output buffer pointers are both initialized. The UART address and interrupt parameters are initialized. The existing UART interrupt vector is stored, and a new one is established. The new interrupt vector points to the interrupt vector in COM.C. Finally, the 8259 Interrupt Controller on the PC bus is told to start accepting interrupts from the UART. Note that the UART won't start generating interrupts yet, because it has not had its interrupts enabled yet. It would be unwise to enable interrupts before setting the rest of the operating parameters.

There are two lines in the port_open routine that store the DOS CTRL-BREAK vector off and establish our own private interrupt handler for CTRL-BREAK processing. This is done so that the user can't break out of the program without giving the code a chance to turn off interrupts and restore the old interrupt vectors. Note that in a communications system that was supporting multiple ports simultaneously, this processing would only be done when the first port was opened, so there would need to be a flag set once the CTRL-BREAK vector was subverted to insure that it only happened once.

The Control Procedure(s)

After a program has opened a COM port, it needs to set the baud rate, number of bits, parity, etc. for the port. Depending on the number of features available in the package, there may be many control procedures. Some may act directly on the UART, others will operate on the data structure associated with the UART. My implementation of a control procedure is a single function, called port_set(), which allows the caller to set the baud rate, parity, number of data bits, and number of stop bits for a COM port. The parameters are the same and in the same order as the DOS MODE command. The prototype for the port_set() procedure is:

void port_set(PORT *port,
              long speed,
              char parity,
              int data,
              int stopbits);

The code for this routine, shown in Listing 3, accomplishes this in a straightforward manner, by updating all the relevant registers in the UART. Before any changes can occur, all interrupts in the UART are disabled. At that point, the registers are all updated. Note that it is imperative to have interrupts disabled while the baud rate is being changed. If an interrupt occurred while DLAB was set to 1, the interrupt service routine would think it was accessing the Receive or Transmit data buffers, when in fact it was modifying the divisor registers.

This routine also turns on DTR, RTS, and OUT2. OUT2 has to be enabled on the IBM PC COM card in order for interrupts to occur. A complete package would allow the user some control over DTR and RTS, but adding those functions to this package should be straightforward. Finally, after all is ready, this routine turns Receive interrupts back on. At that point, any incoming characters will be received by the Interrupt Service Routine and inserted into the input buffer.

The Input Function

Input and output functions take on quite a few different forms, and it is unlikely that any single function would do. However, I have implemented just a single function here, port_getc(), which attempts to get a single character from the input buffer for the port. Understanding how this routine works would allow you to easily build other functions, such as port_get_buffer(), port_getc_with_timeout(), port_get_string(), etc.

The input function here, port_getc(), receives just a single parameter, which is a pointer to the port data structure. It doesn't talk to the UART at all. Rather, it just looks to see if there are any characters in the input buffer, and extracts one if there is. It returns an error immediately if there are no characters available. An alternative way to implement this function would be to wait either for a fixed amount of time or indefinitely if no characters are available.

The Output Function

The output function for the sample communications package is called port_putc(). Its prototype is:

int port_putc( unsigned char c, PORT *port )

This routine has to first check to see if the output buffer is already full. If it is, an error is returned. (Note that it would be a simple matter to modify the routine so it just waited for there to be room in the buffer). In the event that there is room in the buffer, the single character is inserted. Note that the character must be placed in the buffer before the index is incremented. When writing code like this, you have to consider the ramifications of an interrupt occurring at any point in any operation during the routine.

This routine differs from the port_getc() routine in one respect: it has to actually communicate directly with the UART. The reason for directly modifying the UART is that Transmit interrupts are continually being enabled and disabled on the UART. When no characters are present in the buffer, it is necessary to turn off the Transmit interrupt, otherwise it would be generated continuously. This means that after a new character is inserted into the buffer, the port_putc() routine needs to see if Transmit interrupts are already enabled. If they aren't, this routine enables them. This starts the chain of events that leads to a Transmit Interrupt occurring, and the character that has been placed in the buffer being transmitted.

It is probably more common for programmers to implement this routine as a polled mode function. The code both in this routine and in the Interrupt Service Routine is shortened somewhat when this is done, at the expense of a certain amount of efficiency. A polled mode version of port_putc() would look like this:

int port_putc( unsigned char c, PORT *port )
{
  while ( (inportb( port->uart_base + LSR ) & LSR_TEMT ) == 0 )
    ;
  outportb( port->uart_base, c );
}

The Close Function

A program that has enabled interrupts on the COM port has to be careful to restore the computer's configuration back to "normal" before exiting the program. Failure to do so could leave interrupts enabled on the port. After the program exits, the interrupt service routine will no longer be in memory, so if an interrupt occurs, disaster will follow.

The close function here is called port_close(). All it takes as an argument is a pointer to the port structure:

void port_close( PORT *port );

The first thing port_close() does is disable all interrupts on the UART. That by itself is enough to restore things to a safe state, but it does a couple of more things in the interest of cooperation with other programs. First, it disables the selected interrupt at the 8259 Interrupt Controller, and then restores the interrupt vector that was in place before the program was selected. Finally, it restores the system CTRL-BREAK handler. Note that if a program is written to use multiple ports, you would only want to restore the system break handler when the last port is closed, or the program exits.

When the port is closed, this code drops DTR and RTS. This should have the effect of letting any device attached to the PC know that the port is no longer active. For example, if a modem was attached to the COM port, and it had a call in progress, dropping DTR should cause it to hang up.

One way this port_close() routine could be drastically improved would be by saving the settings of the COM port when it was opened so it could be completely restored when closed. Right now, the port is left in an arbitrary state on exit. If a previous program had the port set up with a certain baud rate and parity settings, these routines would obliterate them. It is not too hard to add the code to the port_open() routine to read in all the register settings of the UART before it is opened. Then, those settings can be restored upon exit. This should include the settings of the 8259 interrupt controller as well. This kind of attention to detail would be mandatory if, for example, you were writing a COM program that would be a TSR.

The Interrupt Service Routine

The heart of the communications port interface code is the Interrupt Service Routine. This is where all the bytes get moved in and out of the UART. This is also the one part of the interface code that the application program never sees.

If you were going to write an interrupt service routine for a C program 3 or 4 years ago, you would have had to get out the Assembly Language reference books, install a copy of MASM, and start doing some low level bit twiddling. But today, both Microsoft and Borland have built into their compilers the function type modifier "interrupt". If you declare a C procedure to be type "interrupt", the compiler takes care of some important details for you. First of all, it saves all the registers, which a normal C routine doesn't do. Secondly, it loads the DS segment register with a pointer to DGROUP, the default data segment. And in the exit code for the routine, it restores all the registers, and then returns with an "iret" instruction instead of the normal "ret".

There are still quite a few precautions you have to take when writing an interrupt service routine in C. You are precluded from using most of the run time library, as the routines are generally not written to be re-entrant. You probably don't want to call any DOS or BIOS functions, for the same reasons. And you need to be very careful about calling other C routines. For example, if the other C routines have stack overflow checking turned on, they will probably abort when called from inside an interrupt service routine.

With all that in mind, it is still possible to write a fully functional ISR in C. The ISR written for this routine is shown in Listing 3. The 8250 ISR is relatively simple. It sits in a loop, reading in the Interrupt Identification Register over and over, servicing each interrupt type as it appears. When it finally reads the IIR and sees that no more interrupts are pending, it exits the ISR.

The reason the 8250 ISR has to continually read the IIR until all interrupts have been dealt with is due to the way the PC hardware is configured. The 8259 interrupt controller on the PC is configured to be edge sensitive. It will only detect an interrupt on a device when the interrupt line makes an OFF to ON transition. If we were to exit our 8250 Interrupt Service Routine without servicing all of the interrupt types that were pending, the 8250 would keep its interrupt line ON, thinking that this would get the processor's attention later on. However, the 8259 interrupt controller would assume that since the UART hadn't brought the line down yet, it was still being serviced from the previous interrupt. So it is necessary to clear out all pending interrupt conditions on the device before exiting.

The Interrupt Service Routine has a switch() statement that examines the IID, and goes to one of five cases upon reading the result. The first four are for the conventional interrupt sources. In the case of Modem Status Register and Line Status Register interrupts, the ISR just reads the appropriate register to clear out the interrupt. Since this program isn't using those interrupts, they should never be executed anyway.

The IIR_RECEIVE case in the ISR is called when there is a new character in the receiver buffer. The first the ISR does is read the character out of the RBR, which clears the interrupt source. Then, if there is room in the input buffer, the character it received is queued up in the buffer. A useful addition here would be to set an error flag when a character is received but can't be inserted into the buffer.

The IIR_TRANSMIT case is branched to when the Transmit Holding Register is empty. This occurs in one of two cases. When transmit interrupts are first enabled by port_putc(), an interrupt occurs immediately, since the THR is empty at that time. The other case is when the Transmitter Register empties out, and the old character in the THR is moved into the transmitter. At this point, the UART is ready for another character, and an interrupt is generated.

The IIR_TRANSMIT code first checks to see if a character is ready in the output buffer. If one is ready, it is pulled out of the buffer and written out to the THR. If no characters are in the buffer, it is time to shut down transmitter interrupts, as they are no longer needed. The next time port_putc() is called, they will be started back up.

The final case in the IID switch() statement is for when there are no further interrupts pending. In this case, the EOI indicator is written out to the 8259 interrupt controller so it knows that the interrupt has been serviced.

One of the alternative ways to handle COM port I/O that was discussed in this article was the idea of only allowing receiver interrupts, and having the transmit done with polled I/O. If this is done, it will greatly simplify the interrupt service routine, since it can assume that every interrupt is a receiver interrupt. In that case, the ISR will look like this:

static void interrupt far interrupt_service_routine()
{
  if ((com->in.write_index+1 ) != com->in.read_index)
    com->in.buffer[ com->in.write_index++ ] =
      (unsigned char) inportb( com->uart_base + RBR );
  outportb( INT_CONTROLLER, EOI );
}

Putting It All Together

In order to test and demonstrate this code, I created a very short terminal program, which is found in TERM.C, in Listing 1. After opening the port and setting up the transmission parameters, the program just sits in a loop polling the keyboard and COM port for input. Keyboard characters are sent out through the COM port. Characters read in from the COM port are displayed on the screen using putc(). Hitting the Escape key shuts down the port and exits.

While this is not a very useful program, it does provide a good test bed for the program. However, I was able to use it to verify the most important fact, which was that the interrupt service routine was able to keep up with a steady stream of incoming data at 9600 baud on a standard XT without missing any incoming characters. Using putc() for output, the program wasn't able to output the characters to the screen fast enough to keep up, but I was able to get around that by switching over to direct video access, and less frequent polling of the keyboard.

In order to build this program using QuickC, enter:

qcl /W3 /Ox term.c com.c

Using Turbo C, enter:

tcc -w term.c com.c

Enhancements

The communications interface presented here is more than adequate for many applications. And in the places where it isn't adequate, it provides a framework for developing enhancements. Some enhancements that immediately come to mind are:

Optimization of the three most heavily used portions of the code: port_putc(), port_getc(), and the interrupt service routine. All three are candidates for rewriting in assembly code for speed. Port_putc() and port_getc() are candidates to be rewritten as macros so they can be called in line, saving some overhead.

Adding hardware and/or software flow control: XON/XOFF handshaking is frequently needed when performing terminal emulation, and RTS/CTS or DSR/DTR handshaking is useful when talking to a variety of devices such as printers and modems.

Modifying the code so it can simultaneously support multiple ports: The PORT structure has already encapsulated all of the data for a COM port, so this could be accomplished relatively easily. The main thing that needs to be done is to provide special handling for things that only need to be done once, like interception of the CTRL-BREAK function. The atexit() function would be a useful way to implement this.

Adding detection for incoming break characters, and other line status errors.

Adding support for the 16 byte receive and transmit FIFOs on the 16550 UARTS: This allows data to be moved in and out with far fewer interrupts occurring, resulting in much more efficient code.

This code can provide a useful added capability to your programming toolkit, and takes care of a noticeable gap in the MS-DOS library of device drivers. Best of all, the code is actually portable across several of the leading MS-DOS C compilers, and doesn't require you to understand assembly language. So if you have an application that needs to take advantage of RS-232 communications, you can now take the plunge with full confidence that the project can be accomplished.

Listings