B.3.1. Structures, Types and General Definitions

B.3.1.1. WDC_DEVICE_HANDLE

B.3.1.2. WDC_DRV_OPEN_OPTIONS Definitions

Preprocessor definitions of flags that describe tasks to be performed when
opening a handle to the WDC library (see WDC_DriverOpen() [B.3.2]).

Name

Description

WDC_DRV_OPEN_CHECK_VER

Compare the version of the WinDriver source files used by the code with the
version of the loaded WinDriver kernel

WDC_DRV_OPEN_REG_LIC

Register a WinDriver license registration string

The following preprocessor definitions provide convenient WDC driver open
options, which can be passed to WDC_DriverOpen() [B.3.2]:

Name

Description

WDC_DRV_OPEN_BASIC

Instructs WDC_DriverOpen() [B.3.2] to perform only the basic WDC open
tasks, mainly open a handle to WinDriver's kernel module.

NOTE: The value of this option is zero (<=> no driver open flags),
therefore this option cannot be combined with any of the other WDC driver
open options.

WDC_DRV_OPEN_KP

Convenience option when calling WDC_DriverOpen() [B.3.2] from the
Kernel PlugIn. This option is equivalent to setting the
WDC_DRV_OPEN_BASIC flag, which is the recommended option to
set when opening a handle to the WDC library from the Kernel PlugIn.

WDC_DRV_OPEN_ALL

A convenience mask of all the basic WDC driver open flags —
WDC_DRV_OPEN_CHECK_VER and
WDC_DRV_OPEN_REG_REG_LIC. (The basic functionality of opening
a handle to WinDriver's kernel module is always performed by
WDC_DriverOpen() [B.3.2], so there is no need to also set the
WDC_DRV_OPEN_BASIC flag).

WDC_DRV_OPEN_DEFAULT

Use the default WDC open options:
• For user-mode applications: equivalent to setting
WDC_DRV_OPEN_ALL ;
• For a Kernel PlugIn: equivalent to setting
WDC_DRV_OPEN_KP

B.3.1.3. WDC_DIRECTION Enumeration

Enumeration of a device's address/register access directions.

Enum Value

Description

WDC_READ

Read from the address

WDC_WRITE

Write to the address

WDC_READ_WRITE

Read from the address or write to it.
This value is used, for example, in the WinDriver samples and generated
DriverWizard diagnostics code in order to describe a register's access
mode, indicating that the register can either be read from or written to.

B.3.1.4. WDC_ADDR_MODE Enumeration

Enumeration of memory or I/﻿O addresses/registers read/write modes.
The enumeration values are used to determine whether a memory or I/﻿O
address/register is read/written in multiples of 8, 16, 32 or 64 bits (i.e., 1,
2, 4 or 8 bytes).

Enum Value

Description

WDC_MODE_8

8 bits (1 byte) mode

WDC_MODE_16

16 bits (2 bytes) mode

WDC_MODE_32

32 bits (4 bytes) mode

WDC_MODE_64

64 bits (8 bytes) mode

B.3.1.5. WDC_ADDR_RW_OPTIONS Enumeration

Enumeration of flags that are used to determine how a memory or I/﻿O address
will be read/written.

Enum Value

Description

WDC_ADDR_RW_DEFAULT

Use the default read/write options: memory addresses are accessed
directly from the calling process; block transfers are performed from
subsequent addresses (automatic increment).

NOTE: The value of this flag is zero (<=> no read/write flags),
therefore it can not be combined in a bit-mask with any of the other
read/write options flags.

This option is used by the
WDC_ReadAddr8/16/32/64() [B.3.19] and
WDC_WriteAddr8/16/32/64() [B.3.20] functions.

WDC_ADDR_RW_NO_AUTOINC

Do no automatically increment the read/write address in block transfers,
i.e., hold the device address constant while reading/writing a block of
memory or I/﻿O addresses (relevant only for block (string) transfers).

Send debug messages from the WDC library to a debug file. By default, the
debug file will be stderr, unless a
different file is set in the sDbgFile parameter of the
WDC_SetDebugOptions() function [B.3.48].
This option is only supported from the user mode (as opposed to the Kernel
PlugIn).

The following flags determine the debug level — i.e., what type of WDC
debug messages to display, if at all:

Name

Description

WDC_DBG_LEVEL_ERR

Display only WDC error debug messages

WDC_DBG_LEVEL_TRACE

Display both error and trace WDC debug messages

WDC_DBG_NONE

Do not display WDC debug messages

The following preprocessor definitions provide convenient debug flags
combinations, which can be passed to WDC_SetDebugOptions() [B.3.48]:

A mask of any of the supported open flags [B.3.1.2],
which determines the initialization actions that will be performed by the
function.

sLicense

