Documentation for PortIO32


Overview

PortIO32 is a driver and library which allows you to do low-level port IO from any programming language which can use a DLL in Windows or can link with a C library in Linux. This includes C/C++, Visual Basic, and others. Being able to use low-level port I/O allows you to manually program Winford Engineering's I/O cards. Although it is more difficult to use than Winford Engineering's Portal API, it can sometimes be advantageous to directly manipulate the hardware. This documentation does not cover the details of individual cards and how to program them. It only covers how to use the PortIO32 library. To find out more about directly programming your I/O card, see your user's manual (Manuals are also available on Winford Engineering's website. Visit http://www.winfordeng.com).

Getting Started

The basic steps to getting started are:
  1. Install the driver and library on your system. This only needs to be done once.
  2. Learn how to use PortIO32 in the applications you write. You may find the sample applications useful as a guide in writing your own applications.
  3. Write your applications. See the function reference for a list of the functions provided by PortIO32.
  4. Compile and run your applications!

Systems Supported

PortIO32 is designed to work with the following operating systems:

Function Reference:

int OutByte (unsigned short Port, int Data);
OutByte writes a value to a single I/O port. Pass OutByte the Port you want to write to and the Data value you want to write. Since I/O ports are 8-bit, this function can only write 8 bits of information to the port. If Data is too large to be expressed with 8 bits, the lower eight bits are written to the port. This function returns a 0 for success, or a -1 if an error occurred.

int OutWord (unsigned short Port, int Data);
OutWord is like OutByte except that 16 bits of data are written to two consecutive ports instead of 8 bits to a single port. The lower 8 bits are written to Data and the upper eight bits are written to Data + 1.

int InByte (unsigned short Port, int * Data);
InByte reads a value from a single I/O port. You must pass InByte the Port you want to read from and a pointer to a variable that you have declared. When the function is finished, your variable will contain the value that was read from the port. The value is returned in this way so that the return value of the function can indicate whether or not the operation succeeded. The function returns a value of 0 when it succeeds, and -1 when it fails.

int InWord (unsigned short Port, int * Data);
InWord is similar to InByte except that 16 bits of data are read from two consecutive ports instead of 8 bits from a single port. The lower 8 bits are read from Data and the upper eight bits are read from Data + 1.

int InByteR (unsigned short Port);
InByteR is like InByte in that it reads a value from a single port. This function is provided for those who have difficulty dealing with pointers to variables (the method that is used for InByte). Instead of giving you the value through a pointer, this function returns the value that was read. The only disadvantage is that you do not get an indication if the function failed or succeeded with this method. The function will return 0 if it was unable to read from the port, but since 0 is a valid value that could have been successfully read from the port, you never know if the function failed.

int InWordR (unsigned short Port);
InWordR is like InWord in that it reads 16 bits of data from two consecutive ports. The difference is that it gives you the value it reads through its return value instead of a pointer (See InByteR above for details).

Programming Languages:

Declarations

There are a few special steps that must be taken to use PortIO32 from a programming language. First of all, you must include a file in your project which gives you the declarations for the functions. In C/C++, this is the portio32.h file. In Visual Basic 5 and 6 it is PortIO32.bas, and in Visual Basic .NET it is PortIO32.vb.

Linking with Library Files

On Linux, you must link your program with the portio32.a library file. It is probably easiest to copy portio32.a into the directory of your source code. Here is an example of compiling a program:
gcc myfile.c portio32.a
The portio32.a file is a static library. This means that after you have compiled your program, your program is not dependent on the library file.

On Windows, compiling procedures vary depending on what compiler you are using. You must instruct your compiler to link with the PortIO32.lib file that is provided with the Windows version. In Microsoft Visual Studio C++, this is done by adding PortIO32.lib to the list of libraries in the Link section of the Project Settings / Project Properties. For example, in Visual Studio .NET, open the Project Properties and navigate to Configuration Properties -> Linker -> Input, and enter "PortIO32.lib" in the "Additional Dependencies" box.

If you are using a Borland C/C++ compiler, you will need to link your project with the bPortIO32.lib file instead. As a general tip for Borland users, Microsoft format (COFF) .lib files can be converted to Borland's format (OMF) using Borland's COFF2OMF utility, for example:

COFF2OMF -lib:st PortIO32.lib bPortIO32.lib

If ever necessary, a Borland format .lib file can be created directly from a DLL, for example:

implib bPortIO32.lib PortIO32.dll

In Visual Basic, no special compiling/linking steps are necessary. You must simply include the appropriate module (as described above) in your project.

Installation:

The installation for PortIO32 is very simple, but it is different depending on the operating system you use.

Windows

The driver/library installation procedure is very similar on all versions of Windows except Windows NT (see below). The driver is installed using the "Add Hardware" option of the Control Panel. Since there is no hardware that will be detected automatically by Windows, the PortIO32 driver will need to be installed by manually selecting a driver, using the "Have Disk" button to point Windows to the "win\driver" directory. More detailed instructions are available below:

