You have a hardware device that is not 100 percent compatible with the devices supported by the Windows version 3.1 retail device drivers, orDavid Long
Microsoft Developer Network Technology Group
Created: August 4, 1992
The virtuous David Long was last seen paddling his virtual kayak device in a virtually unknown river near Snoqualmie, Washington (the virtually famous virtual town called Twin Peaks).
Abstract
This article introduces the tools, development files, sample sources, and online information for developing virtual devices using the MicrosoftÒ Developer Network VxD-Lite Mini-DDK, which is a subset of the Microsoft WindowsÔ version 3.1 Device Driver Kit.
"VxD-Lite: Everything you always wanted in a DDK. And less."
Virtual devices (VxDs) provide the device management that the MicrosoftÒ WindowsÔ operating system needs when operating in enhanced mode. Virtual devices ensure that the computer's actual devices continue to operate correctly, even when two or more applications access the device at the same time. There are two types of VxDs: device-oriented VxDs (this is the most common type) and application-oriented VxDs. Because VxDs run in ring 0 and can call directly into the virtual machine manager (VMM) and into other VxDs, they also provide services to MS-DOSÒ and Microsoft Windows-based applications. Services such as interprocess communication between virtual machines (VMs) would be unavailable without VxDs.
The Mini-DDK is only a subset of the full Microsoft Windows version 3.1 DDK. It provides documentation, tools, and samples for building application-oriented VxDs. It does not include source code for the virtual devices shipped with the Windows version 3.1 retail product, nor does it include files for building device drivers for Windows. You will need to purchase the complete DDK if:
You have a hardware device that is not 100 percent compatible with the devices supported by the Windows version 3.1 retail device drivers, or
You want to offer users access to unique features of your device.
On the other hand, if your only purpose in writing a VxD is to access VMM or VxD services for your application, dynamic-link library (DLL), or terminate-and-stay-resident (TSR) program, the VxD-Lite Mini-DDK will meet your needs.
The Microsoft Developer Network CD includes the complete Windows version 3.1 DDK documentation set. Much of the DDK information is oriented toward writing Windows-based device drivers and is therefore not needed by VxD authors. The most important manual for the VxD-Lite Mini-DDK is the Virtual Device Adaptation Guide.
The CD also contains Windows DDK articles in the Knowledge Base and Bug Lists sections of the source index. Also watch for Technical Articles covering areas of interest to VxD writers.
The Microsoft Developer Network CD includes a variety of non-device-oriented VxD samples; browse in the VxD Samples section (under Sample Code in the source index) to see these samples and to copy them from the CD.
The CD does not provide source code for the retail device drivers or virtual devices for Windows; if you need these sources, you will have to purchase the DDK.
The VxD-Lite Mini-DDK provides the following VxD-specific tools:
|
MASM5.EXE | 32-bit version of Microsoft Macro Assembler version 5.1. |
|
LINK386.EXE | 32-bit version of LINK. |
|
ADDHDR.EXE | Special .EXE header modifier. |
|
MAPSYM32.EXE | 32-bit version of the symbol file generator. |
|
WDEB386.EXE | 32-bit debugger. |
|
WIN386D.EXE | Debugging version of WIN386. Debugging and non-debugging .SYM files are also provided. |
Appendix A of the Windows version 3.1 DDK Installation and Update Guide describes these utilities in greater detail.
1.Read the Windows version 3.1 DDK Installation and Update Guide. It describes the purpose and contents of the DDK, lists hardware and software requirements, and tells you how to write or modify a VxD. Keep in mind that this manual was written with the assumption that you purchased the full DDK, so some of the files and samples will not be relevant to the Mini-DDK.
2.Decide where you want to place your samples and development files. Because many VxD samples assume that the INCLUDE directory is adjacent to the sample code subdirectories, a good layout is to place all samples and development files under the same root, such as C:\VXD. For example:
3.Read the "VxD Include Files" abstract (located in the Sample Code section of the source index, under VxD Samples). This abstract explains how you can copy the include files from the CD and place them in the INCLUDE subdirectory you selected in step 2. You do not necessarily have to modify your MS-DOS INCLUDE environment variable; read the abstract for details.
4.Read the "VxD Tools" abstract (located in the Sample Code section of the source index, under VxD Samples). This abstract explains how you can copy the files from the CD, place them in the TOOLS subdirectory you selected in step 2, and then modify your MS-DOS PATH environment variable to point to this directory.
5.Write batch files to automate the process of switching between debugging and retail versions of WIN386.EXE. For example, assuming that your installation directory for Windows is C:\WINDOWS and that your VxD directory is C:\VXD, the following simple batch files will allow you to switch versions easily.
DEB386.BAT:
REM Installs the debugging version of WIN386.EXE and WIN386.SYM
REM in the Windows SYSTEM directory.
copy c:\vxd\tools\WIN386D.* c:\windows\system\WIN386.*
RET386.BAT:
REM Installs the retail version of WIN386.EXE and WIN386.SYM
REM in the Windows SYSTEM directory. Before using this batch
REM file for the first time, copy the retail WIN386.EXE from
REM your Windows SYSTEM directory to your TOOLS subdirectory
REM and rename it to WIN386R.EXE.
copy c:\vxd\TOOLS\WIN386R.* c:\windows\system\WIN386.*
These batch files must be executed outside the Windows environment. That is, you must first exit Windows, run the batch file to switch between retail and debugging versions of WIN386.EXE, and then restart Windows so the change will take effect.
1.Choose a VxD sample from the VxD Samples section of Sample Code on the CD; GENERIC and VWATCHD are good starting points. Read the abstract for instructions on copying the sample to a subdirectory in your VXD parent directory. Build the sample by switching to the sample VxD directory and running NMAKE.
2.If you're inside Windows, exit to MS-DOS.
3.Switch to the debugging version of WIN386.EXE (use the DEB386 batch file you wrote when installing the VxD tools). This step is important because the debugging WIN386.EXE performs extra error checking; also, many VxD samples have special Trace_Out notification messages that execute only in debug mode.
4.Install the sample VxD you just built in step 1 according to the instructions in the sample abstract. This usually involves copying the VxD to the Windows SYSTEM directory and adding the line DEVICE=VxD-name.386 to the [386Enh] section of the SYSTEM.INI file.
5.Make sure that you have a debugging terminal connected to COM1 so you can see the informative messages displayed by VMM and various VxDs (including your sample VxD).
6.Restart Windows in enhanced mode; this will load the VxD and execute its initialization code. Most of the sample VxDs display Trace_Out messages on your debugging terminal when run in debug mode.