WinDriver license registration string.
This argument is ignored if the WDC_DRV_OPEN_REG_LIC flag is
not [B.3.1.2] set in the openOptions
argument.
If this parameter is a NULL pointer or an empty string, the function
will attempt to register the demo WinDriver evaluation license. Therefore,
when evaluating WinDriver pass NULL as this parameter. After registering
your WinDriver toolkit, modify the code to pass your WinDriver license
registration string.

B.3.4. WDC_PciScanDevices()

Purpose

Scans the PCI bus for all devices with the specified vendor and device ID
combination and returns information regarding the matching devices that were
found and their locations. The function performs the scan by iterating through
all possible PCI buses on the host platform, then through all possible PCI
slots, and then through all possible PCI functions.

Scan-By-Topology Note

On rare occasions, as a result of malfunctioning hardware, the scan information
may contain repeated instances of the same device. As a result, the function
might fail to return valid scan data. In such cases, if you cannot remove the
malfunctioning device, you can scan the PCI bus using
WDC_PciScanDevicesByTopology() [B.3.5] or
WDC_PciScanRegisteredDevices() [B.3.6].

If you set both the vendor and device IDs to zero, the function will return
information regarding all connected PCI devices.

B.3.5. WDC_PciScanDevicesByTopology()

Purpose

Scans the PCI bus for all devices with the specified vendor and device ID
combination and returns information regarding the matching devices that were
found and their locations. The function performs the scan by topology —
i.e., for each located bridge the function scans the connected devices and
functions reported by the bridge, and only then proceeds to scan the next
bridge.

In the case of multiple host controllers,
WDC_PciScanDevicesByTopology() will perform the scan only for
the first host controller.

By default, use WDC_PciScanDevices() [B.3.4] to scan the PCI bus,
unless a device malfunction intererferes — refer to the note in the
description of PciScanDevices().

If you set both the vendor and device IDs to zero, the function will return
information regarding all connected PCI devices.

B.3.6. WDC_PciScanRegisteredDevices()

Purpose

Scans the PCI bus for all devices with the specified vendor and device ID
combination that have been registered to work with WinDriver, and returns
information regarding the matching devices that were found and their locations.
The function performs the scan by iterating through all possible PCI buses on
the host platform, then through all possible PCI slots, and then through all
possible PCI functions.

By default, use WDC_PciScanDevices() [B.3.4] to scan the PCI bus,
unless a device malfunction intererferes — refer to the note in the
description of PciScanDevices().

The resources information is obtained from the operating system's
Plug﻿-﻿and﻿-﻿Play manager, unless the information is not available, in which case it
is read directly from the PCI configuration registers.
Note: On Windows, you must install an INF
file file, which registers your device with WinDriver,
before calling this function (see Section 15.1
regarding creation of INF files with WinDriver).

If the interrupt request (IRQ) number is obtained from the Plug﻿-﻿and﻿-﻿Play manager, it is
mapped, and therefore may differ from the physical IRQ number.

B.3.10. WDC_PciDeviceOpen()

Purpose

Allocates and initializes a WDC PCI device structure, registers the device with
WinDriver, and returns a handle to the device.

This function

Verifies that none of the registered device resources (set in
pDeviceInfo-﻿>Card.Item) are already locked for
exclusive use.

A resource can be locked for exclusive use by setting the
fNotSharable field of its WD_ITEMS structure [B.7.6]
to 1, before calling WDC_PciDeviceOpen().

Maps the physical memory ranges found on the device both to kernel-mode and
user-mode address space, and stores the mapped addresses in the allocated
device structure for future use.

Saves device resources information required for supporting the
communication with the device. For example, the function saves the
interrupt request (IRQ) number and the interrupt type, as well as retrieves and saves
an interrupt handle, and this information is later used when the user calls
functions to handle the device's interrupts.

If the caller selects to use a Kernel PlugIn driver to communicate with the
device, the function opens a handle to this driver and stores it for future
use.

If your card has a large memory range that cannot be fully mapped to the
kernel address space, you can set the
WD_ITEM_MEM_DO_NOT_MAP_KERNEL flag in the
I.Mem.dwOptions field of the relevant WD_ITEMS
memory resource structure [B.7.6]
(pDeviceInfo-﻿>Card.Item[i].I.Mem.dwOptions), received from WDC_PciGetDeviceInfo(),
before passing it to the device﻿-﻿open function.
This flag instructs the function to map the memory range only to the
user-mode virtual address space, and not to the kernel address space.

Note that if you select to set the
WD_ITEM_MEM_DO_NOT_MAP_KERNEL flag,
the device information structure that will be created by the function
will not hold a kernel-mapped address for this resource (the
pAddrDesc[i].pAddr base address kernel mapping field of
the relevant memory range in the
WDC_DEVICE structure [B.4.3]
will not be updated),
and you will therefore not be able to rely on this mapping in calls to
WinDriver APIs — namely interrupt handling APIs or any API called from a
Kernel PlugIn driver.

