MSI MS-9656- User Manual

CONTENTS 12 B.8.17 WD_LogAdd() . . . . . . . . . . . . . . . . . . . . . . . . 376 B.9 WinDriver Status Codes . . . . . . . . . . . . . . . . . . . . . . . 377 B.9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 377 B.9.2 Status Codes Returned by WinDriver . . . . . . . . . . . . 37...

List of Figures 1.1 WinDriver Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 19 2.1 Monolithic Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 2.2 Layered Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 2.3 Miniport Drivers . . . . . . . . . . . ...

Chapter 1 WinDriver Overview In this chapter you will explore the uses of WinDriver, and learn the basic steps ofcreating your driver. NOTE This manual outlines WinDriver’s support for PCI / PCMCIA / CardBus / ISA /EISA / CompactPCI / PCI Express devices. WinDriver also supports the UniversalSerial ...

1.2 Background 15 with the features that WinDriver offers to the advanced user. However, mostdevelopers will find that reading this chapter and glancing through the DriverWizardand function reference chapters is all they need to successfully write their driver. WinDriver supports development for all...

1.2 Background 16 1.2.2 The WinDriver Solution Easy Development: WinDriver enables Windows, Windows CE, Linux and Solaris programmers to create PCI/PCMCIA/CardBus/ISA/EISA/CompactPCI/PCIExpress based device drivers in an extremely short time. WinDriver allowsyou to create your driver in the familiar...

1.5 WinDriver Benefits 18 1.5 WinDriver Benefits • Easy user-mode driver development. • Kernel PlugIn for high-performance drivers. • Friendly DriverWizard allows hardware diagnostics without writing a single line of code. • Automatically generates the driver code for the project in C, C#, Delphi (P...

1.6 WinDriver Architecture 19 1.6 WinDriver Architecture Figure 1.1: WinDriver Architecture

1.7 What Platforms Does WinDriver Support? 20 For hardware access, your application calls one of the WinDriver user-modefunctions. The user-mode function calls the WinDriver kernel, which accesses thehardware for you through the native calls of the operating system. WinDriver’s design minimizes perf...

1.8 Limitations of the Different Evaluation Versions 21 1.8 Limitations of the Different Evaluation Versions All the evaluation versions of WinDriver are full featured. No functions are limited orcrippled in any way. The evaluation version of WinDriver varies from the registeredversion in the follow...

1.10 What Does the WinDriver Toolkit Include? 22 1.9.2 On Windows CE 1. Plug your hardware into a Windows host machine. 2. Diagnose your hardware using DriverWizard. 3. Let DriverWizard generate your driver’s skeletal code. 4. Modify this code using eMbedded Visual C++ to meet your specific needs. I...

1.10 What Does the WinDriver Toolkit Include? 23 1.10.1 WinDriver Modules • WinDriver (WinDriver/include) – the general purpose hardware access toolkit. The main files here are: – windrvr.h: Declarations and definitions of WinDriver’s basic API. – wdc_lib.h and wdc_defs.h: Declarations and definitio...

1.10 What Does the WinDriver Toolkit Include? 24 1.10.2 Utilities • pci_dump.exe (WinDriver/util/pci_dump.exe) – used to obtain a dump of the PCI configuration registers of the installed PCI cards. • pci_diag.exe (WinDriver/util/pci_diag.exe) – used for reading/writing PCI configuration registers, a...

1.11 Can I Distribute the Driver Created with WinDriver? 25 1.10.4 Samples In addition to the samples provided for specific chipsets [ 1.10.3 ], WinDriver includes a variety of samples that demonstrate how to use WinDriver’s API to communicatewith your device and perform various driver tasks. • C sa...

Chapter 2 Understanding Device Drivers This chapter provides you with a general introduction to device drivers and takes youthrough the structural elements of a device driver. NOTE Using WinDriver, you do not need to familiarize yourself with the internal workingsof driver development. As explained ...

2.2 Classification of Drivers According to Functionality 27 2.2 Classification of Drivers According toFunctionality There are numerous driver types, differing in their functionality. This subsectionbriefly describes three of the most common driver types. 2.2.1 Monolithic Drivers Monolithic drivers a...

2.2 Classification of Drivers According to Functionality 28 2.2.2 Layered Drivers Layered drivers are device drivers that are part of a stack of device drivers thattogether process an I/O request. An example of a layered driver is a driver thatintercepts calls to the disk and encrypts/decrypts all d...

2.3 Classification of Drivers According to Operating Systems 29 Figure 2.3: Miniport Drivers Windows NT/2000/XP/Server 2003/Vista provide several driver classes (calledports) that handle the common functionality of their class. It is then up to theuser to add only the functionality that has to do wi...

2.3 Classification of Drivers According to Operating Systems 30 WDM drivers are PnP drivers that support power management protocols, and includemonolithic drivers, layered drivers and miniport drivers. 2.3.2 VxD Drivers VxD drivers are Windows 95/98/Me Virtual Device Drivers, often called VxDsbecaus...

2.4 The Entry Point of the Driver 31 2.3.5 Solaris Device Drivers Solaris device drivers are also based on the classic Unix device driver model. LikeLinux drivers, Solaris drivers may be either statically linked with the kernel ordynamically loaded and removed from the kernel. Like Unix and Linux de...

