Getting Started

Contents

Disclaimer

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Information in this document is subject to change without notice and is provided for informational purposes only. The entire risk of the use or results of the use of this document remains with the user, and Microsoft Corporation makes no warranties, either express or implied. The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation.

ActiveSync, ActiveX, BackOffice, Direct3D, DirectAnimation, DirectDraw, DirectInput, DirectMusic, DirectPlay, DirectShow, DirectSound, DirectX, MSDN, Microsoft, MS-DOS, MS, Outlook, Visual C++, Win32, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Other product and company names mentioned herein may be the trademarks of their respective owners.

©1999 Microsoft Corporation. All rights reserved.

Introduction

• System requirements and instructions for installing the Windows 98 DDK.
• Instructions for using the Setenv.bat batch file provided with the Windows 98 DDK to set up the device driver build environment.
• Instructions and tips for getting started building WDM drivers.

Installing the Windows 98 DDK

These notation conventions are used in this section:

• %98DDK% — root directory of the installed Windows 98 DDK.
• %MSTOOLS% — root directory of the Microsoft Platform SDK (if it is installed; it is optional).
• %VCPPDEV% — root directory of the installed Microsoft Visual C++® development environment.

System Requirements

• Microsoft Windows 98 operating system final release.
• Microsoft Visual C++ version 4.2 or 5.0 (including service packs) for x86-based systems. Microsoft VC++ version 5.0 (including service packs) is required to compile the video capture samples. Note that Visual C++ 6.0 is not supported for any of the samples.

Important: You must install the Visual C++ compiler/development environment before you install the Windows 98 DDK. Otherwise, the Setenv.bat file in the Windows 98 DDK will not set up the correct environment when you run it. For more information, see "Setting Up and Using the Windows 98 Driver Build Environment."
• Microsoft Internet Explorer version 4.01 or greater for the DDK documentation set.
• CD-ROM drive, if installing from CD or testing CD drivers.
• 16 MB RAM.
• 82 MB hard disk space for the full installation (32 MB of hard disk space for a minimum installation, which does not include the sample driver source code, Help files, or other documentation files).
• Legacy Driver Samples:  The legacy driver samples require a 16-bit compiler and linker.  They have been tested under VC 1.52 and VC 1.51.  If you don't already have the VC 1.52 compiler, you can obtain it from the following sources:
  1. VC 1.52 is found on Disk 3 (16-bit DDKs) of the MSDN Platform Archive series. This series is obtained by filling out the special request card that came supplied in your first MSDN package.
  2. When you receive VC 4.2, there is a special request card that you can use to request VC 1.52.
  3. VC1.52 comes supplied as part of the VC 4.0 package.

Using the Setup Program to Install the DDK

1. Run Setup.exe from the Windows 98 DDK compact disc, or download the self-extracting executable file, which will begin setup.exe upon completion of the uncompression.

Setup.exe is a Windows-based application that you can run either from the Start/Run button or from an MS-DOS® Prompt.
2. Click Next to install the DDK.
3. Read the Software License Agreement and, if you agree with its terms, select "I accept the Agreement" and click Next.
4. Select the setup functions you prefer, and then click Next.
5. Select the drive and directory where you want to install the Windows 98 DDK, and then click Next.  Note:  The Windows 98 DDK cannot be installed in a directory that does not follow 8.3 naming convention.  Also, the Windows 98 DDK should not be installed over a previous version of the Windows 98 DDK.   This will cause problems with the build environment and command line tools included in Visual C++.
6. Select the component groups you want to install. Use the Details button to select or deselect sub-components. (By default, all sub-components are selected when you select a component area.) Click Next.
7. Verify that the appropriate components will be installed, and then click Next.
8. When the installation of components is completed, click Next, and then click Exit.

The Setup program installs the selected Windows 98 DDK components in the specified installation directory and creates program folders.

You should increase your environment space because the Windows 98 DDK, compiler, and assembler (and the optional Platform SDK) all use additional environment space for storage of search paths.

Note: The Windows 98 DDK uses the current VCVars.Bat as part of creating the build environment.  This includes setting your current path to include the installation source of VC.  You may want to delete the line vcsource=<Install Path> from %DDKRoot%\Bin\DDKVars.Bat if you installed from over a network.  Doing so may reduce the time required to build the drivers.

To increase the environment space:

• Add the following command to your Config.sys file (or change the line already there):

Setting Up and Using the Windows 98 Driver Build Environment

This section provides instructions for establishing a WDM driver build environment and using the Build utility to build drivers.

Using SETENV.BAT to Set Up the Driver Build Environment