B.3.11. WDC_IsaDeviceOpen()

Purpose

Allocates and initializes a WDC ISA device structure, registers the device with
WinDriver, and returns a handle to the device.

This function

Verifies that none of the registered device resources (set in
pDeviceInfo-﻿>Card.Item) are already locked for
exclusive use.

A resource can be locked for exclusive use by setting the
fNotSharable field of its WD_ITEMS structure [B.7.6]
to 1, before calling WDC_IsaDeviceOpen().

Maps the device's physical memory ranges device both to kernel-mode and
user-mode address space, and stores the mapped addresses in the allocated
device structure for future use.

Saves device resources information required for supporting the
communication with the device. For example, the function saves the
interrupt request (IRQ) number and the interrupt type, as well as retrieves and saves
an interrupt handle, and this information is later used when the user calls
functions to handle the device's interrupts.

If the caller selects to use a Kernel PlugIn driver to communicate with the
device, the function opens a handle to this driver and stores it for future
use.

If your card has a large memory range that cannot be fully mapped to the
kernel address space, you can set the
WD_ITEM_MEM_DO_NOT_MAP_KERNEL flag in the
I.Mem.dwOptions field of the relevant WD_ITEMS
memory resource structure [B.7.6]
(pDeviceInfo-﻿>Card.Item[i].I.Mem.dwOptions)
before passing it to the device﻿-﻿open function.
This flag instructs the function to map the memory range only to the
user-mode virtual address space, and not to the kernel address space.

Note that if you select to set the
WD_ITEM_MEM_DO_NOT_MAP_KERNEL flag,
the device information structure that will be created by the function
will not hold a kernel-mapped address for this resource (the
pAddrDesc[i].pAddr base address kernel mapping field of
the relevant memory range in the
WDC_DEVICE structure [B.4.3]
will not be updated),
and you will therefore not be able to rely on this mapping in calls to
WinDriver APIs — namely interrupt handling APIs or any API called from a
Kernel PlugIn driver.

B.3.12. WDC_PciDeviceClose()

Purpose

Uninitializes a WDC PCI device structure and frees the memory allocated for it.

Prototype

DWORD DLLCALLCONV WDC_PciDeviceClose(WDC_DEVICE_HANDLE hDev);

Parameters

Name

Type

Input/Output

hDev

WDC_DEVICE_HANDLE

Input

Description

Name

Description

hDev

Handle to a WDC PCI device structure, returned by
WDC_PciDeviceOpen() [B.3.10]

Pointer to an array of cleanup transfer commands to be performed [B.7.10]

dwCmds

Number of cleanup commands in the Cmd array

bForceCleanup

If FALSE: The cleanup transfer commands (Cmd)
will be performed in either of the following cases:
• When the application exits abnormally.
• When the application exits normally without closing the card by
calling one of the WDC_xxxDeviceClose() functions (PCI [B.3.12] /
ISA [B.3.13]).

If TRUE: The cleanup transfer commands will be performed
both in the two cases described above, as well as in the following
case:
• When the relevant WD_xxxDeviceClose() function is
called for the card.

It's also possible to use the WDC_xxxDeviceOpen() functions (PCI [B.3.10] /
ISA [B.3.11]) to open a handle to a Kernel
PlugIn driver, as part of the device-open operation. However, this method
cannot be used to open a handle to a 64-﻿bit Kernel PlugIn driver from a
32-﻿bit user-mode application. Therefore, to ensure that your code works in
all the supported configurations, it is recommended that you use
WDC_KernelPlugInOpen() to open the Kernel PlugIn driver handle.
This is also the only supported method for opening a Kernel PlugIn handle from
a .NET application. (See detailed information in
Section 12.4.)

B.3.16. WDC_CallKerPlug()

Purpose

Sends a message from a user-mode application to a Kernel PlugIn driver. The
function passes a message ID from the application to the Kernel PlugIn's
KP_Call [B.8.4] function, which should be implemented to handle the
specified message ID, and returns the result from the Kernel PlugIn to the
user-mode application.

The transfers are performed using the low﻿-﻿level
WD_MultiTransfer() WinDriver function, which reads/writes the
specified addresses in the kernel (see the WinDriver PCI Low﻿-﻿Level API Reference for details).

Memory addresses are read/written in the kernel (like I/﻿O addresses)
and NOT directly in the user mode, therefore the port addresses passed
to this function, for both memory and I/﻿O addresses, must be the
kernel-mode mappings of the physical addresses, which are stored in the
device structure [B.4.3].

B.3.24. WDC_AddrSpaceIsActive()

Purpose

