Introduction

This manual provides a single reference guide to all functionality provided by the AIOWDM driver package. This driver supports several families of APIs for using PCI-based plug and play devices, including direct register access, watchdog timer control, and change-of-state IRQ handling.

This document describes the API's functions in sections to better distinguish which ones apply to YOUR device.

All PCI- and PCIe-compatible devices, other than serial boards, use this AIOWDM driver. This includes PCI, PCI Express, mPCIe, M.2, PCI-104, PC/104+, and many others.

The top of each section will include a header, like the following.

Please check the header to make sure you need to bother reading any given section, based on which card you"re working with." Black, bold text means "the following section is applicable to these categories of boards or functionality."" This driver has many functions, and it might seem a little overwhelming." Make sure you don"t get bogged down trying to learn entire families of functions" that have nothing to do with your product!

General Information

All functions are exported in three forms: underscored with the cdecl calling convention (the easiest for C++), undecorated with the stdcall calling convention (easiest for Visual BASIC), and undecorated with the cdecl calling convention (easiest for most other languages). Import declarations are given for Object Pascal / Delphi, Visual C++, and Visual BASIC. Visual BASIC doesn't have true pointers, and thus pointer-using functions are declared in Visual BASIC to always have a non-null pointer.

For function signatures or prototypes in any specific language, please refer to the language-specific source "header" files (AIOWDM.h, AIOWDM.cs, AIOWDM.vb, etc.) installed to your C:\Users\Public\Documents\ACCES\{package name}\Win32\Driver.SRC\AIOWDM\Headers\ folder.

There are two ways to use the functions in this driver: A simple way, and a flexible way." If you know at design time that you will never have more than one PCI or PCI-Express based card (any card that uses AIOWDM as its driver) in your system, use the simple way." If you will ever need to support more than a single AIOWDM-using card in the system simultaneously, you need to implement the more flexible interface.

The difference lies in how you acquire the parameter "CardNum". CardNum is a handle into the list of AIOWDM-using cards detected in the system.

In a simple setup with only one AIOWDM-using card, CardNum will always be Zero, being the first and only card in the system.

If you have two or more AIOWDM-using cards you will need to determine which card is installed at which CardNum index, using the API"s flexible GetNumCards() and QueryCardInfo() functions." Please see the "Flexible Access" section of the manual for detailed information on using multiple cards in a system.

Once you have your CardNum squared away, whether it be simply Zero (0) or the specific CardNums determined via QueryCardInfo(), the way you use the rest of the AIOWDM functions is the same.

Accessing Registers

RelInPortB RelInPort RelInPortL RelOutPortB RelOutPort RelOutPortL

All of these functions take a CardNum as the first parameter, and a register offset as the second parameter."

The "In" family reads from the specified device"s specified register and returns the value (a Byte, a Word, or a 32-bit Unsigned value) requested." These functions perform an operation equivalent to the "IN AX, DX" assembler instruction, or the READ_PORT_UCHAR Windows" kernel macro.

The "Out" family takes a third parameter (a Byte, a Word, or a 32-bit Unsigned value) and writes it to the specified device"s specified register." These functions perform an operation equivalent to the "OUT DX, AX" assembler instruction, or the WRITE_PORT_UCHAR Window"s kernel macro.

So, to read a Word from the first card"s register at offset 2:

value = RelInPort(0, 2);

To read a Byte from the second card"s register at offset 12:

value = RelInPortB(1, 12);

To write a 32-bit value to the first card"s register at offset zero:

RelOutPortL(0, 0, value);

Example Function Prototype:

UInt16 RelInPortB( Uint32 CardNum, UInt32 Register );

A note about error handling:

All of these functions can return an error value of "0xAA55", which means the underlying driver

(AIOWDM.SYS) is not installed correctly." Because 0xAA55 is a valid return value from the Word and 32bit functions, it is useful to issue a single Byte sized read from an innocuous address at the init-time of your program to check for this error: no byte read function can return a 16-bit value unless it is this error, and if any function returns this error, all functions will, every time, until the driver is installed correctly." This also means, if you perform this byte-read init-time error check, no further error handling is needed in your program for these functions.

