User Mode Drivers

I have a regular discussion about
user-mode drivers and Linux. It starts with a customer who
maintains a DOS system realizing that at some point--usually sooner
than later--he must upgrade his application to run under another
OS. Of course I suggest Linux.In these discussions, the customer will proceed to explain
that he or she doesn't know how to write a device driver and
doesn't want to spend the time to learn how to do so. The
customer's code on the DOS system is console-based and uses simple
(x86) I/O ports to read the adaptor card. Typically, he or she also
will vent a bit about how operating systems have hardware
protection. It only takes me a minute to mention that Linux
supports methods of directly accessing the device with a user
application. Then there's the customer's problem with the absence
of ISA slots in modern PCs; the old adaptor card won't work in a
new system. PCI-based cards can replace the ISA-based device, but
for his or her code there's a clincher: how do you know the
settings of the PCI device?This is a short article on writing user-mode device drivers
to penetrate the abstraction layer from a user application and to
determine where a PCI card is located. This information is useful
for those concerned with replacing their DOS machines and porting
code to Linux. There are many reasons in favor of a user-mode
driver. The user-mode method is very useful for validating new
hardware. It's also convenient for informal accessing of the device
on a register level. But, there are many simple hardware devices
that don't implement interrupts, and their operation is hardly
worth writing a device driver for.Accessing I/O Map DevicesHistorically, x86 peripherals were I/O mapped. The x86
architecture has two memory maps: one for the memory and the other
for peripherals. This separate map has unique instructions for
accessing it. In Port and Out Port were used to read and write
bytes, words or longs (in those days) to the hardware.The Linux system calls ioperm(2) and iopl(2) (with a level
argument of 3) are the silver-bullet commands for penetrating the
abstraction layer. These functions are reserved for the root user
(UID == 0), and each is slightly different.
ioperm() opens up a block of the
I/O space to the user application. This function requires the
starting I/O base address and the block size (length) of
consecutive addresses. ioperm() is
useful for accessing ports located from 0x0000 through 0x03ff. On
the other hand, iopl() opens up the entire I/O space for accessing.
PCI devices that are I/O mapped typically are located above the
space ioperm() permits, so iopl() must be used.Once the abstraction layer is opened, there are six primary
system calls for reading and writing to the I/O map. Three are for
reading, and three are for writing to the I/O map. The reading
triplet is inb(), inw() and inl() (for byte, word and long,
respectively). The writing triplet is outb(), outw() and outl()
(for byte, word and long, respectively). The header file is
<sys/io.h>.First the application needs only to call the appropriate
function (ioperm or iopl), then inspect the error code returned by
the system call, if any. Both ioperm and iopl return zero on
success. Now you can start reading and writing--it's that
simple.Accessing Memory-Mapped DevicesMany devices are memory mapped for two reasons. First, for
x86 architectures, the memory map is more expansive than the I/O
map. Most other architectures only have a memory-mapped
architecture (in other words, you don't get a choice); only the x86
architecture has the second address space for peripherals. Again,
there are methods to penetrate the memory protection mechanism to
access the hardware. The other reason is that arguably, more
powerful addressing modes allow faster and more flexible methods of
accessing the memory. The x86 port commands are extremely limited
in features.To access your memory-mapped hardware, the device /dev/mem is
the silver bullet, and mmap() is the method to select the memory
physical base address and the block size to access. To open the
peripheral memory, open /dev/mem. Use the opened file descriptor in
mmap(), with the appropriate address and the block size (in bytes)
to open. mmap() returns an address
that is mapped to the physical base address; cast it to the
appropriate data type and use it like any other pointer, array,
structure pointer or your favorite method.What's My Device's Address?Many hardware devices are hard-coded. Usually a good
reference will describe where the device is located. For example,
my employer manufactures many ISA-based products where the device
address is set using jumpers. A device's address is found by
comparing its jumpers and a table in a user's guide. That's
easy...almost.PCIPCI is this wonderful interface that automatically configures
the hardware and automatically assigns the device interrupts and up
to six base addresses. You can plug in a card and forget about
it--until you need to write the driver. Well fortunately, there's
another great cheat to help with this task (drumroll, please):
/proc/bus/pci/devices. When you view this file in the /proc
pseudo-filesystem, what appears is a bunch of hexadecimal numbers.
Here's what my machine says (ignoring the other devices):

0168   148aac05   b   f6400008   f6aff008   00000000
00000000   00000000   00000000   00000000   00400000
00001000   00000000   00000000   00000000   00000000
00000000

For example, I installed a parallel I/O card manufactured by
my employer (part number PCI-AC5) into my computer. Looking at this
last entry (starting with the 0168), the important fields are the
ones that say 148aac05, f6400008 (base address register zero or
BAR0) and f6aff008 (BAR1). A vendor and device ID identify each PCI
device. The 0x148aac05 indicates this device has a vendor ID of
0x148a (Opto 22) and a device ID of 0xac05. Vendor IDs are managed
by the PCISIG organization; Opto 22 chose the specific device ID.
Continuing with the example, the PCI-AC5 I/O card has two
configured base address registers (addresses 0xf6400000 and
0xf6aff000). The lowest nibble (least significant four bits) is
ignored (set to zero). The least significant bit indicates whether
the base address is I/O mapped or memory mapped in the case of x86
architectures. PCI devices may have up to six base addresses and an
interrupt (the b in the list). User-mode drivers can't take
advantage of the interrupt. A simple fscanf() program can read
these values and open the appropriate areas for access.In the event that you have multiple identical cards, you may
find it difficult to know who's who. Do not rely on the order
/proc/bus/pci/devices gives compared to the silkscreen slot numbers
printed on the motherboard to identify which card is which. To
identify the card, I've written applications to toggle some
indicators on the cards. This application asks which device index
to find and test.PitfallsWhile user-mode drivers are simple, there are a few
shortcomings you should watch out for:

• Multiple access to the hardware must be made thread
  safe. That is, two applications or threads cannot randomly share
  the device unless the hardware itself is not prone to uncoordinated
  (non-atomic) accesses.
• Writing to a wrong I/O address may have disastrous
  effects on the computer or hardware components. I recommend
  validating the port address arithmetic before attempting a port
  read or port write. Use some printfs of the I/O addresses before
  finding out something is wrong.
• Improper memory accesses as a result of improper
  pointer arithmetic may freeze the computer. Try some pointer
  printouts before finding out the hard way. Once the pointer is
  cast, the most common problem is errors created due to improperly
  sized pointer arithmetic. Be very careful with pointer
  arithmetic.
• While there are mechanisms to determine the size of
  a PCI base address block, don't rely on them. Determine the actual
  register locations of the device by locating real hardware
  documentation. Writing to an undefined location in the allocated
  block may result in a hard-frozen computer.

ConclusionIf you're thinking about porting that old DOS application,
testing out a new hardware device or just want to create a
quick-and-dirty hardware application, consider using a user-mode
driver. It's ideal for hardware devices that require a simple
interface and don't have timing requirements, and it may just help
you meet that impossible deadline.

Bryce Nakatani
(linux@opto22.com) is
an engineer at Opto 22, a manufacturer of automation components in
Temecula, California. He specializes in real-time controls,
software design, analog and digital design, network architecture
and instrumentation.

email: bnakatani@opto22.com