Checks if the specified memory or I/﻿O address space is active — i.e.,
if its size is not zero.

B.3.25. WDC_PciReadCfgBySlot()

Purpose

Reads data from a specified offset in a PCI device's configuration space or a
PCI Express device's extended configuration space.
The device is identified by its location on the PCI bus.

Access to the PCI Express extended configuration space is supported on
target platforms that support such access (e.g., Windows and Linux). For such platforms, all PCI references in the
following documentation include PCI Express as well.

B.3.26. WDC_PciWriteCfgBySlot()

Purpose

Write data to a specified offset in a PCI device's configuration space or a PCI
Express device's extended configuration space.
The device is identified by its location on the PCI bus.

Access to the PCI Express extended configuration space is supported on
target platforms that support such access (e.g., Windows and Linux). For such platforms, all PCI references in the
following documentation include PCI Express as well.

B.3.27. WDC_PciReadCfg()

Purpose

Reads data from a specified offset in a PCI device's configuration space or a
PCI Express device's extended configuration space.

Access to the PCI Express extended configuration space is supported on
target platforms that support such access (e.g., Windows and Linux). For such platforms, all PCI references in the
following documentation include PCI Express as well.

B.3.28. WDC_PciWriteCfg()

Purpose

Writes data to a specified offset in a PCI device's configuration space or a
PCI Express device's extended configuration space.

Access to the PCI Express extended configuration space is supported on
target platforms that support such access (e.g., Windows and Linux). For such platforms, all PCI references in the
following documentation include PCI Express as well.

Access to the PCI Express extended configuration space is supported on
target platforms that support such access (e.g., Windows and Linux). For such platforms, all PCI references in the
following documentation include PCI Express as well.

Access to the PCI Express extended configuration space is supported on
target platforms that support such access (e.g., Windows and Linux). For such platforms, all PCI references in the
following documentation include PCI Express as well.

Access to the PCI Express extended configuration space is supported on
target platforms that support such access (e.g., Windows and Linux). For such platforms, all PCI references in the
following documentation include PCI Express as well.

Access to the PCI Express extended configuration space is supported on
target platforms that support such access (e.g., Windows and Linux). For such platforms, all PCI references in the
following documentation include PCI Express as well.

Pointer to a pointer to be filled by the function with the user-mode mapped
address of the allocated DMA buffer

dwOptions

A bit mask of any of the following flags (defined in an enumeration in
windrvr.h):
• DMA_FROM_DEVICE: Synchronize the DMA buffer for
transfers from the device to memory.
• DMA_TO_DEVICE: Synchronize the DMA buffer for
transfers from memory to the device.
• DMA_TO_FROM_DEVICE: Synchronize the DMA buffer
for transfers in both directions — i.e., from the device to memory
and from memory to the device (<=> DMA_FROM_DEVICE |
DMA_TO_DEVICE).
• DMA_ALLOW_CACHE: Allow caching of the memory.
• DMA_KBUF_BELOW_16M: Allocate the physical DMA
buffer within the lower 16MB of the main memory.
• DMA_ALLOW_64BIT_ADDRESS: Allow allocation of
64-﻿bit DMA addresses. This flag is supported on Windows
and Linux.

dwDMABufSize

The size (in bytes) of the DMA buffer

ppDma

Pointer to a pointer to a DMA buffer information structure [B.7.9], which is allocated by the function.
The pointer to this structure (*ppDma) should be passed to
WDC_DMABufUnlock() [B.3.36] when the DMA buffer is no longer needed.

When calling this function you do not need to set theDMA_KERNEL_BUFFER_ALLOC flag, since the function sets this
flag automatically.

This function is currently only supported from the user mode.

On Windows x86 and x86_64 platforms, you should normally set the
DMA_ALLOW_CACHE flag in the DMA options bitmask parameter
(dwOptions).

If the device supports 64-﻿bit DMA addresses, it is recommended to set the
DMA_ALLOW_64BIT_ADDRESS flag in
dwOptions.
Otherwise, when the physical memory on the target platform is larger than
4GB, the operating system may only allow allocation of relatively small
32-bit DMA buffers (such as 1MB buffers, or even smaller).

B.3.34. WDC_DMASGBufLock()

Purpose

Locks a pre-allocated user-mode memory buffer for DMA and returns the
corresponding physical mappings of the locked DMA pages. On Windows the
function also returns a kernel-mode mapping of the buffer.

Pointer to a user-mode buffer to be mapped to the allocated physical DMA
buffer(s)

dwOptions

