CanIO I/O-port access
[Rulbus Interface]

---

Detailed Description

Documentation for CANIO

Copyright © 2002 CanSoft

The CanIO software is a 2-file combination utility: a DLL and SYS kernel mode driver [CANIO].

The DLL can be loaded like any other DLL and the routines are outlined below. The purpose of the application is to open up port access (for example the CMOS at port 0x70) anywhere in the 64k IO space through Windows NT/2000/XP and .Net applications. Windows 95, 98, ME do not block access to these ports but the other MS operating systems do. My utility will assign rights to your application to read and write from these ports in these applications.

How it works

You load the DLL and call the AddMultiPort routine as needed. The DLL will check your OS (or you can do this yourself in your own application if you want) and if you have NT/2000/XP/.Net installed it will then call the kernel mode driver which will in turn give to your calling application the rights to read/write from the requested ports. If it is Win95/98/ME then the DLL won't call the SYS, as it won't even be installed, and will just do nothing, as your app already has rights in this environment.

Installation

Your application should detect OS and then install the CanIO. SYS driver if needed through your own install process depending upon your development language.

For testing purposes, however, there are two ways you can install the kernel mode driver:

Method 1

With the instdrv.exe application, type at the command prompt: instdrv canio c:\pathtocaniosys\canio.sys The "pathtocaniosys" directory is whatever directory you have copied the CanIO.sys driver to. If you use this method, the CanIO.dll does not have to be in the same directory as the CanIO.sys file.

Method 2

Everytime you load the CanIO.DLL library, it will detect the OS type installed and then if it is WinNT/2000/XP/.Net it will try to get a handle to the CanIO service (CanIO.sys). If it cannot get a handle to the CanIO service (meaning it is not installed or is not running), it will attempt to locate the CanIO.sys file and attempt to install and start the service automatically for you.

This will work if and only if you are logged into the machine with administrative privileges. Also, the CanIO. sys file MUST be in the same directory as the CanIO.dll file because that is where it will look for it. So this method actually requires that you do nothing other than making sure you have admin privileges on the machine and that the .sys file is on the same directory as the .dll.

ROUTINES

1. BOOL AddMultiPort(ULONG, INT)
   This routine returns true or false and requires two parameters - the first is a 32bit integer which is the starting port address (In Delphi it would be "Longword"). The second is a standard integer type, which outlines how many bytes to open starting from the passed address.
   
   So, if you wanted to read a word from port 0x400 you would call:

   AddMultiPort(0x400, 2);
   

   
   To read just one byte from port 0x70 you would call:

   AddMultiPort(0x70, 1);
   

   
   NOTE Make SURE when declaring the routine in your application that you match the parameters correctly. In other words, don't declare AddMultiport as AddMultiPort(Word, int) or something like that. This WILL give you problems.
   
   
2. BOOL UnloadDrvr()
   This call is optional and it will attempt to unload the .sys driver IF AND ONLY IF the running instance of the DLL also installed it. This means that if you are running your machine with admin privileges, the CanIO.DLL will install and start the CanIO service for you when it loads and when you are done reading from the various ports you need to, you can unload the driver from memory by calling this routine. This way the driver only stays in memory for a brief period.

Defines
#define	IMPORT   __declspec(dllimport)
	use function from DLL
#define	CANIO_API   __stdcall
	CanIO dynamic-link library calling convention.
Functions
IMPORT BOOL CANIO_API	AddMultiPort (ULONG base, int length)
	provide access privilege to a range of I/O-port addresses.

---

Define Documentation

#define CANIO_API   __stdcall

It's not stated in the documentation, but CanIO uses the Pascal calling convention (like WinAPI). Initially I defined CANIO_API as empty and could use the Rulbus Device Library DLL succesfully (that is without access violation exceptions). After some code changes, rulbus.dll started to give access violation exceptions. Debugging with fprintf() statements finally pointed to AddMultiPort() and I started to suspect its prototype. Changing the empty CANIO_API to __stdcall solved the problem. Martin J. Moene, 4 June 2003.

---

Function Documentation

IMPORT BOOL CANIO_API AddMultiPort (  ULONG  base, int  length )

this function provides port access to the number of i/o-ports specified by length and starting at address base. Parameters: base  first address to open length  number of i/o-ports to open Returns: it's not documented, but the function appears to behave like other Windows API functions and return 0 for failure, !0 for success.

---