Developing Drivers with the Windows Driver Foundation (Pro Developer)
UMDF includes a built-in verifier that detects problems in framework and UMDF driver code. UMDF Verifier is always enabled in both the free and checked build environments-you do not need to do anything to enable it. Because UMDF Verifier is always enabled, problems in UMDF driver code are always fatal; that is, they cause the host process to stop responding unless a debugger is attached to the other process that is running the UMDF driver.
UMDF Verifier checks UMDF driver code for incorrect calls to the UMDF device driver interfaces. UMDF Verifier also checks a number of private calls within the framework itself.
Table 21-4 lists the kinds of errors that UMDF Verifier can detect, with examples of calls that are checked for each kind of error.
| Error | Example |
|---|---|
| Passing NULL for a parameter | Passing NULL for a parameter to IWDFDevice::CreateSymbolicLink, IWDFDevice::GetDefaultIoTarget, or IWDFDevice::GetDriver. |
| Passing an empty string for a parameter | Passing a pointer to an empty string as a parameter to IWDFDevice::CreateSymbolicLink. |
| Passing zero as the size for a parameter | Passing zero as the buffer size to IWDFMemory::SetBuffer. |
| Passing a value that is not defined as part of the enumeration | Passing a value that is not a member of the WDF_PNP_STATE enumeration as the first parameter to IWDFDevice::SetPnpState. |
| Attempting to complete an already completed request | Calling IWDFIoRequest::CompleteWithInformation or IWDFIoRequest::Complete for a request that has already been completed. |
| Attempting to enable or disable the cancellation of an I/O request that was delivered from an I/O queue | Calling IWDFIoRequest::UnmarkCancelable for an I/O request that was not delivered from a queue. |
| Attempting to retrieve the memory object that represents the input buffer in an I/O request that is not of type Write or DeviceIoControl | Calling IWDFloRequest::GetInputMemory for a read I/O request. |
| Attempting to format for a write operation an I/O request object on a USB pipe that is not an OUT endpoint | Calling IWDFUsbTargetPipe::FormatRequestForWrite for an I/O request object on a pipe that is an IN endpoint. |
UMDF Bug Checks
When UMDF Verifier detects an error, it causes a UMDF bug check in the host process. Unlike a kernel-mode bug check, a UMDF bug check does not cause the system to crash. Instead, UMDF:
-
Creates a memory dump file and saves the file to the computer's log file directory-for example, %windir%\System32\LogFiles\WUDF\Xxx.dmp.
-
Creates an error report that a user can choose to send to Microsoft.
-
Breaks into the debugger, if one is attached to the computer.
The debugger displays an error message such as the example shown in Listing 21-4.
Listing 21-4: Example debugger output from UMDF Verifier
**** WUDF DriverStop - Driver error 0x501000100000f34 **** in Host **** z:\umdf\drivers\wdf\umdf\driverhost\framework\wudf\wdfdevice.cpp:3892(CWdfDevice:: CreateSymbolicLink): Invalid input parameter **** (b)reak repeatedly, break (o)nce, (i)gnore or (t)erminate process?
-
Terminates the host process and disables the device.
Listing 21-4 shows an example of debugger output from an error detected by UMDF Verifier. In this example, the UMDF driver called IWDFDevice::CreateSymbolicLink with a pointer to a NULL string, which is an invalid parameter for that function.
UMDF Error Reporting
UMDF reports errors detected by UMDF Verifier as well as other problems through Windows Error Reporting (WER). In addition to UMDF Verifier errors, UMDF reports unhandled exceptions in the host process, unexpected termination of the host process, and failure or timeout of critical operations.
The contents of a UMDF WER error report depend on the problem that occurred. The error report can contain the following information:
-
A memory dump of the host process.
-
A copy of the UMDF internal trace log.
-
Information about the device configuration, which can include the device name, manufacturer, and names and versions of installed drivers for the device.
-
Internal analysis of the problem, which can include the address of the last driver-to-framework call (or vice versa), problem code, exception information, and so on.
Tip See "Handling Driver Failures" in the WDK for details about how UMDF and the operating system handle errors in a UMDF driver-online at http://go.microsoft.com/fwlink/ ?LinkId=79794. See also "Windows Error Reporting: Getting Started" on the WHDC Web site for details about WER-online at http://go.microsoft.com/fwlink/?LinkId=79792.
Категории