WD1480LNX86_64.tar.gz

C# PCI Sample ============== This file contains: 1. An overview of the contents of the csharp.net\pci_sample\ directory. 2. List of pci_sample/ files. 3. List of kp_pci/ Kernel PlugIn files. 4. Instructions for using the sample application. 5. Instructions for building the PCI library. 6. Instructions for building the PCI sample code. 7. Instructions for building the kp_pci Kernel PlugIn driver. 8. Instructions for installing the kp_pci Kernel PlugIn driver. 1. Overview ========= This code sample is provided AS-IS and as a guiding sample only. The csharp.net\pci_sample\ directory contains: - A C# .NET PCI library - pci_lib.dll. - A graphical (GUI) C# .NET PCI sample diagnostics application - pci_sample.exe. - The source code of the C# PCI library and diagnostics application. The code was written by Jungo Connectivity using WinDriver's PCI API. General Overview ----------------- The library and sample application support handling of multiple PCI devices and simultaneous execution of several tasks on different devices. It demonstrates how to use WinDriver's .NET WDC library to communicate with PCI devices, including: -- Scanning the PCI bus to locate a specific device and retrieve its resources information -- Reading/writing from/to a specific address or register -- Reading/writing from/to the PCI configuration space -- Handling the interrupts of a PCI device -- Registering to receive notifications for Plug and Play and power management events for the device Both the library and the sample code use the WinDriver .NET API DLL - wdapi_dotnet<version>.dll - which provides the required .NET interface for the WinDriver PCI API and enables the use of the C WinDriver API DLL - wdapi<version>.dll (found under the WinDriver\redist\ directory). A copy of wdapi_dotnet<version>.dll is provided with the sample (see below), as well as under the WinDriver\lib\<CPU>\<.NET Version>\ directory (e.g. WinDriver\lib\x86\v1.1.4322 - for Windows x86 32-bit, .NET v1.1.4322). The source code of wdapi_dotnet<version>.dll is found in the WinDriver\src\wdapi.net\ directory. In addition to the pci_lib library and the pci_sample application, the .NET pci_sample solution also includes a Kernel PlugIn project - kp_pci - which demonstrates how WinDriver's Kernel PlugIn feature can be combined with our .NET library. The kp_pci project included in the sample's solution is the same project used by the C pci_diag sample, and its source code can be found under the WinDriver\samples\pci_diag\kp_pci\ directory. The pci_lib Library --------------------------- The library provides an interface between the WinDriver .NET API DLL (wdapi_dotnet<version>.dll - see above) and .NET PCI applications, such as the pci_sample application. The library's core are the PCI_Device and PCI_DeviceList classes, which provide an object oriented implementation of a PCI device object and a PCI driver object. The pci_sample Application --------------------------- The GUI sample, which uses the pci_lib.dll library, displays the resources information for each connected device, and enables communication with the device through several GUI forms. The sample enables you to select whether to communicate with the device(s) entirely from the user mode, or use the kp_pci Kernel PlugIn driver to handle performance critical operations in kernel mode, as explained below. The kp_pci Kernel PlugIn Driver --------------------------------- The kp_pci project was implemented using WinDriver's Kernel PlugIn feature. This feature enables optimal performance I/O and interrupt handling, by executing these directly from the kernel mode. The Kernel PlugIn project is built into a *.sys kernel-mode driver, which is driven from a user-mode WinDriver application. The Kernel PlugIn is written in C and uses the same WinDriver C APIs (WDC_XXX/WD_XXX) in the kernel mode, as are supported in the user mode. This enables user-mode WinDriver C code to be easily ported to the kernel mode, thereby saving the context-switch time and enabling the developer to create a high performance driver. Using the kp_pci Kernel PlugIn Driver -------------------------------------- After opening a handle to the device, the .NET user-mode application (pci_sample) attempts to open a handle to the kp_pci Kernel PlugIn driver. If successful, pci_sample can use the Kernel PlugIn driver to perform performance-critical operations, such as interrupt handling. pci_sample also demonstrates how to pass data between the .NET user-mode application and Kernel PlugIn driver. If the application fails to open a handle to kp_pci (for example, if you did not install this driver), it will continue to perform all communication with the device, including interrupt handling and handling of Plug and Play and power management events, from the user mode. This structure enables you to first test the communication with the device solely from the user mode, and then easily port functionality from the user mode to the kernel by simply installing the kp_pci Kernel PlugIn driver. Interrupt Notes ---------------- 1. The sample Kernel PlugIn interrupt handler clears each interrupt at HIGH IRQL, and performs deferred processing and notifies the user-mode once for every 5 interrupts. 2. As documented in the code, the commands for acknowledging the interrupt are hardware-specific. Therefore, to use this sample to handle the interrupts on your device, you must first modify the code to implement the correct commands for acknowledging the interrupts. When using kp_pci to handle the interrupts, change the implementation of KP_PCI_IntAtIrql() (in kp_pci.c) in order to correctly acknowledge the interrupt on your device. When handling interrupts without a Kernel PlugIn driver, change the code in EnableInterrupts() and CreateIntTransCmds() (in PCI_Device.cs) and set up the correct transfer commands for clearing the interrupt, as indicated by the comments in these functions. 2. pci_sample/ Files ================== This section describes the sub-directories and files provided under the csharp.net\pci_sample\ directory. - readme.txt: Describes the contents of the csharp.net\pci_sample\ directory. - Visual Studio solution files for building the pci_lib library, kp_pci Kernel PlugIn driver and pci_sample application: For x86 32-bit platforms: ------------------------- - x86\ subdirectory - msdev_20xx\ subdirectory - pci_sample.sln Visual Studio 20xx C# solution file. For AMD64 64-bit platforms: ------------------------- - amd64\ subdirectory - msdev_20xx\ subdirectory - pci_sample.sln Visual Studio 20xx C# solution file. - lib\ sub-directory: ------------------- This directory contains the source code of the pci_lib.dll library, as well as project files for building the library: For all Windows platforms: -------------------------- - PCI_Device.cs: C# source file. Implements a PCI device class. - PCI_DeviceList.cs: C# source file. Implements the library's driver module. - PCI_Regs.cs: C# source file. Implements a register struct and an array of configuration space registers. - log.cs: C# source file. Implements a log class for the library's error and trace messages. - diag\ sub-directory: -------------------- This directory contains the pci_sample.exe sample application, as well as its source code and project files for building the code: For all Windows platforms: -------------