1394 Diagnostic Tools

Windows Driver Kit: WDM Devices

Description

This document and the associated source code describe how to interact with the Microsoft Windows Driver Model (WDM) 1394 stack. The 1394 Diagnostic Tools consist of two sample WDM Drivers (1394vdev.sys and 1394diag.sys), an API that interfaces to those drivers (1394api.dll), and a user-mode application that allows access to the interfaces of the sample driver.

Theory of Operation

The 1394vdev.sys and 1394diag.sys source codes provide examples of sample drivers that interface with the upper-edge of the WDM 1394 stack. In addition to handling asynchronous and isochronous data transfers, the sample source code demonstrates the correct way to handle Plug and Play (PnP) and Power Management I/O Request Packets (IRPs), which are the basic I/O manager structures that communicate with the 1394 stack. For more information about the IRPs that are discussed in this sample, see the Windows Driver Kit (WDK).

The difference between the 1394vdev.sys and 1394diag.sys drivers is how they are enumerated. The 1394vdev.sys driver is meant to be a virtual diagnostic driver that is loaded by using the IOCTL_IEEE1394_API_REQUEST that is defined in the 1394 DDI section. The 1394diag.sys driver is meant to be a physical diagnostic device driver that is loaded on an actual 1394 device that is plugged into the computer. In Windows XP, 1394vdev.inf is used to load both 1394vdev.sys and 1394diag.sys drivers.

The 1394api.dll source code provides a simple way that the various 1394 DDIs can be accessed. User-mode applications can use this DLL to access various 1394 routines. Also, this DLL provides ways for implementing loopback routines on both asynchronous and isochronous data.

The Win1394.exe source code provides examples of a user-mode application that leverages the 1394 stack to provide access to all of the various interfaces. Win1394.exe can be used as a sample application that takes advantage of 1394 technology or as a testing tool to verify the various 1394 interfaces.

Building the Sample

To build the sample, run the build -c command. You must build samples individually for each component. The sample will produce four binaries: two WDM drivers (1394vdev.sys and 1394diag.sys), one DLL (1394api.dll), and one .exe file(Win1394.exe).

The driver supports Plug and Play (PnP) and Power Management and builds properly with Microsoft Visual C 6.0. It has undergone extensive testing, and there are no known bugs or issues to report.

Installation

General

You can install the 1394 WDK samples by installing the 1394vdev.inf file. This file is located in the \src\wdm\1394\driver\1394vdev directory. To install, right-click the file and click Install. This command will copy the 1394api.dll file to the windows\system32 directory and the 1394vdev.sys and 1394diag.sys files to the windows\system32\drivers directory. This command will also create the appropriate entries in the registry so when a 1394 diagnostic device (either virtual or physical) is created on the system it will be enumerated and installed silently without user intervention.

The Win1394.exe application requires the 1394api.dll to function properly. If the 1394vdev.inf has been installed, this file will already by present in the system directory and no further action will be required by the user.

To install and use the sample 1394 tool set that is provided, you must use a test device. Previously, any other computer that was running the Windows operating system and connected by 1394 would be enumerated as a 1394 Test Device, but this situation is no longer true in Windows XP. Now a test device can be loaded virtually by using the menu options in Win1394.exe or can be loaded physically by putting the 1394 stack into diagnostic mode. Once in Diagnostic Mode, all devices that are plugged in will be enumerated as 1394 test devices. You can enable or disable diagnostic mode by using the menu options in the Win1394.exe application.

Code Tour

File Manifest

File	Description
1394vdev	A driver name. The following files are needed to build it.
1394vdev.c	Entry points for 1394vdev driver.
1394vdev.h	Prototype file for 1394vdev driver.
1394vdev.rc	Resource file for 1394vdev driver.
debug.h	Prototype file for debug functions.
ioctl.c	Source file for all IOCTLs.
makefile	Standard WDK build environment makefile.
pch.h	Prototype file for all external dependencies.
pnp.c	Source file for all Plug and Play (PnP) handling.
power.c	Source file for all Power handling.
1394api.c	Common source file with 1394diag for general 1394 class DDIs.
asyncapi.c	Common source file with 1394diag for async related 1394 class DDIs.
common.h	Common header file with 1394diag for external definitions.
isochapi.c	Common source file with 1394diag for all isoch 1394 DDIs.
util.c	Common source file with 1394diag for utility functions.
makefile	Standard WDK build environment makefile.
sources	The generic file for building the code sample.
1394diag	A driver name. The following files are needed to build it.
1394diag.c	Entry points for 1394diag driver.
1394diag.h	Prototype file for 1394diag driver.
1394diag.rc	Resource file for 1394diag driver.
debug.h	Prototype file for debug functions.
ioctl.c	Source file for all IOCTLs.
makefile	Standard WDK build environment makefile.
pch.h	Prototype file for all external dependencies.
pnp.c	Source file for all Plug and Play (PnP) handling.
power.c	Source file for all Power handling.
1394api.c	Common source file with 1394vdev for general 1394 class DDIs.
asyncapi.c	Common source file with 1394vdev for async related 1394 class DDIs.
common.h	Common header file with 1394vdev for external definitions.
isochapi.c	Common source file with 1394vdev for all isoch 1394 DDIs.
util.c	Common source file with 1394vdev for utility functions.
makefile	Standard WDK build environment makefile.
sources	The generic file for building the code sample .
1394api	The name of the API that interfaces to those drivers. The following files are required to build it.
1394api.c	Source file for general 1394 API calls.
1394main.c	Main source file for 1394api DLL.
Asyncapi.c	Source file for async 1394 API calls.
Debug.c	Source file for debug.
Isochapi.c	Source file for isoch 1394 API calls.
Utils.c	Source file for misc. util functions.
Debug.h	Prototype file for debug.
Local.h	Prototype file for local dependencies.
Pch.h	Prototype file for external dependencies.
Util.h	Prototype file for util functions.
1394api.rc	Resource file for 1394api DLL.
1394api.def	Definition file for 1394api DLL.
makefile	Standard WDK build environment makefile.
sources	The generic file for building the code sample.
Win1394	A user-mode application that allows access to the interfaces of the sample driver. The following files are required to build it.
1394.c	Source file for general 1394 calls.
Async.c	Source file for async 1394 calls.
Debug.c	Source file for debug calls.
Isoch.c	Source file for isoch 1394 calls.
Util.c	Source file for util functions.
Win1394.c	Main source file for win1394 executable.
Win1394.rc	Resource file for win1394 executable.
1394.h	Prototype file for 1394.c.
Async.h	Prototype file for Async.c.
Debug.h	Prototype file for Debug.c.
Isoch.h	Prototype file for Isoch.c.
Local.h	Prototype file for local dependencies.
Pch.h	Prototype file for external dependencies.
Resource.h	Prototype file for win1394 executable resources.
Util.h	Prototype file for Util.c.
Win1394.ico	Icon file for 1394.
makefile	Standard WDK build environment makefile.
sources	The generic file for building the code sample.

Build machine: CAPEBUILD