Yes — with WinDriver you can develop a single cross-platform driver codebase that runs on Windows, Linux, and macOS.

WinDriver provides a uniform API across operating systems, allowing you to write your device logic once and compile it for each supported OS. The same application and driver logic can be reused, significantly reducing development time and maintenance effort.

WinDriver handles the OS-specific kernel interaction layer, including support for PCI/PCIe/SoC and USB devices, DMA, and interrupts.

This approach enables true cross-platform driver development without rewriting your driver separately for each operating system.

In version 6.2.0 of WinDriver, the PCI configuration space read/write method on Windows was upgraded to a more advanced method. On rare occasions, this method fails to identify some PCI devices. To resolve this problem, from WinDriver version 10.3.1 you can revert to the legacy PCI configuration space read/write method by doing the following:

Set the PciCfgRwCompat registry key flag in the WinDriver driver INF file (windrvr<version>.inf(e.g. windrvr1660.inf) / windrvr6.inf in earlier versions)) — to 1:

HKR, Parameters, PciCfgRwCompat, 0x00010001, 1

Beginning with version 11.1.0 of WinDriver, the driver INF file contains a similar line, which sets the PciCfgRwCompat flag to 0 (default), so you only need to modify the value of the flag in the existing line to 1:

Open a command-line prompt and reinstall the driver by running the following commands from the WinDriver\util\wdregdirectory (where “WinDriver” is the path to your WinDriver installation directory):

$ wdreg -inf  uninstall
$ wdreg -inf  uninstall
$ wdreg -inf  install
$ wdreg -inf  install

First, locate the slot to which your card is connected, using WDC_PciScanDevices().

Then get the card’s information by calling WDC_PciGetDeviceInfo().

This information includes the memory range chosen for the card by the Plug and Play system.

Now call WDC_PciDeviceOpen() to install the memory range and map it into both kernel and user mode virtual address spaces.

You can then either access the memory directly from your user mode application (more efficient), by using the user mode mapping of the physical address — returned by WDC_PciDeviceOpen() in ((PWDC_DEVICE)hDev)->cardReg.Card.Item[i].I.Mem.pUserDirectAddr (where i is the index number of the memory range in the Item array) — or pass the kernel mode mapping of the memory — ((PWDC_DEVICE)hDev)->cardReg.Card.Item[i].I.Mem.pTransAddr — to WD_Transfer() / WD_MultiTransfer(), in order to access the memory in the kernel. Check out the documentation of WDC_DEVICE for more info.

This is demonstrated, for example, in the sample code found in the WinDriver/samples/c/pci_diag directory, and in the diagnostics DriverWizard code that you can generate for your PCI card.
⚠ Attention: ‍‍To access memory directly in the kernel, from within a Kernel PlugIn project, you must use the kernel mode mapping of the physical memory address — returned by WDC_PciDeviceOpen() in (PWDC_DEVICE)hDev)->cardReg.Card.Item[i].I.Mem.pTransAddr — and not the user mode mapping that is used to access the memory directly from your user-mode application.

Assuming your computer’s Thunderbolt adapter is correctly configured and your device is recognized by the operating system, then a PCI Express device connected over Thunderbolt should be recognized by WinDriver as a regular PCI Express device and this should not require special actions on the WinDriver side. Some motherboard chipsets require changes in their BIOS settings to enable Thunderbolt support, consult your vendor’s documentation for more info.

The “shared” status determines whether the resource is locked for exclusive use. When a memory, I/O, or interrupt item is defined as non-sharable, the device registration function — WDC_PciDeviceOpen() / WDC_IsaDeviceOpen(), or the low-level WD_CardRegister() function — checks whether the resource is already locked for exclusive use. If it is, the registration fails; otherwise, the resource is locked exclusively, and any subsequent attempt to lock the resource — either from within the same application, or from another WinDriver application — will fail, until the resource is released using WDC_PciDeviceClose() / WDC_IsaDeviceClose(), or the low-level WD_CardUnregister() function.

⚠ Attention: ‍‍Device registers cannot be defined as shared.

PCI resources, and specifically interrupts, should generally be defined as sharable.

For memory and I/O, the share status defined with WinDriver affects only WinDriver-based applications. However, for interrupts there is further significance to the share status, since it also determines whether other drivers (not necessarily WinDriver drivers) can lock the same interrupt. For an explanation of how to read the value of the PCI interrupt status register, please see futher FAQ questions.