A bit mask of any of the following flags (defined in an enumeration in
windrvr.h):
• DMA_FROM_DEVICE: Synchronize the DMA buffer for
transfers from the device to memory.
• DMA_TO_DEVICE: Synchronize the DMA buffer for
transfers from memory to the device.
• DMA_TO_FROM_DEVICE: Synchronize the DMA buffer
for transfers in both directions — i.e., from the device to memory
and from memory to the device (<=> DMA_FROM_DEVICE |
DMA_TO_DEVICE).
• DMA_ALLOW_CACHE:
Allow caching of the memory.
• DMA_ALLOW_64BIT_ADDRESS: Allow allocation of
64-﻿bit DMA addresses. This flag is supported on Windows
and Linux.

dwDMABufSize

The size (in bytes) of the DMA buffer

ppDma

Pointer to a pointer to a DMA buffer information structure [B.7.9], which is allocated by the function.
The pointer to this structure (*ppDma) should be passed to
WDC_DMABufUnlock() [B.3.36] when the DMA buffer is no longer needed.

When calling the function to allocate large buffers (> 1MB) you do
not need to set the DMA_LARGE_BUFFER flag, which is
used for allocation of large Scatter/﻿Gather DMA buffers using the low﻿-﻿level
WinDriver WD_DMALock() function (see the WinDriver PCI Low﻿-﻿Level API Reference),
since WDC_DMASGBufLock() handles this for you.

This function is currently only supported from the user mode.

On Windows x86 and x86_64 platforms, you should normally set the
DMA_ALLOW_CACHE flag in the DMA options bitmask parameter
(dwOptions).

If the device supports 64-﻿bit DMA addresses, it is recommended to set the
DMA_ALLOW_64BIT_ADDRESS flag in
dwOptions.
Otherwise, when the physical memory on the target platform is larger than
4GB, the operating system may only allow allocation of relatively small
32-bit DMA buffers (such as 1MB buffers, or even smaller).

B.3.35. WDC_DMAReservedBufLock()

The physical address returned from this API (ppDma->Page[0].pPhysicalAddr) may
be different then the address supplied by the caller (qwAddr) when the system
uses IOMMU. When performing DMA transfer using this mapped buffer, make sure to
use the returned address.

Pointer to a pointer to be filled by the function with the user-mode mapped
address of the locked DMA buffer

dwOptions

A bit mask of any of the following flags (defined in an enumeration in
windrvr.h):
• DMA_FROM_DEVICE: Synchronize the DMA buffer for
transfers from the device to memory.
• DMA_TO_DEVICE: Synchronize the DMA buffer for
transfers from memory to the device.
• DMA_TO_FROM_DEVICE: Synchronize the DMA buffer
for transfers in both directions — i.e., from the device to memory
and from memory to the device (<=> DMA_FROM_DEVICE |
DMA_TO_DEVICE).
• DMA_ALLOW_64BIT_ADDRESS: Allow allocation of
64-﻿bit DMA addresses. This flag is supported on Windows
and Linux.

dwDMABufSize

The size (in bytes) of the DMA buffer

ppDma

Pointer to a pointer to a DMA buffer information structure [B.7.9], which is allocated by the function.
The pointer to this structure (*ppDma) should be passed to
WDC_DMABufUnlock() [B.3.36] when the DMA buffer is no longer needed.

B.3.36. WDC_DMABufUnlock()

Unlocks and frees the memory allocated for a DMA buffer by a previous call to
WDC_DMAContigBufLock() [B.3.33], WDC_DMASGBufLock() [B.3.34] or
WDC_DMAReservedBufLock() [B.3.35].

Prototype

DWORD DLLCALLCONV WDC_DMABufUnlock(WD_DMA *pDma);

Parameters

Name

Type

Input/Output

pDma

WD_DMA*

Input

Description

Name

Description

pDma

Pointer to a DMA information structure [B.7.9], received from a
previous call to WDC_DMAContigBufLock() [B.3.33] (for a contiguous DMA buffer)
or WDC_DMASGBufLock() [B.3.34] (for a Scatter/﻿Gather DMA buffer) —
*ppDma returned by these functions

B.3.38. WDC_DMAGetGlobalHandle Macro

Utility macro that returns a contiguous DMA global handle that can be used for
buffer sharing between multiple processes.

Prototype

WDC_DMAGetGlobalHandle(pDma)

Parameters

Name

Type

Input/Output

pDma

WD_DMA*

Input

Description

Name

Description

pDma

Pointer to a DMA information structure [B.7.9], received from a
previous call to WDC_DMAContigBufLock() [B.3.33]

Return Value

DMA buffer handle of pDma.

B.3.39. WDC_DMASyncCpu()

Purpose

Synchronizes the cache of all CPUs with the DMA buffer, by flushing the data
from the CPU caches.

This function should be called before performing a DMA transfer (see Remarks
below).

Prototype

DWORD DLLCALLCONV WDC_DMASyncCpu(WD_DMA *pDma);

Parameters

Name

Type

Input/Output

pDma