A program folder named "Development Kits\Windows 98 DDK" is created. This folder contains items called Free Build Environment and Checked Build Environment. Each time you restart the operating system, before you build a driver, click one or the other of these program folder items. These items call Setenv.bat in %98DDK%\BIN to create the driver build environment with the correct environment variables.

To run SETENV.BAT manually:

• Use the following syntax at the MS-DOS Prompt or in the Start/Run box:

For example, from the C:\98ddk\bin> prompt, type setenv C:\98ddk free

The first argument, <destination>, specifies the directory where the DDK is installed. Note that in the case of default setup, the destination is \98ddk. The optional second argument specifies the target build environment; the default type is free.

To remove your VC++ install directory from the search path:

• Remove set vcsource from the %98DDK%\bin\ddkvars.bat file.

WDM drivers are built using the Build utility, which uses a set of rules and project files that specify how drivers should be created. The Build utility is used to build WDM drivers on both Windows 98 and Windows NT® platforms.

This section summarizes the structure of the driver build tree and the file components in that tree upon which the Build utility depends. You need to know this information to build your own WDM drivers. For a detailed version of this information, see the Windows NT 4.0 or Windows 2000 DDK documentation about the Build utility. Also, a working example of a WDM driver build tree, with all the correct component files, is available on your hard disk after the Windows 98 DDK is installed. The driver build tree root is at %98DDK%\src. Look at the contents the Makefile.def in %98DDK%\inc and at the contents of the various Dirs and Sources files scattered throughout the driver build trees. Use these as examples for your own work.

The Dirs file specifies which directories in the subtrees contain source code files to be built. For 16bit samples the %98DDK%\inc\master.mk needs to be modified to reference the path of your 16bit compiler. Set the C16_ROOT to point to the base directory of the 16bit compiler (ex: C16_TOOLS=C:\MSVC). It is not recommend to have the 16bit tools in the path due to possible conflicts with multiple linkers and compilers.

The Sources file specifies which source files are required to build a driver in each subdirectory.

To build one or more drivers in a driver build tree:

• Make a subdirectory in the driver build tree of the current directory, and then run the Build utility.

An example of this is described in "Verifying Your Windows 98 DDK Installation" below, where the Build utility is run with the current directory at the root of the Windows 98 DDK sample driver build tree (%98DDK%\src). This causes all the sample drivers on the Windows 98 DDK to be built. For Example, if you are only interested in building the sample drivers for the Audio device class, set the current directory to %98DDK%\src\audio and then run the Build utility.

Verifying Your Windows 98 DDK Installation

A form of the build command that is often used is build -cZ; this causes the Build utility to do a scan of dependency files, perform a clean build, and create an error log.

To verify your installation:

• Run build -cZ from the \<destination>\src directory to build the complete set of installed sample driver sources.

If the build does not complete or reports excessive compile errors, you will need to confirm that the installation steps listed above were followed correctly.

After the drivers are built, the binaries are in %98DDK%\lib\i386\[free|checked]

Starting to Build Your Own WDM Drivers

Once you have built the sample drivers to verify the Windows 98 DDK installation, you can start building your own WDM driver. This section gives some tips about doing that. Note that much of the detailed information about building kernel-mode drivers in the Windows NT 4.0 or Windows 2000 DDK also applies to building WDM drivers.

The debugger tool provided on the Windows 98 DDK is the Windows System Debugger (Wdeb386.exe). For detailed information how to install and use Wdeb386.exe, see "About Windows System Debugger" in the Windows 98 DDK documentation  under Windows 98 DDK / Related Driver Documentation / Windows 95 Documentation / Programmer's Guide / WDEB386 System Debugger.

If your driver will consist of multiple binaries, or the source will be kept in multiple directories, you might need to create a Dirs file specifying which directories are to be built and in what order. Each separate binary requires a Sources file describing which files are to be compiled/linked to create the driver.

Each driver directory also contains a Makefile. Build spawns the Nmake utility for each source file listed in sources, and Nmake uses the Makefile to generate dependency and command lists. The standard Makefile file in a driver source code directory directs Nmake to the master Nmake macro definition file, Makefile.def. This file defines the flags for the build tools such as the compiler and linker. Makefile.def simplifies the creation of platform-independent driver projects and is similar to the Ntwin32.mak file in the Microsoft Platform SDK.

After you have Dirs, Sources, and Makefile files created, the next step is to run the Build utility that parses the sources file and spawns Nmake for each source file. The Nmake utility evaluates the macros in Makefile.def and spawns the C compiler with the proper switches. After the compile stages are completed, Build spawns Nmake again to link the objects and complete the driver building phase.