Use one of the following methods to check whether a resource is defined as sharable:

• From your code, print the value of the fNotSharable flag for the memory/IO/interrupt item that you wish to check — deviceInfo.Card.Item[i].fNotSharable when using the WDC API, or cardReg.Card.Item[i].fNotSharable when using the low-level WinDriver API. A value of 1 indicates that the resources is not sharable. A value of 0 indicates that the resource is sharable.
• If you have used the DriverWizard to generate your code, you can run the DriverWizard, open the xxx.wdp DriverWizard project file, which served as the basis for your application, select the Memory, I/O, or Interrupt tab (respectively) and click on Edit. Then look to see if the Shared box in the Resource Information window is checked, to signify that the resource is defined as shared for this device. Note that this test is only relevant when using the original xxx.wdp project file for your application code, and assuming your code does not modify the “shared” status — since any changes made in the xxx.wdp file, via the DriverWizard, will only affect subsequent code generation, and will not affect the existing application code. Therefore, checking the “shared” values from the code is more accurate.

As a general guideline, avoid locking the same resource twice. It is always recommend to release a previously locked resource before trying to lock it again (either from the same application, or from different applications). If you need to access the resources from several applications, you can share the handle received from a single call to the device registration function — WDC_PciDeviceOpen() / WDC_IsaDeviceOpen(), or the low-level WD_CardRegister() function.

It is possible to create several WinDriver-based driver processes that will access the same card, although we do not recommend this, and it should not generally be required.

Should you decide to implement such a design, consider the synchronization issues carefully. To bypass the synchronization problems, we recommend you use only one point of access to your hardware. Use a single process to directly access your hardware, while the other processes should access the hardware only via this process. The advantage of this design is that only one point requires synchronization.

Please note, however, that we will not be able to provide technical support specifically related to the implementation of such designs and accompanying issues (such as synchronization problems that might occur). You should therefore carefully consider if this is indeed the desired design in your case.

For USB, note that while multiple calls to WDU_Init() for the same device may succeed, after the first attach callback accepts control of the device no other attach notifications will be received until WDU_Uninit() is called for the relevant WDU_Init() call. Using a single process to perform a single WDU_Init() call with a single attach callback function, as suggested above, will eliminate problems resulting from multiple WDU_Init() calls.

You may consider accessing the device from one application, and communicate with other apps using the IPC API.

When handling the interrupts from the user mode you must acknowledge (clear) the interrupt on the card whether your card generated the interrupt or not (in case of shared IRQs). However, this does not necessarily present a problem.

To determine which card generated the interrupt, and activate your ISR only in case the interrupt was generated by your card, you can set up the transfer commands of the WD_INTERRUPT structure, which is passed to WDC_IntEnable() / InterruptEnable(), or to the lower level WD_IntEnable() function — int.Cmds — to include a command to read from the interrupt register before clearing the interrupt. The register will then be read in the kernel, immediately when an interrupt is received and before it is cleared, and you will be able to access the read value from your user mode interrupt handler routine when it is activated.

⚠ Attention: ‍‍In order to save the read value you must set the INTERRUPT_CMD_COPY flag in the dwOptions field of the WD_INTERRUPT structure (int.dwOptions |= INTERRUPT_CMD_COPY).

When using WinDriver’s Kernel PlugIn feature to handle the interrupts directly in the kernel, you can read the value of the interrupt status register on your card directly when an interrupt is received, from within your [KP_IntAtIrql()] (KP_PCI_IntAtIrql) routine, and proceed to acknowledge (clear) the interrupt and execute your ISR only if the value of the status register indicates that the interrupt was indeed generated by your card. For more information on how to handle shared PCI interrupts from the Kernel PlugIn, please refer to the Kernel PlugIn chapter of this manual.

WinDriver supports the implementation of interrupt service routines and locking down DMA buffers into memory, giving you the physical addresses and lengths of the kernel DMA buffer.

Assuming you want to implement slave DMA for an ISA card, you will need to write the code to program the DMA controller yourself. There is no specific API to program the system DMAC on PCs, but you can use the generic WinDriver API for direct hardware access and DMA allocation from your application
(see specifically WDC_DMAContigBufLock(), WDC_DMASGBufLock(),
and the WDC_PciReadCfg8() / WDC_PciReadCfg16() / WDC_PciReadCfg32() / WDC_PciReadCfg64()
and WDC_PciWriteCfg8() / WDC_PciWriteCfg16() / WDC_PciWriteCfg32() / WDC_PciWriteCfg64() or the lower-level WD_DMALock() and WD_Transfer() APIs).