Migrating Legacy Code (ACCES95.dll, ACCES32.dll, VBACCES.dll, etc)

Operating system migration: Moving legacy applications to Windows 7 The following register access functions are deprecated:

InPortB() InPort() InPortL() OutPortB() OutPort() OutPortL()

These functions do not use CardNum as the first parameter, nor the register offset as the second. Instead, they are NON PLUG AND PLAY, and use an absolute address into the I/O memory space as their first parameter (which then eliminates the second)."

For example, instead of

value = RelInPortL( CardNum, RegisterOffset );

these functions would use

value = InPortL( CardBaseAddress + RegisterOffset );

Because of this "CardBaseAddress" business, if the card"s plug-and-play assigned base address changes, your code needs to know how to handle this.

To support this we implemented QueryCardInfo() in a way that allows your program to acquire the actual absolute address of the card, which older code used to do every time your program ran.

Before even the QueryCardInfo technique customers were using the non-plug-and-play ACCES32 driver which doesn"t support QueryCardInfo() at all. In order to get the absolute base address of a card in programs written that Int32 ago the software would query a set of Windows Registry keys containing an array of structures called "PCI_COMMON_CONFIG" which then had to be parsed to find the base address." Additionally, this registry information was only updated by running a utility called PCIFind and its underlying kernel driver NTioPCI.SYS, none of which works in modern operating systems!

In summary, AIOWDM eliminates the need to know the address of your card." It eliminates the

NTioPCI.SYS driver running at every start-up of your system." It eliminates the PCIFind.exe utility copying the information from NTioPCI.SYS into the software-readable Windows registry locations every time the computer boots." It eliminates the need for applications to query this array of structures from the registry and wade through the data to determine a base address of the card."

For systems using only a single PCI card through AIOWDM, all of this simplification is achieved just by changing from "address+offset" to " 0, offset" in calls to the API.

If you have a single card system, you can migrate from ACCES32 or the QueryCardInfo() techniques to the modern plug-and-play API by making the following changes to your program:

1)               Locate your init code." This code either calls QueryCardInfo() or accesses the "HKLM/Software/PCIFind/Parameters" registry key.

2)               Delete all of this init code." Really.

3)               Search and replace all instances of "InPort" and "OutPort" in your program with "RelInPort" and

"RelOutPort" respecively." Note, this changes "InPortB" and "OutPortL" to "RelInPortB" and "RelOutPortL", etcetera, at the same time.

4)               Search and replace all instances of your base address variable plus an offset with zero comma the offset." For example, if the orignal code had the following line:

u32bData = InPortL( BASE + 3 ); it will now be, after the search and replace mentioned in step 3:

u32bData = RelInPortL( BASE + 3 );

Now perform a replace of "( BASE + " with "( 0, "." This will transform the line into: u32bData = RelInPortL( 0, 3 ); which is perfect and correct for the new, plug-and-play, functions.