If your Sources file is correct, running Build -cZ is all that is required to compile and link your driver. Using Build and Makefile.def removes the guesswork of which compiler switches are required, which arguments the linker requires, and so on.

During driver development, you will need to build free and checked versions of your driver. This is controlled by environment variable settings that are interpreted by Build and Nmake. These variables are set by Setenv.bat, as discussed earlier. To build a free driver, run Build from the free environment. To build a checked driver, run Build from the checked environment.

Important: Not all WDM-specific libraries are available in checked form on the DDK CD. When you build a checked version of your driver, you might have to explicitly reference the path to the free form of those libraries in the TARGETLIBS line of the Sources file for your driver.

Debug binaries and components are provided for Windows 98 in the \dbg_sym directory on the Windows 98 DDK distribution CD.

Template files (.tpl) for Dirs, Sources, Makefile, and other files can be found on the Windows 98 DDK distribution CD, in the directory \98DDK\DDK\DOC\BUILD. As stated earlier, working versions of these files can be found in driver source subdirectories of the DDK. Examining these files along with Makefile.def (located in the %98DDK%\INC directory) provides additional information.

Information at www.Microsoft.com

The Hardware Development Web Site at http://www.microsoft.com/hwdev provides connections to information from Microsoft to help with hardware and driver development. This Web site provides the following:

• Driver development information for Plug and Play, power management, manageability, NDIS 5.0, WDM, and specific device classes such as audio, imaging, and so on.
• Third-party driver development and training resources.
• Advice from "Dr. Iver" on special driver topics, such as WDM, Plug and Play, and power management.
• Specifications for power management, Plug and Play, and other special topics.

• Downloads for service packs or patches for Microsoft development tools.
• Special developer tools for MSDN Online Members to try out and evaluate, designed to compliment and integrate with the Microsoft programming environments you already use.
• Up-to-date SDK releases.
• Access to user groups, chats, event information, the MSDN Library Online, and a host of products and technologies for developers.

• Microsoft DirectX SDK download.
• Connections to technical articles, support information, news groups, and so on.

• The most current DDK available, publicly downloadable.
• Current documentation for the DDK, downloadable or browseable online.
• Announcements of new DDK developments.
• Feedback for reporting bugs, suggesting content, and rating the DDK.

• Additional driver samples.
• Tools for device drivers and debugging.
• FAQs for Windows driver development.

Release Notes

Internet Explorer Required for Documentation

Visual Studio Service Pack 3 recommended

PC98 samples require source from other samples

Information on creating IrDA drivers

Information on creating WDM Audio drivers

Information on creating WDM DVD drivers

Information on creating 1394 drivers

Information on creating Modem drivers

Content in the %DDKRoot%\src\PC98 is unsupported

Release Notes for the WDM Video Capture Testcap sample driver

   case SRB_READ_DATA:

        // Rule:
        // Only accept read requests when in either the Pause or Run
        // States.  If Stopped, immediately return the SRB.

        if (pStrmEx->KSState == KSSTATE_STOP) {
            CompleteStreamSRB (pSrb);
            break;
        }

        //
        // Put this read request on the pending queue
        //


        VideoQueueAddSRB (pSrb);

        // Since another thread COULD HAVE MODIFIED THE STREAM STATE
        // in the midst of adding it to the queue, check the stream
        // state again, and cancel the SRB if necessary.  Note that
        // this race condition was NOT handled in the original DDK
        // release of testcap!

        if (pStrmEx->KSState == KSSTATE_STOP) {
            VideoQueueCancelOneSRB (
                pStrmEx,
                pSrb);
        }

Release Notes for the Broadcast Architecture Driver Development Kit (DDK)

Visual C++ 4.2 Errors

Legacy Documentation

Legacy Drivers

1. Insert !include $(BASEDIR)\inc\master.mk as the first line in the makefile.
2. Change all references to 16-bit compile tools to $(CL16) for cl.exe, $(LINK16) for link.exe and $(RC16) for rc.exe.
3. Include and lib paths can be defined using $(INC32), $(INC16), $(C16_ROOT)\include, $(LIB32), $(LIB16), $(C16_ROOT)\lib. C16_ROOT is defined in master.mk as the base dir of your 16-bit compile tools.
4. If you want to use build.exe to make your driver, add the following around the link step.
• !ifndef PASS0ONLY
• link step commands
• !endif
Echo's can be inserted where command names aren't explicit so build can count compiles and links (see an existing legacy makefile on how this is done). Add your driver sub directory name to the Dirs file in order for a recursive build to work.