“Regular” memory (stack, heap, etc.) is cached by the operating system. When using WinDriver DMA APIs, the data is non-cached, in order to make it DMA-safe. Therefore, the memory access is slower. Note that this is the correct behavior for DMA.

When performing Contiguous Buffer DMA, you can set the DMA_ALLOW_CACHE flag in the dwOptions parameter of WDC_DMAContigBufLock(), or directly in the dwOptions field of the WD_DMA structure that is passed to WD_DMALock() (when using the low-level WinDriver API), in order to allocate a cached DMA buffer. When working on Windows x86 and x86_64 platforms, it is recommended to always set this flag.

If you have allocated the memory in the user mode and then passed its address to WDC_DMASGBufLock() or to the low-level WD_DMALock() function in order to lock a Scatter/Gather DMA buffer, then calling WD_DMAUnlock() will unlock the memory buffer and it will now function like other “regular” memory in terms of access speed.

WinDriver does not impose any inherent limitation on the size of the DMA buffer that can be allocated using its DMA APIs. However, the success of the DMA allocation is dependent of the amount of available system resources at the time of the attempted allocation. Therefore, the earlier your try to allocate the buffer, the better your chances of succeeding.

For contiguous-buffer DMA allocation, there must be enough contiguous physical memory for the allocation. On Windows, WinDriver allows preallocation of DMA buffers to evade this, so please refer to the relevant chapter of the manaul for more information.

When allocating a Scatter/Gather DMA buffer that is larger than 1MB, using the low-level WinDriver API, be sure to set the [DMA_LARGE_BUFFER] (DMA_LARGE_BUFFER) flag in the dwOptions field of the WD_DMA() structure that is passed to WD_DMALock(). (When using the high-level WDC_DMASGBufLock() function, this flag is already handled internally by the function.)

The DMA buffer allocated by WinDriver uses page-locked memory, to ensure a safe DMA operation. This memory is allocated from Windows’ non-paged kernel pool of memory. The size of this pool is fixed at boot time by a Registry setting. You can increase the allocated memory by increasing the value of the NonPagedPoolSize Registry entry, found under HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management.