WD_DMA*

Input

Description

Name

Description

pDma

Pointer to a DMA information structure [B.7.9], received from a
previous call to WDC_DMAContigBufLock() [B.3.33] (for a contiguous DMA buffer)
or WDC_DMASGBufLock() [B.3.34] (for a Scatter/﻿Gather DMA buffer) —
*ppDma returned by these functions

An asynchronous DMA read or write operation accesses data in memory, not in
the processor (CPU) cache, which resides between the CPU and the host's
physical memory. Unless the CPU cache has been flushed, by calling
WDC_DMASyncCpu(), just before a read transfer, the data
transferred into system memory by the DMA operation could be overwritten
with stale data if the CPU cache is flushed later. Unless the CPU cache has
been flushed by calling WDC_DMASyncCpu() just before a write
transfer, the data in the CPU cache might be more up-to-date than the copy
in memory.

This function is currently only supported from the user mode.

B.3.40. WDC_DMASyncIo()

Purpose

Synchronizes the I/﻿O caches with the DMA buffer, by flushing the data from
the I/﻿O caches and updating the CPU caches.

This function should be called after performing a DMA transfer (see Remarks
below).

Prototype

DWORD DLLCALLCONV WDC_DMASyncIo(WD_DMA *pDma);

Parameters

Name

Type

Input/Output

pDma

WD_DMA*

Input

Description

Name

Description

pDma

Pointer to a DMA information structure, received from a previous call to
WDC_DMAContigBufLock() [B.3.33] (for a contiguous DMA buffer) or
WDC_DMASGBufLock() [B.3.34] (for a Scatter/﻿Gather DMA buffer) —
*ppDma returned by these functions

After a DMA transfer has been completed, the data can still be in the
I/﻿O cache, which resides between the host's physical memory and the
bus-master DMA device, but not yet in the host's main memory. If the CPU
accesses the memory, it might read the wrong data from the CPU cache. To
ensure a consistent view of the memory for the CPU, you should call
WDC_DMASyncIo() after a DMA transfer in order to flush the
data from the I/﻿O cache and update the CPU cache with the new data. The
function also flushes additional caches and buffers between the device
and memory, such as caches associated with bus extenders or bridges.

This function is currently only supported from the user mode.

B.3.41. WDC_IntEnable()

Purpose

Enables interrupt handling for the device.

On Linux and Windows 7 and higher, when attempting to enable interrupts for a PCI device that
supports Extended Message-Signaled Interrupts (MSI-﻿X) or Message-Signaled Interrupts (MSI) (and was installed with a
relevant INF file — on Windows [9.2.7.1]), the
function first tries to enable MSI-﻿X or MSI; if this fails, or if the target
OS does not support MSI/MSI-﻿X, the function attempts to enable legacy
level-sensitive interrupts (if supported by the device).
On Linux, you can use the function's
dwOptions parameter to specify the types
of PCI interrupts that may be enabled for the device (see the
explanation in the
parameter description).
For other types of hardware (PCI with no MSI/MSI-﻿X support / ISA),
the function attempts to enable the legacy interrupt type supported by the
device (Level Sensitive / Edge Triggered) — see further information in
Section 9.2.

When enabling interrupts using a Kernel PlugIn driver
(fUseKP=TRUE), the Kernel PlugIn functions used to handle the
interrupts are derived from the type of interrupts enabled for the device: for
MSI/MSI-﻿X, the KP_IntAtIrqlMSI and KP_IntAtDpcMSI
functions are used; otherwise, the KP_IntAtIrql and
KP_IntAtDpc functions are used.

If the caller selects to handle the interrupts in the kernel, using a Kernel
PlugIn driver, the Kernel PlugIn KP_IntAtIrql [B.8.8]
(legacy interrupts) or KP_IntAtIrqlMSI [B.8.10]
(MSI/MSI-﻿X) function,
which runs at high interrupt request level (IRQL), will be invoked immediately when an interrupt
is received.

The function can receive transfer commands information, which will be performed
by WinDriver at the kernel, at high IRQ level, when an interrupt is received (see
further information in Section 9.2.6). If a
Kernel PlugIn driver is used to handle the interrupts, any transfer
commands set by the caller will be executed by WinDriver after the Kernel PlugIn
KP_IntAtDpc or KP_IntAtDpcMSI function completes its execution.
When handling level-sensitive interrupts (such as legacy PCI interrupts) from
the user mode, without a Kernel PlugIn driver, you must prepare and pass
to the function transfer commands for acknowledging the interrupt. When using a
Kernel PlugIn driver, the information for acknowledging the interrupts
should be implemented in the Kernel PlugIn
KP_IntAtIrql function [B.8.8], so the transfer commands in the
call to WDC_IntEnable() are not required (although they can still
be used).

