PORTIO Version 2.0 -- Written by William Lavender

"Portio" is a Linux device driver for performing x86 port I/O to a restricted
range of port addresses from user mode programs.  This driver has the
following advantages:

  1.  It only allows access to a restricted and configurable range of I/O ports.

  2.  It does not require the user mode program to be setuid root or to
      be run as root.

  3.  It does not require the program to be setgid kmem.

This driver is written as a kernel module so it is installed using the
"insmod" command.  The range of ports allowed is set at the time the module
is loaded.  Security of the computer is enforced by the fact that only root
can run "insmod" and the fact that one can use standard Unix file permissions
to restrict access to the device file "/dev/portio".

The current version of the driver is designed for Linux 2.4.x or 2.2.x and
is available at http://www.imca.aps.anl.gov/mx/src/portio-2.0.tar.gz.
If you need support for Linux 2.0.x, please use version 0.3 of the driver
which can be found at http://www.imca.aps.anl.gov/mx/src/portio-0.3.tar.gz.

Installation:

  1.  Set the major number that the driver will use by changing the
      #define for PORTIO_MAJOR in the file "portio.h".  As distributed,
      this is set to 60, but it can be changed if it conflicts with another
      driver needed on your machine.  The value 60 was chosen since the file
      'Documentation/devices.txt' in the Linux kernel source distribution
      lists the range 60-63 as being for local/experimental use.

  2.  Make a character special file called "/dev/portio" with a command like:

         mknod /dev/portio c 60 0

      Set the permissions on the special file to match the group of users
      that you want to have access to the I/O port.

  3.  Compile the source code in this directory with the command "make".

  4.  The command "make install" will then copy the compiled user binaries
      to the "/usr/local" directory tree or to wherever you have set the
      makefile variable INSTALL_DIR to.

  5.  The module itself must be copied to the miscellaneous directory for
      kernel modules for your current kernel.  This is normally found as
      "/lib/modules/2.4.x/misc" where you replace the 'x' with the revision
      number of your kernel.  Also, you must edit the file
      "/lib/modules/2.4.x/modules.dep" to include a reference to your
      new module.

  6.  The module may be installed using "insmod" with a command line like
      the following:

         insmod ./portio.o ports='0x344-0x347;0x300-0x301'

      This command line results in the following configuration:

         device 0: base_addr = 0x344, length = 4  (0x344-0x347)
         device 1: base_addr = 0x300, length = 2  (0x300-0x301)

      There is also a command line argument called "debug" which if set to
      a non-zero integer will cause the "portio" driver to write messages
      describing the I/O operations being performed to the system log file.
      Be careful about leaving the debug variable set to a non-zero value
      for too long since your system log files will grow rapidly while it
      is turned on.

The compilation process produces a set of user binaries: inb, inw, outb, outw,
portio_getmap, and portio_debug.  These programs serve as useful utilities
for learning how to talk to your I/O device.  The source for them also
serves as examples of how to invoke the "portio" driver from your own
source code.