Sometimes, there is enough contiguous memory, but there are not enough page table entries to map the memory. Even after increasing the value of the relevant Registry entries, the memory allocation might still fail, specifically when trying to allocate a very large buffer (such as 1GB). The solution in this case is to try decreasing the size of the buffer you are trying to lock, until you succeed.
⚠ Attention: ‍‍Please note that the WinDriver DMA allocation APIs ((WDC_DMAContigBufLock() / WDC_DMASGBufLock() / WD_DMALock()) also map the physical memory of the allocated buffer into virtual user mode space. Therefore, there must also be enough free virtual memory to enable the mapping of the entire buffer into the user space.

See 11.2. Performing Direct Memory Access (DMA) and 11.3. Performing Direct Memory Access (DMA) transactions.

Locate and register both cards (using WDC_PciScanDevices(), WDC_PciGetDeviceInfo() and
WDC_PciScanDevices()). At least one of the cards must be PCI DMA Master Capable.

Program it with the physical address of the Slave card. Obtaining this address is possible by using pciCard.Card.Item[i].I.Mem.pPhysicalAddr, set by WDC_PciGetDeviceInfo() for the slave card.

Refer to the DMA section of this manual for more info regarding programming DMA using WinDriver.

You can use WDU_ResetDevice().

The 0xC000000C error code, is defined in windrvr.h as WD_USBD_STATUS_BUFFER_OVERRUN.

The WD_USBD_XXX status codes returned by WinDriver (see windrvr.h) comply with the URB status codes returned by the low-level USB stack driver (e.g., URB code 0XC000000CL — WD_USBD_STATUS_BUFFER_OVERRUN). You can refer to the Debug Monitor log to see the URB and IRP values returned from the stack drivers.

For Windows, the URB and IRP codes can be found in the Windows Driver Kit (WDK) under the inc\ directory. The URB status codes can be found in the usbdi.h file or the usb.h file (depending on the OS). The IRP status codes can be found in the ntstatus.h file. For Linux, WinDriver translates the error codes returned from the stack driver into equivalent USBD errors.

For information regarding the specific error you received and when it might occur, review the operating system’s documentation.

The USBD_STATUS_BUFFER_OVERRUN error code (0xC000000C) is set by the USB stack drivers when the device transfers more data than requested by the host.

There are two possible solutions for this buffer overrun problem:

• Try setting the buffer sizes in the calls to WDU_Transfer() in your code to multiples of the maximum packet size. For example, if the maximum packet size is 64 bytes, use buffer sizes that are multiples of 64 (64 bytes, 128 bytes, etc.).
• Define a protocol between the device and device driver, making sure that the device does not transfer more data than requested. When you have access to the device firmware code, this solution is recommended.

💡 Recommendation ‍‍Recheck your firmware and the hardware specification to verify that you are implementing the communication with the device correctly. It is also recommended to use a USB bus analyzer to determine what is happening on the bus.

You can use WinDriver’s WDU_GetStringDesc() function to get the desired string descriptors.

Use WDU_Init() to register to listen for the notifications you are interested in.

You should set the pBuffer parameter of the WDU_Transfer() function to NULL and set the dwBufferSize parameter to 0.

No. Windriver USB is designed for writing drivers for USB devices (USB client drivers). It cannot be used to write a USB hub or a USB Host Controller driver.

Yes. WinDriver provides WDU_Stream functions for peforming streaming USB data transfers on Windows.

The main difference between C#/Java/Python and C is that the former languages have a garbage collector which automatically manages the memory, whereas C is totally “manual” – meaning that it is the user’s responsibility to allocate and free memory from the heap (using malloc() and free()). Some WinDriver APIs that are written in C require usage of unmanaged memory.

For each “managed” langauge that WinDriver supports, WinDriver provides a sample of this kind of use:

• C#.NET: WinDriver/samples/csharp.net/pci_sample/lib/dma.cs (Using the System.Runtime.InteropServices.Marshal class)
• Python: WinDriver/samples/python/pci_diag.py (Using global variables and the ctypes class)
• Java: WinDriver/samples/java/com/jungo/PciDiag.Java (Using the java.nio.ByteBuffer class).

Although most samples provided in the WinDriver package are console-mode applications, it is possible to integrate WinDriver’s API into Graphic User Interface (GUI) applications. Some examples of GUI applications that were built with WinDriver are our DriverWizard and Debug Monitor (built with the Qt Framework), and also our .NET GUI samples/generated codes.

With WinDriver, the initial driver skeleton can be generated within minutes using the DriverWizard tool. This automatically creates a working driver framework, allowing developers to focus on device-specific logic instead of low-level kernel infrastructure.

Actual development time still depends on features such as DMA, interrupts, performance tuning, and validation, but WinDriver significantly reduces the overall development effort compared to writing a driver from scratch.

WinDriver is used by companies developing custom PCI/PCIe/SoC and USB hardware across industries such as industrial automation, medical devices, semiconductor test equipment, aerospace and defense, automotive systems, telecommunications, and scientific research.

It is possible. For the sake of simplicity, our C, Java and Python PCI samples only allow opening one device at a time, but it is indeed possible in these languages as well. Our USB samples for C, Java and Python allow opening multiple devices at the same time. Our .NET samples also allow opening multiple devices at the same time.

Generally, each device controlled by WinDriver has its own unique handle, allowing applications to open multiple handles at the same time if needed.

Yes. You can run several WinDriver-based applications simultaneously on the same machine. It is strongly recommended that the WinDriver Kernel Module will be renamed in that case.

Yes. Using WinDriver, you can group I/O and memory transfers by calling WD_MultiTransfer(), which can perform multiple transfers in one call. However, Jungo generally recommeds using the High-Level API (WDC_xxx) for I/O.

Note that you can also access the memory directly from your user-mode application using the virtual user-mode mapping of the physical address, which is returned by or WDC_PciDeviceOpen() in (((PWDC_DEVICE)hDev)->cardReg.Card.Item[i].I.Mem.pUserDirectAddr or WD_CardRegister() in cardReg.Card.Item[i].I.Mem.pUserDirectAddr, where i is the index item of the relevant memory item in the WD_ITEMS Item array.

WinDriver generally rids you of the need to do any changes in your program’s code. Of course some OS specific functions that you have been using that are not from the WinDriver API might not work anymore (i.e. Win32 functions that are not provided by POSIX, or the other way around), but this is why we recommend trying to stick only to cross-platform standard functions in your C code and to the WinDriver API. There are about 10% of WinDriver’s API features that are not cross platform, but usually this could be overcome with different alternatives. If this could not be overcome, contact Jungo Support for assistance.

The recommended and easiest way to shift between platforms is to generate a CMakeLists.txt file for your project using the DriverWizard. This will allow you to port the code over all supported OSes and makes the porting a much easier task, assuming you’ve installed CMake on your target development machine.

On supported languages other than C, porting should be even easier as these languages support cross-platform use inherently.

Assuming you’re using a renamed driver – a step you will have to go through is creating a new project from the DriverWizard in your new operating system. This will create a renamed driver for your target platform (i.e. if you had a .sys file for your driver on a Windows system, then on Linux the wizard would create a .ko file, etc.).

As described in 7.4.1. Regenerating code and gradually merging, the best way for this kind of porting is first to generate new code with the DriverWizard, make sure that it works without any modifications, and then gradually merge your code from the other operating system into your new OS code.

So why use wddebug_gui?

The GUI version offers easier search options and is more comfortable to use on modern desktop operating systems.

And why use wddebug?

• The GUI version depends on Qt, and runs slower than the console-version, and in some cases might make your application run slower when they run at the same time.
• If you wish to debug a WinDriver-based user application on a machine that does not have WinDriver installed on it (a redistribution machine)- it would be more complicated to run wddebug_gui on it because you will have to install or copy all Qt DLL/.so dependencies to that machine for the Debug Monitor to work. In contrast, wddebug only requires the wdapi shared library (wdapi1660.dll/.so).
• wddebug’s source code is available at WinDriver/samples/c/wddebug. This allows you greater flexibility in modifying this application for your specific debugging needs. Jungo does not provide the source code for wddebug_gui.
• wddebug is easier to use in scripts, or remote console sessions such as PowerShell, SSH, etc.

Yes! The code of the device driver you write runs in normal Win32 user mode. Therefore, you can compile and debug your code using MS Visual Studio. Generally, WinDriver-based user-code can be debugged on any IDE that allows compiling C/C++ applications in Windows.

Besides using wddebug_gui / wddebug as described in this chapter, we also recommend using the following tools when needed:

• Basic user-mode development: Use IDEs such as Visual Studio / Visual Studio Code / XCode (MacOS) and the debuggers that they offer. Other recommended tools are valgrind (Linux) / Dr. Memory (Windows) for locating memory leaks.
• Debugging into calls to the WDAPI shared library: You can use its source code which is available in WinDriver/src/wdapi.
• Kernel debugging (For Kernel-PlugIn or identifying issues with WinDriver): In Windows you can use WinDbg / WinDbg Preview. More info on how to set these up is available on MSDN. In Linux/MacOS you can use dmesg to view kernel panics. MacOS also provides crash dumps for every application or kernel crash in a designated directory (Usually ~/Library/Logs).

There are several reasons why the call to WD_KernelPlugInOpen() might fail:

• You did not set up the parameters correctly in the call to WD_KernelPlugInOpen(). Please check this carefully.
• You did not set up the driver name correctly in all locations in the code. Please verify that you are using the correct Kernel PlugIn driver name in all the relevant locations in the code. Look specifically at the Kernel PlugIn KP_Init() implementation and at kernelPlugIn.pcDriverName in the user mode project. Please indicate the driver name in capital letters and without the file extension (*.sys/.ko).
• You did not install the driver properly. Make sure you copied the driver file that was created to the correct location (e.g.,windir%\system32\drivers — to install a SYS Kernel PlugIn driver on Windows) and that you installed the Kernel PlugIn kernel module correctly, as explained in the this Manual.

For Windows, for example, make sure to use the correct wdreg/wdreg_gui/wdreg_frontend syntax. For SYS drivers:

wdreg -name {your KP driver name} install

• For registered users. You did not call WD_License() before calling WD_KernelPlugInOpen(). If you are using a registered version of WinDriver, remember to call WD_License() (or a registration function, which calls WD_License() ) before calling WD_KernelPlugInOpen().

⚠ Attention: ‍‍‍WD_KernelPlugInOpen() is also called from the high-level WDC_KernelPlugInOpen() function, and from the WDC_PciDeviceOpen() / WDC_IsaDeviceOpen() functions — when they are called with the name of a Kernel PlugIn driver.

Yes, you can erase the user mode interrupt handler routine.

You can also implement some of the interrupt handling in the Kernel PlugIn and some of it in the user mode. The return value of KP_IntAtDpc() (which is called when the high-priority KP_IntAtIrql() routine returns TRUE) determines the number of times that the user mode interrupt handler routine will be executed (if at all).

You can use WinDriver’s WD_DebugAdd() function to print debug messages from your Kernel PlugIn or user-mode code to the Debug Monitor utility, and then view the messages in the Debug Monitor log. WD_DebugAdd() can be called from within any user-mode or Kernel PlugIn function, including KP_IntAtIrql().

You can also select to send the debug information from WinDriver’s Debug Monitor to a kernel debugger, as explained in Chapter 8: Debugging Drivers.

In addition, you can add calls in your Kernel PlugIn code to OS kernel functions that print directly to the kernel debugger — such as KdPrint() on Windows, or printk() on Linux.

This might happen if you are enabling the interrupt from your Kernel PlugIn interrupt routines, and simultaneously disabling it from the user mode (using WD_IntDisable() or InterruptEnable() / WDC_IntEnable() — which call WD_IntDisable()). Since the interrupt is active (having been enabled from the Kernel PlugIn), the interrupt cannot be disabled and the PC hangs waiting for WD_IntDisable() to return.

A possible solution, is to call WD_IntDisable() / InterruptEnable() / WDC_IntEnable() as an atomic operation, so that it will disable the interrupts successfully before the Kernel PlugIn interrupt routine enables the interrupt.

The Kernel PlugIn is a kernel module, and therefore must be written in the C language. However, the user application that calls the Kernel PlugIn can be of any langauge supported by WinDriver: C, C#.NET, Visual Basic.NET, Java, Python. When generating code in the DriverWizard in languages other than C with Kernel PlugIn, the Kernel PlugIn code will still be generated in C. This user application would communicate with the C-language Kernel PlugIn.

If you select to implement such a design, in order to ensure the correct interaction between the user mode and Kernel PlugIn applications, you will need to implement a file in your programming language that contains common definitions for the Kernel PlugIn and the user mode applications — as done in the library header files of the sample and DriverWizard generated Kernel PlugIn C projects (e.g. WinDriver\samples\pci_diag\pci_lib.h, used by the sample KP_PCI driver). WinDriver implements these files for you when you generate code with DriverWizard, and they should be generated in your project directory, for you to start as fast and easy as possible.

For further examples check: WinDriver/include/windrvr.h C header file and the corresponding WinDriver/samples/python/wdlib/windrvr.py (Python), WinDriver/src/wdapi_dotnet/windrvr.h (.NET), WinDriver/lib/wdapi_javaXXX.jar (Java) as examples of implementing the same code both in C and other supported/ languages.

WinDriver implements malloc() and free() in its Kernel PlugIn library (kp_nt1660.lib/kp_linux1660.o_shipped), to which your Kernel PlugIn code is linked.

These functions are implemented to allocate locked memory when called from the kernel mode, so you can use that memory in your interrupt handler as well.

PCI interrupts are normally handled at the kernel level. Therefore, the best way to handle PCI interrupts with WinDriver is using the Kernel PlugIn feature, which lets you implement code directly at the kernel level. This is specifically true when handling interrupts that are shared between different hardware devices — a very common phenomenon in the case of PCI interrupts, which are by definition sharable.

The Kernel PlugIn consists of two interrupt handler functions:

⚠ Attention: ‍‍‍Replace “KP_” in the function names below with the name of your Kernel PlugIn driver. For example, the Kernel PlugIn interrupt handler functions for the sample KP_PCI driver are KP_PCI_IntAtIrql and KP_PCI_IntAtDpc.

KP_IntAtIrql — this function is executed in the kernel at high IRQ (Interrupt Request) level immediately upon the detection of an interrupt. The function should contain the write/read commands for clearing the source of the interrupt (acknowledging the interrupt) and any additional high-priority interrupt-handling code.
If additional deferred kernel- or user-mode interrupt processing is required, KP_IntAtIrql should return TRUE, in which case the deferred KP_IntAtDpc routine (see below) will be executed once the high-level processing is completed. Otherwise, the function should return FALSE and KP_IntAtDpc (as well as any existing user-mode interrupt-handler routine) will not be executed. The generated and sample WinDriver Kernel PlugIn projects, for example, schedule deferred interrupt processing once every five interrupts by implementing code that returns TRUE only for every fifth KP_IntAtIrql call.

KP_IntAtDpc — this function is executed in the kernel at raised execution level, provided KP_IntAtIrql returned TRUE (see above), and should contain any lower-priority kernel interrupt handling that you wish to perform. The return value of this function determines how many times, if at all, the user-mode interrupt-handler routine (which can be set in the call to WDC_InterruptEnable() from the user-mode) will be executed once the control returns to the user mode.
To handle shared PCI interrupts with WinDriver, perform the following steps:

Generate a Kernel PlugIn project using WinDriver’s DriverWizard utility. When generating C code with the DriverWizard, you will be given the option to generate Kernel PlugIn code — simply check the relevant check-box and proceed to generate the code. Alternatively, you can also use the generic WinDriver Kernel PlugIn sample — KP_PCI(WinDriver\samples\c\pci_diag\kp_pci\kp_pci.c) — as the basis for your Kernel PlugIn project. If you are developing a driver for a Xilinx PCI Express card with Bus Master DMA (BMD) design, you can use the sample Kernel PlugIn driver for this design — KP_BMD (WinDriver\samples\c\xilinx\bmd_design\kp\kp_bmd.c) — or select to generate customized DriverWizard code for this design, including Kernel Plugin code.
The advantage of using the DriverWizard is that the generated code will utilize the specific device configuration information detected for your device, as well as any hardware-specific information that you define with the DriverWizard. When generating Kernel PlugIn code for handling PCI interrupts, in the DriverWizard’s Registers tab define the registers that you wish to access upon the detection of an interrupt, and then in the Interrupts tab assign the registers read/write commands that you wish to perform at high IRQ level (KP_IntAtIrql) to the interrupt. The exact commands for acknowledging the interrupt are hardware-specific and you should therefore consult your hardware specification to determine the correct commands to set.

The correct way to handle PCI interrupts with the Kernel PlugIn, and shared interrupts in particular, is to include a command in KP_IntAtIrql that reads information from the hardware (normally you would read from the interrupt status register — INTCSR) in order to determine if your hardware generated the interrupt. (You can define a relevant read command in the DriverWizard before generating your Kernel PlugIn code — refer to step #1 above — or manually modify the generated/sample code to add such a command.) If the interrupt was indeed generated by your hardware, the function can set the value of the fIsMyInterrupt parameter to TRUE in order to accept control of the interrupt, and then proceed to write/read the relevant hardware register(s) in order to acknowledge the interrupt, and either return TRUE to perform additional deferred processing or return FALSEif no such processing is required (see above). If, however, you determine that the interrupt was not generated by your hardware, fIsMyInterrupt should be set to FALSE, in order to ensure that the interrupt will be passed on to other drivers in the system, and KP_IntAtIrql should return FALSE. Important to mention that there is no real harm in setting fIsMyInterrupt to FALSE even if the interrupt belongs to you, as done by default in the generated and sample WinDriver code, since other drivers in the system, assuming they were implemented correctly, should not attempt to handle the interrupt if it was not generated by their hardware.
The portion of the code that performs the check whether your hardware generated the interrupt is based on hardware-specific logic that cannot be defined in the DriverWizard. You will therefore need to modify the generated/sample KP_IntAtIrql implementation and add a relevant “if” clause to ensure that you do not accept control of an interrupt that was not generated by your hardware and do not attempt to clear the source of such an interrupt in the hardware.

Following is a sample KP_IntAtIrql implementation. The code reads the INTCSR memory register (defined elsewhere in the code) and only proceeds to accept control of the interrupt and acknowledge it if the value read from the INTCSR is 0xFF (which serves as an indication in this sample that our hardware generated the interrupt). The interrupt in this sample is acknowledged by writing back to the INTCSR the value that was read from it.

BOOL __cdecl KP_XXX_IntAtIrql(PVOID pIntContext, BOOL *pfIsMyInterrupt)
{
    XXX_HANDLE hXXX = (XXX_HANDLE) pIntContext;
    DWORD data = 0;
    PVOID pData = NULL;
    DWORD addrSpace;
    WD_ITEMS *pItem;

    addrSpace = XXX_INTCSR_SPACE;
    pItem = &hXXX->cardReg.Card.Item[hXXX->addrDesc[addrSpace].index];
    pData = (DWORD*)pItem->I.Mem.dwTransAddr;
    (DWORD)pData += XXX_INTCSR_OFFSET; 
    data = dtoh32(*((DWORD*)pData));

    if (data == 0xFF)
    {
        *((DWORD*)pData) = dtoh32(data);
        *pfIsMyInterrupt = TRUE; 
        return TRUE;
    }
    else
    {
        *pfIsMyInterrupt = FALSE;
        return FALSE;
    }
}

pIntContext is private context data that is passed from KP_IntEnable to the Kernel PlugIn interrupt handler functions — KP_IntAtIrql() and KP_IntAtDpc().

Jungo strongly recommends using the high-level WDC (PCI) API instead of using the low-level API.

To obtain the handle to WinDriver’s kernel module (hWD) from the Kernel PlugIn, you can call WD_Open() directly from the Kernel PlugIn.

For PCI/ISA, you can also use the hWD handle, which is passed from the user mode via WD_KernelPlugInOpen(), and received as the second argument of the Kernel PlugIn callback function KP_Open(). Alternatively, you can also pass the handle from the user mode to the Kernel PlugIn using the pData field of the WD_KERNEL_PLUGIN_CALL struct, which is used in the call to WD_KernelPlugInCall() in the user mode and results in a callback to KP_Call() in the Kernel PlugIn.

After obtaining the handle to WinDriver, the call to WD_Transfer() (or any other WinDriver API that receives a handle to WinDriver as a parameter) is the same as in the user mode.

Variables defined in the Kernel PlugIn project (such as global and local variables) are non paged. WinDriver also implements malloc() to allocate non-paged memory when used from within the kernel.

If you are using a pointer to the memory in the user mode from within the Kernel PlugIn, you need to make a copy of its contents (allocate memory and copy the data to the non-paged memory) in order to access it from your KP_IntAtIrql function, in order to ensure safe access to the data at all times.

You can call WD_Transfer() from within the KP_IntAtIrql or KP_IntAtDpc functions (replace “KP” in the function names with your Kernel PlugIn driver name — e.g., “KP_PCI”) in order to access the hardware.

⚠ Attention: ‍You can also access the memory or I/O directly from within the Kernel PlugIn interrupt functions. For direct memory access, use the kernel mapping of the memory, returned from WD_CardRegister() in cardReg.Card.Item[i].I.Mem.pTransAddr.

When calling WD_Transfer() you will need to pass as the first argument a handle to WinDriver (hWD). You can refer to the FAQ questions in this chapter to find out how to obtain a handle to WinDriver from within the Kernel PlugIn.

As specified in the aforementioned FAQ questions, you can store the handle to WinDriver in a global Kernel PlugIn variable (recommended), or pass it from one function to another. Below is an example of passing a handle to WinDriver from KP_Open() to KP_IntAtIrql:

Add the following line to KP_Open()

ppDrvContext = (PVOID) hWD;

Add the following line to KP_IntEnable()

ppIntContext = pDrvContext;

You can now use WD_Transfer() to access memory/IO from within KP_IntAtIrql. For example (IO access):

HANDLE hWD = (HANDLE) pIntContext;
WD_TRANSFER trans;
​
BZERO(trans);
trans.cmdTrans = WP_BYTE;
trans.dwPort = 0x378;
trans.Data.Byte = 0x65;
WD_Transfer(hWD, &trans);

This will write 0x65 to port 0x378 upon interrupt. The hWD handle is passed from KP_Open() to KP_IntEnable() to KP_IntAtIrql via the context.

You can also view the generated DriverWizard Kernel PlugIn code for an example of calling WD_MultiTransfer() from KP_IntAtIrql, provided you have used the DriverWizard to define and assign the register/s for the interrupt acknowledgment before generating the code.

From your user application, use the WDS_SharedBufferAlloc() function to allocate a shared memory buffer, which can be used both from a user-mode application and a Kernel PlugIn driver.

Pass the returned ppKerBuf->pKernelAddr value from the above function to the Kernel PlugIn using the pData paramter of the function WDC_CallKerPlug(). Note that WDS_SharedBufferAlloc() is part of the Server APIs of WinDriver, these APIs require a special license.

‍ℹ️ Note ‍If you would like to get more information about Server APIs licensing, please send an e-mail to [email protected], and our team will assist you.

No. Only the callbacks used by WinDriver need to be declared as __cdecl.