The function receives a user-mode interrupt handler routine, which will be
called by WinDriver after the kernel-mode interrupt processing is completed.
If the interrupts are handled using a Kernel PlugIn driver, the return
value of the Kernel PlugIn deferred interrupt handler function —
KP_IntAtDpc [B.8.9]
(legacy interrupts) or KP_IntAtDpcMSI [B.8.11]
(MSI/MSI-﻿X) — will determine how many times (if at all)
the user-mode interrupt handler will be called (provided
KP_IntAtDpc or KP_IntAtDpcMSI itself is executed — which is determined by
the return value of the Kernel PlugIn KP_IntAtIrql [B.8.8] or KP_IntAtIrqlMSI [B.8.10] function).

An array of transfer commands information structures that define the
operations to be performed at the kernel level upon the detection of an
interrupt, or NULL if no transfer commands are required.

NOTE:
• Memory allocated for the transfer commands must remain available
until the interrupts are disabled
.
• When handling level-sensitive interrupts (such as legacy PCI
interrupts) without a Kernel PlugIn [11],
you must use this array to define the hardware-specific commands for
acknowledging the interrupts in the kernel, immediately when they are
received — see further information in
Section 9.2.

For an explanation on how to set the transfer commands, refer to the
description of WD_TRANSFER in
Section B.7.10, and to the explanation in
Section 9.2.6.

dwNumCmds

Number of transfer commands in the pTransCmds array

dwOptions

A bit mask of interrupt handling flags — can be set to zero for no
options, or to a combination of any of the following flags:

INTERRUPT_CMD_COPY: If set, WinDriver will copy any data
read in the kernel as a result of a read transfer command, and return
it to the user within the relevant transfer command structure.
The user will be able to access the data from his user-mode interrupt
handler routine
(funcIntHandler).

The following flags are applicable only to PCI interrupts on Linux.
If set, these flags determine the types of interrupts that may be enabled
for the device — the function will attempt to enable only interrupts
of the specified types, using the following precedence order, provided the
type is reported as supported by the device:

INTERRUPT_MESSAGE_X: Extended Message-Signaled Interrupts (MSI-﻿X)

INTERRUPT_MESSAGE: Message-Signaled Interrupts (MSI)

INTERRUPT_LEVEL_SENSITIVE — Legacy level-sensitive
interrupts

funcIntHandler

A user-mode interrupt handler callback function, which will be executed
after an interrupt is received and processed in the kernel. (The prototype
of the interrupt handler — INT_HANDLER — is
defined in windrvr_int_thread.h).

If TRUE — The device's Kernel PlugIn driver's
KP_IntAtIrql [B.8.8] or KP_IntAtIrqlMSI [B.8.10] function, which runs at high interrupt request level (IRQL), will be
executed immediately when an interrupt is received. The Kernel PlugIn
driver to be used for the device is passed to
WDC_xxxDeviceOpen() and stored in the WDC device structure.
If the caller also passes transfer commands to the function
(pTransCmds), these commands will be executed by WinDriver at
the kernel, at high IRQ level, after KP_IntAtIrql or KP_IntAtIrqlMSI completes
its execution.
If the high-IRQL handler returns TRUE, the Kernel PlugIn
deferred interrupt processing routine — KP_IntAtDpc [B.8.9] or KP_IntAtDpcMSI [B.8.11] —
will be invoked. The return value of this function determines how many
times (if at all) the user-mode interrupt handler
(funcIntHandler) will be executed once the control returns
to the user mode.
If FALSE — When an interrupt is received, any transfer
commands set by the user in pTransCmds will be executed by
WinDriver at the kernel, at high IRQ level, and the user-mode interrupt
handler routine (funcIntHandler) will be executed when the
control returns to the user mode.

The function enables interrupt handling in the software. After it
returns successfully you must physically enable generation of interrupts
in the hardware (you should be able to do so by writing to the device
from the code).

A successful call to this function must be followed with a call to
WDC_IntDisable() later on in the code, in order to disable the
interrupts.
The WDC_xxxDriverClose() functions
(PCI: [B.3.12],
ISA: [B.3.13]) call WDC_IntDisable() if
the device's interrupts are enabled.

WinDriver must be registered with the OS as the driver of the device before
enabling interrupts. For Plug﻿-﻿and﻿-﻿Play hardware (PCI﻿/﻿PCI Express) on
Windows platforms, this association is made by installing an INF file for the
device [15.1].
If the INF file is not installed, WDC_IntEnable()
will fail with a WD_NO_DEVICE_OBJECT error [B.11].

B.3.42. WDC_IntDisable()

Purpose

Disables interrupt interrupt handling for the device, pursuant to a previous
call to WDC_IntEnable() [B.3.41].