2.6 Communicating with Drivers 32 2.6 Communicating with Drivers A driver can create an instance, thus enabling an application to open a handle to thedriver through which the application can communicate with it.The applications communicate with the drivers using a file access API (ApplicationProgram...

Chapter 3 Installing WinDriver This chapter takes you through the process of installing WinDriver on yourdevelopment platform, and shows you how to verify that your WinDriver is properlyinstalled. The last section discusses the uninstall procedure. To find out how to installthe driver you create on ...

3.1 System Requirements 34 3.1.2 Windows CE System Requirements • An x86 / MIPS / ARM Windows Embedded CE v6.00 or Windows CE 4.x – 5.0 (.NET) target platformor:an ARMV4I Windows Mobile 5.0/6.0 target platform. • Windows 2000/XP/Server 2003/Vista host development platform. • For Windows CE 4.x – 5.0...

3.1 System Requirements 35 3.1.4 Solaris System Requirements • Solaris 8 / 9 / 10 / OpenSolaris. NOTE For Solaris 8 it is recommended to use update 3 or higher (available fromSun: http://www.sun.com ). • 64-bit or 32-bit kernel on SPARC platform OR32-bit kernel on x86 platform. • Any development env...

3.2 WinDriver Installation Process 36 3.2 WinDriver Installation Process The WinDriver CD contains all versions of WinDriver for all the different operatingsystems. The CD’s root directory contains the Windows 98/Me/2000/XP/Server2003/Vista and Windows CE version. This will automatically begin when ...

3.2 WinDriver Installation Process 38 3.2.2 Windows CE WinDriver Installation Instructions 3.2.2.1 Installing WinDriver CE when Building New CE-Based Platforms NOTES • The following instructions apply to platform developers who build Windows CE kernel images using Windows CE Platform Builder or usin...

3.2 WinDriver Installation Process 42 3.2.3 Linux WinDriver Installation Instructions 3.2.3.1 Preparing the System for Installation In Linux, kernel modules must be compiled with the same header files that thekernel itself was compiled with. Since WinDriver installs the kernel modulewindrvr6.o/.ko, ...

3.2 WinDriver Installation Process 45 12. Select the Register WinDriver option from the File menu and insert the license string you received from Jungo. 13. Click the Activate License button. 14. To register source code that you developed during the evaluation period, refer to the documentation of W...

3.2 WinDriver Installation Process 46 3.2.4 Solaris WinDriver Installation Instructions Installation of WinDriver should be performed by the system administrator loggedin as root, or with root privileges, since the WinDriver installation process includesinstallation of the kernel module windrvr6. 1....

3.3 Upgrading Your Installation 48 3.3 Upgrading Your Installation To upgrade to a new version of WinDriver on Windows, follow the steps outlinedin section 3.2.1 , which illustrate the process of installing WinDriver for Windows 98/Me/2000/XP/Server 2003/Vista. You can either choose to overwrite the...

3.4 Checking Your Installation 49 3.4 Checking Your Installation 3.4.1 Windows, Linux and Solaris Installation Check 1. Start DriverWizard: On Windows, by choosing Programs | WinDriver | DriverWizard fromthe Start menu, or using the shortcut that is automatically created on yourDesktop. A third opti...

3.5 Uninstalling WinDriver 50 3.5 Uninstalling WinDriver This section will help you to uninstall either the evaluation or registered version ofWinDriver. 3.5.1 Windows WinDriver Uninstall Instructions NOTES • For Windows 98/Me, replace references to wdreg below with wdreg16. • For Windows 2000/XP/Se...

3.5 Uninstalling WinDriver 51 4. Uninstall WinDriver: • On the development PC, on which you installed the WinDriver toolkit: Run Start | WinDriver | Uninstall, OR run the uninstall.exe utility fromthe WinDriver \ installation directory. The uninstall will stop and unload the WinDriver kernel module(...

3.5 Uninstalling WinDriver 53 3.5.2 Linux WinDriver Uninstall Instructions NOTE You must be logged in as root to perform the uninstall procedure. 1. Verify that the WinDriver module is not being used by another program: • View a list of modules and the programs using each of them: /# /sbin/lsmod • C...

3.5 Uninstalling WinDriver 54 3.5.3 Solaris WinDriver Uninstall Instructions NOTE You must be logged in as root to perform the uninstall procedure. 1. Make sure no programs are using WinDriver. 2. If you created a Kernel PlugIn driver, remove it by following these steps: (a) # /usr/sbin/rem_drv kpna...

Chapter 4 Using DriverWizard This chapter describes WinDriver DriverWizard’s hardware diagnostics and drivercode generation capabilities. NOTE CardBus devices are handled via WinDriver’s PCI API, therefore any references toPCI in this chapter also include CardBus. 4.1 An Overview DriverWizard (inclu...

4.2 DriverWizard Walkthrough 56 have to be modified according to the specific functionality of the device in question.Preferably, use the complete source code libraries and sample applications (suppliedin the package) tailored to the various PCI chipsets. DriverWizard is an excellent tool for two ma...

4.2 DriverWizard Walkthrough 59 Figure 4.3: DriverWizard INF File Information (b) DriverWizard will display information detected for your device – Vendor ID, Device ID, Device Class, manufacturer name and devicename – and allow you to modify the manufacturer and device namesand the device class info...

4.3 DriverWizard Notes 64 Figure 4.9: Code Generation Options 4.3 DriverWizard Notes 4.3.1 Sharing a Resource If you want more than one driver to share a single resource, you must define thatresource as shared: 1. Select the resource. 2. Right click on the resource. 3. Select Share from the menu.

4.3 DriverWizard Notes 65 Figure 4.10: Additional Driver Options NOTE New interrupts are set as Shared by default. If you wish to define an interrupt asunshared, follow Steps 1 and 2 , and select Unshared in Step 3 . 4.3.2 Disabling a Resource During your diagnostics, you may wish to disable a resou...

4.3 DriverWizard Notes 66 input and output during the diagnostics stage, so that you may analyze your device’sphysical performance at a later time. You can save the log for future reference. Whensaving the project, your log is saved as well. Each log is associated with one project. 4.3.5 Automatic C...

4.3 DriverWizard Notes 67 • A diagnostics program that utilizes the generated DriverWizard API (declared in xxx_lib.h) to communicate with your device(s): xxx_diag.c The source code of the generated diagnostics console application. Use this diagnostics program as your skeletal device driver. • A lis...

4.3 DriverWizard Notes 68 NOTES • For Windows 98/Me/2000/XP/Server 2003/Vista, the generated IDE files are located under an x86 \ directory – for 32-bit projects, or amd64 \ directory – for 64-bit projects. • For Windows CE, note that the generated Windows Mobile code is targeted at the Windows Mobi...

Chapter 5 Developing a Driver This chapter takes you through the WinDriver driver development cycle. NOTE If your device is based on one of the chipsets for which WinDriver providesenhanced support (PLX 9030, 9050, 9052, 9054, 9056, 9080 and 9656; Alterapci_dev_kit; Xilinx VirtexII and Virtex 5; AMC...

5.2 Writing the Device Driver Without the DriverWizard 70 • Use any C / .NET / Delphi / Visual Basic compiler (such as MSDEV/Visual C/C++, MSDEV .NET, Borland C++ Builder, Borland Delphi, Visual Basic6.0, MS eMbedded Visual C++, MS Platform Builder C++, GCC, etc.) tocompile the skeletal driver you n...

5.2 Writing the Device Driver Without the DriverWizard 71 3. Link your code with the wdapi920 library/shared object: • For Windows 98/Me/2000/XP/Server 2003/Vista: WinDriver \ lib \ <CPU> \ wdapi920.lib or wdapi920_borland.lib (for Borland C++ Builder), where the <CPU> directory is eithe...

5.3 Developing Your Driver on Windows CE Platforms 72 the device, which you can later use to communicate with the device using the WDC_xxx API. 5. Communicate with the device using the WDC_xxx API (see description in Appendix B ). To enable interrupts, call WDC_IntEnable() [ B.3.43 ]. To register to...

5.4 Developing in Visual Basic and Delphi 73 5.4 Developing in Visual Basic and Delphi The entire WinDriver API can be used when developing drivers in Visual Basic andDelphi. 5.4.1 Using DriverWizard DriverWizard can be used to diagnose your hardware and verify that it is workingproperly before you ...

Chapter 6 Debugging Drivers The following sections describe how to debug your hardware access applicationcode. 6.1 User-Mode Debugging • Since WinDriver is accessed from the user mode, we recommend that you first debug your code using your standard debugging software. • The Debug Monitor utility [ 6...

6.2 Debug Monitor 75 6.2 Debug Monitor Debug Monitor is a powerful graphical- and console-mode tool for monitoring allactivities handled by the WinDriver kernel (windrvr6.sys/.dll/.o/.ko).You can use this tool to monitor how each command sent to the kernel is executed.In addition, WinDriver enables ...

6.2 Debug Monitor 77 • Level – Choose the level of messages you want to see for the resources defined. Error is the lowest trace level, resulting in minimum output to the screen. Trace is the highest trace level, displaying every operation the WinDriver kernel performs. • Select the Send debug messa...

6.2 Debug Monitor 78 6.2.2 Using the Debug Monitor in Console Mode – wddebug The Debug Monitor utilitycomes in a console-mode version – WinDriver/util/wddebug – which is availablefor all supported operating systems. To use the wddebug console-mode version of the Debug Monitor utility on Windows98/Me...

6.2 Debug Monitor 79 – dbg_off : Stop redirecting debug messages from the Debug Monitor to a kernel debugger. NOTE The on and dbg_on commands can be run together with the level and/or sections options described below. • dump : Continuously display (”dump”) debug information until the user presses Es...

Chapter 7 Enhanced Support for SpecificChipsets 7.1 Overview In addition to the standard WinDriver API and the DriverWizard code generationcapabilities described in this manual, which support development of drivers for anyPCI/ISA/PCMCIA/CardBus device, WinDriver offers enhanced support for specificP...

7.2 Developing a Driver Using the Enhanced Chipset Support 82 7.2 Developing a Driver Using the Enhanced ChipsetSupport When developing a driver for a device based on one of the enhanced-supportchipsets [ 7.1 ], you can use WinDriver’s chipset-set specific support by following these steps: 1. Locate...

Chapter 8 PCI Express 8.1 PCI Express Overview The PCI Express (PCIe) bus architecture (formerly 3GIO or 3rd Generation I/O) wasintroduced by Intel, in partnership with other leading companies, including IBM,Dell, Compaq, HP and Microsoft, with the intention that it will become the prevailingstandar...

8.1 PCI Express Overview 84 The increased bandwidth support makes PCI Express ideal for the growing number ofdevices that require high bandwidth, such as hard drive controllers, video streamingdevices and networking cards. The usage of a switch to control the data flow in the PCI Express bus, as exp...

8.2 WinDriver for PCI Express 85 8.2 WinDriver for PCI Express WinDriver fully supports backward compatibility with the standard PCI features onPCI Express boards. The wide support provided by WinDriver for the standard PCIbus – including a rich set of APIs, code samples and the graphical DriverWiza...

Chapter 9 Advanced Issues This chapter covers advanced driver development issues and contains guidelinesfor using WinDriver to perform tasks that cannot be fully automated by theDriverWizard. Note that WinDriver’s enhanced support for specific chipsets [ 7 ] includes custom APIs for performing hardw...

9.1 Performing Direct Memory Access (DMA) 88 9.1.1.1 Sample Scatter/Gather DMA Implementation BOOL DMARoutine(WDC_DEVICE_HANDLE hDev, DWORD dwBufSize, UINT32 u32LocalAddr, DWORD dwOptions, BOOL fPolling, BOOL fToDev) { PVOID pBuf; WD_DMA *pDma = NULL; BOOL fRet = FALSE; /* Allocate a user-mode buffe...

9.1 Performing Direct Memory Access (DMA) 90 9.1.1.2 What Should You Implement? In the code sample above, it is up to you to implement the following MyDMAxxx() routines, according to your device’s specification • MyDMAProgram() : Program the device’s DMA registers. Refer the device’s datasheet for t...

9.1 Performing Direct Memory Access (DMA) 91 9.1.2.1 Sample Contiguous Buffer DMA Implementation BOOL DMARoutine(WDC_DEVICE_HANDLE hDev, DWORD dwDMABufSize, UINT32 u32LocalAddr, DWORD dwOptions, BOOL fPolling, BOOL fToDev) { PVOID pBuf = NULL; WD_DMA *pDma = NULL; BOOL fRet = FALSE; /* Allocate a DM...

9.1 Performing Direct Memory Access (DMA) 93 9.1.2.2 What Should You Implement? In the code sample above, it is up to you to implement the following MyDMAxxx() routines, according to your device’s specification • MyDMAProgram() : Program the device’s DMA registers. Refer the device’s datasheet for t...

9.2 Handling Interrupts 94 9.2 Handling Interrupts WinDriver provides you with API, DriverWizard code generation, and samples, tosimplify the task of handling interrupts from your driver. If you are developing a driver for a device based on one of the enhanced-supportWinDriver chipsets [ 7 ], we rec...

9.2 Handling Interrupts 96 9.2.2 WinDriver Interrupt Handling Sequence NOTE This section describes how to use WinDriver to handle interrupts from a user-modeapplication. Since interrupt handling is a performance-critical task, it is very likelythat you may want to handle the interrupts directly in t...

9.2 Handling Interrupts 98 9.2.4 Determining the Interrupt Type Enabled for a PCI Card When attempting to enable interrupts for a PCI card on Linux or Windows Vista,WinDriver first tries to use MSI-X or MSI, if supported by the card. If this fails,WinDriver attempts to enable legacy level sensitive ...

9.2 Handling Interrupts 102 [ I n s t a l l . NT .HW] AddReg = I n s t a l l . NT .HW. AddReg [ I n s t a l l . NT .HW. AddReg ] HKR , " I n t e r r u p t M a n a g e m e n t " , 0 x 0 0 0 0 0 0 1 0HKR , " I n t e r r u p t M a n a g e m e n t \ M e s s a g e S i g n a l e d I n t e r r ...

9.2 Handling Interrupts 104 interrupt_handler, (PVOID)hDev, FALSE); /* WDC_IntEnable() allocates and initializes the required WD_INTERRUPT structure, stores it in the WDC_DEVICE structure, then calls InterruptEnable(), which calls WD_IntEnable() and creates an interrupt handler thread */ if (WD_STAT...

9.3 Byte Ordering 107 9.3 Byte Ordering 9.3.1 Introduction to Endianness There are two main architectures for handling memory storage. They are calledBig Endian and Little Endian and refer to the order in which the bytes are stored inmemory. • Big endian means that the most significant byte of any m...

9.3 Byte Ordering 108 9.3.3 Macros for PCI Target Access WinDriver’s macros for PCI target access are used for converting endianness whilereading/writing from/to PCI cards using memory mapped ranges of PCI devices. NOTE These macro definitions apply to Linux PowerPC architecture. • dtoh16 - Macro de...

9.3 Byte Ordering 109 9.3.4 Macros for PCI Master Access WinDriver’s macros for PCI master access are used for converting endianness of datain host memory that is accessed by the PCI master device, i.e. in cases of access thatis initiated by the device rather than the host. NOTE These macro definiti...

Chapter 10 Improving Performance 10.1 Overview Once your user-mode driver has been written and debugged, you might find thatcertain modules in your code do not operate fast enough (for example: an interrupthandler or accessing I/O-mapped regions). If this is the case, try to improveperformance in on...

10.1 Overview 111 10.1.1 Performance Improvement Checklist The following checklist will help you determine how to improve the performance ofyour driver: Problem Solution ISA Card – accessing anI/O-mapped range on the card When transferring a large amount of data, use block(string) transfers and/or g...

10.2 Improving the Performance of a User-Mode Driver 112 10.2 Improving the Performance of a User-ModeDriver As a general rule, transfers to memory-mapped regions are faster than transfers toI/O-mapped regions, because WinDriver enables you to access memory-mappedregions directly from the user mode,...

10.2 Improving the Performance of a User-Mode Driver 113 Whatever the method you select to access the memory on your card, it is important toalign the base address according to the size of the data type, especially when issuingstring transfer commands. Otherwise, the transfers are split into smaller...

11.2 Do I Need to Write a Kernel PlugIn Driver? 116 • The parts of the code that will run in the kernel through the Kernel PlugIn are platform independent and therefore will run on every platform supported byWinDriver and the Kernel PlugIn. A standard kernel-mode driver will run onlyon the platform ...

11.5 The Kernel PlugIn Architecture 117 11.5 The Kernel PlugIn Architecture 11.5.1 Architecture Overview A driver written in user mode uses WinDriver’s API ( WDC_xxx and/or WD_xxx [ B.2 ]) to access devices. If a certain function that was implemented in the user moderequires kernel performance (the ...

11.5 The Kernel PlugIn Architecture 118 11.5.2 WinDriver’s Kernel and Kernel PlugIn Interaction There are two types of interaction between the WinDriver kernel and the WinDriverKernel PlugIn: Interrupt handling: When WinDriver receives an interrupt, by default it will activate the caller’s user-mode...

11.5 The Kernel PlugIn Architecture 119 11.5.4 Kernel PlugIn Event Sequence The following is a typical event sequence that covers all the functions that you canimplement in your Kernel PlugIn: 11.5.4.1 Opening Handle from the User Mode to a Kernel PlugIn Driver Event/Callback Notes Event: Windows lo...

11.6 How Does Kernel PlugIn Work? 122 Event/Callback Notes Event: A Plug and Play or power managementevent (to which the application registered tolisten) occurs.Callback: Your KP_Event() Kernel PlugIn routine [ B.6.5 ] is called. KP_Event() receives information about the event that occurred and can ...

11.6 How Does Kernel PlugIn Work? 123 NOTE While this is not a minimal requirement, when developing a Kernel PlugIn driverit is highly recommended that you use two computers: set up one computer asyour host platform and the other as your target platform. The host computer is thecomputer on which you...

11.6 How Does Kernel PlugIn Work? 129 if (!pAddrDesc) goto malloc_error; COPY_FROM_USER(pAddrDesc, pDev->pAddrDesc, dwSize); pDev->pAddrDesc = pAddrDesc; *ppDrvContext = pDev; KP_PCI_Trace("KP_PCI_Open: Kernel PlugIn driver opened successfully\n"); return TRUE; malloc_error: KP_PCI_Err...

11.6 How Does Kernel PlugIn Work? 131 11.6.4 Kernel PlugIn Sample/Generated Code DirectoryStructure 11.6.4.1 pci_diag and kp_pci Sample Directories The Kernel PlugIn sample code – KP_PCI – is implemented in the kp_pci.c file.This sample driver is part of the WinDriver PCI diagnostics sample – pci_di...

11.6 How Does Kernel PlugIn Work? 133 11.6.4.2 The Generated DriverWizard Kernel PlugIn Directory The generated DriverWizard Kernel PlugIn code for your device will include akernel-mode Kernel PlugIn project and a user-mode application that communicateswith it. As opposed to the generic KP_PCI and p...

11.6 How Does Kernel PlugIn Work? 134 • xxx_diag.c: Implementation of a sample diagnostics user-mode console (CUI) application, which demonstrates communication your device using the xxx_liband WDC libraries.The application also demonstrates how to communicate with a Kernel PlugIndriver from a user-...

11.6 How Does Kernel PlugIn Work? 135 returns TRUE . The return value of KP_IntAtDpc() determines how many times (if at all) the user-mode interrupt handler routine will be executed.In the KP_PCI sample, for example, the Kernel PlugIn interrupt handler code countsfive interrupts and notifies the use...

11.6 How Does Kernel PlugIn Work? 136 11.6.5.2 Interrupt Handling in the Kernel (Using a Kernel PlugIn) To have the interrupts handled by the Kernel PlugIn, the user-mode applicationshould open a handle to the device with a Kernel PlugIn driver, by passing the nameof a Kernel PlugIn driver to the WD...

11.6 How Does Kernel PlugIn Work? 137 If the Kernel PlugIn interrupt handler is enabled, then KP_IntAtIrql() [ B.6.8 ] for each incoming interrupt. The code in the KP_IntAtIrql() function is executed at high interrupt request level. While this code is running, the system is halted, i.e.,there will b...

11.6 How Does Kernel PlugIn Work? 138 11.6.6 Message Passing The WinDriver architecture enables a kernel-mode function to be activated from theuser mode by passing a message from the user mode to the Kernel PlugIn driver using WDC_CallKerPlug() [ B.3.17 ] or the low-level WD_KernelPlugInCall() funct...

Chapter 12 Writing a Kernel PlugIn The easiest way to write a Kernel PlugIn driver is to use DriverWizard to generatethe Kernel PlugIn code for your hardware (see sections 11.6.3 and 11.6.4.2 ). Alternatively, you can use the sample KP_PCI PCI Kernel PlugIn driver, found underthe WinDriver/samples/p...

12.2 Prepare the User-Mode Source Code 140 12.2 Prepare the User-Mode Source Code 1. Isolate the functions you need to move into the Kernel PlugIn. 2. Remove any platform-specific code from the functions. Use only functions that can also be used from the kernel. 3. Recompile your driver in the user ...

12.4 Create a Handle to the Kernel PlugIn 141 2. Change all instances of ”KP_PCI” and ”kp_pci” in all the Kernel PlugIn files in your new directory to ”KP_MyDrv” and ”kp_mydrv” (respectively).Note: The names of the KP_PCI_xxx() functions in the kp_pci.c files do not have to be changed in order for t...

12.5 Set Interrupt Handling in the Kernel PlugIn 142 XXX_DeviceOpen() / PCI_DeviceOpen() library function (which is called from the generated/sample xxx_diag/pci_diag user-mode application.) If you are not using the WDC library from your code [ B.2 ], you need to call WD_KernelPlugInOpen() at the be...

12.6 Set I/O Handling in the Kernel PlugIn 143 3. Move the implementation of the user-mode interrupt handler, or the relevant portions of this implementation, to the Kernel PlugIn’s interrupthandler functions. High-priority code, such as the code for acknowledging(clearing) level sensitive interrupt...

12.7 Compile Your Kernel PlugIn Driver 144 12.7 Compile Your Kernel PlugIn Driver 12.7.1 On Windows The sample WinDriver \ samples \ pci_diag \ kp_pci Kernel PlugIn directory and the generated DriverWizard Kernel PlugIn <project_dir> \ kermode directory (where <project_dir> is the direct...

12.7 Compile Your Kernel PlugIn Driver 147 12.7.2 On Linux 1. Open a shell terminal. 2. Change directory to your Kernel PlugIn directory. For example, when compiling the sample KP_PCI driver, run: cd WinDriver/samples/pci_diag/kp_pci When compiling the Kernel PlugIn driver for your generated DriverW...

12.7 Compile Your Kernel PlugIn Driver 148 12.7.3 On Solaris NOTE WinDriver generates makefiles for GNU make utility only. If you wish to use the standard make utility, instead of the GNU make, youmust modify the makefile that WinDriver generates. The GNU make package isavailable from http://www.sun...

12.8 Install Your Kernel PlugIn Driver 149 12.8 Install Your Kernel PlugIn Driver 12.8.1 On Windows 1. Copy the driver file (xxx.sys) to the target platform’s drivers directory: %windir% \ system32 \ drivers (e.g., C: \ WINNT \ system32 \ drivers – on Windows 2000, or C: \ Windows \ system32 \ drive...

12.8 Install Your Kernel PlugIn Driver 150 represents the path to your generated DriverWizard project directory (e.g./home/user/WinDriver/wizard/my_projects/my_kp/): cd <path>/kermode/ 2. Run the following command to install your Kernel PlugIn driver: make install 12.8.3 On Solaris NOTE Instal...

12.8 Install Your Kernel PlugIn Driver 151 4. Copy your Kernel PlugIn driver to the target’s drivers directory. For example to copy the sample KP_PCI driver: On 64-bit platforms run: # cp kp_pci /kernel/drv/sparcv9 On 32-bit platforms run: # cp kp_pci /kernel/drv 5. Install the driver by running: # ...

13.2 Windows Dynamic Driver Loading 153 13.2 Windows Dynamic Driver Loading 13.2.1 Windows Driver Types Windows drivers can be implemented as either of the following types: • WDM (Windows Driver Model) drivers: Files with the extension .sys on Windows 98/Me/2000/XP/Server 2003/Vista (e.g. windrvr6.s...

13.2 Windows Dynamic Driver Loading 155 Usage: The wdreg utility can be used in two ways as demonstrated below: 1. wdreg -inf <filename> [-silent] [-log <logfile>] [install | uninstall | enable | disable] 2. wdreg -rescan <enumerator> [-silent] [-log <logfile>] • OPTIONS wdre...

13.2 Windows Dynamic Driver Loading 156 13.2.2.2 Non-WDM Drivers This section explains how to use the wdreg utility to install non-WDM drivers,namely Kernel PlugIn drivers, on Windows 98/Me/2000/XP/Server 2003/Vista. Usage: wdreg [-file <filename>] [-name <drivername>] [-startup <leve...

13.2 Windows Dynamic Driver Loading 158 NOTE Note that in order to successfully stop a driver, there cannot be any openhandles to the driver (such as open applications that use the driver). This isalso true for the install and uninstall shortcuts, since both commands includestopping the driver. 13.2...

13.2 Windows Dynamic Driver Loading 159 13.2.4 Dynamically Loading/Unloading Your Kernel PlugInDriver If you have used WinDriver to develop a Kernel PlugIn driver, you must load yourKernel PlugIn after loading the WinDriver generic driver windrvr6.sys.When uninstalling your driver, you should unload...

13.3 Linux Dynamic Driver Loading 160 13.3 Linux Dynamic Driver Loading • To dynamically load WinDriver on Linux, execute: /sbin/modprobe windrvr6 • To dynamically unload WinDriver, execute: /sbin/rmmod windrvr6 • You can also use the wdreg script from the WinDriver/util/ directory to install (load)...

13.5 Windows Mobile Dynamic Driver Loading 161 13.5 Windows Mobile Dynamic Driver Loading The WinDriver \ redist \ Windows_Mobile_5_ARMV4I \ wdreg.exe utility can be used for loading the WinDriver kernel module (windrvr6.dll) on a Windows Mobileplatform. TIP On Windows Mobile the operating system’s ...

Chapter 14 Distributing Your Driver Read this chapter in the final stages of driver development. It will guide you inpreparing your driver for distribution. 14.1 Getting a Valid License for WinDriver To purchase a WinDriver license, complete the WinDriver/docs/order.pdf orderform and fax or email it...

14.2 Windows Driver Distribution 163 14.2 Windows Driver Distribution NOTES • For Windows 2000/XP/Server 2003/Vista, all references to wdreg in this section can be replaced with wdreg_gui, which offers the same functionalitybut displays GUI messages instead of console-mode messages.For Windows 98/Me...

14.2 Windows Driver Distribution 164 Distributing the driver you created is a multi-step process. First, create a distributionpackage that includes all the files required for the installation of the driver on thetarget computer. Second, install the driver on the target machine. This involvesinstalli...

14.2 Windows Driver Distribution 165 14.2.2 Installing Your Driver on the Target Computer NOTE The user must have administrative privileges on the target computer in order toinstall your driver. Follow the instructions below in the order specified to properly install your driver onthe target compute...

14.2 Windows Driver Distribution 166 • Install WinDriver’s kernel module: 1. Copy windrvr6.sys, windrvr6.inf and wd920.cat to the same directory. NOTE wd920.cat contains the driver’s Authenticode digital signature forWindows 2000/XP/Server 2003/Vista. In order to maintain thesignature’s validity thi...

14.2 Windows Driver Distribution 168 • Install wdapi920.dll: If your hardware control application/DLL uses wdapi920.dll (as is the case forthe sample and generated DriverWizard WinDriver projects), copy this DLL tothe target’s %windir% \ system32 directory. If you are distributing a 32-bit applicati...

14.3 Windows CE Driver Distribution 169 usage, please refer to Chapter 13 (see specifically section 13.2.4 for Kernel PlugIn installation). 14.3 Windows CE Driver Distribution 14.3.1 Distribution to New Windows CE Platforms NOTE The following instructions apply to platform developers who build Windo...

14.3 Windows CE Driver Distribution 171 5. Select Make Run-Time Image from the Build menu and name the new image NK.BIN. 6. Download your new kernel to the target platform and initialize it either by selecting Download/Initialize from the Target menu or by using a floppy disk. 7. Restart your target...

14.4 Linux Driver Distribution 172 3. Restart your target CE computer. The WinDriver CE kernel will automatically load. You will have to do a warm reset rather than just suspend/resume (use thereset or power button on your target CE computer). 4. Install your hardware control application/DLL on the ...

14.4 Linux Driver Distribution 173 is used for kernels compiled with GCC v2.x.x, and windrvr_gcc_v3.a is usedfor kernels compiled with GCC v3.x.x. windrvr_gcc_v3_regparm.a is usedfor kernels compiled with GCC v3.x.x with the regparm flag. • linux_wrappers.c/h: wrapper library source code files that ...

14.4 Linux Driver Distribution 174 wish to protect your source code from unauthorized copying) or as source code. Notethat under the license agreement with Jungo you may not distribute the source code ofthe libwdapi920.so shared object. CAUTION! If you select to distribute your source code, make sur...

14.5 Solaris Driver Distribution 175 14.5 Solaris Driver Distribution NOTE If you have renamed the WinDriver kernel module (windrvr6), as explained insection 15.2 , replace the relevant windrvr6 and windrvr references with the name of your driver, and replace references to the WinDriver redist/ and ...

15.1 INF Files – Windows 98/Me/2000/XP/Server 2003/Vista 177 15.1.1 Why Should I Create an INF File? • To stop the Windows Found New Hardware Wizard from popping up after each boot. • To ensure that the operating system can initialize the PCI configuration registers on Windows 98/Me/2000/XP/Server 2...

15.1 INF Files – Windows 98/Me/2000/XP/Server 2003/Vista 179 15.1.3 How Do I Replace an Existing Driver Using the INF File? NOTE You must have administrative privileges in order to replace a driver on Windows98/Me/2000/XP/Server 2003/Vista. 1. On Windows 2000, if you wish to upgrade the driver for P...

15.2 Renaming the WinDriver Kernel Driver 181 15.2 Renaming the WinDriver Kernel Driver The WinDriver APIs are implemented within the windrvr6.sys/.dll/.o/.ko kerneldriver module (depending on the OS), which provides the main driver functionalityand enables you to code your specific driver logic fro...

15.2 Renaming the WinDriver Kernel Driver 185 3. Verify that your application calls the WD_DriverName() function [ B.1 ] with your new driver name before calling any other WinDriver function.Note that the sample and generated DriverWizard WinDriver applicationsalready include a call to this function...

15.2 Renaming the WinDriver Kernel Driver 187 build method relies on the existence of these directories directly under the sameparent directory as the redist/ directory. 3. Verify that your application calls the WD_DriverName() function [ B.1 ] with your new driver name before calling any other WinD...

15.2 Renaming the WinDriver Kernel Driver 188 directory with the following files and directories: • redist/ directory: This directory provides modified versions of the files from the original WinDriver/redist directory – i.e. the windrvr6 kernelmodule and windrvr6.conf installation file – which have...

15.3 Digital Driver Signing & Certification – Windows 2000/XP/Server 2003/Vista 191 15.3.2 Driver Signing & Certification of WinDriver-BasedDrivers As indicated above [ 15.3.1.1 ], The WinDriver \ redist \ windrvr6.sys driver has an Authenticode signature. Since WinDriver’s kernel module (wi...

15.3 Digital Driver Signing & Certification – Windows 2000/XP/Server 2003/Vista 192 (or your renamed driver) and any INF files used in your driver’sinstallation. – Assign the name of your new catalog file to the CatalogFile entry in your driver’s INF file(s). (You can either change the CatalogFi...

15.4 Windows XP Embedded WinDriver Component 193 • The tests submission requires you to provide a *.pdb debug symbol file and an ouput of the PREfast utility (defects.xml). You can find copies of these filesfor the windrvr6.sys driver in the WinDriver \ redist directory. When selecting to rename and...

Appendix A 64-bit Operating SystemsSupport A.1 Supported 64-bit Architectures WinDriver supports the following 64-bit platforms: • Solaris SPARC 64-bit. For a full list of Solaris platforms supported by WinDriver, refer tosection 3.1.4 . • Linux AMD64 or Intel EM64T (x86_64). For a full list of the ...

Appendix B API Reference NOTE This function reference is C oriented. The WinDriver .NET, Visual Basic andDelphi APIs have been implemented as closely as possible to the C APIs, therefore.NET, VB and Delphi programmers can also use this reference to better understandthe WinDriver APIs for their selec...

B.2 WDC Library Overview 200 B.2 WDC Library Overview The "WinDriver Card" – WDC – API provides convenient user-mode wrappers to thebasic WinDriver PCI/ISA/PCMCIA/CardBus WD_xxx API, which is described in the WinDriver PCI Low-Level API Reference. The WDC wrappers are designed to simplify th...

B.3 WDC High Level API 201 B.3 WDC High Level API This section describes the WDC API defined in the WinDriver/include/wdc_lib.hheader file. B.3.1 Structures, Types and General Definitions B.3.1.1 WDC_DEVICE_HANDLE Handle to a WDC device information structure [ B.4.3 ] type: typedef void * WDC_DEVICE...

B.3 WDC High Level API 220 D E S C R I P T I O N Name Description phDev Pointer to a handle to the WDC device allocated by thefunction pDeviceInfo Pointer to a PCI device information structure [ B.5.12 ], which contains information regarding the device to open pDevCtx Pointer to device context infor...

B.3 WDC High Level API 227 B.3.12 WDC_PciDeviceClose() P U R P O S E • Un-initializes a WDC PCI device structure and frees the memory allocated for it. P ROTOT Y P E DWORD DLLCALLCONV W D C _ P c i D e v i c e C l o s e ( WDC_DEVICE_HANDLE hDev ) ; P A R A M E T E R S Name Type Input/Output ➢ hDev W...

B.3 WDC High Level API 231 P A R A M E T E R S Name Type Input/Output ➢ hDev WDC_DEVICE_HANDLE Input ➢ Cmd WD_TRANSFER* Input ➢ dwCmds DWORD Input ➢ bForceCleanup BOOL Input D E S C R I P T I O N Name Description hDev Handle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI [ B.3.9 ] / PCMCIA [ ...

B.3 WDC High Level API 233 R E M A R K S • Normally you do not need to call this function, since you can open a handle to a Kernel PlugIn driver when opening the handle to your device, as explainedin the description of the WDC_xxxDeviceOpen() functions (PCI [ B.3.9 ] / PCMCIA [ B.3.10 ] / ISA [ B.3....

B.3 WDC High Level API 268 R E M A R K S • When calling this function you do not need to set the DMA_KERNEL_BUFFER_ALLOC flag, since the function sets this flag automatically. • This function is currently only supported from the user mode. • On Solaris x86 platforms, for an allocation of a Contiguou...

B.3 WDC High Level API 276 B.3.43 WDC_IntEnable() P U R P O S E • Enables interrupt handling for the device. • If the caller selects to handle the interrupts in the kernel, using a Kernel PlugIndriver, the Kernel PlugIn KP_IntAtIrql() function [ B.6.8 ], which runs at high IRQ (Interrupt Request) le...

B.3 WDC High Level API 277 P A R A M E T E R S Name Type Input/Output ➢ hDev WDC_DEVICE_HANDLE Input ➢ pTransCmds WD_TRANSFER* Input ➢ dwNumCmds DWORD Input ➢ dwOptions DWORD Input ➢ funcIntHandler typedef void (*INT_HANDLER)( PVOID pData); Input ➢ pData PVOID Input ➢ fUseKP BOOL Input D E S C R I P...

B.3 WDC High Level API 283 Name Description fUseKP 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.6.5 ] will be called. (The Kernel PlugIn driver to be used for the deviceis passed to ...

B.3 WDC High Level API 290 B.3.52 WDC_GetWDHandle() P U R P O S E • Returns a handle to WinDriver’s kernel module, which is required by the basic WD_xxx WinDriver PCI/PCMCIA/ISA API, described in the WinDriver PCI Low-Level API Reference (see Remarks below). P ROTOT Y P E HANDLE DLLCALLCONV WDC_GetW...

B.4 WDC Low Level API 295 B.4 WDC Low Level API This section described the WDC types and preprocessor definitions defined in theWinDriver/include/wdc_defs.h header file. B.4.1 WDC_ID_U Union WDC device ID information union type (used for PCI and PCMCIA devices): Name Type Description ➢ pciId WD_PCI_...

B.5 WD_xxx Structures, Types and General Definitions 303 B.5 WD_xxx Structures, Types and GeneralDefinitions This section describes basic WD_xxx structures and types, which are used by the WDC_xxx APIs. The APIs described in this section are defined in the WinDriver/include/windrvr.h header file. B....

B.5 WD_xxx Structures, Types and General Definitions 318 Name Type Description ➢ dwPages DWORD Number of physical memory blocks used for theallocated buffer.For Contiguous Buffer DMA this field is always set to 1. ➢ hCard DWORD Low-level WinDriver card handle, which isacquired by WDC_xxxDeviceOpen()...

B.6 Kernel PlugIn Kernel-Mode Functions 321 B.6 Kernel PlugIn Kernel-Mode Functions The following functions are callback functions which are implemented in your KernelPlugIn driver, and which will be called when their calling event occurs. For example: KP_Init() [ B.6.1 ] is the callback function th...

B.6 Kernel PlugIn Kernel-Mode Functions 328 D E S C R I P T I O N Name Description pDrvContext Driver context data that was set by KP_Open() [ B.6.2 ] and will also be passed to KP_Close() [ B.6.3 ], KP_IntEnable() [ B.6.6 ] and KP_Event() [ B.6.5 ] kpCall Structure with user-mode information receiv...

B.6 Kernel PlugIn Kernel-Mode Functions 336 R E M A R K S • Code running at IRQL will only be interrupted by higher priority interrupts. • Code running at IRQL is limited by the following restrictions: – You may only access non-pageable memory. – You may only call the following functions (or wrapper...

B.6 Kernel PlugIn Kernel-Mode Functions 340 B.6.10 COPY_TO_USER_OR_KERNEL,COPY_FROM_USER_OR_KERNEL P U R P O S E • Macros for copying data from the user mode to the Kernel PlugIn and vice versa. R E M A R K S • The COPY_TO_USER_OR_KERNEL and COPY_FROM_USER_OR_KERNEL are macros used for copying data ...

B.6 Kernel PlugIn Kernel-Mode Functions 341 B.6.11 Kernel PlugIn Synchronization APIs This section describes the Kernel Plug-In synchronization APIs.These APIs support the following synchronization mechanisms: • Spinlocks [ B.6.11.2 – B.6.11.5 ], which are used to synchronize between threads on a si...

B.7 Kernel PlugIn Structure Reference 354 B.7 Kernel PlugIn Structure Reference This section contains detailed information about the different Kernel PlugIn relatedstructures. WD_XXX structures are used in user-mode functions and KP_XXX structures are used in kernel-mode functions. The Kernel PlugIn...

B.7 Kernel PlugIn Structure Reference 358 B.7.5 KP_OPEN_CALL This is the structure through which the Kernel PlugIn defines the names of itscallback functions (other than KP_Open() ). It is used from the KP_Open() [ B.6.2 ] Kernel PlugIn function, which sets the callbacks in the structure. A Kernel P...

B.8 User-Mode Utility Functions 360 B.8 User-Mode Utility Functions This section describes a number of user-mode utility functions you will find useful forimplementing various tasks. These utility functions are multi-platform, implementedon all operating systems supported by WinDriver. B.8.1 Stat2St...

B.9 WinDriver Status Codes 377 B.9 WinDriver Status Codes B.9.1 Introduction Most of the WinDriver functions return a status code, where zero( WD_STATUS_SUCCESS ) means success and a non-zero value means failure. The Stat2Str() functions can be used to retrieve the status description string for a gi...

B.9 WinDriver Status Codes 378 B.9.2 Status Codes Returned by WinDriver Status Code Description WD_STATUS_SUCCESS Success WD_STATUS_INVALID_WD_HANDLE Invalid WinDriver handle WD_WINDRIVER_STATUS_ERROR Error WD_INVALID_HANDLE Invalid handle WD_INVALID_PIPE_NUMBER Invalid pipe number WD_READ_WRITE_CON...

Appendix C Troubleshooting and Support Please refer to http://www.jungo.com/st/support/support_windriver. html for additional resources for developers, including: • Technical documents • FAQs • Samples • Quick start guides 379

Appendix D Evaluation Version Limitations D.1 Windows WinDriver Evaluation Limitations • Each time WinDriver is activated, an Unregistered message appears. • When using DriverWizard, a dialogue box with a message stating that an evaluation version is being run appears on every interaction with the h...

D.3 Linux WinDriver Evaluation Limitations 381 • WinDriver CE emulation on Windows 2000/XP/Server 2003/Vista will stop working after 30 days. D.3 Linux WinDriver Evaluation Limitations • Each time WinDriver is activated, an Unregistered message appears. • DriverWizard [ 4 ]: – Each time DriverWizard...

Appendix E Purchasing WinDriver Fill in the order form found in Start | WinDriver | Order Form on your Windowsstart menu, and send it to Jungo via email, fax or mail (see details below). Your WinDriver package will be sent to you via Fedex or standard postal mail. TheWinDriver license string will be...

Appendix F Distributing Your Driver –Legal Issues WinDriver is licensed per-seat. The WinDriver license allows one developer on asingle computer to develop an unlimited number of device drivers, and to freelydistribute the created drivers without royalties, as outlined in the license agreementin the...

Appendix G Additional Documentation U P DAT E D M A N UA L S The most updated WinDriver user manuals can be found on Jungo’s site at: http://www.jungo.com/st/support/support_windriver. html . V E R S I O N H I S TO RY If you wish to view WinDriver version history, refer to the WinDriver Release Note...