This page describes my experiences writing a LinuxPPC device driver for the Keyspan SX serial card.
Back to Otto's LinuxPPC Goodies page.

Gathering information

The first stage of writing the device driver consisted of gathering information about the card I have, learning about Linux device drivers and an investigation on existing PCI serial card drivers.

Hardware description of the card

I started by looking at the card itself. I found two big chips on it: a chip marked PLX9050 and a chip marked ST16C654. I did searches via various search engines on the net and came up with two links:

PLX Technology, a company making PCI related devices. Here I could download the data sheet of the PLX9050 chip. This chip is a so called PCI bridge. Intended to attach slave devices to a PCI bus.
Exar, a company making various mixed signal IC's. Amongst there products is the ST16C654 four channel UART.

So it looked like the card has a fairly simple architecture: one chip containing a UART cabable of handling four serial ports, connected to the PCI bus via a chip that is designed to simplify access to hardware devices from the PCI bus. Furthermore, the UART is a member of the family of UARTs commonly found in PC's.

This information nicely corresponds with information I could find using Linux commands. See the next sections for more details.

Why not ask Keyspan for this information?

Good question. I think it is a nice challenge to try to reverse engineer the workings of the card. I looks like I have come a long way, without disassembling the existing MacOS driver. Maybe I will ask Keyspan for some confirmation on some issues at some point in time, however.

Linux kernel, device drivers and PCI information

In the meantime I studied the Linux existing serial drivers to find out how they worked. I looked at the code in linux/drivers/char/serial.c and linux/drivers/macintosh/macserial.c. I found out that if I could make some glue to make the existing serial.c code talk to the UARTs on the SX card, I had a good chance of coming up with a working driver quickly. The serial.c code supports various UARTs from the same family as the ST16C654 directly. Sadly, there is no PCI support there. Other drivers, like cyclades.c do support PCI, but have a different architecture, so a direct port is not possible.

I also read an online document about the Linux kernel which also has a nice chapter about PCI. Sadly the "Linux Kernel Hackers' Guide" seems to be out of date on a lot ob subjects. I also browsed though the files in the linux/Documentation directory. The file linux/Documentation/kernel-docs.txt contains some references, but I found that a lot of them are outdated. The most comprehensive source of information is the book "Linux Device Drivers" by Alessandro Rubini. I think that understanding Linux device drivers was not too hard for me, since I learned a lot about Unix and device drivers in general during my study of Computer Science and subsequent jobs.

Looking at te card runing Linux

Linux > 2.1.81 has the lspci command to retrieve information about PCI devices on the PCI bus. It is normally located in /sbin. The following lines are an extract of the information lspci -v gives on my machine when there is no driver available for the card:

01:03.0 Bridge: PLX Technology, Inc. PCI <-> IOBus Bridge (rev 01) 
    Subsystem: Unknown device 11a9:5334 
    Flags: medium devsel, IRQ 24 
    Memory at 80880000 (32-bit, non-prefetchable) [disabled] 
    I/O ports at 1080 [disabled] 
    Memory at 80888000 (32-bit, non-prefetchable) [disabled] 
    Memory at 80884000 (32-bit, non-prefetchable) [disabled]

The PLX9050 is located on bus 1, device 3, function 0. It is a revison 1 chip and contains subsystem vendor id 11a9 and subsystem device id 5334. [what does medium devsel mean?] It uses interrupt request 24, and it has three memory regions and one I/O port region, which are all disabled.

Since all memory and I/O regions are disabled, the PLX9050 is not active in this state. It looks like the Mac Open Firmware booting process does not enable the card, and neither does the Linux PCI startup code. See below for configuration data from the card when running MacOS.

Existing PCI serial card drivers

First I looked on the WEB for PCI Linux serial card drivers available in source code. After some searching I found two promising links:

GTEK sells a card that very much looks like the SX card: the JetPort II. Look at the picture and you can see the nice big PLX logo. When I found this information I thought I was very lucky: a card that use the PLX9050 and the ST16C654 and with an available Linux driver! Alas, it did not work:
[add info about the JetPort driver and why it didn't work]
Connect Tech Inc. has a Linux driver for their BlueHeat card. It can be found here.
[add info about the BlueHeat driver and why it didn't work]

Investigating the card running MacOS

Next thing I tried was getting as much information about the card as possible. When running MacOS, that card is enabled, so I thought it was a good idea to look at the card when it is operating.

SX Manager

SX Manager is a little program that comes with the SX card MacOS driver. It has a reporting facility. Here is a screen shot of the SX Manager Event Log after asking for port statistics for both ports:

Screenshot SX Manager Event Log

We can see some interesting things in this window:

First, the addresses we saw using the lspci command come back here. So MacOS is using the same PCI address configuration as Linux.
The only address that differs between the two ports is the portBaseAddr. The name of the address suggest that the UARTs are mapped to these locations by the PLX9050. At this point in time, I don't know what burstBaseAddr is used for. lcrBaseAddr is the base address of the "Local Configuration Register" of the PLX9050. Note that there is no mentioning of any I/O address in this screen shot
Item 3 and 4 are just reports of me typing the wrong key combination for screen shots on the Mac...

PCIPeek

PCIPeek is a program that comes with the PCI developers' kit available free from Apple. Here are two screen shot of PCIPeek:

Screenshot PCIPeek

This screen shows the local configuration registers from the PLX9050. The most interesting one is probably the command register, which shows that only memory access is enabled. I/O access is disabled. This information confirms the suspicion that the UARTs are accessed memory mapped, and not I/O mapped. This has big consequences since most UART drivers I have seen use I/O mapping. This explains why the drivers I tried could not contact the UART!

Screenshot PCIPeek

But of course Keyspan had some extra surpise. This one took me some time to find out: the UART registers are not mapped to a memory region of 7 consequtive bytes, but are mapped 0x80 bytes apart from each other. Reading from offset 0x00 to 0x7f just reads the same register! You can see data coming out of the UART in the bottom half of the screen dump nicely. The second block shows the value of the interrupt status register. The reason the first block of data changes in the middle is that while I was executing the dpm command, my modem was dumping its configuration at 300 baud to a terminal window. I happened to catch a part of one of the S register settings.

The first working probe!

Here you can find the code of the very first working version of a device driver that does a probe for the SX card and its UARTs. This code works if you have a 2.2.10 source tree with this patch applied first. With other kernel versions it may also work, but I did not test that.

[add some explanation here]

Design decisions to make

There are some design issues to resolve before I can proceed writing the real driver. I requested some assistence by sending out a mail to various mailing lsists. You can find the request here. If You have any comment to make, I'd like to hear.

Testing

Currently I am organizing some people to test the driver. The first step was set on Monday, Aug 9 1999. I send out a call to the linuxppc-dev and linuxppc-user mailing lists and the comp.os.linux.powerpc newsgroup. You can find the call here.

The Future

Originally, the following items were on my wish list:

support for any PLX9050 based serial card with any of the serial.c UARTs?
What about other bridge chips?
More platforms!

Well, it looks like the future is here! The Keyspan SX driver evolved into a general purpose PCI serial driver. If you have a "dumb" PCI serial card and are running Linux 2.2.x on Intel, PowerPC, Alpha or any other system supporting PCI, chances are the driver will work for you. More information can be found here.

Please email comments to Otto Moerbeek