1. Device Enumeration and Startup
To prepare the device for operation, UMDF calls the driver’s callback routines in a fixed sequence.
The following shows the
callbacks for a driver that is involved in bringing a device to the
fully operations state, starting from the DeviceArrived state at the bottom of the following steps.
|
Device Operational
End Sequence
1. | Enable self-managed I/O, if driver supports it.
IPnpCallbackSelfManagedIo::OnSelfManageIoInit
or OnSelfManagedIoRestart
| 2. | Start power-managed queues.
(Called only if UMDF earlier invoked IQueueCallbackIoStop::OnIoStop during power-down.) IQueueCallbackIoResume::OnIoResume
| 3. | Notify driver of state change.
IPnpCallback::OnDOEntry
|
Restart from here if device is in low-power state
4. | Prepare hardware for power.
IPnpCallbackHardware::OnPrepareHardware
|
Restart from here if rebalancing resources
5. | Create device object.
IDRiverEntry::OnDeviceAdd
|
Device Arrived
Start Sequence Above
|
At the
bottom of the preceding steps, the device is not present on the system.
When the user plugs it in, UMDF begins by calling the driver’s IDRiverEntry::OnDeviceAdd
callback so the driver can create a device object to represent the
device. UMDF continues calling the driver’s callback routines by
progressing up through the sequences above until the device is
operational. If the device was stopped because the PnP manger was
rebalancing system resources or if the device was physically present but
not in the working state, not all of the steps are required, as the
sequence shows.
2. Device Power-Down and Removal
UMDF might remove a device from the operational state for several reasons:
To put the device in a low-power state because the system is entering a sleep state
To rebalance resources
To remove the device after the user has requested an orderly removal
To disable the device in response to the user’s request in Device Manager
The following shows the
sequence of callbacks that are involved in power-down and removal. The
sequence starts at the top of the sequence below with an operational
device that is in the working power state (DO).
|
Device Operational
Start Sequence
1. | Suspend self-managed I/O.
IPnpCallbackSelfManagedIo::OnSelfManagedIoSuspend
| 2. | Stop power-managed queues.
IQueueCallbackIoStop::OnIoStop
| 3. | Notify driver of state change.
IPnpCallback::OnDoExit
|
Stop here if transitioning to low-power state
4. | Release hardware (Not called if target device state is WdfPowerDeviceD3Final).
IPnpCallbackHardware::OnReleaseHardware
|
Stop here if rebalancing resources
5. | Purge power-managed queues.
IQueueCallbackIoStop::OnIoStop
| 6. | Flush I/O buffers, if driver supports self-managed I/O.
IPnpCallbackSelfManagedIo::OnSelfManagedIoFlush
| 7. | Purge nonpower-managed queues.
IQueueCallbackIoStop::OnIoStop
| 8. | Clean up I/O buffers, if driver supports self-managed I/O.
IPnpCallbackSelfManagedIo::OnSelfManagedIoCleanup
|
Device Removed
End Sequence
|
As
the preceding sequence shows, the UMDF power-down and removal sequence
involves calling the corresponding “undo” callbacks in the reverse order
from which UMDF called the methods that it invoked to make the device
operational.
2.1. Surprise-Removal Sequence
If the user removes the
device without warning, by simply unplugging it without using Device
Manager or the Safely Remove Hardware utility, the device is considered surprise removed.
When this occurs, UMDF follows a slightly different removal sequence.
It also follows the surprise-removal sequence if another driver
invalidates the device state (for example, a Kernel Mode Driver calls IoInvalidateDeviceState), even if the device is physically present.
In the surprise-removal sequence, UMDF calls the IPnpCallback::OnSurpriseRemoval
callback to notify the driver that the device has been unexpectedly
removed. This callback is not guaranteed to occur in any particular
order with the other callbacks in the removal sequence.
Drivers for all removable
devices must ensure that the callbacks in both the shutdown and startup
paths can handle failure, particularly failures that are caused by the
removal of the hardware. The reflector times out the driver if an
attempt to access the hardware waits indefinitely.
The following sequence shows the surprise-removal sequence.
|
Device Surprise Removed
Start here if device is in the working state
1. | Suspend self-managed I/O.
IPnpCallbackSelfManagedIo::OnSelfManagedIoSuspend
| 2. | Stop power-managed queues.
IQueueCallbackIoStop::OnIoStop
| 3. | Notify driver of state change.
IPnpCallback::OnDOExit
|
Start here if device is not in the working state
4. | Release hardware.
IPnpCallbackHardware::OnReleaseHardware
| 5. | Purge power-managed queues.
IQueueCallbackIoStop::OnIoStop
| 6. | Flush I/O buffers, if driver supports self-managed I/O.
IPnpCallbackSelfManagedIo::OnSelfManagedIoFlush
| 7. | Purge nonpower-managed queues.
IQueueCallbackIoStop::OnIoStop
| 8. | Clean up I/O buffers, if driver supports self-managed I/O.
IPnpCallbackSelfManagedIo::OnSelfManagedIoCleanup
|
Removal Processing Complete
|
If the device was not in the working state when it was removed, UMDF starts with the IPnpCallbackHardware::OnReleaseHardware method. It omits the intervening steps, which were already performed when the device exited from the working state.
3. Build, Test, and Debug
Like Kernel Mode Drivers,
UMDF drivers are built with the Windows Driver Kit (WDK). The WDK
includes the required libraries and header files to build a UMDF driver,
along with sample code and build scripts.
The WDK includes a library of
debugger extensions for use with UMDF drivers. The debugger extensions
work with CDB, NTSD, and WinDbg. UMDF drivers can be debugged in either
user mode or kernel mode. Debugging a User Mode Driver is similar to
debugging a service. Symbol files are also included as an aid in
debugging.
UMDF drivers can use Event
Tracing for Windows (ETW) to generate a trace log of driver events. The
logs can be viewed using the tracing tools provided with the WDK.
The user mode components
that Microsoft supplies start trace sessions that record their
activities and note such events as driver hangs, time-outs, and
failures. UMDF has integrated verification code that is always enabled.
If a driver uses UMDF DDIs incorrectly or passes incorrect parameters,
the verifier saves a memory dump in the system log file directory and
optionally creates a Windows error report. The trace log files and error
reports can optionally be sent to the Microsoft Windows Error Reporting
(WER) facility. WER captures software crash data and supports end-user
reporting of crash information. The information collected through WER
is accessible to vendors so that they can analyze problems and respond
directly to their customers.
You can also use PREfast, a
static analysis tool that is part of the WDK, with UMDF drivers. PREfast
examines code paths on a per-function basis and can find logic and
usage errors in a driver at compile time.
3.1. Installation and Configuration
UMDF drivers are installed by using standard INF files, in the same way as Kernel Mode Drivers. A hardware vendor’s installation package thus includes
An INF file for the driver
The redistributable update co-installer WUDF_Update_MMmmm.dll (where MM is the major UMDF version number and mmm is the minor version number)
A driver binary
An optional custom installation application
The INF file includes a [DDInstall.CoInstallers]
section that references the co-installer. The co-installer is available
to hardware vendors in the WDK and in general distribution releases
(GDRs). Microsoft provides the redistributable co-installer
Wudf_Update_MMmmm.dll, which vendors can ship as part of their driver
packages. The co-installer is a signed component. Driver installation
fails if the certificate with the co-installer was signed and is not
available on the target system.
The Wdf section of the driver’s INF
file specifies the driver service name, the driver class ID, the order
in which the UMDF drivers should be installed in the device stack, and
the maximum impersonation level that the UMDF driver can use.
The DestinationDirs section of the INF
file specifies the location to which to copy the driver. All UMDF
drivers must reside in %SystemRoot%\system32\drivers\UMDF. This
directory has sufficient ACLs to ensure that an unprivileged user cannot
tamper with the drivers.
If the UMDF device stack for the driver contains only filter drivers, the INF
installs the reflector as the top-level filter driver in the Kernel
Mode Driver stack. However, if the function driver for the device is a
UMDF driver, the INF installs the reflector as the service for the device.
When the INF
for the device is processed, the co-installer starts the driver manager
if it is not already running. User Mode Driver installation must not
require a reboot of the system.
3.2. Versioning and Updates
UMDF supports versioning,
which enables a driver binary to run with the same major version of UMDF
independent of the operating system version. Versioning helps to ensure
that a driver uses the components with which it was designed, tested,
and released. Each version of the operating system supports all versions
of UMDF. Updates to UMDF or the operating system do not require updates
to the driver. Microsoft is responsible for ensuring consistent
behavior across releases.
Although
two major versions of UMDF can run side by side simultaneously, two
minor versions of the same major version cannot. At installation, a more
recent minor version of the UMDF run-time library or other components
overwrites an existing, older minor version. If the older version is
already loaded when a user attempts to install a driver with a newer
version, the user must reboot the system.