Windows XP

  1. Open the Control Panel.
  2. Open the "Add Hardware" wizard. If you are using Windows XP's default "Category View" for the Control Panel, this is done by clicking on "Printers and Other Hardware" and under "See Also" on the left, click "Add Hardware".
  3. The wizard typically displays a screen explaining what it is used for. Click Next to continue.
  4. The wizard may automatically scan for new hardware. The scanning will not detect anything related to PortIO32.
  5. You may be asked "Have you already connected this hardware to your computer?" Regardless of whether you have installed any cards yet, click Yes.
  6. You will be shown a list of the hardware already installed in your computer. Scroll all the way down and select "Add a new hardware device"
  7. You will be asked whether Windows should search for the new hardware. Select "Install the hardware that I manually select from a list"
  8. A list of hardware categories will be shown. Select "Show All Devices" (On some versions of Windows this may be called "Other")
  9. Click the "Have Disk" button and point Windows to the "win\driver" directory of the PortIO32 distribution.
  10. A list of drivers found in the directory you specified will be shown. Select the "PortIO32 Port I/O Driver" item and click Next.
  11. Click Next again to "start installing your new hardware."
  12. The files will be copied and installed. Click Finish to complete. You do not need to restart your computer.

Windows 2000

  1. Open the Control Panel
  2. Open the "Add/Remove Hardware" wizard
  3. The wizard typically displays a screen explaining what it is used for. Click Next to continue.
  4. You will be asked whether to Add or Uninstall a device. Select "Add/Troubleshoot a device" and click Next.
  5. The wizard may automatically scan for new hardware. The scanning will not detect anything related to PortIO32.
  6. You will be shown a list of the hardware already installed in your computer. Select "Add a new device"
  7. You will be asked whether Windows should search for the new hardware. Select "No, I want to select the hardware from a list"
  8. A list of hardware categories will be shown. Select "Other devices"
  9. Click the "Have Disk" button and point Windows to the "win\driver" directory of the PortIO32 distribution.
  10. A list of drivers found in the directory you specified will be shown. Select the "PortIO32 Port I/O Driver" item and click Next.
  11. You will be informed that "Windows will use default settings to install the software for this hardware device." Simply click Next to begin installation.
  12. The files will be copied and installed. Click Finish to complete. You do not need to restart your computer.

Windows NT

  1. Run the NTinstall.exe program, located in the "win\driver" directory
  2. A message box will be shown explaining that the driver will be installed. Click Yes to continue.
  3. A message box will be shown confirming that the driver was installed. Click OK to complete. You do not need to restart your computer.

Windows Me

  1. Open the Control Panel.
  2. Open the "Add New Hardware" wizard. (You may have to click "view all Control Panel options" for this to be displayed.)
  3. The wizard typically displays a screen explaining what it is used for. Click Next to continue.
  4. You will be told that the wizard will scan for new Plug and Play devices. Click Next to continue. The scan will not find anything related to PortIO32. If the wizard displays a list of devices that were found, select "No, the device isn't in the list".
  5. You will be asked if Windows should search for non Plug and Play hardware. Select "No, I want to select the hardware from a list".
  6. A list of hardware categories will be shown. Select "Other devices"
  7. Click the "Have Disk" button and point Windows to the "win\driver" directory of the PortIO32 distribution.
  8. A list of drivers found in the directory you specified will be shown. Select the "PortIO32 Port I/O Driver" item and click Next.
  9. One last page will be shown stating "Windows can continue installing your hardware now." Simply click Finish to perform the installation. You do not need to restart your computer.

Windows 98

  1. Open the Control Panel.
  2. Open the "Add New Hardware" wizard.
  3. The wizard typically displays a screen explaining what it is used for. Click Next to continue.
  4. You will be told that the wizard will scan for new Plug and Play devices. Click Next to continue. The scan will not find anything related to PortIO32. If the wizard displays a list of devices that were found, select "No, the device isn't in the list".
  5. You will be asked if Windows should search for non Plug and Play hardware. Select "No, I want to select the hardware from a list".
  6. A list of hardware categories will be shown. Select "Other devices"
  7. Click the "Have Disk" button and point Windows to the "win\driver" directory of the PortIO32 distribution.
  8. A list of drivers found in the directory you specified will be shown. Select the "PortIO32 Port I/O Driver" item and click Next.
  9. One last page will be shown stating "Windows can continue installing your hardware now." Simply click Finish to perform the installation. You do not need to restart your computer.

Windows 95

  1. Open the Control Panel
  2. Open the "Add New Hardware" wizard
  3. The wizard typically displays a screen explaining what it is used for. Click Next to continue.
  4. You will be asked if Windows should search for your new hardware. Select "No".
  5. A list of hardware categories will be shown. Select "Other devices"
  6. Click the "Have Disk" button and point Windows to the "win\driver" directory of the PortIO32 distribution.
  7. A list of drivers found in the directory you specified will be shown. Select the "PortIO32 Port I/O Driver" item and click Next.
  8. One last page will be shown stating "Windows can continue installing your hardware now." Simply click Finish to perform the installation. You do not need to restart your computer.

Removal

On all Windows operating systems except Windows NT, the driver is displayed in the system Device Manager / Device Tree (along with your Serial Ports, Sound Cards, etc.). The driver will be shown under the category of "Winford Engineering I/O Devices". The driver can be uninstalled right from the device tree, typically by selecting the driver and hitting the Delete key or by right-clicking and selecting Uninstall. On Windows NT, use the NTuninstall.exe program in the "win\driver" directory to uninstall the driver service.

Linux

The linux version of PortIO32 uses the device file /dev/port to perform port I/O. Therefore, no driver installation is necessary. The only thing you must do is ensure that your applications are executed with root-level privileges. This is due to the fact that port I/O is a privileged operation and is not available to non-root users. Other than that, just be sure to link your program with portio32.a as described in the instructions above.

Download:

Please see Winford Engineering's
Download Page for the latest version of PortIO32.

Sample Code:

The following samples are included with the PortIO32 download and demonstrate the use of the PortIO32 driver and library.

Copyright 2004 Winford Engineering.