If you are forced to use the "flexible" method of determining your CardNums because you have more than one AIOWDM-using device in your system, use the variable you"ve chosen to hold your detected CardNum instead of the "0": replace "( BASE + " with "( CardNumVariable, ". This would yield:

u32bData = RelInPortL( CardNumVariable, 3 );

These few steps will completely convert from the older, absolute address based API to the new plug-and-play API." Just make sure you"re careful with your replace operations not to impact calls to non AIOWDM functions!

Operating Analog Outputs (DACs)

This section describes a relatively new set of API Functions in AIOWDM.dll, the DAC_*() functions. These are designed to operate the PCI- and PCIe- DAC output cards (PCIe-DA16-16 down through PCI-DA12-2, inclusive).

These cards are each very similar to the others: they power on or reset into a "maximum output voltage restricted" state so they can't output more than millivolts until explicitly configured, and they all support either Simultaneous or Asynchronous update modes for the DACs. These cards also support storing calibration values, per range and per DAC, in onboard EEPROM.

With all these cards it is necessary to clear the "Voltage Restrict" feature before you'll get any outputs. Generally, write known values to all DACs, take the card out of Simultaneous mode and issue an update (LDAC), then clear the Voltage Restrict feature.

DAC_GetNumDacs(long CardNum, out UInt16 numDacs)

This function populates numDacs with the number of DACs on the specified card (so you can make your application adapt appropriately if desired)

DAC_GetMaxCounts(long CardNum, out UInt32 maxCounts)

This function populates maxCounts with the highest possible count value for the specified card (either 4095, for 12-bit DACs, or 65535 for 16-bit DACs) (so you can make your application adapt appropriately if desired).

DAC_ConfigureVoltageRestrictMode(long CardNum, long bRestricted)

bRestricted is a "boolean" value, zero or non-zero. Call DAC_ConfigureVoltageRestrictMode with bRestricted cleared to 0 (false) to remove the Voltage Restrict Mode and enable DACs to output actual values.

DAC_ConfigureSimultaneousMode(long CardNum, long bSimultaneous, long bUpdate)

bSimultaneous and bUpdate are "boolean" values, zero or non-zero. Set bSimultaneous to 0 (false) to enter Asynchronous mode. Set bUpdate to 1 (true) to cause all DACs to update their outputs to their last commanded values (LDAC)

DAC_GetRange(long CardNum, ushort iDac, ref uint RangeCode)

DAC_GetRanges(long CardNum, ref ushort pNumRangeCodes, UInt32[] RangeCodes)

These functions populate RangeCode/RangeCodes[] with the configured DAC range for the specified (or all) DAC(s). When possible this is the range actually configured at the on-card Range Selection DIP-Switch. For cards that do not support reading the DIP-Switch selected ranges the data is taken from global variables inside the AIOWDM.dll (which must have been set by DAC_SetRange/DAC_SetRanges to be available.

DAC_SetRange(long CardNum, ushort iDac, UInt32 RangeCode)

DAC_SetRanges(long CardNum, ushort numRangeCodes, UInt32[] RangeCodes)

These functions, on cards that do not support reading the Range DIP-Switch configured range(s), inform the DLL what range you've configured for each DAC.

DAC_EnableCalibration(long CardNum, ushort bEnabled)

Pass 1 (true) for bEnabled to turn on DLL software calibration of the DACs using the data stored in the on-card EEPROM.

DAC_ReloadCalibrationData(long CardNum)

Primarily useful to the factory this updates the DLL's shadow copy of the EEPROM Calibation data — in case someone changed the Range DIP-Switch or EEPROM contents "live".

DAC_GetCalibrationData(long CardNum, ref ushort pBufLength, double[] pBuf)

Primary useful to the factory this function reads the EEPROM stored calibration data for all Ranges/DACs

DAC_WriteCalibrationData(long CardNum, ref ushort pBufLength, byte[] pBuf, ushort bToEEPROM)

Primarily useful to the factory and the Calibration utility this function writes the DLL's shadow copy of the per-Range, per-DAC calibration data, and optionally writes that data into the on-card EEPROM.

DAC_OutputCount(long CardNum, ushort iDac, uint Counts)

DAC_OutputCounts(long CardNum, ushort numCounts, uint[] Counts)

These low-level functions write raw count values to one or all DACs.

DAC_Output(long CardNum, ushort iDac, double Value)

DAC_Outputs(long CardNum, ushort NumValues, double[] Values)

These high-level functions take floating-point value(s) (either voltage or current) and output it to the specified DAC(s). The value passed is converted by the DLL to counts using the Range and MaxCount information, and, if in-DLL calibration is enabled, calibrates the counts before output.

DAC_ValueFromCounts(long CardNum, ushort iDac, uint Counts, ref double Value)

A Utility function. This function takes a count value and populates Value with the equivalent voltage or current floating-point value as appropriate for the configured DAC Range.

Handling IRQs

WaitForIRQ()

UInt32 WaitForIRQ(Int32 CardNum);

This function deadlocks the calling thread until an IRQ occurs or the request is aborted. It's intended for multi-threaded IRQ handling, where the calling application spawns a separate thread to service IRQs quickly.

It returns nonzero if it returned because an IRQ occurred, or zero if it returned because the wait was aborted or there was an error. If the wait was aborted, GetLastError() will return

ERROR_OPERATION_ABORTED, and if someone is already waiting for an IRQ on that card, it will return

ERROR_INVALID_FUNCTION. (Other errors will return other error codes.)

AbortRequest()

UInt32 AbortRequest(Int32 CardNum);

This function cancels an IRQ request begun by WaitForIRQ() or COSWaitForIRQ(), or the one begun internally by WDGHandleIRQ(). It returns zero if it fails or nonzero if it succeeds, though the return value is generally not useful since if it fails there was no pending IRQ request on that card to abort.

Warning: """"""""" Make sure you call AbortRequest() or CloseCard() before closing the requesting thread or application; if you don't, the thread will never complete, and the driver will retain the request even though the thread or application has been unloaded from memory. If an IRQ then occurs, or the request is aborted, the wait will resume execution in the nonexistent thread, which will cause a Blue Screen Of Death.

If this does happen, perhaps due to the application crashing, do not then call AbortRequest(). Instead, use Device Manager to disable all devices using AIOWDM, then re-enable them. This will clear the faulty request without causing a Blue Screen Of Death, and allow you to resume working.

CloseCard()

UInt32 CloseCard(Int32 CardNum);

This function aborts any pending IRQ requests and closes the handle for the card. While it's necessary to abort all pending requests before closing the application, it isn't necessary to close the handles, as this is done automatically when AIOWDM.dll is unloaded. (When the .DLL is unloaded during an application close, IRQ-requesting threads have been closed already, and thus it's already too late to abort the pending requests - doing so would simply crash the computer.)

It returns zero if it fails or nonzero if it succeeds, though the return value is generally not useful since if it fails there was no open handle to close.

Handling Change-of-State IRQs (8255 DIO cards, mostly)

COSWaitForIRQ()

UInt32 COSWaitForIRQ(Int32 CardNum, UInt32 PPIs, void *pData);

This function is similar to WaitForIRQ(), but it also reads data from the card's PPIs immediately after the IRQ. It's designed specifically for the PCI-DIO-24S, PCI-DIO-48S, IOD24S, and IOD48S, and can be dangerous with another card (as some cards take action based on incoming reads), so check the DeviceID of your card through QueryCardInfo() first. Parameters are as follows:

""" * PPIs - This is the number of PPIs on the card. The PCI-DIO-24S has 1 PPI, the PCI-DIO-48S has 2 PPIs. (You can also specify 1 PPI with the PCI-DIO-48S if you don't need the data from the second one.)"""" * pData - This is a pointer to a buffer for the data. It must be at least 3 bytes per PPI.

For Visual BASIC, pData should be the first byte in an array of at least 3 bytes per PPI. For example, if Data was declared with "Dim Data(0 To 5) As Byte", you might make the call "COSWaitForIRQ(CardNum, 2, Data(0))".

AbortRequest() CloseCard()

Both of these functions, described in the "Generic IRQ Handling" section, also apply to COS IRQ Handling.

Watchdog Timer and Computer Status Monitor Functions

WDGInit()

UInt32 WDGInit(Int32 CardNum);

This function prepares a watchdog card driver for further WDG...() function calls, like WDGPet() and WDGHandleIRQ(). It's designed specifically for the PCI-WDG-CSM, and can be dangerous with another card, so check the DeviceID of your card through QueryCardInfo() first. If you call one of these functions on a card whose driver hasn't been prepared, it will fail. It returns nonzero if it succeeds, or zero if it fails.

WDGHandleIRQ()

UInt32 WDGHandleIRQ(Int32 CardNum, UInt32 Action);

This function sets up an IRQ handler to handle the next watchdog IRQ from the card specified. (This card's driver must already be prepared for watchdog operation by the WDGInit() function.) It returns nonzero if it succeeds, or zero if it fails. Action determines how the IRQ will be handled, as follows:

0  = Ignore.

""""""""""" This will allow the watchdog circuit to trip when the timer times out, performing a "hard" reset (if connected to the computer's reset line or power supply). A "hard" reset doesn't give Windows the opportunity to save important data, but is as certain a reset as possible. Note that this is what will happen if WDGHandleIRQ() is never called.

1  = Disable.

""""""""""" The watchdog timer will be disabled when the card generates an IRQ. This is not generally useful by itself except in testing.

2  = "Soft" Shutdown And Restart.

""""""""""" When the card generates an IRQ the driver will set the watchdog timer to a 90sec timeout, then begin a system shutdown. This "soft" shutdown allows Windows and other programs to save important data, but possibly allows them to cancel it. When the watchdog timer times out, however, the reset circuit will trip, performing a "hard" restart. If the "soft" shutdown completed successfully, the computer will be reset at that time.

3  = Disable And "Soft" Restart.

""""""""""" When the card generates an IRQ the driver will disable the watchdog timer, then begin a system restart. This is similar to 2, but doesn't allow the watchdog timer to actually time out except in case of failures so dire the IRQ doesn't get handled.

4  = "Mostly Soft" Shutdown And Restart.

""""""""""" When the card generates an IRQ the driver will set the watchdog timer to a 90sec timeout, then begin a system shutdown. This "mostly soft" shutdown allows Windows and other

6

programs to save important data within a limited timeframe, and doesn't allow the shutdown to be cancelled. When the watchdog timer actually times out, the reset circuit will trip, performing a "hard" restart. If the "mostly soft" shutdown completed successfully, the computer will be reset at that time.

5  = Disable And "Mostly Soft" Restart.

""""""""""" When the card generates an IRQ the driver will disable the watchdog timer, then begin a system restart. This is similar to 4, but doesn't allow the watchdog timer to actually time out except in case of failures so dire the IRQ doesn't get handled.

Actions greater than 5 are not supported, and will cause this function to fail.

WDGSetTimeout() double WDGSetTimeout(Int32 CardNum, double Milliseconds, double MHzClockRate);

This function stops the watchdog's timer, sets the timer's timeout duration, and prepares it for a WDGStart(). (This card's driver must already be prepared for watchdog operation by the WDGInit() function.) If it fails, it returns zero. If it succeeds, it returns the actual timeout achieved, which will be as close to Milliseconds as allowed by the counter's resolution. Parameters are as follows:

*  Milliseconds is the desired timeout duration in milliseconds.

*  MHzClockRate is the clock rate of the card, in MHz; for the PCI-WDG-CSM, this is 2.08333, and forthe WDG-CSM (ISA card), this is 0.894886. These constants are provided in the AIOWDM headers as PCI_WDG_CSM_RATE and ISA_WDG_CSM_RATE.

WDGSetResetDuration() double WDGSetResetDuration(Int32 CardNum, double Milliseconds, double MHzClockRate);

This function sets the duration of the watchdog circuit's reset for the PCI-WDG-CSM, or enables or disables the buzzer for the WDG-CSM (ISA card). (This card's driver must already be prepared for watchdog operation by the WDGInit() function.) Setting Milliseconds to 0.0 will disable the WDG-CSM's buzzer, or prevent the PCI-WDG-CSM from triggering the reset circuit even if it times out. Setting Milliseconds to a value greater than 0.0 but less than or equal to 1.0 will enable the WDG-CSM's buzzer, or set an infinite reset duration for the PCI-WDG-CSM. Setting Milliseconds to a value greater than 1.0 will enable the WDG-CSM's buzzer, or set the PCI-WDG-CSM's reset duration as close to the value passed as possible. If it sets the reset duration to a finite value, it returns that value, otherwise (if it fails or merely controls the buzzer) it returns zero.

WDGPet()

UInt32 WDGPet(Int32 CardNum);

This function "pets" a watchdog card, resetting its timers to prevent it from timing out. (This card's driver must already be prepared for watchdog operation by the WDGInit() function.) It returns nonzero if it succeeds, or zero if it fails.

WDGReadTemp() double WDGReadTemp(Int32 CardNum);

This function returns the temperature sensor from a watchdog card, in degrees Farenheit. (This card's driver must already be prepared for watchdog operation by the WDGInit() function.) A watchdog card without a temperature sensor will report a temperature of 194.0 degrees F. An actual temperature will never be less than 7.0 degrees F (and even that should never be seen in practice, of course). If this function fails, it returns 0.0 degrees F.

WDGReadStatus()

UInt32 WDGReadStatus(Int32 CardNum);

This function reads a watchdog card's status byte at Base + 4. (This card's driver must already be prepared for watchdog operation by the WDGInit() function.) Note that this action incidentally enables watchdog IRQs, but that IRQs will be ignored unless WDGHandleIRQ() has been called for that card. It returns the value of the status byte (which will be FF hex or less) if it succeeds, or a value greater than FF hex if it fails. The format of this byte is described in the card's manual.

WDGStart()

UInt32 WDGStart(Int32 CardNum);

This function starts watchdog timing. (This card's driver must already be prepared for watchdog operation by the WDGInit() function.) Note that the watchdog timer should be configured (as by WDGSetTimeout()) to start properly. It returns nonzero if it succeeds, or zero if it fails.

WDGStop()

UInt32 WDGStop(Int32 CardNum);

This function stops watchdog timing. (This card's driver must already be prepared for watchdog operation by the WDGInit() function.) It returns nonzero if it succeeds, or zero if it fails.

AbortRequest() CloseCard()

Both of these functions, described in the "Generic IRQ Handling" section, also apply to Watchdog IRQ Handling.

EmergencyReboot()

UInt32 EmergencyReboot(void);

This function begins a "mostly soft" restart, which allows Windows and other programs to save important data within a limited timeframe, but doesn't allow the restart to be cancelled. It returns nonzero if it succeeds, or zero if it fails(which probably means the calling process isn't allowed to restart the system).

Plug-and-play — detecting and identifying hardware

When using more than one AIOWDM-using card in your system your program should always begin by calling the two functions described below, GetNumCards, and QueryCardInfo." These two functions allow your software to acquire a "CardNum", used as a kind of "handle" into the list of cards installed in your system that AIOWDM has detected." All further accesses will use this CardNum to ensure you"re controlling the correct device.

GetNumCards()

Int32 GetNumCards(void);

This function returns the number of cards in the system using AIOWDM. The cards are numbered from zero to one less than the number returned by GetNumCards(); these card numbers are specified for the CardNum parameters of most other AIOWDM.dll functions. If an invalid card number is specified to another function, the function will fail.

QueryCardInfo()

UInt32 QueryCardInfo(Int32 CardNum, UInt32 *pDeviceID, UInt32 *pBase, UInt32 *pNameSize, unsigned char *pName);

This function retrieves information about the card indicated by CardNum. It returns nonzero if it succeeds, or zero if it fails (which probably means CardNum was bad). The information retrieved is:

*  DeviceID. This is a DWord value that tells you what kind of card it is. (For PCI cards, this is equal totheir PCI DeviceID.)

*  Base Address. This is the card's location within I/O space. To control the card, take data from it, etc,use this base address.

*  "Friendly Name". This Windows ANSI string is the name of the card. It corresponds directly to theDeviceID, but makes sense to a human. If the friendly name could not be retrieved, QueryCardInfo() will give an empty string.

Parameters are as follows:

*  pDeviceID - This is a pointer to a place to put the DeviceID of the card (or a null pointer if you don'tneed this information).

*  pBase - This is a pointer to a place to put the base address of the card (or a null pointer if you don'tneed this information).

o NOTE: because the modern Rel*() functions were added to the AIOWDM API there is no good reason to use this parameter and we recommend you always pass "null".

*  pNameSize - This is a pointer to the size of the buffer for the card's friendly name (or a null pointer ifyou don't need this information). This value will be changed to the actual size needed for the buffer, including the terminating null character.

*  pName - This is a pointer to a buffer for the card's friendly name (or a null pointer if you don't need this

information). If the value pointed to by pNameSize is initially zero, or if it's greater after the call to QueryCardInfo() (indicating that a larger buffer is required), this buffer will not be altered.