A user-mode event handler callback function, which will be called when an
event for which the caller registered to receive notifications (see
dwActions) occurs. (The prototype of the event handler
— EVENT_HANDLER — is defined
in windrvr_events.h.)

If TRUE — When an event for which the caller
registered to receive notifications (dwActions) occurs, the
device's Kernel PlugIn driver's KP_Event function [B.8.5] will
be called. (The Kernel PlugIn driver to be used for the device is passed to
WDC_xxxDeviceOpen() and stored in the WDC device
structure).
If this function returns TRUE, the user-mode events handler
callback function (funcEventHandler) will be called when the
kernel-mode event processing is completed.
If FALSE — When an event for which the caller
registered to receive notifications (dwActions) occurs, the
user-mode events handler callback function will be called.

A successful call to this function must be followed with a call to
WDC_EventUnregister() [B.3.46] later on in the code, in order to
unregister from receiving Plug-and-play and power management notifications
from the device.

B.3.46. WDC_EventUnregister()

Purpose

Unregisters an application from a receiving Plug﻿-﻿and﻿-﻿Play and power management
notifications for a device, pursuant to a previous call to
WDC_EventRegister() [B.3.45].

Prototype

DWORD DLLCALLCONV WDC_EventUnregister(WDC_DEVICE_HANDLE hDev);

Parameters

Name

Type

Input/Output

hDev

WDC_DEVICE_HANDLE

Input

Description

Name

Description

hDev

Handle to a Plug﻿-﻿and﻿-﻿Play WDC device, returned by
WDC_PciDeviceOpen() [B.3.10]

B.3.47. WDC_EventIsRegistered()

Checks if the application is currently registered to receive Plug﻿-﻿and﻿-﻿Play and power
management notifications for the device.

Prototype

BOOL DLLCALLCONV WDC_EventIsRegistered(WDC_DEVICE_HANDLE hDev);

Parameters

Name

Type

Input/Output

hDev

WDC_DEVICE_HANDLE

Input

Description

Name

Description

hDev

Handle to a Plug﻿-﻿and﻿-﻿Play WDC device, returned by
WDC_PciDeviceOpen() [B.3.10]

Return Value

Returns TRUE if the application is currently registered to receive
Plug﻿-﻿and﻿-﻿Play and power management notifications for the device; otherwise returns
FALSE.

B.3.48. WDC_SetDebugOptions()

Purpose

Sets debug options for the WDC library — see the description of WDC_DBG_OPTIONS [B.3.1.8] for details regarding the possible debug options to set.

This function is typically called at the beginning of the application, after
the call to WDC_DriverOpen() [B.3.2], and can be re-called at any time
while the WDC library is in use (i.e., WDC_DriverClose() [B.3.3] has not
been called) in order to change the debug settings.

Until the function is called, the WDC library uses the default debug options
— see WDC_DBG_DEFAULT [B.3.1.8].

When the function is recalled, it performs any required cleanup for the
previous debug settings and sets the default debug options before attempting
to set the new options specified by the caller.

A bit mask of flags indicating the desired debug settings — see
WDC_DBG_OPTIONS [B.3.1.8].
If this parameter is set to zero, the default debug options will be used
— see WDC_DBG_DEFAULT [B.3.1.8].

sDbgFile

WDC debug output file.
This parameter is relevant only if the WDC_DBG_OUT_FILE flag
is set in the debug options (dbgOptions) (either directly or
via one of the convenience debug options combinations — see
WDC_DBG_OPTIONS [B.3.1.8]).
If the WDC_DBG_OUT_FILE debug flag is set and
sDbgFile is NULL, WDC debug messages will be logged to the
default debug file — stderr.

Format-control string, which contains the trace message to display. The
string is limited to 256 characters (CHAR)

argument

Optional arguments for the format string

Return Value

None

B.3.51. WDC_GetWDHandle()

Purpose

Returns a handle to WinDriver's kernel module, which is required by the basic
WD_xxx WinDriver PCI﻿/﻿ISA API, described in the
WinDriver PCI Low﻿-﻿Level API Reference (see Remarks below).

Prototype

HANDLE DLLCALLCONV WDC_GetWDHandle(void);

Return Value

Returns a handle to WinDriver's kernel module, or
INVALID_HANDLE_VALUE in case of a failure

Remarks

When using only the WDC API, you do not need to get a handle to WinDriver,
since the WDC library encapsulates this for you. This function enables you
to get the WinDriver handles used by the WDC library so you can pass it to
low﻿-﻿level WD_xxx API, if such APIs are used from your
code. In such cases, take care not to close the handle you received
(using WD_Close()). The handle will be closed by the WDC
library when it is closed, using WDC_DriverClose() [B.3.3]. The
low﻿-﻿level WD_xxx API is described in the WinDriver PCI Low﻿-﻿Level API Reference.